Purpose
Reads a record from an input or update file.
Syntax
READ FILE(f)[INTO(v) [KEY(k)|KEYTO(r)]|
SET(p)[KEY(k)|KEYTO(r)]
IGNORE(expr)];
Parameters
-
f
- A reference to the file from which the record is to be read.
-
v
- A reference to the variable to which the record contents are to be assigned.
-
p
- A pointer variable.
-
expression
- Is evaluated and converted to an integer value.
-
k
- An expression that specifies the key to be used to locate the record to be read.
-
r
- The designated variable to which the key of the record being read is to be assigned.
The FILE, INTO, KEYTO, and KEY specifiers may be written in any order. KEYTO must not be specified if KEY is specified. A READ statement without an INTO, SET, or IGNORE option is equivalent to a READ with an IGNORE(1).
Example
READ FILE(F) INTO(X);
READ FILE(G) INTO(Y) KEY(N+1);
READ FILE (TOWN_FILE) INTO (TOWN_BUFFER) KEYTO (SAVE_ADDRESS);
In the last example, the READ statement reads the next sequential record in the file TOWN_FILE into the variable TOWN_BUFFER. The key associated with the record that is read is copied into the variable SAVE_ADDRESS.
Description
The READ statement reads a record from a record file.
The FILE option must contain a reference f that produces a file value. The file identified by f must either have been previously opened with RECORD INPUT or UPDATE, or must be closed. If closed, it is opened by the READ statement and given the INPUT RECORD SEQUENTIAL attributes.
If the file has been opened with the KEYED SEQUENTIAL attributes, the KEY option may be specified. If the file has been opened with the DIRECT attribute, the KEY option must be specified.
The READ statement with INTO option copies the data record into the referenced variable. The SET option specifies a pointer variable that is set to point to the location in a buffer into which data has been moved during the READ operation. The storage for this buffer is handled by the run-time system.
In the following example, the value of the pointer value P is set to the location of F in the buffer of the next sequential record:
The IGNORE option can be used in a READ statement for any indexed SEQUENTIAL INPUT or SEQUENTIAL UPDATE file.
expression in the IGNORE option is evaluated and converted to an integer value, n. If n is greater than zero, n records are ignored. A subsequent READ statement for the file will access the (n+1)th record. If n is less than 1, the READ statement has no effect.
The IGNORE option cannot be used with non-indexed files.
The following example specifies that the next five records in the file are to be ignored:
If specified for non-indexed files, the KEY option must be an expression whose value can be converted to a positive integer. Its value must be a key value of a record in the keyed file identified by the file associated with f. An attempt to read the file using a key value that does not identify a record in f results in a signal of the KEY condition. For indexed (VSAM) files, the key value must be of type Character, Widechar or Graphic, otherwise it is converted to Character.
If specified, the KEYTO option must be of Character type; if not, it is converted to Character type. Its maximum length is implementation-defined. (For details, see your Open PL/I User's Guide.) The file must be a keyed file. The key value of the record is assigned to r.
If a KEY option is given, the file must have been opened previously with the KEYED attribute. The presence of the KEY option does not cause implicit opening to produce the KEYED attribute.
Regardless of how the file was opened, it must have either the INPUT or UPDATE attribute.
If a KEY option is given, the file is positioned to read the record identified by the key value; otherwise, it is positioned to read the current record of a SEQUENTIAL file. After reading the record, the current position is advanced to the next record if the file is SEQUENTIAL. The current position for a DIRECT file is not changed.
Open PL/I allows the use of READ with a stream file, as long as the READ statement specifies a scalar character varying string variable in its INTO option. The READ statement reads the next complete input line and assigns it to the character varying string specified by the INTO option. The string does not include any new-line character.