Controls the transmission of data to and from a stream I/O file by a GET or PUT statement.
Syntax
name:FORMAT(format-list);
Parameters
name
An unsubscripted label prefix that is not a statement label and cannot be used by a GOTO statement.
format-list
A list of format specification items.
Description
The FORMAT statement describes the format-specification list to be used by the GET or PUT statement to control the transmission of data to and from a stream I/O file or string. The FORMAT statement has no effect unless it occurs as a consequence of executing the GET or PUT statement.
The format list consists of a list of format items separated by commas. Each format item can be preceded by an optional repetition factor. The repetition factor is either an expression enclosed in parentheses or an integer. The repeat count must be separated from the item by at least one space for all but the parenthetical format list. The value of the repetition factor must be greater than zero and less than 255.
The format items are:
(format-list)
A(w) or A
B(w) or B
B1 (w) or B1
B2(w) or B2
B3(w) or B3
B4(w) or B4
E(w) or E(vv,d)
F(w) or F(w,d)
P 'Picture'
R (name)
COLUMN(n) or COL(n)
LINE(n)
PAGE
SKIP or SKIP(n)
TAB or TAB(n)
X(n) or X
(format-list) is a parenthetical format list used as a format item; A–P are data format items; and each w, d, or n is an integer constant or an expression whose value k must be 0<=k<=255, unless further restricted by the definition of a particular format item.
Each time control passes to a format list, all format items between the last used format item and the next data format item are evaluated. The next data format item is then used to control the conversion of the data being transmitted to or from the stream file.
If control reaches the end of a format list in a FORMAT statement, it returns to the R-format that transferred control to the FORMAT statement.
If control reaches the end of a format list in a GET or PUT statement, and one or more values are still to be transmitted in the statement's I/O list, control transfers to the beginning of the format list. If there are more format items than values to be transmitted in the statement's I/O list, the extra format items are ignored.
Each format item is described as follows. (Examples of the FORMAT statement are included in the format item descriptions.)
The parenthetical format list (format-list)
When a parenthetical format list is used as a format item, it is used as many times as specified by its repeat count.
The data format items (A, B, B1, B2, B3, B4, E, F, and P)
The data format items A, B, B1, B2, B3, B4, E, F, and P control the transmission and conversion of a value to or from a stream file. Each data format causes w characters to be read from an input stream or written to an output stream, where w is the field width given in the format or calculated during the conversion. (For additional information, see the chapter Data Type Conversions.)
If fewer than w characters remain in an input line, any characters remaining on that line are read and a fresh line is obtained. Additional characters are then read from the fresh line so that a total of w characters are read.
If fewer than w characters remain in an output line, as many characters as fit are written on that line and a fresh line is begun. Any remaining characters are written onto the line so that a total of w characters are written.
For a detailed description of how each data format controls conversion of a value, see the section Format Controlled Conversion in the chapter Data Type Conversions .
R(label)
The R(label) format item indicates that format items are to be acquired from the FORMAT statement at the specified label. That is, the R(label) format item transfers control to the format list of the FORMAT statement whose name appears in the R-format.
The effect of this transfer is as if the format list of the FORMAT statement were called as a subroutine; when the remote format list is exhausted, control returns to the format item following the R-format.
F: FORMAT(A,X(3));
PUT EDIT(P,Q) (R(F),E(14,3));
In the previous example, the value of P is transmitted by the A-format contained in the FORMAT statement. Transmission of Q finishes the remote format list by evaluating the X control format and returns to use the E-format to transmit the value of Q. This is equivalent to the following:
PUT EDIT(P,Q) (A,X(3),E(14,3));
COLUMN(n) or COL(n)
The COLUMN or COL format item puts blanks into an output stream or skips characters of an input stream so that the next character is read or written into column n of a line.
The COLUMN format is valid for files only.
If the current output line contains exactly n-1 characters, no output is performed and the next output begins in column n of the current line.
If the current output line contains less than n-1 characters and n is less than or equal to the line size, sufficient blanks are placed into the current line to cause the next output to begin in column n.
If the current output line contains less than n-1 characters and n is greater than the line size of this file, the current line is written and a new line is begun. The next output begins in column 1 of the new line.
If the current output line already contains more than n characters, it is written to the stream file and a new line is begun. If n is greater than the line size of this file, no blanks are placed into the new line; otherwise, n-1 blanks are placed into the new line, causing the next output to begin in column n of the line.
If the current input line is positioned such that the next character to be read is located in column n, no characters are skipped.
If the current input line is positioned such that the current column is less than column n and n does not exceed the size of the current line, sufficient characters of the line are skipped so that the next input occurs from column n.
If the current input line is positioned such that the current column is less than column n, but n exceeds the size of the current line, or if the current column is greater than column n, a fresh line is read. If n exceeds the size of the fresh line, no characters are skipped and the next input occurs from column 1; otherwise, n-1 characters are skipped, causing the next input to occur from column n.
The value n must be greater than zero.
Example:
COL(n)
COLUMN
LINENO
NEW COLUMN
NEW LINENO
25
25
1
25
1
24
25
1
24
2
26
25
1
26
1
30
25
1
1
2
The previous examples assume a linesize, s, that is 26≤s≤30.
LINE(n)
The LINE format item sets a print file to a specific line; therefore, it can be used only to control output to a stream file that has been opened with the PRINT attribute and that, consequently, has a page size.
The LINE format item is valid for print files only; it positions the stream file to a specified line relative to the top of a page.
If the current line number is less than n and n does not exceed the page size, sufficient lines are written to the output so that the current line is line number n.
If the current line number is greater than n or if n exceeds the page size, the remainder of the page is filled with blank lines and the ENDPAGE condition is signaled, unless the current line number already exceeds the page size. In that case, a new page is begun without signaling the ENDPAGE condition.
If n equals the current line and the current column is one, no output occurs. If n equals the current line, but the current column is not one, the ENDPAGE condition is signaled, unless the current line number already exceeds the page size. In that case, a new page is begun without signaling the ENDPAGE condition.
The value n must be greater than zero.
PAGE
The PAGE format item is used with print files to begin a new page. It can be used only to control output to a stream file that has been opened with the PRINT attribute.
The PAGE format item positions the stream to the top of a new page and thereby resets the line number to one and increases the page number by one.
SKIP(n) or SKIP
The SKIP format item sets a stream file to a new position relative to the current line. It can be used only with input and output files.
The SKIP format item applied to an input stream skips the rest of the current input line and n-1 subsequent lines; that is, it skips over n line boundaries.
A SKIP format applied to an output stream writes the current line and n-1 empty lines; that is, it writes n line boundaries.
If n is omitted, a value of one is supplied. The value of n must be greater than zero. If the value of n is less than or equal to zero, the SKIP option is ignored.
If the output stream file has been opened with the PRINT attribute, and if the total number of lines written as a result of the SKIP format item would exceed the page size, the current line is written, followed by sufficient empty lines to fill the page, and the ENDPAGE condition is signaled.
TAB(n) or TAB
The TAB format item sets a print file to a specified tab stop n. It can be used only to control output to a stream file opened with the PRINT attribute.
The TAB format item causes sufficient blanks to be placed into the current line to position it to the nth tab stop relative to the current column of the line. The relative positions of tabs are implementation-defined (8 characters apart in this implementation). Other implementations may differ and may in fact not place tab stops at constant intervals.
If the current column is a tab stop, the TAB format item produces sufficient blanks to cause the next output to begin at the next tab stop.
If n tab stops do not remain on the current line, the current line is written and a new line begun. If the first tab stop is not column 1, sufficient blanks are placed into this line to position it to the first tab stop.
If TAB format items are used, line size must not be less than the first tab stop. If n is omitted, a default value of one is supplied.
The value of n must be greater than zero.
If either of the two preceding rules are violated, a line feed is inserted and data continues to be transmitted.
X(n) or X
The X format item writes n blanks to an output file or skips n positions in an input file. If n is omitted, the default value of n is 1. The X format item is valid with both the FILE and STRING options of the GET EDIT and PUT EDIT statements.
If fewer than n characters remain in the current line, the remaining characters are skipped on input or written as blanks on output, and additional characters are skipped or written as blanks on the next line so that a total of n characters are written or skipped.
Description
The FORMAT statement describes the format-specification list to be used by the GET or PUT statement to control the transmission of data to and from a stream I/O file or string. The FORMAT statement has no effect unless it occurs as a consequence of executing the GET or PUT statement.
The format list consists of a list of format items separated by commas. Each format item can be preceded by an optional repetition factor. The repetition factor is either an expression enclosed in parentheses or an integer. The repeat count must be separated from the item by at least one space for all but the parenthetical format list. The value of the repetition factor must be greater than zero and less than 255.
The format items are:
(format-list) is a parenthetical format list used as a format item; A–P are data format items; and each w, d, or n is an integer constant or an expression whose value k must be 0<=k<=255, unless further restricted by the definition of a particular format item.
Each time control passes to a format list, all format items between the last used format item and the next data format item are evaluated. The next data format item is then used to control the conversion of the data being transmitted to or from the stream file.
If control reaches the end of a format list in a FORMAT statement, it returns to the R-format that transferred control to the FORMAT statement.
If control reaches the end of a format list in a GET or PUT statement, and one or more values are still to be transmitted in the statement's I/O list, control transfers to the beginning of the format list. If there are more format items than values to be transmitted in the statement's I/O list, the extra format items are ignored.
Each format item is described as follows. (Examples of the FORMAT statement are included in the format item descriptions.)
When a parenthetical format list is used as a format item, it is used as many times as specified by its repeat count.
This example is equivalent to:
The data format items A, B, B1, B2, B3, B4, E, F, and P control the transmission and conversion of a value to or from a stream file. Each data format causes w characters to be read from an input stream or written to an output stream, where w is the field width given in the format or calculated during the conversion. (For additional information, see the chapter Data Type Conversions.)
If fewer than w characters remain in an input line, any characters remaining on that line are read and a fresh line is obtained. Additional characters are then read from the fresh line so that a total of w characters are read.
If fewer than w characters remain in an output line, as many characters as fit are written on that line and a fresh line is begun. Any remaining characters are written onto the line so that a total of w characters are written.
For a detailed description of how each data format controls conversion of a value, see the section Format Controlled Conversion in the chapter Data Type Conversions .
The R(label) format item indicates that format items are to be acquired from the FORMAT statement at the specified label. That is, the R(label) format item transfers control to the format list of the FORMAT statement whose name appears in the R-format.
The effect of this transfer is as if the format list of the FORMAT statement were called as a subroutine; when the remote format list is exhausted, control returns to the format item following the R-format.
In the previous example, the value of P is transmitted by the A-format contained in the FORMAT statement. Transmission of Q finishes the remote format list by evaluating the X control format and returns to use the E-format to transmit the value of Q. This is equivalent to the following:
The COLUMN or COL format item puts blanks into an output stream or skips characters of an input stream so that the next character is read or written into column n of a line.
The COLUMN format is valid for files only.
If the current output line contains exactly n-1 characters, no output is performed and the next output begins in column n of the current line.
If the current output line contains less than n-1 characters and n is less than or equal to the line size, sufficient blanks are placed into the current line to cause the next output to begin in column n.
If the current output line contains less than n-1 characters and n is greater than the line size of this file, the current line is written and a new line is begun. The next output begins in column 1 of the new line.
If the current output line already contains more than n characters, it is written to the stream file and a new line is begun. If n is greater than the line size of this file, no blanks are placed into the new line; otherwise, n-1 blanks are placed into the new line, causing the next output to begin in column n of the line.
If the current input line is positioned such that the next character to be read is located in column n, no characters are skipped.
If the current input line is positioned such that the current column is less than column n and n does not exceed the size of the current line, sufficient characters of the line are skipped so that the next input occurs from column n.
If the current input line is positioned such that the current column is less than column n, but n exceeds the size of the current line, or if the current column is greater than column n, a fresh line is read. If n exceeds the size of the fresh line, no characters are skipped and the next input occurs from column 1; otherwise, n-1 characters are skipped, causing the next input to occur from column n.
The value n must be greater than zero.
Example:
The previous examples assume a linesize, s, that is 26≤s≤30.
The LINE format item sets a print file to a specific line; therefore, it can be used only to control output to a stream file that has been opened with the PRINT attribute and that, consequently, has a page size.
The LINE format item is valid for print files only; it positions the stream file to a specified line relative to the top of a page.
If the current line number is less than n and n does not exceed the page size, sufficient lines are written to the output so that the current line is line number n.
If the current line number is greater than n or if n exceeds the page size, the remainder of the page is filled with blank lines and the ENDPAGE condition is signaled, unless the current line number already exceeds the page size. In that case, a new page is begun without signaling the ENDPAGE condition.
If n equals the current line and the current column is one, no output occurs. If n equals the current line, but the current column is not one, the ENDPAGE condition is signaled, unless the current line number already exceeds the page size. In that case, a new page is begun without signaling the ENDPAGE condition.
The value n must be greater than zero.
The PAGE format item is used with print files to begin a new page. It can be used only to control output to a stream file that has been opened with the PRINT attribute.
The PAGE format item positions the stream to the top of a new page and thereby resets the line number to one and increases the page number by one.
The SKIP format item sets a stream file to a new position relative to the current line. It can be used only with input and output files.
The SKIP format item applied to an input stream skips the rest of the current input line and n-1 subsequent lines; that is, it skips over n line boundaries.
A SKIP format applied to an output stream writes the current line and n-1 empty lines; that is, it writes n line boundaries.
If n is omitted, a value of one is supplied. The value of n must be greater than zero. If the value of n is less than or equal to zero, the SKIP option is ignored.
If the output stream file has been opened with the PRINT attribute, and if the total number of lines written as a result of the SKIP format item would exceed the page size, the current line is written, followed by sufficient empty lines to fill the page, and the ENDPAGE condition is signaled.
The TAB format item sets a print file to a specified tab stop n. It can be used only to control output to a stream file opened with the PRINT attribute.
The TAB format item causes sufficient blanks to be placed into the current line to position it to the nth tab stop relative to the current column of the line. The relative positions of tabs are implementation-defined (8 characters apart in this implementation). Other implementations may differ and may in fact not place tab stops at constant intervals.
If the current column is a tab stop, the TAB format item produces sufficient blanks to cause the next output to begin at the next tab stop.
If n tab stops do not remain on the current line, the current line is written and a new line begun. If the first tab stop is not column 1, sufficient blanks are placed into this line to position it to the first tab stop.
If TAB format items are used, line size must not be less than the first tab stop. If n is omitted, a default value of one is supplied.
The value of n must be greater than zero.
If either of the two preceding rules are violated, a line feed is inserted and data continues to be transmitted.
The X format item writes n blanks to an output file or skips n positions in an input file. If n is omitted, the default value of n is 1. The X format item is valid with both the FILE and STRING options of the GET EDIT and PUT EDIT statements.
If fewer than n characters remain in the current line, the remaining characters are skipped on input or written as blanks on output, and additional characters are skipped or written as blanks on the next line so that a total of n characters are written or skipped.
The value of n must be greater than zero.