6.2.28 "COBOL Language Reference" IBM Library Server

6.2.28 READ Statement

For sequential access, the READ statement makes the next logical record from a file available to the object program. For random access, the READ statement makes a specified record from a direct-access file available to the object program.

When the READ statement is executed, the associated file must be open in INPUT or I-O mode.


    ___ Format 1--Sequential Retrieval _____________________________________ 
   |                                                                        |
   | >>__READ__file-name-1__ _______________ __ ________ _________________> |
   |                        |_NEXT__________|  |_RECORD_|                   |
   |                        |            (1)|                               |
   |                        |_ PREVIOUS ____|                               |
   |                                                                        |
   | >__ ____________________ ____________________________________________> |
   |    |_INTO__identifier-1_|                                              |
   |                                                                        |
   | >__ _____________________________________ ___________________________> |
   |    |_ ____ __END__imperative-statement-1_|                             |
   |      |_AT_|                                                            |
   |                                                                        |
   | >__ __________________________________________ __ __________ _______>< |
   |    |_NOT__ ____ __END__imperative-statement-2_|  |_END-READ_|          |
   |           |_AT_|                                                       |
   |                                                                        |
   | Note:                                                                  |
 X | (1)  PREVIOUS is only supported on AIX, OS/2, and Windows.             |
   |                                                                        |
   |________________________________________________________________________|


    ___ Format 2--Random Retrieval _________________________________________ 
   |                                                                        |
   | >>__READ__file-name-1__ ________ __ ____________________ ____________> |
   |                        |_RECORD_|  |_INTO__identifier-1_|              |
   |                                                                        |
   | >__ __________________________ ______________________________________> |
   |    |_KEY__ ____ __data-name-1_|                                        |
   |           |_IS_|                                                       |
   |                                                                        |
   | >__ __________________________________________ ______________________> |
   |    |_INVALID__ _____ __imperative-statement-3_|                        |
   |               |_KEY_|                                                  |
   |                                                                        |
   | >__ ______________________________________________ __ __________ ___>< |
   |    |_NOT INVALID__ _____ __imperative-statement-4_|  |_END-READ_|      |
   |                   |_KEY_|                                              |
   |                                                                        |
   |________________________________________________________________________|

file-name-1

Must be defined in a Data Division FD entry.

NEXT RECORD

Reads the next record in the logical sequence of records. NEXT is optional when ACCESS MODE IS SEQUENTIAL; it has no effect on READ statement execution.

>_Host_> Under OS/390 and VM, you must specify the NEXT RECORD phrase for files in dynamic access mode, which are retrieved sequentially. <_Host_<

X >_Workstation_> Under AIX, OS/2, and Windows, you must specify either
X the NEXT or PREVIOUS phrase for files in dynamic access mode, which
X are retrieved sequentially. <_Workstation_<

X PREVIOUS RECORD (Workstation Only)

X >_Workstation_> Reads the previous record in the logical sequence of
X records. PREVIOUS applies to indexed and relative files with DYNAMIC
X access mode.

X You must specify either the NEXT or PREVIOUS phrase for files in
X dynamic access mode, which are retrieved sequentially.

X If you specify READ...PREVIOUS and no previous logical record exists,
X the AT END condition occurs and the READ statement is unsuccessful.

X When you specify READ...PREVIOUS, the setting of the file position
X indicator is used to determine which record to make available
X according to the following rules:

X If the file position indicator indicates that no valid previous
X record has been established, the READ is unsuccessful.
X If the file position indicator is positioned by the execution of
X an OPEN statement, the AT END condition occurs.
X If the file position indicator is established by a previous START
X statement, the first existing record in the file whose relative
X record number (if a relative file) or whose key value (if an
X indexed file) is less than or equal to the file position indicator
X is selected.
X If the file position indicator is established by a previous READ
X statement, the first existing record in the file whose relative
X record number (if a relative file) or whose key value (if an
X indexed file) is less than the file position indicator is
X selected. <_Workstation_<

INTO Identifier-1

Identifier-1 is the receiving field.

The result of the execution of a READ statement with the INTO phrase is equivalent to the application of the following rules in the order specified:

The execution of the same READ statement without the INTO phrase.
The current record is moved from the record area to the area specified by identifier-1 according to the rules for the MOVE statement without the CORRESPONDING phrase. The size of the current record is determined by rules specified for the RECORD clause. If the file description entry contains a RECORD IS VARYING clause, the implied move is a group move. The implied MOVE statement does not occur if the execution of the READ statement was unsuccessful. Any subscripting or reference modification associated with identifier-1 is evaluated after the record has been read and immediately before it is moved to the data item. The record is available in both the record area and the data item referenced by identifier-1.
X If identifier-1 is a date field, then the implied MOVE statement
X is performed according to the behavior described under "Moves
X Involving Date Fields" in topic 6.2.24.1.1.

The INTO phrase can be specified in a READ if:

Only one record description is subordinate to the file description entry, or
All record-names associated with file-name-1, and the data item referenced by identifier-1, describe a group item or an elementary alphanumeric item.

The record areas associated with file-name-1 and identifier-1 must not be the same storage area.

X Identifier-1 (the record area) can be a DBCS or floating point data
X item.

X Multiple non-alphanumeric records can be specified for file-name-1.
X Identifier-1 need not describe a group item or an elementary
X alphanumeric item. The following rules apply:

X If the file referenced by file-name-1 is described as containing
X variable-length records, or as a QSAM file with RECORDING MODE 'S'
X or 'U', a group move will take place.
X If the file referenced by file-name-1 is described as containing
X fixed-length records, the movement will take place according to
X the rules for the MOVE statement, using, as a sending field
X description, the record that specifies the largest number of
X character positions. If more than one such record exists, the
X sending field record selected will be the one among those records
X that appears first under the description of file-name-1.

X >_OS/2_> Under OS/2, you can only READ a file with LOCK MODE AUTOMATIC if
X no other file connector holds a lock on the record you are trying to
X access. If the record is locked by another file connector, the READ
X statement is unsuccessful and the file status is set to indicate "record
X locked." For sequential files, the setting of the file position indicator
X is unaffected. <_OS/2_<

Subtopics:

Adobe, the Adobe logo, Acrobat, the Acrobat logo, and Acrobat Reader are registered trademarks of Adobe Systems incorporated.

6.2.28 READ Statement

IBM Library Server Copyright 1989, 2005 IBM Corporation. All rights reserved.