Transfers data from the program to the output stream.
PUT[FILE(f)][SKIP[(n)]][LINE(m)][PAGE][list];
or
PUT STRING(r)[list];
or
DATA (output-list)
or
EDIT(output-list) (format-list)[(output-list) (format-list)]...
or
(output-list iterative-DO)
If specified:
For the definition of a format list, see the section FORMAT Statement.
No comma separates an iterative-DO from its output-list.
An output-list containing one iterative-DO has two sets of parentheses, as shown in the following example:
PUT LIST (((ARR(I,J) DO I = 1 TO 5) DO J = 1 TO 5))
A parenthetical output-list containing an iterative-DO transmits values under control of the iterative-DO, as if it were a DO-group.
If none of LIST, DATA, EDIT is specified, LIST is assumed. In this default case, the output-list must occur immediately after the word PUT.
Description
The PUT statement transfers data from the program to the output stream. The output stream can be either a stream file or a character-string variable.
The PUT statement has several forms that include the following options: format-list, FILE, SKIP, STRING, LINE, PAGE, and LIST, DATA, or EDIT.
The options may be given in any order, but the format-list is part of the EDIT option and must always immediately follow the output-list.
With PUT DATA and PUT LIST, if a variable of type AREA or a structure containing elements of type AREA is used as an argument, <...> is output as its contents. This is because the actual contents of the contents of AREA in these cases is not readable.
The FILE option must reference a file value whose associated file control block has either been opened as a STREAM OUTPUT file or is closed. If closed, it is opened automatically by the PUT statement and with the attributes STREAM OUTPUT LINESIZE(80). If the FILE option is omitted, FILE(SYSPRINT) is supplied by default. When SYSPRINT is opened, it acquires the PRINT attribute by default. Note that the LINESIZE value for an implicit OPEN differs from that in an explicit OPEN where the LINESIZE option is omitted.
The SKIP option positions the output file at the start of a new line. The expression in the SKIP option must produce a positive integer value n. The option writes n lines, beginning with the current line so that any subsequent output begins on a new line. If SKIP is given without n, a value of one is supplied by default.
The STRING option specifies that the output item is a referenced character-string variable rather than a file. The STRING option cannot be used with FILE, LINE, PAGE, or SKIP. The target of the PUT STRING operation must have sufficient space allocated to store the entire result of the operation, including any spaces, semicolons, and quotation marks added by the PUT LIST or PUT DATA processing. If the target does not have enough space, the ERROR condition is signaled.
The LINE option positions the stream file to a specific line relative to the top of the page. Subsequent output begins on that line. The LINE option is evaluated as if it were a LINE format; see the section LINE(n). If n is less than the current line position, the ENDPAGE condition is signaled.
If both SKIP and LINE are specified, LINE is evaluated first.
The PAGE option positions the output file at the start of a new page so that subsequent output begins on line one of that page. If the PAGE and LINE options are both given, PAGE is evaluated first.
SKIP, PAGE, and LINE are always evaluated prior to writing any output produced by the PUT statement, regardless of their position in the PUT statement. If the output from a statement does not share its last line with subsequent output, two statements must be used. (See the section Examples.)
The output-list is evaluated from left-to-right. Each expression may be either an array reference, structure reference, or scalar-valued expression. Structures with the UNION attribute cannot be used as variables in a PUT statement.
A scalar value causes one value to be transmitted to the output stream and, if EDIT is specified, uses one data format. An array variable causes n values to be transmitted, where n is the number of elements in the array. If EDIT is specified, it uses n data formats. Values are transmitted from the array in row-major order, as defined in the section Arrays in the chapter Data Types. A structure variable causes all members of the structure and members of all contained substructures to transmit a value. The values are transmitted in left-to-right order. If EDIT is specified, each value requires a data format.
Only arithmetic, pictured, or string values can be transmitted by a PUT statement.
The number of lines written by a PUT statement is determined by the number of values specified by the output-list, as well as by the SKIP, LINE, and PAGE options, and any control formats given in the format list. However, unless control items or options force new lines to be written, transmission begins with the current position of the current line and uses as many lines as are necessary to satisfy the output list.