7.13 Using Grace

As mentioned in the Introduction, grace(C-1) provides a convenient way of running C/Base reports and channeling output to the screen or printer. If output is displayed on the screen, grace handles wide report viewing and paging of output. Within toolkit, when a reportfile is run by selecting the menu choice D3 - Test Report Execution, grace is executed to run the report. Grace may be invoked by issuing it as a direct command. The syntax of this command is:

c:\> grace [-atw] [#copies] rptfile

The rptfile can represent several reportfile types or specify that standard input is to be used for output. When using standard input for reporting, rptfile is specified as -.

Rptfile most commonly represents either the pathname for a reportfile or the name of a logical reportfile. If rptfile is the pathname to a file, this file may contain a report description in either a visual format, text format containing Report Writer language code (created either with a text editor or by the preport command), or rptfile can be in a compiled format (the output from crw(C-1).

If rptfile is the name of a logical report, the reportfile catalog contains information regarding the reportfile's compiling status. If the logical report has the precompile status field set to yes, a compiled reportfile is maintained. The compiled reportfile pathname is formed by appending .rw to the pathname of the logical reportfile. If a compiled reportfile is being maintained, the reportfile is compiled if it has been changed since it was last compiled, or if the compiled reportfile does not exist. If the precompile status field is set to no, grace creates a temporary file for the compiled version of the report. The temporary file is interpreted by wtr(C-1) and then removed.

When a reportfile is a visual report, it is first converted by preport(C-1) into Report Writer code and written into a temporary file. This temporary file is then compiled by crw(C-1) into a form interpretable by wtr(C-1). Wtr is invoked on this compiled version of the reportfile to run the report.

The following flags apply to grace.

-a Forces a parameter form to be displayed that requests whether output from grace is to be directed to a printer.

-t Forces the output of grace to be sent to the screen.

-w Causes grace to wait for the interpreter to finish writing the report output. If the output is being sent to the printer and the -w flag is omitted, a separate process is created to run the report.

#copies Represents a number which indicates how many copies of the report output are to be printed on the system printer. For more information on grace, review the manual page for grace(C-1) in Chapter 12, C/Base Commands.

The crw program is used to compile text reportfiles and will detect syntax errors which may be present within the reportfile. Since creating visual reports is an interactive process that carefully verifies its input (e.g., file names, field names, field types, etc.) as it is entered, running a separate 'compile' process on a visual report (such as crw) for the sake of 'error-checking' would seem to be both redundant and unnecessary. Because it may not be used directly on visual reportfiles, further references to crw will not be made in this chapter. Rather, its usage and syntax are covered in other chapters within the C/Base manuals. At this point it is sufficient to state that grace will examine the file named in the rptfile argument to perform the processing necessary to print the report. (It will not, however, attempt to correct errors which occur in the compilation process due to faulty syntax in a reportfile).