GET
Purpose
Gets data from an input stream that is either a stream file or a character-string expression.
Syntax
GET [FILE(f)][SKIP[(n)]][LIST](input-list);
or
GET [FILE(f)][SKIP[(n)]]EDIT(input-list)(format-list)[(input-list)(format-list)]…;
or
GET STRING(s)[LIST](input-list);
or
GET STRING(s) EDIT(input-list)(format-list)[(input-list)(format-list)]…;
If neither LIST nor EDIT is specified, LIST is assumed. In this default case, the
input-list must occur immediately after the word GET.
Parameters
input-list is input-item [,input-item]...
An input-item is either:
variable-reference
or
(input-list iterative-DO)
No comma separates the iterative-DO from its associated input list.
An input list consisting of one iterative-DO has two sets of parentheses, as shown in the following example:
GET LIST (((ARR(I,J) DO I = 1 TO 5) DO J = 1 TO 5))
Each variable reference may be either an array reference, structure reference, or scalar variable reference. Structures with the UNION attribute cannot be used as variables in a GET statement.
The options may appear in any order.
Examples
The following example shows a GET statement whose input list consists of one iterative-DO.
GET FILE(F) LIST((A(K),B(K) DO K = 1 TO 10))
Note that this is the same as:
DO K = 1 TO 10; GET FILE(F) LIST(A(K),B(K)); END;
The following example shows a GET statement whose parenthetical input-list contains an iterative-DO, which transmits values under control of the iterative- DO as if it were a DO-group.
DECLARE A(10) FLOAT; DECLARE (B,C) FLOAT; . . . GET FILE(F) LIST(A,B,C); GET FILE(F) EDIT(A(K),K,B(K)) (3 E(14,6)); GET FILE(F) LIST(B,(A(K) DO K = 1 TO 5),C);
In this example, the first GET statement transmits 10 values to the array A and then transmits values to B and C in that order. The second GET statement transmits a value to A (K) , transmits a value to K, and then transmits a value to B (K) using the new value of K as a subscript. All three values are transmitted using the same E-format. The third GET statement transmits a value to B, transmits values to A(1),A(2),A(3),A(4), and A(5), and to C in that order.
The following example shows a GET statement with the STRING option.
GET EDIT (NAME.FIRST,NAME.LAST) (A(8),X(3),A(20))
STRING('Deborah M. Park ');
In this example, the GET statement assigns the character string 'Deborah
' to the structure NAME.FIRST, skips the middle initial, periods, and space, and assigns the character string 'Park
' to NAME.LAST. Blanks may be used to separate items in list-directed I/O, but for edit-directed I/O they are interpreted
differently for character strings. For example, the same example would be interpreted as follows for edit-directed I/O with
the format (A (10) , X (3) , A(20)):
For list-directed I/O, the following example:
GET LIST(NAME.FIRST, NAME.LAST)
STRING('Deborah M. Park ');
would assign 'Deborah' to NAME.FIRST and 'M.' to NAME.LAST.
The following sections contain additional information on the EDIT and LIST options.
Description
The GET statement gets data from an input stream that is either a stream file or a character-string expression. The input file may be declared either with the STREAM attribute or with the default SYSIN, commonly associated with the user's default input device.
The GET statement has several forms, which include the following options: format-list, FILE, SKIP, STRING, and LIST, or EDIT.
The FILE, SKIP, and LIST options or the FILE, SKIP, and EDIT options may be given in any order, but a format list is contained in the EDIT option and must immediately follow the input list. If SKIP is given without (n), a value of one is supplied. If FILE is not given, FILE(SYSIN) is supplied by default.
After any SKIP option has been evaluated, the input list is evaluated together with any format list.
The input list is evaluated from left-to-right. Each variable reference may be an array reference, structure reference, or scalar variable reference.
A scalar variable reference causes one value to be transmitted from the input stream and, if EDIT is specified, it 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 to 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 receive a value. The values are transmitted in left-to-right order. If EDIT is specified, each value requires a data format.
Only arithmetic, pictured, and string values can be transmitted by a GET statement. In Open PL/I, the maximum length of a string value transmitted by a GET statement is 256 bits for bit strings or 256 characters for character strings.
A parenthetical input list containing an iterative-DO transmits values under control of the iterative-DO as if it were a DO-group.
The number of lines read by a GET statement is determined by the size of the list, the SKIP option, and any control formats given in the format list. However, unless control items or SKIP forces new lines to be read, transmission begins with the current position of the current line and uses as many lines as are necessary to satisfy the input list.
The maximum length of any line in the input file is limited to the larger of 258 or the value of the LINESIZE option (specified in the OPEN statement) plus 2. If a line in the file is longer than this limit, the GET processing will truncate it with no run-time warning.