C.3 Report Procedure Interface Specifications

As the Report Builder finds report procedures in the customized directory, it queries each report procedure for its interface specification. It does this by starting a separate process with CreateProcess(). A valid report procedure must implement an interface specification and return formatted text to STDOUT that conforms to this specification:

description : ["<text to display in description pane for this report>"]

id : <numeric help id>

helpfile : ["<full path to user-written help file for what's this report help>"]

parameters : [<parameter_spec_1>] [<parameter_spec_2>] ... [<parameter_spec_N>]

rightclick : [<rightclick_spec_1>] [<rightclick_spec_2>] ... [<rightclick_spec_N>]

fields : [<field_spec_1>] [<field_spec_2> ... [<field_spec_N>]

If a serious parsing error occurs in processing the interface specification, the report does not appear in the reports pane. The helpfile specification is reserved for future use and is not supported in this release. For information on troubleshooting parsing errors, see Troubleshooting.

The examples in the following sections show how the interface specification is defined in specific report procedures.

Interface Specification for All_Views.prl

The Report Builder uses this command to run All_Views.prl:

ccperl "D:\Program Files\Rational\Clearcase\Reports\scripts\Views\All_Views.prl" -i

This is the interface specification:

description : "All Views"
id : 2001
helpfile :
parameters :
rightclick : Properties_of_View(single)
fields : "View Tag"(view_tag, rightclick, initial_width 30, sort 1) "View Owner"(user_dq)

The report interface attaches the Report Viewer to the View Tag and View Owner fields; the right-click event in the Report Viewer window calls Properties _of_View.prl, which is based on a data stream from the View Tag field.

Interface Specification for test_null.prl

The Report Builder uses this command to run test_null.prl:

ccperl "D:\Program Files\Rational\Clearcase\Reports\scripts\samples\test_null.prl" -i

This is the interface specification:

description : "null interface"
fields : "field1"(string)

This report interface attaches the Report Viewer to the field named field1.

Interface Specification for test2_null.prl

The Report Builder uses this command to run test2_null.prl:

ccperl "D:\Program Files\Rational\Clearcase\Reports\scripts\samples\test2_null.prl" -i

This is the interface specification:

description : "null interface"

When only description is defined, a report procedure can run other graphical user interfaces (for example, clearprompt) or otherwise interact with the user. Note, the only required line in the interface specification is description; all other interface definitions are optional. The reports in the \ClearCase_Tools folder define description only.

Description Specification

The description is the only required part of an interface specification. Descriptions can contain anything other than the delimiter, a double quote ("). There is no maximum length for this definition, but long strings do not wrap in the reports pane.

Help ID Specification

Help IDs for the description and parameter fields are supplied for the Report Builder user interface. The help id specification is the ID that supports context-sensitive help for the description or parameter fields in the Report Builder user interface. The IDs are integers in the following range:

The help file for ClearCase Reports is ccase-home-dir\bin\cc_reports.hlp. The help IDs for the parameter and description fields are included in this file. In this version of ClearCase Reports, you cannot add an ID for your own report.

Parameters Specification

When specifying parameters, you can use only those supplied with ClearCase Reports. Each parameter has an associated chooser control, parameter text, and a help ID (Table 6 ). When you use one of these parameters, naming it is all that is required. For example, this is the parameters specification for the Elements Changed Between Two Labels report:

parameters : LOOKIN LABEL LABEL

The order of parameters is important. They are displayed in the parameter pane in the order of the specification. (Each parameter appears as a link; when users click the link, they are prompted to enter a parameter value.) At run time, the Report Viewer calls the report procedure, which must handle the parameter values in the same order as defined in the specification.

The parameters in Table 6 that are associated with the Type Chooser must also include the LOOKIN parameter in the interface specification. The LOOKIN parameter must have a value before any values for other parameters that use the Type Chooser can be specified. The paths that are the values for the LOOKIN parameter are used to build the set of VOBs that types can be read from. At run time, if a user attempts to set a type parameter in reverse order, the Report Builder displays this error message:

Before this parameter can be set, you must first set a value for the "Select pathnames in view to report on" parameter.

Rightclick Specification

The rightclick specification is a list of commands available on the shortcut menu in the Report Viewer. All right-click events are supported by a list of scripts in the \scripts_rightclick directory. This specification allows you to control the text on the shortcut menu. At run time, underscores in these text strings are replaced by spaces.

rightclick : properties_of_view delete_view

By default, the commands are valid for both single and multiple selections of result records in the Report Viewer. This behavior can be controlled by using the single modifier:

rightclick : properties_of_view(single) delete_view(single)

A special string, sep, allows visual separators to group commands. At run time, these commands appear on the shortcut menu in the order specified.

Fields Specification

The fields specification defines the names of the field headings and a number of modifiers to describe the results a report procedure returns to the Report Viewer. Table 7 describes the supported modifiers.

For example, the following fields specification describes a single field with the minimum specification allowed. The field_type modifier is required.

fields: "view tag"(view_tag)

In this example, the fields specification defines two fields, view tag and last mod time, with all the allowable modifiers:

fields: "view tag"(view_tag, rightclick, initial_width 10) "last mod time"(time_t, hidden, sort 1)

field_type Conventions

Table 8 lists the names for field_types and the kind of data represented. We encourage you to use these definitions in your own report procedures wherever possible, but you can use your own definitions.

Depending on the column width required to display for a user-defined field_type, the fields specification in a report procedure may need to adjust the display column size with the Inital_width N modifier.

Parameter Choosers

When a user opens a folder in the Report Builder tree pane, the reports pane is populated with the list of descriptions that the Report Builder discovered in the interface specification. When the user selects a report, the associated parameters are loaded in the Report Builder. Each parameter in the interface specification has associated parameter text, a help ID, and a chooser. All parameters have an associated chooser (Table 6).

These choosers are supplied with ClearCase Reports:

• Path Chooser

• UCM Targets Chooser

• Types Chooser

• Date/Time Chooser

• Text Chooser

For user information, click Help in any chooser dialog box.

Path Chooser

The Path Chooser is associated with the LOOKIN parameter. It presents a list of view pathnames for users to select, and then sends the selected pathnames to the report procedure. It is also used for the PVOB and PVOBS parameters to choose the VOB-tag of a UCM project VOB.

UCM Targets Chooser

The UCM Targets Chooser is associated with the PROJECT, PROJECTS, STREAM, STREAMS, ACTIVITY, ACTIVITIES, ISTREAM, and ISTREAMS parameters and allows you to select UCM objects.

Type Chooser

The Type Chooser presents values for the BRANCH, ATTRIBUTE, LABEL, HYPERLINK, and TRIGGER parameters. All parameters that the Type Chooser supports require an initial value LOOKIN parameter.

Date/Time Chooser

The Date/Time Chooser is used to select date/time values for the CCTIME parameter.

Text Chooser

The Text Chooser presents values for these parameters: COMPONENT, COMPONENTS, BASELINE, BASELINES, USER, GROUP, ATTRIBUTE_VALUE, ELTYPE, BRANCHLEVELS, FILE_NAME, PATH, STRING, INTEGER, and REGULAR_EXPRESSION.

Data typed into the Text Chooser is not validated or parsed in any way by the Report Builder or Report Viewer. The report procedure that accepts the parameter value must perform any validation required.

For most parameters, the text above the text box is Enter value for user. For parameters that require the name of a baseline, a component, or an element type, the text changes to reflect the parameter. For example: Enter value for baseline.

Viewing the Report

When all required parameters have values, clicking Run Report opens the Report Viewer window (Figure 63). The Report Builder creates a command line to pass the user-defined parameters, in the order defined by interface specification . For example, if a report procedure asks for parameters LOOKIN LABEL, the Report Viewer passes these values as follows:

ccperl elements_with_label.prl %LOOKIN='s:\frontpage\acctst';%LABEL=V4.0;

The Report Viewer creates a process to run the report procedure using ccperl.exe for .prl, perl for .pl, cscript.exe for .js and .vbs, and default activation for .exe. The report procedure returns results to STDOUT. The results are separated by semicolons, in the same order, number, and type specified in the fields definition in the interface specification.

When the report procedure has collected all its data, it exits. The report procedure must return records to STDOUT in the most efficient manner possible; the Report Viewer sorts the results and formats them for display. At run time, users can change the default sorting order by clicking the column headings in the Report Viewer. Simple text sorting is used for all fields except those whose field_type is time_t, integer, or cctime. For these three fields only, Report Viewer uses numeric sorting.

Figure 63 Report Viewer Window

Saving Report Data

Clicking Save As in the Report Viewer window opens a standard file selection dialog box to prompt the user to save the results in one of the following output formats:

Saving the file is performed by the save_results.prl script in \script_tools. This script supports two switches, -html and -csv, and the header, followed by semicolon-separated data rows. This script also needs a pathname value for the -out option, where pathname is the value that the Report Viewer passes from the Path Chooser.

XML output is supported directly by the Report Viewer. You can reimplement the .CSV and .HTML output by modifying save_result.prl. You can also define additional XSL style sheets that can be referred to in XML output. We recommend that you start with the style sheet supplied with ClearCase Reports (\script_tools\table.xsl) to create customized XSL files.