Report generation
Overview
Model 204 provides several report generation capabilities, including:
- Sorting output
- Formatting output
- Directing output
Sorted output
User Language provides the following features that allow output to be produced in sorted order:
- IN ORDER clause — This clause can be specified on FOR EACH RECORD and FOR EACH VALUE statements in order to produce output in sorted order. See Processing records in order for a discussion of the IN ORDER clause for the FOR EACH RECORD statement. See FOR EACH VALUE statement for a discussion of the IN ORDER clause for the FOR EACH VALUE statement.
- SORT RECORDS and SORT RECORD KEYS statements — These statements can be used when the IN ORDER clause cannot be used to provide the order you desire. Sorting includes a detailed discussion of sort statements.
Formatting capabilities
Model 204 provides User Language statements, commands, and parameters to allow you to control the following report formatting elements:
- Headings or comments
- Spacing on a line (skipping spaces)
- Assignment of columns for output
- Printing record numbers and record IDs
- Page headers and trailers
- Pausing execution of request output
The PRINT statement
You use variations of the PRINT statement to perform most of the formatting capabilities described above. The PRINT statement is described in more detail throughout this topic.
For additional information about formatting
Basic SOUL statements and commands provides a discussion of these statements, which control report formatting:
- FIND AND PRINT COUNT
- PRINT ALL INFORMATION
- PRINT fieldname
- SKIP n LINES
Example of formatting output
The complete syntax of the PRINT statement provides several options that permit you to design quite complex formats for reports. Some of these are illustrated in this request:
BEGIN DRIVERS: FIND ALL RECORDS FOR WHICH RECTYPE = DRIVER STATE = MASSACHUSETTS END FIND PRINT ''MASSACHUSETTS DRIVERS' AT COLUMN 12 SKIP 1 LINE PRINT 'POLICY NO' WITH 'NAME' AT COLUMN 15 - WITH 'DRIVER ID' TO COLUMN 45 SKIP 1 LINE FOR EACH RECORD IN DRIVERS PRINT POLICY NO WITH FULLNAME AT COLUMN 15 - WITH DRIVER ID TO COLUMN 45 END FOR END
The output from this request appears as:
MASSACHUSETTS DRIVERS POLICY NO NAME DRIVER ID 100095 ALTON, BARBARA W 100223 100095 ALTON, CARRIE Y 100225 100095 ALTON, CHARLES Z 100226 100095 ALTON, THOMAS V 100222 100095 ALTON, TIMOTHY X 100224 100096 ANCH, EDITH X 100228
Directed output
The features described at the end of this page allow you to direct output from a User Language request.
| Use Model 204 feature... | To direct output to... |
|---|---|
| AUDIT statement | Journal or audit trail. |
| USE command | Devices other than the user's terminal. |
| WRITE IMAGE statement | Sequential file, a terminal, or a a Host Language application program. See WRITE IMAGE statement for more information. |
PRINT statement
The PRINT statement controls most report formatting.
This section provides an overview of the PRINT statement. Specific uses of the PRINT statement are described in later sections. See also:
- Find And Print Count statement
- Print All Information (or PAI) statement.
Syntax
The basic form of the PRINT statement is provided here, followed by a discussion of the statements used in the example and several additional output features.
PRINT [[fieldname | %variable | 'string' | VALUE IN label | COUNT IN label] [AT [COLUMN] n] [AND | TAB | WITH] ... [TO [COLUMN] n] [AND | TAB | WITH] ...] ... [...]
List of terms
A list of terms specifying what is to be printed and the placement of the printing on the line follows the statement name PRINT. Terms can be specified in any order.
Each PRINT statement normally specifies one line of output. Alternatively, see Continuing the PRINT statement.
Use of keyword FIELD
The keyword FIELD is required in order to print a field whose name begins with the word IMAGE, MENU, or SCREEN if the field name appears at the beginning of the PRINT statement. For example:
PRINT FIELD SCREEN SIZE
prints the field named SCREEN SIZE.
The keyword FIELD is recognized only when it is the first word after PRINT. FIELD should not be used with field names that appear elsewhere in a PRINT statement.
TO and AT column options
When using the PRINT statement in conjunction with the AT or TO column options, you cannot specify negative numbers or numbers greater than 32767 for the column.
Procedures containing PRINT statements with negative numbers or numbers greater than 32767 fails at compile time with this counting error message:
M204.0263: AT/TO MUST BE BETWEEN 1 AND 32767
Continuing the PRINT statement
Normally, each PRINT statement formats one line of output. However, if a PRINT statement ends with an ellipsis (...), the next PRINT statement continues on the same output line. In this way an unlimited number of PRINT statements can apply to a single line of output.
The first PRINT statement that does not end with an ellipsis, or SKIP or NEW PAGE statement, ends the output line. The END statement ends the output line if the last PRINT statement ends with an ellipsis.
For example, the following request prints each vehicle identification number for blue Mustangs, with three spaces between each number:
BEGIN FIND.RECS: FIND ALL RECORDS FOR WHICH MODEL = MUSTANG AND COLOR = BLUE END FIND FOR EACH RECORD IN FIND.RECS PRINT VIN AND AND AND ... END FOR END
The output looks like:
FOR2100547 FOR2101155
Formatting/printing headers or comments
Use the PRINT statement
To print out headings or comments, the PRINT statement is used with the desired phrase, which is enclosed in single quotation marks.
For example:
PRINT 'FIRST REPORT'
causes Model 204 to print:
FIRST REPORT
Use of quotation marks
The pair of single quotation marks delineates the quoted string. Any character that appears within the quotation marks (including space) is considered part of the text to be printed. A pair of consecutive single quotation marks ('') embedded in quoted text reproduces a single quotation mark in the output. Thus:
PRINT 'WHY JOHNNY CAN''T READ'
yields:
WHY JOHNNY CAN'T READ
Quoted phrases are stored and utilized by Model 204 with quotation marks dropped. Quotation marks provides additional information about the use of quotation marks.
Controlling spacing on an output line
The spacing of printed output can be controlled by using the connectives AND, WITH, and TAB with the PRINT statement, as described below.
Connectives required for multiple outputs on one line
When several pieces of output are to be printed on a single line, a connective or placement phrase must follow each field name except the last. The following statements are legal:
PRINT CITY WITH ', ' WITH STATE PRINT CITY AND STATE
but the statements below are not:
PRINT CITY STATE PRINT '('TOTAL PREMIUM')'
Skipping one space (AND)
When AND is used, one space is skipped before further printing. For example, if Model 204 has retrieved a record with the field:
TOTAL PREMIUM = 15,000
then:
PRINT 'PREMIUM IS $' TOTAL PREMIUM AND 'PER YEAR'
yields the printout:
PREMIUM IS $15,000 PER YEAR
This statement:
PRINT AND AND COUNT IN CT
skips two spaces before printing the count.
Skipping no spaces (WITH)
When WITH is used, no spaces are skipped. For example, the statement:
PRINT '($' WITH TOTAL PREMIUM WITH ')'
yields:
($15,000)
WITH more efficient than AND
WITH is more efficient than AND. When a quoted string is used, WITH can replace AND by including an extra space in the string as illustrated below:
PRINT 'PREMIUM IS $' TOTAL PREMIUM AND 'PER YEAR'
can be changed to:
PRINT 'PREMIUM IS $' TOTAL PREMIUM WITH ' PER YEAR'
Using tab stops
When TAB is used, further printing begins at the next tab stop. Tab stops normally are set to 1, 11, 21, and so on. For example, the statement:
PRINT COUNT IN CT TAB PREMIUM TAB TAB MODEL
would result in output such as:
8 392 PINTO
The standard spacing between successive tab stops can be changed by resetting the TABSP parameter.
When a TAB is specified, at least two spaces are left after the last character printed. If the last character printed ends at the next tab stop or there is only one space remaining before the next tab stop, Model 204 automatically inserts an extra TAB.
Specifying columns for output
The phrases AT COLUMN n and TO COLUMN n, used with the PRINT statement, provide for the left- or right-justification of output.
- AT COLUMN n means that printing begins in column n.
- TO COLUMN n specifies that output is positioned to end in column n.
Note: A placement phrase applies only to the single piece of output that precedes it in the PRINT statement and not to the entire output line.
Example
This request illustrates the use of placement phrases:
BEGIN FIND.RECS: FIND ALL RECORDS FOR WHICH RECTYPE = DRIVER INCIDENT IS PRESENT END FIND FOR EACH RECORD IN FIND.RECS PRINT 'INCIDENT TYPE:' - WITH INCIDENT AT COLUMN 30 PRINT 'DATE OF INCIDENT:' - WITH INCIDENT DATE AT COLUMN 30 PRINT 'POLICYHOLDER:' - WITH FULLNAME AT COLUMN 30 SKIP 1 LINE END FOR END
These statements produce output such as:
INCIDENT TYPE: T2 DATE OF INCIDENT: 19900222 POLICYHOLDER: ABBOTT, FRANKLIN G
Using AT COLUMN n and TO COLUMN n together
AT COLUMN n can be immediately followed by TO COLUMN n. For example:
PRINT FULLNAME AT COLUMN 30 TO COLUMN 40
If the value of FULLNAME in this example is less than 11 characters long, trailing blanks are added. If the value is more than 11 characters, only the first 11 are printed. See the next section for more information about exceptional conditions relating to the placement of output.
Placement of output: Exceptional conditions
These conditions can affect the placement of output:
- Line too long
- Overlapping TAB
- Overlapping TO COLUMN n
- Overlapping placement
Impact of the OUTCCC parameter setting
The rules for handling the four exceptional conditions described below do not apply if the user parameter OUTCCC is set to 0. This causes output to be truncated to one line.
Line too long
When output does not fit on a designated line, Model 204 prints a hyphen at the end of the line and continues printing in column 1 on the next line.
Overlapping TAB
If a TAB spaces beyond the end of a line, the output is continued beginning at the first tab on the next line. For example, if the end of the line is column 130 (the output device line width is 130 columns) and the last tab occurs at column 121, the statement:
PRINT 'AGE' AT COLUMN 120 TAB AGE
prints AGE in columns 120-122, places a hyphen in column 130, and continues output on the next line beginning at the first tab, as follows:
AGE - 54
Overlapping TO COLUMN n
If output positioned by the phrase TO COLUMN n is too large to fit on one line and still end at the specified column, it is printed on two lines so as to end on the second line at the specified column. Model 204 prints a hyphen at the end of the first line.
Therefore, the result of:
PRINT 'MASSACHUSETTS' TO COLUMN 10
is:
MAS - SACHUSETTS
Overlapping placement
If the column number given in an AT COLUMN n or TO COLUMN n phrase is less than a previously specified column number, output is placed on the next line. So the result of:
PRINT NAME AT COLUMN 20 AND AGE AT COLUMN 1
is:
JOSEPH MARTIN - 29
Similarly, if the value to be printed overlays the next AT COLUMN n or TO COLUMN n, output is printed on the next line. If the PRINT is in this form:
PRINT NAME AND ADDRESS AT COLUMN 20
and the name to be printed consists of more than 19 characters, the address prints in column 20 on the next line:
COMPUTER CORPORATION OF AMERICA 500 OLD CONNECTICUT PATH
Printing the record number and record ID
Printing the record number
This statement prints the internal Model 204 record number of the current record:
PRINT *RECORD
Note: The internal record number can also be obtained by using the $CURREC function; see $CURREC.
Printing the record ID
For a sorted file, if the current record is an overflow record, this statement prints the ID of the preferred master area for the record:
PRINT *ID
If the current record is a master record, the character string "MASTER RECORD" is printed. If the current record is not in a sorted file, the string "UNSORTED FILE" is printed.
For more information on sorted files and sorting, see Sorting retrieved values, Sorting, and Sorted files.
Formatting page headers and trailers
Headers and trailers
Model 204 provides the capability to add header and trailer lines to each page of a report. The headers and trailers include:
| Headers or trailers | Which by default is... |
|---|---|
| Header 0 | Automatically generated at the top of each page by Model 204. It includes the date, time, and page number. |
| User defined header lines | Up to four header lines that can be printed out on the lines immediately below the header 0 line. |
| User defined trailer lines | Up to five trailer lines that can be printed out on lines at the bottom of the page. |
Header 0
Below is an example of a header 0:
90.218 AUG 06 09.05.00 PAGE 63
At the left is the Julian date: year and day of year. This is followed by the month and day of month and the time, recorded on a 24-hour clock in hours, minutes, and seconds. The page number, incremented automatically, is at the right.
Setting headers and trailers
Use the SET HEADER m statement to define (format) each header line you want; use the SET TRAILER m statement to define each trailer.
Whenever a new page of a report is started, all headers and trailers that are set are printed at the top and bottom of the page, respectively.
After completion of a request, the headers and trailers that were set in that request are no longer printed.
The number of SET HEADER and SET TRAILER statements allowed in one request is unlimited.
Suppressing the printing of headers and trailers
Setting the user parameter HDRCTL to 1 suppresses the printing of Header 0.
The RESET HEADER m statement suppresses the printing of Header m. For example, if header lines 2, 3, and 4 are set and the statement RESET HEADER 3 is issued, a line is effectively skipped between headers 2 and 4 when they are printed.
When RESET HEADER is used, the header becomes inactive. For example, if the user can specify as many as 5 header lines and header 5 is not specified, a blank line is not reserved for headers 4 and 5 if the statement RESET HEADER 4 is issued (printing begins immediately after header 3).
Similarly, the RESET TRAILER m statement suppresses the printing of trailer m.
You are allowed an unlimited number of RESET HEADER and RESET TRAILER statements.
SET HEADER statement
The SET HEADER m statement sets up a line of header information to be printed at the top of a page on the mth line after the system-generated page header (after Header 0).
Number of header lines
The number of header lines that you can set is controlled by the MAXHDR parameter. (The default is 5.)
Purpose
The header line is formatted but not printed by the SET HEADER statement. Whenever Model 204 starts a new page of output, any header lines that are already set are printed. The header feature is designed to label output from the request in which the SET HEADER statement is issued.
Syntax
SET HEADER m [[fieldname | %variable | 'string' | VALUE IN label | COUNT IN label [AT [COLUMN] n] [AND | TAB| WITH] ... [TO [COLUMN] n] [AND | TAB | WITH] ...] ... [...]
Any information that can be printed can be formatted on a header line. Placement of the header can be controlled by the phrases AT COLUMN n or TO COLUMN n. The connectives AND, WITH, and TAB can be used.
If a SET HEADER statement ends with an ellipsis (...), the arguments of the next PRINT statement are appended to the arguments of the SET statement.
Length of header lines
A header corresponds to a single line of output, normally 132 characters. The maximum length of an output line is determined by the OUTMRL parameter. The header is truncated if the maximum length is exceeded; it does not wrap.
The HTLEN parameter should be set by the system manager or the user if a header is to be longer than 132 characters. If the line is longer than 132 characters, it is truncated when it exceeds the HTLEN parameter value. (The header does not wrap.)
Multiple header lines
Multiple header lines can be specified by repeating the SET HEADER statement that has the header number incremented. A later SET statement that has the same header number overrides a previous one. When no terms are specified following the words SET HEADER m, the mth line is effectively skipped in printing. For example, SET HEADER 2 with no text causes two lines to be skipped after header 0, provided that header 1 was not set.
Example
This request illustrates the use of headers.
BEGIN SET.HEADERS: SET HEADER 2 'POLICYHOLDERS REPORT' - AT COLUMN 10 SET HEADER 3 'SECOND QUARTER, 1990' - AT COLUMN 10 SET HEADER 5 'AUDIT DEPARTMENT' - AT COLUMN 12 NEW PAGE SET.PG.HDR: SET HEADER 3 SET HEADER 4 'NAME' AT COLUMN 3 - WITH 'POLICY NO.' AT COLUMN 29 SET HEADER 5 NEW PAGE POL.HOLDERS: FIND ALL RECORDS FOR WHICH RECTYPE = POLICYHOLDER END FIND FOR EACH RECORD IN POL.HOLDERS PRINT FULLNAME AT COLUMN 3 - WITH POLICY NO TO COLUMN 36 END FOR END
Example
The first page is headed:
90.218 AUG 06 09.05.00 PAGE 63 POLICYHOLDERS REPORT SECOND QUARTER, 1990 AUDIT DEPARTMENT
All subsequent pages have this format:
90.218 AUG 06 09.05.01 PAGE 64 POLICYHOLDERS REPORT NAME POLICY NO. ABBOTT, FRANKLIN G 100340 ABBOTT, HAZEL W 100642 ABBOTT, LILLIE P 100037 ABBOTT, SHARON M 100944 . . . . . .
Considerations
Note the following details about this request:
- The SET.HEADERS and SET.PG.HDR statements each specify a NEW PAGE, in order to generate a page break between the first and second pages. If NEW PAGE is omitted from the SET.HEADERS statements, the first page is not generated. If NEW PAGE is omitted from the SET.PG.HDR statements, the output begins on the first page.
- Header 3 is printed only on the first page. The SET.PG.HDR statements reset headers 3 and 5, overriding previous SET HEADER statements. After the first page, headers 3 and 5 are blank lines.
- The SET.PG.HDR statements set header 4, which was a blank line for the first page.
SET TRAILER statement
The SET TRAILER m statement sets up one line of trailer information to be printed at the bottom of a page. Before Model 204 begins a new page, it displays the trailers that were set up on the bottom of the current page.
Syntax
SET TRAILER m [[fieldname | %variable | 'string' | VALUE IN label | COUNT IN label [AT [COLUMN] n] [AND | TAB| WITH] ... [TO [COLUMN] n] [AND | TAB | WITH] ...] ... [...]
Number of trailer lines
The number of trailer lines that can be set by the user is controlled by the MAXTRL parameter. (The default is 5.)
Length of trailer lines
A trailer corresponds to a single line of output, normally 132 characters. Like headers, the maximum length of a trailer line is determined by the OUTMRL parameter.The trailer is truncated if the maximum length is exceeded; it does not wrap.
The HTLEN parameter should be set by the system manager or the user if a trailer is longer than 132 characters. If the line is longer than 132 characters, it is truncated when it exceeds the HTLEN parameter value. (The trailer does not wrap.)
Specifying page numbers
The $HPage and $SetP functions are particularly useful in formatting headers or trailers.
- $HPage is replaced by the current page number when the header or trailer is printed. $HPage also can be used to help replace header 0. (See $HPage.)
- $SetP sets the current page number for the output device in effect and can be used to format header 0 or fill in a value for $HPage. $SetP is not valid in a SET HEADER statement. (See $SetP.)
Interrupting request execution
PAUSE statement
The PAUSE statement causes request execution to pause and wait for the user to respond before continuing. The PAUSE statement is useful for changing and aligning forms on non-CRT devices.
The user's response depends upon the terminal being used. Refer to the Rocket Model 204 Terminal User's Guide for a detailed description of the appropriate responses for each terminal type.
Example
This request causes execution to halt temporarily after Model 204 has skipped to a new page but before it has printed the page header or the first record:
BEGIN FIND.RECS: FIND ALL RECORDS END FIND NEW PAGE PAUSE FOR EACH RECORD IN FIND.RECS PRINT ALL INFORMATION END FOR END
Use of the PAUSE n statement
Another form of the PAUSE statement, PAUSE n, is particularly useful in record locking conflicts. Refer to PAUSE statement for more information.
Directing output to a journal/audit trail
AUDIT statement
If production of a journal and/or an audit trail has been specified for the run, output can be directed to these data sets by using the AUDIT statement. The AUDIT statement is the same as the PRINT statement, substituting the keyword AUDIT for the PRINT keyword (see The PRINT statement for a description of the PRINT statement).
AUDIT ALL INFORMATION statement
The AUDIT ALL INFORMATION (or AAI) statement writes the output of entire records to the audit trail, CCAAUDIT.
The output is identical to the output from the Print All Information (or PAI) statement but each field=value pair is sent to the audit trail as a series of US lines.
The AUDIT ALL INFORMATION statement occurs in a FOR EACH RECORD or FOR RECORD NUMBER loop.
Syntax
AUDIT ALL INFORMATION
or
AAI
AUDIT output
AUDIT statement output is directed to the journal, the audit trail, or both, depending upon which is included in the run. The AUDIT statement directs the information to the journal or audit trail where it is printed with the prefix US.
If an AUDIT message is too long to fit on one line, it is continued on a second line with the prefix XX rather than US.
The Rocket Model 204 System Manager's Guide contains a complete description of the journal and audit trail.
Example
This statement tracks changes to a salary field:
. . . AUDIT $USERID WITH ' HAS CHANGED SALARY FROM ' - WITH %SALARY1 ' TO ' WITH SALARY . . .
In the previous statement, the $USERID function is used to obtain the ID of the user making the change. The statement produces the following audit trail record when it is executed:
86123110011 1 1 135 US SMITH HAS CHANGED SALARY FROM 20344 TO 45888
Using the AUDIT and PRINT statements together
If the AUDIT statement ends in an ellipsis (...), it can be added to with PRINT or SET statements. For example:
AUDIT 'BEGIN' ... PRINT '123' ... PRINT 'END'
produces US BEGIN123END in the audit trail.
If the AUDIT statement follows a normal PRINT statement that ends in an ellipsis, the PRINT line is ended by the AUDIT statement. The PRINT line ends when the AUDIT line begins.
Printing records using AUDIT
If a record is printed by means of an AUDIT statement, the lines printed by the user can be broken, and the partial lines intermixed with lines printed by another user in an online system.
This problem can be alleviated by assigning the field value to a variable (see Field name variables) and then referring to the variable in the AUDIT statement, or by using a NOTE statement and referring to it with a VALUE IN phrase in the AUDIT statement.
See Noting character strings for more information about the NOTE statement and the VALUE IN phrase.
Directing output to other devices
The USE command
The USE command directs the output produced by a request to a device other than your terminal, such as a line printer or to a device that is used as input to another program.
Under the VM operating system, a USE command can direct output to another system and can tag output for production on a particular device available on that system.
The syntax of the USE command differs depending upon the operating system under which Model 204 is running. Refer to USE command: Directing output for a detailed description of the USE command for each operating system. For information on the control language requirements associated with the command, refer to the Rocket Model 204 204 System Manager's Guide.
When output from Model 204 is being sent to an alternate device, the USE command must be specified before any commands that produce output on that alternate device are executed.
Handling lengthy reports
The USE command is particularly useful in handling requests that produce lengthy reports, and in creating sequential files from Model 204 files. If the length of a report is not known ahead of time, the END MORE statement and the MORE command permit you to issue the USE command after the number of records has been determined.
Example
If this request:
BEGIN FIND.RECS: FIND ALL RECORDS FOR WHICH SEX = M END FIND CT: COUNT RECORDS IN FIND.RECS PRINT COUNT IN CT END MORE
produces a result of 1220, the user might respond with a USE command in the following form before continuing with the request:
USE output name
where output name is a device or data set name established by the system manager.
The user then continues:
MORE FOR EACH RECORD IN FIND.RECS PRINT FULLNAME WITH DRIVER ID AT COLUMN 30 END FOR END
The final output would then be written, in the following format, to an alternate device, rather than to the user's terminal:
ABBOTT, FRANKLIN G 100816 ABBOTT, HAROLD N 102271 ABBOTT, JACK P 102273 ABRAMS, RALPH M 100138 . . . . . .
The END USE statement
If a request ends with an END USE statement, the device remains available for this user after the request has been completed, allowing output from another request can be added to the original output.
The output page number is not reset.
If the USE keyword is not specified in the END statement, the USE command applies only to the first request following the USE command. USE must be repeated before any other request whose output is to appear on the alternate device.
Note: Both keywords, MORE and USE, can be specified in conjunction with END. Both END MORE USE or END USE MORE are accepted.
Creating a sequential data set
The USE command can create a sequential data set from a Model 204 file.
Example
This request writes all of the data in a Model 204 file to the OUTFILE data set, from which it can be reloaded or used by another program:
USE OUTFILE BEGIN FIND.RECS: FIND ALL RECORDS END FIND FOR EACH RECORD IN FIND.RECS PRINT ALL INFORMATION SKIP 1 LINE END FOR END
The $BINARY, $FLOAT, $FLOATD, and $PACK functions, discussed in SOUL $functions, allow data in special representations to be written to a USE data set.