Function
The READ statement makes the following available to the program:
for sequential access: the next record in the file (for sequential, relative and indexed file organization).
for random access: a record of a file (for relative and indexed file organization) specified by the key.
Format 1 | sequential file access |
Format 2 | random file access |
The extension (WITH NO LOCK) in both formats, which is effective during shared updating of files, is described in the "COBOL2000 User Guide" [1].
Format 1 sequential file access
READ file-name [WITH NO LOCK] {NEXT | PREVIOUS } RECORD [INTO identifier]
[AT END imperative-statement-1]
[NOT AT END imperative-statement-2]
[END-READ]
Syntax rules
In the READ statement, the receiving operand references the same storage area as the record description entry.
If no USE procedure is declared for the file, AT END must be specified in the READ statement.
PREVIOUS may only be specified for indexed and relative files.
If ACCESS MODE RANDOM is entered for the file in the FILE-CONTROL paragraph then AT END, NOT AT END, NEXT and PREVIOUS must not be specified.
If ACCESS MODE SEQUENTIAL is specified for the file in the FILE-CONTROL paragraph and neither NEXT nor PREVIOUS is specified then NEXT is assumed.
If the following conditions hold simultaneously, NEXT is assumed:
ACCESS MODE DYNAMIC is entered for the file in the FILE-CONTROL paragraph.
Neither NEXT nor PREVIOUS is specified.
AT END or NOT AT AND is specified.
General rules
The following applies for sequential, relative and indexed file organization:
An OPEN statement with the INPUT or I-O phrase must be executed for a file before the READ statement can be executed.
The execution of a READ statement causes the contents of the data item specified in the FILE STATUS clause of the related file description entry to be updated (see section "FILE STATUS clause").
When the logical records of a file are described with more than one record description, these records automatically share the same storage area; this is equivalent to an implicit redefinition of the area. The contents of any data items which lie beyond the range of the current record are undefined after execution of the READ statement.
The INTO phrase may be specified in a READ statement:
if only one record description is subordinate to the file description entry, or
if all record-names associated with the file-name and the data item referenced by the identifier represent group items or alphanumeric elementary items.
If, after a READ statement without the INTO phrase, the user wishes to explicitly address the input area, then he is responsible for using the correct record description (i.e. the one which matches the length of the record which was read).
If no exception condition exists, the record is available in the record area, and any implicit move as a result of the INTO phrase is executed.
Whether execution of the READ statement continues depends on whether AT END or NOT AT END is specified (see section "At end condition").
After unsuccessful execution of a READ statement, the content of the input area belonging to the file and the file position indicator are undefined and the I/O status indicates that no valid next record has been read.
If the number of character positions in a read record is less than the minimum length specified in the record descriptions, the contents to the right of the last valid character will be unpredictable.
If the number of character positions is greater than the maximum length specified in the record descriptions, the record will be truncated to the right of the maximum length.
In either case the read operation is successful, but a FILE STATUS is set to indicate the occurrence of a record length conflict.The execution of a READ statement with the INTO phrase is equivalent to:
READ file-name
MOVE record-name TO identifierThe MOVE operation takes place according to the rules for the MOVE statement without the CORRESPONDING phrase. After the READ statement with INTO phrase has been successfully executed, the record is available both in the input area and in the area specified by the identifier. The length of the source field is determined by the length of the record that is read (see section "RECORD clause").
If the file description entry contains a RECORD-IS-VARYING clause, the implicitly executed transfer operation is a group item transfer.
If the execution of the READ statement was unsuccessful, the implied MOVE statement does not occur.
The index for the identifier is calculated after execution of the READ statement and immediately before the data transfer.The file position indicator determines whether a record is supplied and, if so, which record this is:
If the file position indicator indicates “invalid” then the READ statement is unsuccessful.
If the file position indicator was set by a preceding OPEN or START statement then the following result is supplied:
If NEXT was specified either explicitly or implicitly then the first record of the file with a record number or record key
≥file position indicator is supplied.If PREVIOUS was specified then the first record of the file with a record number or record key
≤file position indicator is supplied.
Note:
After OPEN, READ PREVIOUS for a relative file supplies the first record and for indexed files it usually supplies the End condition.If the file position indicator was set by a preceding READ statement then the following result is supplied:
If NEXT was specified either explicitly or implicitly then the first record of the file with a record number or record key
>file position indicator is supplied.If PREVIOUS was specified then the first record of the file with a record number or record key
<file position indicator is supplied.
If a record is supplied, it is available in the record area of the file file-name. The file position indicator is set to the record number or record key. If no record is supplied, the file position indicator indicates “invalid” and processing continues in accordance with rule 5.
For sequentially organized files, the following also applies:
After the at end condition has occurred, no READ statement may be issued for the file until a successful CLOSE statement has been carried out, followed by a successful OPEN statement for that file.
If the physical end of a reel or disk storage volume is encountered during execution of a READ statement for a multi-volume file, then the following operations take place:
The standard volume trailer label routine and, if specified by an appropriate USE procedure, the user volume trailer label routine are executed. The order in which the two routines are performed is specified by the USE procedure.
A volume switch is executed.
The standard volume header label routine and, if specified, the user volume header label routine are executed. Again, the order in which these routines are executed is specified by the USE procedure.
For relative and indexed files, the following also applies:
If the RELATIVE KEY phrase is specified, the execution of the READ statement moves the relative record number of the record made available to the relative key data item according to the rules for the MOVE statement.
After the at end condition has occurred, no further READ statement may be issued for the file until either repositioning has been effected with START or the file has been successfully closed and reopened.
In the case of an indexed file with sequential access, the sequence of records whose keys permit duplicates is defined by the order in which these duplicate keywords were generated by means of WRITE or REWRITE statements. When such files are read with an explicit or implicit NEXT, the read operation starts at the next written record. If PREVIOUS is specified then the operation starts at the previously written record.
Format 2 random file access
READ file-name [WITH NO LOCK] RECORD [INTO identifier]
[KEY IS data-name]
[INVALID KEY imperative-statement-1]
[NOT INVALID KEY imperative-statement-2]
[END-READ]
Syntax rules
In the READ statement, the receiving operand references the same storage area as the record description entry.
If no USE procedure is present for the file, INVALID KEY must be specified.
The
KEY IS data-namephrase is only allowed for indexed file organization.data-name must be the name of a RECORD KEY or ALTERNATE RECORD KEY field declared for this file.
data-name may be qualified.
General rules
An OPEN statement with the INPUT or I-O phrase must be executed for a file before the READ statement can be executed.
When the logical records of a file are described with more than one record description, these records automatically share the same storage area; this is equivalent to an implicit redefinition of the area.
The INTO phrase may be specified in a READ statement:
if only one record description is subordinate to the file description entry, or
if all record-names associated with the file-name and the data item referenced by the identifier represent group items or alphanumeric elementary items.
The execution of a READ statement with the INTO phrase is equivalent to:
READ file-name
MOVE record-name TO identifierThe MOVE operation takes place according to the rules for the MOVE statement without the CORRESPONDING phrase. After the READ statement with INTO phrase has been successfully executed, the record is available both in the input area and in the area specified by the identifier. The length of the source field is determined by the length of the record that is read (see section "RECORD clause"). If the execution of the READ statement was unsuccessful, the implied MOVE statement does not occur.
The index for the identifier is calculated after execution of the READ statement and immediately before the implicit MOVE.
If the input area is to be explicitly referenced following a READ statement without the INTO phrase, it is the user’s responsibility to ensure that the correct record description entry (i.e. corresponding to the length of the read record) is used.
If an invalid key condition does not occur during the execution of a READ statement, the INVALID KEY phrase is ignored, if specified, and the following actions occur:
The I-O status for file-name is updated.
If some other exception condition occurs, control is transferred to the USE procedure.
If no exception condition exists, the record is made available in the record area, and any implicit move as a result of the INTO phrase is executed. Control is transferred to the end of the READ statement or to imperative-statement-2 of the NOT INVALID KEY phrase, if specified. In the latter case, execution continues according to the rules for the specified imperative-statement, and control is transferred to some other branch in the program or to the end of the READ statement.
Following an unsuccessful READ statement, the contents of the input area associated with the file and the file position indicator are undefined.
If the number of character positions in a record is less than the minimum length specified in the record descriptions, the contents to the right of the last valid character will be unpredictable.
If the number of character positions is greater than the maximum length specified in the record descriptions, the record will be truncated to the right of the maximum length.In either case the read operation is successful, but a FILE STATUS is set to indicate the occurrence of a record length conflict.For relative file organization, the following also applies:
- If a file is read randomly, a search is executed for a record whose relative record number is equal to the value of the RELATIVE KEY field for this file. If there is no such record in the file, an invalid key condition occurs and execution of the READ statement is unsuccessful (see section "Invalid key condition").
- If an optional file does not exist, the invalid key condition occurs and execution of the READ statement is unsuccessful.
For indexed file organization, the following also applies: - Execution of the READ statement sets the file position indicator to value in the key of reference. This value is compared with the value contained in the corresponding data item of the stored records in the file until the first record having an equal value is found. In the case an alternate key is used as key of reference and if duplicates are available for this alternate key, the first record written is made available with this very key value. The record thus found is made available in the record area associated with file-name. If no record can be identified in this way, the invalid key condition occurs, and execution of the READ statement is unsuccessful (see "Invalid key condition").
- If KEY is specified, data-name is established as the key of reference for the current read operation. In the case of dynamic access, this key of reference is also used for all subsequent format 1 READ statements until a different key of reference is established for the file.
- If KEY is not specified, the primary key is established as the key of reference. In the case of dynamic access, this key of reference is also used for all subsequent format 1 READ statements until a different key of reference is established for the file.