C.2 What You Can Customize in ClearCase Reports

The ClearCase programming interface enables you to customize four parts of the Report Builder user interface and two parts of the Report Viewer. You can customize by adding, changing, or removing information for the annotated areas of the Report Builder (Figure 59):

• Area 1. The name of the folders in the tree pane.

• Area 2. The directory organization displayed in the tree pane.

• Area 3. The report description.

• Area 4. The report parameters

Figure 59 Customizable Areas of Report Builder Interface

You can customize by adding, changing, or removing information for the annotated areas of the Report Viewer (Figure 60).

• Area 1. The position of a column heading can be moved, a column heading name can be added, modified, or deleted and a default sort order can be added or removed from any column heading.

• Area 2. The commands on the shortcut menu.

Figure 60 Customizable Interface for Report Viewer Window

For programming examples that demonstrate how you can make these customizations, see Report Programming Examples

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. Processing occurs in three 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 either cleartool or the ClearCase Automation Library (CAL) interface 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.

Figure 61 illustrates this processing sequence.

Figure 61 Run-Time Processing Sequence

To execute these processing steps 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, which it calls when a user clicks the associated directory folder.

• The report procedure must have a valid interface specification. If the expected format is not present, the report will not run.

• The interface specification in the report procedure must use parameters and choosers supplied by ClearCase Reports. See Parameters Supplied with 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.

Configuring Shared Report Directories

When Rational ClearCase is installed on the client, the files for ClearCase Reports are installed in ccase-home-dir\reports. Before you modify the contents of this directory, create a copy of it in a shared location. You can then delete or rename folders and add or modify report procedures.

To create the copy, do one of the following:

• Copy the files to a new directory.

• Place a copy of the files under source control and create a ClearCase view to serve as the shared location.

We recommend that you place the copy of the report procedures under source control.

You must remove the .dll and .exe files from the customization directory. The subdirectories for \scripts,\script_tools, and \scripts_rightclick must be present. The \scripts directory becomes the root node Reports in the Report Builder tree pane; you can modify this directory tree. We recommend that you do not delete any files that are in \script_tools and \scripts_rightclick; you may add your own, of course.

The help file used by the reports cannot be modified and is not included in the \reports directory. The help file for ClearCase Reports is located in ccase-home-dir\bin\cc_reports.hlp.

Adding Report Procedures to Source Control

To place a copy of ccase-home-dir\reports under source control:

1. Copy all files to a temporary directory.

2. In the temporary directory, enter a command of this form:

clearexport_ffile -o name-of-data-file

3. In the \reports directory in an existing VOB, enter a command of this form:

clearimport -verbose -directory \reports\name-of-data-file

4. Create a dynamic or snapshot view for the ClearCase reports data that is now under source control .

Setting the Report Builder to the Customized Directory

After you have copied the installed files for ClearCase Reports from ccase-home-dir\reports to a shared directory location, you can set Report Builder to use this location:

1. In the Report Builder window, click Report > Set Scripts Location to open the Configure Reports Directory dialog box.

2. In the dialog box, do one of the following:

• Type the directory path for the customized directory in the text box.

• Click ... to open the Browse for scripts location dialog box to select a directory location.

NOTE: After changing the ClearCase Reports user interface, you must restart Report Builder to activate the changes.

Default Directory Structure for ClearCase Reports

All files for ClearCase Reports are stored in ccase-home-dir\reports. This is the directory structure:

reports\
ccreportbuilder.exe
ccreportviewer.exe
cctypechooser.dll
ccpathchooser.dll
scripts\
ClearCase_Tools\
Elements\
Attributes\
Branches\
Labels\
Triggers\
UCM_Projects\
UCM_Streams\
Views\
VOBs\
scripts_rightclick\
script_tools\

Populating the Report Builder Tree Pane

As Figure 62 shows, the Report Builder window contains three panes: the left pane is the tree pane, the top-right pane is the reports pane, and the bottom-right pane is the parameter pane. When the user clicks any folder in the tree pane, the Report Builder runs the associated report procedures from the command line. The -i option in the command line enables the Report Builder to use a discovery algorithm to collect the user interface information for Report Builder.

Figure 62 Report Builder User Interface

The Report Builder "walks" through the \scripts subdirectory. Directories in the tree appear as folders in the tree pane. Any files whose extensions match those listed below are listed in the reports pane.

All other files are ignored. The file name extension of report procedures supplied with ClearCase Reports is .prl, which the Report Builder associates with ccperl.exe.

At run time, the Report Builder displays all folder names, substituting a space for the underscore and dropping the file name extension. There is one exception: the root directory is always named Reports. This convention cannot be changed.

For example, for this on-disk directory tree

scripts\
Admin_Reports
view_aging.prl
all_views.prl
UCM_Reports\
lagging_streams.prl
completed_acts.prl

the Report Builder displays text in the tree pane as

\Reports
Admin Reports\
UCM Reports\