C.5 Troubleshooting

There are two primary areas that you may need to troubleshoot:

• Errors in the interface specification

• Coding high-level languages other than ccperl

Errors in the Interface Specification

These are the common errors you may make when coding the interface specification for your report procedure:

• The interface syntax used in your program does not conform to the interface specification.

• Invalid parameter names are used for the parameter specification.

• The rightclick specification calls a routine that does not exist in \right_click.

• The print statements to STDOUT are in a different order from that defined by the fields specification.

You can identify errors in the interface specification easily by using the testing script, ifaces.prl. This script checks customized report procedures that have been written in ccperl. It is available at clearcase.rational.com/contrib/ T0046/T0046.zip.

To start the testing script, use a command of this form:

ccperl ifaces.prl <path-to-script-or-directory-tree>

We recommend that you test your report procedures before checking them in to the shared directory tree that you have configured.

If you do not run the testing script before using your report in Report Builder and a parsing error occurs in processing the interface specification, the new report does not appear in the list of reports in the reports pane. There is no feedback; you see the report desciption in the reports pane or you see nothing. If you don't see a description, the parsing error is serious. If you do see a description, the interface specification is somewhat correct, but you may still be using an invalid parameter, referencing a nonexistent right-click routine, or sending output in the wrong order to STDOUT.

The Report Builder does not check for valid parameters. For example, consider the interface specification for a new report procedure, my_custom_report.prl, with the following interface specification:

description : "This test report asks for a three known parameters and two unknown parameters"

id : 2500

parameters : LOOKIN UNKNOWN_1 STREAMS FOO PROJECT

rightclick :

fields : "field 1"(string)

The second and fourth parameters of this interface specification are invalid. At run time, the description for this report appears in the Report Builder reports pane, but the second and fourth parameters are displayed as blank lines in the parameter pane (Figure 64 ).

Figure 64 Report Builder Window with Invalid Parameters

However, the testing script detects these errors because these parameter names are not supplied with ClearCase Reports (see Table 6):

my_custom_report.prl:

desc: this test report asks for a three known parameter and two unknown parameters

id: 2500

parm: LOOKIN

***********************

ERROR: illegal parameter: UNKNOWN_1

***********************

continue? (y/n) > y

UNKNOWN_1 STREAMS

***********************

ERROR: illegal parameter: FOOBAR

***********************

continue? (y/n) > y