Run-time processing sequence for Reports programming interface

Before you begin to customize report procedures, it is important to understand the run-time processing flow for Report Builder and Report Viewer. The processing sequence occurs in the following phases.

  • In phase 1, the user opens one of the subfolders in the Reports folder.

    The Report Builder processes the interface specification of all report procedures associated with the reports in that subfolder and presents the description of each report in the reports pane of the Report Builder. The parameters associated with the first report listed appear in the parameters pane. This processing is done with the command that uses the -i option.

  • In phase 2, the user selects a report in the reports pane.

    The Report Builder populates the parameters pane with the parameters required for that report. When the user clicks a parameter, the associated parameter chooser prompts the user to provide a value. When all parameters have values, the user can run the report. (The Run Report button is not available until all parameters have values.)

  • In phase 3, the report is generated.

    A command line, whose parameters are defined in the interface specification, is passed to the Report Viewer, with the parameter values. The Report Viewer runs the report procedure and uses cleartool to retrieve information from the VOB. The report procedure returns the information to the Report Viewer, which sorts, formats, and displays it. The right-click behavior for all rows in the report (as defined in the interface specification) is now enabled, and the user can also manipulate the report data.

The following figure illustrates this processing sequence.

Figure 1: Run-time processing sequence

The processing sequence shows, in three phases, User Actions on the left half and Run-time processing on the right half.

To execute these processing phases correctly, a report procedure must meet the following requirements:
  • The directory that contains the report procedure must be found at known location. The Report Builder reads the \reports\scripts directory to determine the report procedure file names. When a user clicks the associated directory folder, Report Builder calls the associated report procedure.
  • The report procedure must have a valid interface specification. If the expected format is not present, the report does not run.
  • The interface specification in the report procedure must use parameters and choosers supplied by DevOps Code ClearCase® Reports. See Parameters supplied with DevOps Code ClearCase Reports.
  • The report procedure must support a command line interface that the Report Viewer can use to pass user-defined parameter values to the report procedure.