START REPORT

The START REPORT instruction initializes a report execution.

Syntax

START REPORT report-routine
  [ TO to-clause ]
  [ WITH dimension-option [,...]]

where to-clause is one of:

{ SCREEN
| PRINTER
| [FILE] filename
| PIPE program [ IN FORM MODE |  IN LINE MODE ]
| XML HANDLER sax-handler-object
| OUTPUT destination-expr [ DESTINATION { program  | filename} ]
}

where dimension-option is one of:

{ LEFT MARGIN = m-left
| RIGHT MARGIN = m-right
| TOP MARGIN = m-top
| BOTTOM MARGIN = m-bottom
| PAGE LENGTH = m-length
| TOP OF PAGE = c-top
}

report-routine is the name of the REPORT routine.
filename is a string expression specifying the file that receives report output.
program is a string expression specifying a program, a shell script, or a command line to receive report output.
destination-expr is a string expression that specifies one of: SCREEN, PRINTER, FILE, PIPE, PIPE IN LINE MODE, PIPE IN FORM MODE.
sax-handler-object is a variable referencing an om.SaxDocumentHandler instance.
m-left is the left margin in number of characters. The default is 5.
m-right is the right margin in number of characters. The default is 132.
m-top is the top margin in number of lines. The default is 3.
m-bottom is the bottom margin in number of lines. The default is 3.
m-length is the total number of lines on a report page. The default page length is 66 lines.
c-top is a string that defines the page-eject character sequence.

Usage

The START REPORT statement initializes a report. The instruction allows you to specify the report output destination and the page dimensions and margins.

START REPORT typically precedes a loop instruction such as FOR, FOREACH, or WHILE in which OUTPUT TO REPORT feeds the report routine with data. After the loop terminates, FINISH REPORT completes the processing of the output.

DEFINE file_name VARCHAR(200), page_size INTEGER
...
START REPORT myrep
  TO FILE file_name 
  WITH PAGE LENGTH = page_size

If a START REPORT statement references a report that is already running, the report is re-initialized; any output might be unpredictable.

Output specification

The TO clause can be used to specify a destination for output. If you omit the TO clause, the Genero runtime system sends report output to the destination specified in the report routine definition. If the report routine does not define an OUTPUT clause, the report output is sent by default to the report viewer when in GUI mode, or to the screen when in TUI mode.

Report output can be specified dynamically as follows:

The TO FILE option can specify the filename as a character variable that is assigned at runtime.
The TO PIPE option can specify the program as a character variable that is assigned at runtime.
The TO OUTPUT option can specify the report output with a string expression, described later in detail.

The SCREEN option specifies that output is to the report window. The way the report is displayed to the end user depends on whether you are in TUI mode or GUI mode. In TUI mode, the report output displays to the terminal screen. In GUI mode, the report output displays in a dedicated popup window called the Report Viewer.

The PRINTER option instructs the runtime system to output the report to the device or program defined by the DBPRINT environment variable.

When using the FILE option, you can specify a file name as the report destination. Output will be sent to the specified file. If the file exists, its content will be overwritten by the new report output. The FILE keyword is optional, but it's best to include it to make your code more readable.

The PIPE option defines a program, shell script, or command line to which the report output must be sent, using the standard input channel. When using the TUI mode, you can use the IN [LINE|FORM] MODE option to specify whether the program is in line mode or in formatted mode when report output is sent to a pipe.

The TO OUTPUT option allows you to specify one of the output options dynamically at runtime. The character string expression must be one of: "SCREEN", "PRINTER", "FILE", "PIPE", "PIPE IN LINE MODE", " PIPE IN FORM MODE". If the expression specifies "FILE" or "PIPE", you can also specify a filename or program in a character variable following the DESTINATION keyword.

The XML HANDLER option indicates that the report output will be generated as XML and redirected to a SAX-document handler. When using XML output, the report result can be shown in the Genero Report Engine installed on the front-end workstation. See XML output for more details.

Page dimensions specification

The WITH clause defines the dimensions of each report page and the left, top, right and bottom margins. The values corresponding to a margin and page length must be valid integer expressions. The margins can be defined in any order, but a comma "," is required to separate two page dimensions options.

The LEFT MARGIN clause defines the number of blank spaces to include at the start of each new line of output. The default is 5.
The RIGHT MARGIN clause defines the total number of characters in each line of output, including the left margin. If you omit this but specify FORMAT EVERY ROW, the default is 132.
The TOP MARGIN clause specifies how many blank lines appear above the first line of text on each page of output. The default is 3.
The BOTTOM MARGIN clause specifies how many blank lines follow the last line of output on each page. The default is 3.
The PAGE LENGTH clause specifies the total number of lines on each page, including data, the margins, and any page headers or page trailers from the FORMAT section. The default page length is 66 lines.

In addition to the page dimension options, the TOP OF PAGE clause can specify a page-eject sequence for a printer. On some systems, specifying this value can reduce the time required for a large report to produce output, because SKIP TO TOP OF PAGE can substitute this value for multiple line feeds.