Micro Focus Visual COBOL 3.0 for Eclipse (Windows) > General Reference > COBOL Language Reference > Part 2. Program Definition > Procedure Division > Statements > The READ Statement

The READ Statement

For sequential access, the READ statement makes available the next

or previous

logical record from a file. For random access, the READ statement makes available a specified record from a mass storage file.

General Formats for Format 1 (Record Sequential Files)

General Formats for Format 2 (Line Sequential Files)

General Formats for Format 3 (Relative and Indexed Files)

General Formats for Format 4 (Relative Files)

General Formats for Format 5 (Indexed Files)

Directives and RTS switches

In addition to Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or the semantics described in this section.
- RETRYLOCK - causes the COBOL system to retry to read a locked record.
The following RTS switches may impact the semantics described in this section.
- B, B1 - causes the record pointer to be updated past any locked record encountered when executing a READ NEXT statement.
- N - controls the interpretation of null characters before control characters when reading line sequential records.
- T - controls the interpretation of tab characters when writing line sequential records.

Syntax Rules for All Formats (All Files)

The INTO phrase must not be used when the input file contains logical records of various sizes as indicated by their record descriptions.
This restriction is removed.

The storage area associated with identifier and the storage area which is the record area associated with file-name must not be the same storage area.
Identifier can be a floating-point data item.
The INVALID KEY phrase or the AT END phrase must be specified if no applicable USE procedure is specified for file-name.
This rule is not enforced.

Syntax Rules for Formats 1, 3, 4 and 5 (Record Sequential, Relative and Indexed Files)

The WITH LOCK phrase can be included only when single records are being locked manually in a shareable file.
The WITH NO LOCK phrase is only allowed when records are being locked manually or automatically in a shareable file.

Syntax Rules for Format 3 (Relative and Indexed Files)

The NEXT
or PREVIOUS

phrases must be specified for files in dynamic access mode when records are to be retrieved sequentially.

Syntax Rules for Formats 3, 4 and 5 (Relative and Indexed Files)

The WITH KEPT LOCK phrase can be included only when multiple records are being locked manually in a shareable file.

Syntax Rules for Formats 4 and 5 (Relative and Indexed Files)

Format 4 or 5 is used for files in random access mode or for files in dynamic access mode when records are to be retrieved randomly.

Syntax Rules for Format 5 (Indexed Files)

Data-name
or split-key-name

must be the name of a data item specified as a record key associated with file-name.

Data-name may also be a redefinition of a data-item specified as a record key associated with a file-name, provided the data-name has the same length as that data-item.

The redefinition may have a different length from the record key.
Data-name
or split-key-name
can be qualified.
Split-key-name is a concatenation of one or more data items specified as a record key associated with file-name.
When the DIALECT"RM" or DIALECT"ACU" directives are in effect, the data-name or split-key-name specified in the KEY phrase is implicitly qualified by the file-name specified in the READ statement when the file-name is not already explicitly specified as the final qualifier of the data-name or split-key-name. For any other dialect, the data-name or split-key-name may need to explicitly specify file-name as the final qualifier to satisfy uniqueness of reference rules.

General Rules for All Formats (All Files)

The associated file must be open in the INPUT or I-O mode at the time the statement is executed. (See the topic The OPEN Statement.)
The execution of the READ statement causes the value of the FILE STATUS data item, if any, associated with file-name to be updated. (See the topic I-O Status in the chapter Procedure Division.)
When the logical records of a file are described by 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 data record are undefined at the completion of the execution of the READ statement.
If the INTO phrase is specified, the record being read is moved from the record area to the area specified by identifier according to the rules specified for the MOVE statement without the CORRESPONDING phrase. The implied MOVE does not occur if execution of the READ statement was unsuccessful. Any subscripting or indexing associated with identifier is evaluated after the record has been read and immediately before it is moved to the data item.
When the INTO phrase is used, the record being read is available in both the input record area and data area associated with identifier.
If the file position indicator indicates that no next logical record exists, or that an optional input file is not present, the following occurs in the order specified:
1. A value, derived from the setting of the file position indicator, is placed into the FILE STATUS data item associated with file-name-1 to indicate the at end condition. (See the topic I-O Status in the chapter Procedure Division.)
2. If the AT END phrase is specified in the statement causing the condition, control is transferred to AT END imperative-statement-1. Any USE AFTER EXCEPTION procedure associated with the file connector referenced by file-name-1 is not executed. Execution then continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules of that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the READ statement and the NOT AT END phrase, if specified, is ignored.
3. If the AT END phrase is not specified, a USE AFTER STANDARD EXCEPTION procedure must be associated with this file-name-1, and that procedure is executed. Return from that procedure is to the next executable statement following the end of the READ statement.
  When the AT END condition occurs, the execution of the READ statement is unsuccessful.
Following the unsuccessful execution of any READ statement, the contents of the associated record area are undefined and the file position indicator is set to indicate that no next record has been established.
When running non-transactional file handling on a UNIX platform, when using FCD3, a record locked status returns the process-id of the locking process to the fcd-session-id of the FCD; this operation does not apply when using Fileshare.

General Rules for Format 1 (Record Sequential Files)

The record to be made available by the READ statement is determined as follows:
1. If the file position indicator was positioned by the execution of the OPEN statement, the record pointed to by the file position indicator is made available.
2. If the file position indicator was positioned by the execution of a previous READ statement, the file position indicator is updated to point to the next existing record in the file, and that record is made available.
  However if the previous statement was a READ, and if that READ returned a locked record status, the file position indicator is left unchanged. The record pointed to by the file position indicator is made available.
If the end of a reel or unit is recognized during the execution of a READ statement, and end-of-file has not been reached, the following procedures are executed:
1. The standard ending reel/unit label procedure.
2. A reel/unit swap.
3. The standard beginning reel/unit label procedure.
4. The first data record of the new reel/unit is made available.
If a file described with the OPTIONAL clause is not present at the time the file is opened, then at the time of execution of the first READ statement for the file, the AT END condition occurs and execution of the READ statement is unsuccessful. The standard end of file procedures are not performed. (See the topic The File-Control Paragraph, the topic The OPEN Statement and the topic The USE Statement.) Execution then proceeds as in General Rule 13.
For files opened for INPUT, the READ, READ WITH LOCK or READ WITH KEPT LOCK statements do not acquire a record lock.
Two or more run units can share a sequential output file by opening it EXTEND with AUTOMATIC or MANUAL record locking. Records that are appended to the file are in unspecified order.
For files opened for I/O:
1. With LOCK MODE AUTOMATIC, unless the WITH NO LOCK phrase is specified, each record is locked as it is read.
2. With LOCK MODE MANUAL, a simple READ statement does not acquire a lock on the record - the READ WITH LOCK statement must be used to acquire a record lock. The WITH NO LOCK phrase, if specified, is documentary.
3. The use of multiple or single record locking determines when the record lock is released. (See the topic The File Control Entry.)
If an end-of-file status occurs on a READ statement in a file opened for I/O or INPUT by one run unit and opened EXTEND by another run unit, the run unit that attempted the READ must close the file. This run unit has no access to the appended records because the status remains end-of-file.

General Rules for Formats 1, 2 and 3 (Sequential, Relative and Indexed Files)

If an AT END condition does not occur during the execution of a READ statement, the AT END phrase, if specified, is ignored and the following actions occur:
1. The file position indicator is set and the I/O status associated with file-name-1 is updated.
2. If an exception condition which is not an AT END condition exists, control is transferred according to the rules of the USE statement following the execution of any USE AFTER EXCEPTION procedure applicable to file-name-1. (See the topic The USE Statement.)
3. If no exception condition exists, the record is made available in the record area and any implicit move resulting from the presence of an INTO phrase is executed. Control is transferred to the end of the READ statement or to imperative-statement-2, if specified. In the latter case, execution continues according to the rules for each statement specified in imperative-statement-2. If a control branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the READ statement.
If when a READ statement with the NEXT option is executed, no next logical record exists in the file, the AT END condition occurs, and the execution of the READ statement is considered unsuccessful. See the topic I-O Status in the chapter Procedure Division.
For
sequential files or

files in sequential access mode, the NEXT phrase is optional and has no effect on the execution of the READ statement.

General Rules for Format 3 (Relative and Indexed Files)

Following a READ which encounters a locked record status, the file position indicator points at the locked record. A subsequent READ NEXT or READ PREVIOUS will retrieve the same record again.
The NOT AT END phrase is only executed following successful completion of the operation.
If when a READ statement with the PREVIOUS option is executed no previous logical record exists in the file, the AT END condition occurs, and the execution of the READ statement is considered unsuccessful.
When the AT END condition has been recognized,
the next Format 3 READ statement, if any, executed for that file must be a READ NEXT statement, if AT END occurred because no previous logical record existed. Otherwise

the AT END condition must be followed by:
1. A successful CLOSE statement followed by the execution of a successful OPEN statement for that file.
2. A successful START statement for that file.
3. A successful Format 4 (or Format 5 for indexed files) READ statement for that file.
For a file for which dynamic access mode is specified, a READ statement with the NEXT phrase specified causes the next logical record to be retrieved from the file
as described in General Rule 8.
The record to be made available by the READ statement is determined as follows:
1. If the file position indicator was positioned by the execution of an OPEN statement, and the PREVIOUS option is specified, the AT END condition occurs. Otherwise
  if the file position indicator was positioned by the execution of the START or OPEN statement and the record is still accessible through the path indicated by the file position indicator, the record pointed to by the file position indicator is made available. If the record is no longer accessible, which can have been caused for a relative file by deletion of the record, or for an indexed file by a change in an alternate key, the file position indicator is updated to point to the next
  
  or, if the PREVIOUS option is specified, the previous
  
  existing record within the established key of reference, and that record is then made available.
2. If the file position indicator was positioned by the execution of a previous READ statement, the file position indicator is updated to point to the next
  or, if the PREVIOUS option is specified, the previous
  
  existing record in the file.
  
  However, if the previous statement was a READ, and if that READ returned a locked record status, the file position indicator is left unchanged. The record pointed to by the file position indicator is made available.

General Rules for Formats 1, 3, 4 and 5 (Sequential, Relative and Indexed Files)

If the lock mode is MANUAL with single record locking and the referenced file is opened I/O, the run unit acquires a record lock on the record only if the WITH LOCK phrase is specified. A simple READ statement does not acquire a record lock. To read past a locked record the file position indicator should be updated using the START statement. This, however, cannot be used on alternate keys which allow duplicates.
If the lock mode is MANUAL with multiple record locking and the referenced file is opened I/O, the run unit acquires a lock on the record only if the WITH KEPT LOCK phrase is specified. A simple READ statement does not acquire a record lock. To read past a locked record the file position indicator should be updated using the START statement. This, however, cannot be used on alternate keys which allow duplicates.
The WITH WAIT phrase ensures that a lock is acquired on the record, waiting if necessary.

General Rules for Format 3 (Relative Files)

If the RELATIVE KEY phrase is specified for the file, the execution of a READ statement updates the contents of the RELATIVE KEY data item so that it contains the relative record number of the record made available.

General Rules for Format 4 (Relative Files)

The execution of a READ statement sets the file position indicator to, and makes available, the record whose relative record number is contained in the data item named in the RELATIVE KEY phrase for the file. If the file does not contain such a record, the INVALID KEY condition exists and execution of the READ statement is unsuccessful. (See the topic The INVALID KEY Condition in the chapter Procedure Division.)

General Rules for Formats 3 and 5 (Relative and Indexed Files)

The IGNORE LOCK phrase causes the READ to proceed as if the record were not locked.

General Rules for Format 3 (Indexed Files)

For an indexed file being sequentially accessed, records having the same duplicate value in an alternate record key which is the key of reference are made available in the same order in which they are released by execution of WRITE statements, or by execution of REWRITE statements which create such duplicate values.

General Rules for Format 5 (Indexed Files)

If the KEY phrase is not specified the prime record key is established as the key of reference for this retrieval. If dynamic access mode is specified, this key of reference is also used for retrievals by any subsequent executions of Format 3 READ statements for the file.
If the KEY phrase is specified, data-name-1
or split-key-name

is established as the key of reference for this retrieval. If dynamic access mode is specified, this key of reference is also used for retrievals by any subsequent executions of Format 3 READ statements for the file until a different key of reference is established for the file.
Execution of a Format 5 READ statement causes the value of the key of reference to be 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. The file position indicator is positioned to this record which is then made available. If no record can be so identified, the INVALID KEY condition exists and execution of the READ statement is unsuccessful. (See the topic The INVALID KEY Condition in the chapter Procedure Division.)