Writing report scripts for issues

By making simple edits to the Reports file in the <issue group>/Tables directory of the database, it is possible to define a set of report scripts which can be run directly from the menu bar of the issues program. The file syntax is quite straight forward. Each line of the file contains at least two tab separated fields. The first is the label which will appear on the menu bar, and the second is the script which will be run. An optional third field controls how the issues program will call out to the report script, as defined below. A line consisting only of the tag SEPARATOR will cause a visual separator to appear on the pull-down menu.

To invoke a report script, the user first uses the filter and sort panel to arrive at the collection of issues of interest. Once the list is filtered, the user must highlight the issues of interest. One method is to use the Select all issues option from the menu mouse button. The report is run against only the issues selected, and will be passed in the order displayed (not the order in which they were selected by the mouse).

The standard output of the report script is captured and displayed in a text panel upon completion. The user has the option of reviewing, dismissing, printing, or saving it to a file. Note that if the file does not produce any output, then the program will not pop up a text panel.

For historical reasons, the issues program supports two mechanisms for calling out to attached report scripts, the batch method and the serial method.

The batch method

This is the preferred method for writing and calling out to report scripts. To utilize it, the related line in the Reports file must have a third tab separated field which contains the string "name", as shown in the example below.

Priority Matrix  rz_issue_tally  name

When invoked, the script will be passed only two arguments. The first argument will be the name of a temporary file which contains a list of all the selected issues. The issue numbers will each be on their own line. The second argument will be the process id of the calling issues program. This will match the environment variable RAZOR_PID, which is also available.

It is expected that the report script will cycle through the issues indicated by the file ($1), gather information and send it to its standard output.

Properly written, a report script can also be invoked directly from the command line. The top section of the rz_issue_tally script in $RAZOR_HOME/scripts has an example of how this can be accomplished. It examines the arguments supplied on the command line and decides where to get the list of files. If there are no arguments, it works off all the issues in the database. If the second argument equals the value of RAZOR_PID, then it works off the file mentioned in the first argument. Failing either of those tests, it simply accepts all the arguments on the command line as the list of issues of interest.

if [ "$1" = "" ] ; then
    LIST=`ls`
elif [ $# = "2" -a "$2" = "$RAZOR_PID" ] ; then
    LIST=`cat $1`
else
    LIST=$*
fi

The serial method

The serial method for invoking report scripts is supported mainly for historical reasons.

To use the serial approach, there should be only 2 fields on the line in the Reports file; the 3rd "name" field is not used. In this situation, the script will be called once for every file identified from the main list of issues.

The script will be given 4 arguments on its command line for each invocation. The first is the issue number itself. The second field is the archive version number of the most recent form of the issue in the database. The third argument is the process id of the calling issues program.

The fourth argument is a flag indicating where in the sequence of issues this invocation is. For the first call in a series of selected issues, the fourth argument is RZ_START. For the last call, the argument is set to RZ_END. If there was only one issue selected, then the flag is set to RZ_START_END. All intermediate calls have the fourth argument set to an empty string.

Prior to each call to the script, a read only copy of the full issue is extracted from the database and put into the RAZOR_TMP directory. Its filename will be the concatenation of the issue number, a number sign ("#"), and the process id passed in as the third argument (e.g. $RAZOR_TMP/I...-500#16231).

As with the batch method, all output from the script is captured, but this time it is gathered over the series of invocations. These are then formed into a single long message which is displayed in a text panel upon completion of the whole event.

TIP: During the processing of issues in the serial method, a small notice will appear on the display, offering a count down of the issues as they are passed along to the report script. Dismissing this window will cause the issues program to abbreviate the list and terminate the report process.

Automatic printing of reports

Normally, report output is printed by selecting the Print button from the report output window. However, it is possible to force automatic printing and bypass display of the output by specifying the "print" option in the Reports file. This typically would be combined with the "name" option as shown in the sample below.

Summarize issuerz_issue_summarizename, print

Any reports that are configured with the print option will appear in the Reports pulldown menu with an asterisk (*) appended to the report label signifying that auto-printing is enabled.