TOC PREV NEXT INDEX DOC LIST MASTER INDEX




Tasks > Run Report... (Summit/TM)

The Tasks > Run Report command provides a convenient interface for running various Summit/TM report generation scripts. As described in detail below, this command is best suited for running scripts with a special naming convention and internal format. Some of the sample scripts, included with the product, produce such reports as:

The end result of successfully running a report script is typically either a report output file (which is "visited" in the user's default text editor) or a listing of a group of tasks (which is displayed in a summary window). The actual outcome is determined by the script executed.

These scripts can be customized for particular applications and new ones can be easily added. Such customized scripts should follow the conventions established by the provided example scripts. In particular, they need to follow the same argument passing convention.

When you choose this command, the Task Reports dialog box appears. A report script is not executed until either the OK or Apply button is pressed or a particular report selection is double clicked. When a script is executed, it runs in a separate process so that you can still work on something else while the report is being generated.

Any objects selected within the window from which this dialog is invoked are placed into the Actual Arguments for Report Script field.

If changes are made to a report script file after this dialog has been started and those changes are intended to affect the information displayed by the dialog, then the Reset button must be pressed in order for the dialog information to be updated

Run Report Dialog Box Fields:

Selected Report Field

The pathname of an existing report script to be executed. It is most easily set by clicking on one of the report selections in the Reports To Choose From list box. Alternatively, this field can be entered directly or via its associated search icons.

Visit Report Script Button

This button causes the report script file identified by the Selected Report field to be viewed in a text editor. This is useful for examining or modifying a script.

Reports to Choose From List Box

This list box displays the known report generation scripts that are available to run along with an informative title. Scripts other than the ones listed can also be executed, but they must be manually selected within the Selected Report field. The reports listed are determined by searching for files with a .taskreport suffix within the following directories:

The report scripts from a particular directory are listed only once, where ever the directory first appears in the above search order.

Selecting a report from this list will cause the Selected Report, Argument List Usage for Report Script, and Report Output File fields to be filled in with information derived from the report script file. If a report from this list is double clicked, then the report script will be immediately executed with no opportunity to specify any additional arguments.

The title displayed for a given report is derived from information contained in the report's script file. A source line from this file with the following prefix will be used as the title:

For example:

Argument List Usage for Report Script Field

This field usually displays information about what kinds of arguments can or must be passed to the selected report script. It can also contain any other information that might be helpful to the user in understanding how to use the report script or what the report actually generates. The information in this field cannot be changed. It is derived directly from the script file itself. Any script source lines that begin with the following string are placed in this field:

Multiple source lines of this form can be placed in a script file, but they must be adjacent to one another. For example:

Actual Arguments for Report Script Field

The actual arguments to be passed to the report script can be specified in this field. Since they are passed to the script as command line arguments, special characters, such as spaces must be explicitly quoted. Although multiple lines of arguments can be entered, the lines are combined into one (space separated) before being passed to the report script.

Note that the full pathnames of any objects that are selected in the window from which this dialog is invoked are initially placed in this field. Thus, selected tasks, for example, can be conveniently passed to a given report script.

Report Output File Field

This field specifies the file into which the output of the report is saved. The user can accept the default value displayed or replace it with a different file name. Whether it is used at all or how it is used is determined by the report selected. A report script advertises the fact that it will produce a report output file by including a source line with this prefix:

At most one such source line of this form should appear in a script file. For example:

The example report scripts provided with the product use the following convention for report output file names:

The special characters, %y_%m_%d, are actually replaced by the script with the current year, month and day.

Customized report scripts can be written using their own report output file naming conventions.

Report scripts, that successfully generate a report output file, typically "visit" the file in the user's default text editor, at the conclusion of the report's execution.

Summit/TM is described in the Summit/TM User's Guide and the Summit/TM Customization Guide.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS