Function
The LINAGE clause provides a means of specifying, for an output file, the size of a logical page in terms of the number of lines. It can also be used to specify the size of the top and bottom margins on the logical page and the line number, within the page body, at which the footing area is to begin.
Format
LINAGE IS {data-name-1 | integer-1}
LINES [WITH FOOTING AT {data-name-2 | integer-2}]
[LINES AT TOP {data-name-3 | integer-3}]
[LINES AT BOTTOM {data-name-4 | integer-4}]
Syntax rules
data-name-1, data-name-2, data-name-3, and data-name-4 must be elementary unsigned numeric integer data items.
data-name-1, data-name-2, data-name-3, and data-name-4 may be qualified.
The value of integer-1 or of the data item referenced by data-name-1 must be greater than zero.
The value of integer-2 or of the data item referenced by data-name-2 must be greater than zero, but not greater than integer-1 or the value of the data item referenced by data-name-1.
The value of integer-3 and integer-4, or the data items referenced by data-name-3 and data-name-4, may be 0.
The LINAGE clause is not permitted for files which are opened with OPEN EXTEND.
The LINAGE clause is permitted only for files which are assigned to PRINTER literal-1 or literal-2.
The LINAGE clause provides a means of specifying the size of a logical page in terms of the number of lines. The logical page size is the sum of the values of each phrase in the LINAGE clause except the FOOTING phrase. If the LINES AT TOP or LINES AT BOTTOM phrases are not specified, the value for this function is zero. If the FOOTING phrase is not specified, no footing area is defined (see table 11).
Table 11: Setup of a logical page
The size of a logical page must not necessarily correspond to the size of a physical page.
The value of integer-1 or the data item referenced by data-name-1 specifies the number of lines that can be written and/or spaced on the logical page. This part of the logical page, in which these lines can be written and/or spaced, is called the page body.
The value of integer-3 or the data item referenced by data-name-3 specifies the number of lines forming the top margin of the logical page. This area is left blank.
The value of integer-4 or the data item referenced by data-name-4 specifies the number of lines forming the bottom margin of the logical page. This area is left blank.
The value of integer-2 or the data item referenced by data-name-2 specifies the line number within the page body at which the footing area begins.
The footing area comprises the area of the logical page between the line specified by integer-2 or data-name-2 and the line represented by integer-1 or data-name-1.
The values of integer-1, integer-3 and integer-4 (or the values of data items data-name-1, data-name-3 and data-name-4, if specified) are used at object time by an OPEN statement (with the OUTPUT phrase) to specify the number of lines in each of the indicated parts of the first logical page. At the same time, the value of integer-2 or of data item referenced by data-name-2 (if specified) is used to define the footing area.
If a page overflow occurs during execution of a WRITE statement with the ADVANCING phrase, the values of integer-1, integer-3 and integer-4 are used to specify the number of lines that comprise each of the indicated sections of the next logical page.
The value of integer-2 or of data item referenced by data-name-2 (if specified) is then used to define the footing area of the next logical page.
General rules
The COBOL register LINAGE-COUNTER is generated whenever a LINAGE clause occurs. The LINAGE-COUNTER value at any given time represents the line number at which the printer is positioned within the current page body. The first printable line on each logical page has the number 1.
A separate LINAGE-COUNTER is supplied for each file described in the FILE SECTION whose file description entry contains a LINAGE clause.
The LINAGE-COUNTER may be accessed, but must not be modified, by Procedure Division statements. Since more than one LINAGE-COUNTER may exist in a program, the user must qualify LINAGE-COUNTER by file-name when necessary.
The LINAGE-COUNTER is automatically updated during the execution of a WRITE statement for the file:
If the ADVANCING PAGE phrase is specified in the WRITE statement, the LINAGE-COUNTER is automatically reset to the value 1.
If ADVANCING integer or ADVANCING identifier-2 is specified in the WRITE statement, the LINAGE-COUNTER is incremented by integer or by the value of the data item referenced by identifier-2.
If the ADVANCING phrase is omitted in the WRITE statement, the LINAGE-COUNTER is automatically incremented by the value 1.
The LINAGE-COUNTER is automatically reset to the value 1 when the printer is positioned to the first line to be written on the next logical page (see "WRITE statement").
The LINAGE-COUNTER is automatically set to the value 1 at the time an OPEN statement is executed for the file.
If the LINAGE clause refers to an external file, an equivalent LINAGE clause must be specified in all programs that describe this external file. In contrast to the Standard, the compiler described here requires specifications only of the same type (i.e. either only data-name specifications or only integer specifications). The contents of the data items or the numerical values may be different.