HEADING statement

Syntax

HEADING [ON print.channel] heading
HEADINGE [ON print.channel] heading
HEADINGN [ON print.channel] heading

Description

Use the HEADING statement to specify the text and format of the heading to print at the top of each page of output.

The ON clause specifies the logical print channel to use for output. print.channel is an expression that evaluates to a number from -1 through 255. If you do not use the ON clause, logical print channel 0 is used, which prints to the user's terminal if PRINTER OFF is set (see the PRINTER statement). Logical print channel -1 prints the data on the screen, regardless of whether a PRINTER ON statement has been executed.

heading is an expression that evaluates to the heading text and the control characters that specify the heading's format. You can use the following format control characters, enclosed in single quotation marks, in the heading expression:

C[n]: Prints heading line centered in a field of n blanks. If n is not specified, centers the line on the page.
D: Prints current date formatted as dd mmm yyyy.
T: Prints current time and date formatted as dd mmm yyyy hh:mm:ss. Time is in 12-hour format with "am" or "pm" appended.
\: Prints current time and date formatted as dd mmm yyyy hh:mm:ss. Time is in 12-hour format with "am" or "pm" appended. Do not put the backslash inside single quotation marks.
G: Inserts gaps to format headings.
I: Resets page number, time, and date for PIOPEN flavor only.
Q: Allows the use of the ] ^ and \ characters.
R[n]: Inserts the record ID left-justified in a field of n blanks.
L: Starts a new line.
]: Starts a new line. Do not put the right bracket inside single quotation marks.
N: Suppresses automatic paging.
P[n]: Prints current page number right-justified in a field of n blanks. The default value for n is 4.
S: Left-justified, inserted page number.
^: Prints current page number right-justified in a field of n blanks. The default value for n is 4. Do not put the caret inside single quotation marks.

Two single quotation marks ( ' ' ) print one single quotation mark in heading text.

When the program is executed, the format control characters produce the specified results. You can specify multiple options in a single set of quotation marks.

If either print.channel or heading evaluates to the null value, the HEADING statement fails and the program terminates with a run-time error message.

Pagination begins with page 1 and increments automatically on generation of each new page or upon encountering the PAGE statement.

Output to a terminal or printer is paged automatically. Use the N option in either a HEADING or a FOOTING statement to turn off automatic paging.

HEADINGE and HEADINGN Statements

The HEADINGE statement is the same as the HEADING statement with the $OPTIONS HEADER.EJECT selected. HEADINGE causes a page eject with the HEADING statement. Page eject is the default for INFORMATION flavor accounts.

The HEADINGN statement is the same as the HEADING statement with the $OPTIONS -HEADER.EJECT selected. HEADINGN suppresses a page eject with the HEADING statement. The page eject is suppressed in IDEAL, PICK, REALITY, and IN2 flavor accounts.

Using ] ^ and \ in Headings

The characters ] ^ and \ are control characters in headings and footings. To use these characters as normal characters, you must use the Q option and enclose the control character in double or single quotation marks. You only need to specify Q once in any heading or footing, but it must appear before any occurrence of the characters ] ^ and \.

Formatting the Heading Text

The control character G (for gap) can be used to add blanks to text in headings to bring the width of a line up to device width. If G is specified once in a line, blanks are added to that part of the line to bring the line up to the device width. If G is specified at more than one point in a line, the space characters are distributed as evenly as possible to those points. See the following examples, in which the vertical bars represent the left and right margins:

Specification: Result
"Hello there": |Hello there |
"'G'Hello there": | Hello there|
"'G'Hello there'G'": | Hello there |
"Hello'G'there": |Hello there|
"'G'Hello'G'there'G'": | Hello there |

The minimum gap size is 0 blanks. If a line is wider than the device width even when all the gaps are 0, the line wraps, and all gaps remain 0.

If NLS is enabled, HEADING calculates gaps using varying display positions rather than character lengths.

Left-Justified Inserted Page Number

The control character S (for sequence number) is left-justified at the point where the S appears in the line. Only one character space is reserved for the number. If the number of digits exceeds 1, any text to the right is shifted right by the number of extra characters required. For example, the statement:

HEADING "This is page 'S' of 100000"

results in headings such as:

This is page 3 of 100000
This is page 333 of 100000
This is page 3333 of 100000

INFORMATION Flavor

Page Number Field

In an INFORMATION flavor account the default width of the page number field is the length of the page number. Use the n argument to P to set the field width of the page number. You can also include multiple P characters to specify the width of the page field, or you can include blanks in the text that immediately precedes a P option. For example, 'PPP' prints the page number right-justified in a field of three blanks.

Note: In all other flavors, 'PPP' prints three identical page numbers, each in the default field of four.

Date Format

In an INFORMATION flavor account the default date format is mm-dd-yy, and the default time format is 24-hour style.

In PICK, IN2, REALITY, and IDEAL flavor accounts, use the HEADER.DATE option of the $OPTIONS statement to cause HEADING, FOOTING statement, and PAGE statements to behave as they do in INFORMATION flavor accounts.

PIOPEN Flavor

Right-Justified Overwriting Page Number

The control character P (for page) is right-justified at the point at which the P appears in the line. Only one character space is reserved for the number. If the number of digits exceeds 1, literal characters to the left of the initial position are overwritten. Normally you must enter a number of blanks to the left of the P to allow for the maximum page number to appear without overwriting other literal characters. For example, the statement:

HEADING "This is page 'P' of 100000"

results in headings such as:

This is page 3 of 100000
This is pag333 of 100000
This is pa3333 of 100000

Resetting the Page Number and the Date

The control character I (for initialize) resets the page number to 1, and resets the date.

Example

HEADING "'C' LIST PRINTED:  'D'"
FOR N=1 TO 10
   PRINT "THIS IS ANOTHER LINE"
NEXT

This is the program output:

               LIST PRINTED:  04 Jun 1994
THIS IS ANOTHER LINE
THIS IS ANOTHER LINE
THIS IS ANOTHER LINE
THIS IS ANOTHER LINE
THIS IS ANOTHER LINE
THIS IS ANOTHER LINE
THIS IS ANOTHER LINE
THIS IS ANOTHER LINE
THIS IS ANOTHER LINE
THIS IS ANOTHER LINE