READ Statement - Format 3 - Random Retrieval

Read syntax diagramSkip visual syntax diagram
READ Statement - Format 3 - Random Retrieval

>>-READ--file-name--+--------+--+--------------------+---------->
                    '-RECORD-'  '-INTO--identifier-1-'   

>--+-----------------------+--+--------------------------+------>
   |                   (1) |  '-KEY--+----+--data-name-1-'   
   '-+------+--NO LOCK-----'         '-IS-'                  
     '-WITH-'                                                

>--+--------------------------------------+--------------------->
   |        (1)                           |   
   '-FORMAT------+----+--+-identifier-2-+-'   
                 '-IS-'  '-literal-1----'     

>--+----------------------------------------+------------------->
   |              (1)                       |   
   '-NULL-KEY-MAP------+----+--identifier-5-'   
                       '-IS-'                   

>--+------------------------------------+----------------------->
   |          (1)                       |   
   '-NULL-MAP------+----+--identifier-6-'   
                   '-IS-'                   

>--+------------------------------------------+----------------->
   '-INVALID--+-----+--imperative-statement-1-'   
              '-KEY-'                             

>--+----------------------------------------------+------------->
   '-NOT INVALID--+-----+--imperative-statement-2-'   
                  '-KEY-'                             

>--+----------+------------------------------------------------><
   '-END-READ-'   

Notes:
  1. IBM® Extension
file-name
File-name must be defined in a Data Division FD entry, and must not name a sort or merge file.
RECORD
The next record in the sequence of records.
KEY IS data-name-1
This phrase is specified only for indexed files. Data-name-1 can be qualified; it cannot be subscripted. Data-name-1 must identify a record key associated with file-name.
IBM Extension

IBM Extension Data-name-1 can be defined as a DBCS data-item. When the RECORD KEY clause specifies a DBCS data-item, a KEY specified on the READ statement must be a DBCS data-item. End of IBM Extension

End of IBM Extension
INTO Phrase
The INTO identifier phrase makes a READ statement equivalent to:
  • READ file-name RECORD
  • MOVE record-name TO identifier

After successful processing of the READ statement, the current record becomes available both in the record-name and identifier.

When the INTO identifier phrase is specified, the current record is moved from the input area to the identifier area according to the rules for the MOVE statement without the CORRESPONDING phrase. Any subscripting, indexing, or reference modification associated with the identifier is evaluated after the record has been read and immediately before it is transferred to the identifier. (See also INTO/FROM Identifier Phrase.)

The INTO phrase may be specified in a READ statement if:
  • Only one record description is subordinate to the file description entry, or,
  • All record-names associated with file-name, and the data item referenced by identifier-1, describe a group item or an elementary alphanumeric item.

When using the INTO identifier phrase with variable length records, the amount of data moved to the receiver is equal to the length of the variable length record being read.

identifier-1
Identifier-1 is the receiving field. The current record is moved from the record area to that specified by identifier-1 according to the rules of the MOVE statement without the CORRESPONDING phrase. The following usage notes apply:
  • The size of the current record depends on the rules specified in the RECORD clause
  • If the file description entry contains a RECORD IS VARYING clause, the move is a group move
  • The implied MOVE statement occurs only if the execution of the READ statement is successful
  • Subscripting or reference modification associated with identifier-1 applies after reading the record 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
  • The INTO phrase is allowed in a READ statement only if
    • Only one record description is subordinate to the file description entry, or
    • All record names associated with file-name-1, and the 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
IBM Extension
IBM Extension
  • Identifier-1 can be a floating-point data item.
  • Identifier-1 can be a DBCS data-item.
  • Identifier-1 can be a date-time data-item.
End of IBM Extension
End of IBM Extension
IBM Extension
IBM Extension
NO LOCK Phrase
The NO LOCK phrase prevents the READ operation from obtaining record locks on files that you open in I-O (update) mode. In addition, a READ operation bearing the NO LOCK phrase will be successful even if the record that is to be made available has been locked by another job. A READ statement bearing this phrase releases records that have been locked by a previous READ operation.

If the DUPLICATES phrase is specified for the file, a record that is read by a statement with the NO LOCK phrase cannot be processed by a DELETE or REWRITE statement.

If you use the NO LOCK phrase for a file that is not open in I-O mode, you will receive an error message at compilation time.

For information about file and record locking, see the IBM Rational® Development Studio for i: ILE COBOL Programmer's Guide.

FORMAT Phrase
The FORMAT phrase applies only when the READ statement is performed against an indexed file for which the ASSIGN specified DATABASE as the file device type.

The value specified in the FORMAT phrase contains the name of the record format to use for this I-O operation. The system uses this to specify or select which record format to operate on.

Identifier-2, if specified, must be an alphanumeric data item of 10 characters or less.

Literal-1, if specified, must be an uppercase character-string of 10 characters or less.

If the FORMAT phrase is not specified, the first format defined is used when accessing indexed files in random access mode.

A value of all blanks is treated as though the FORMAT phrase were not specified. If the value is not valid for the file, a FILE STATUS of 9K is returned and a USE procedure is invoked, if applicable for the file.

When the file is read in sequential access mode, the next record in the keyed sequence access path that has the requested format is made available. If omitted, the next record in the keyed sequence access path is made available.

When the file is read in random access mode, the key as defined for the specified format is used to get a record of that format. If a record of that format is not found, an INVALID KEY condition is raised. This occurs even when there are records that have the defined key, but that have a different record format.

If the format is omitted, the common key for the file is used to get the first record of any format that has that common key value. The common key for a file consists of the key fields common to all formats of a file for records residing on the database. The common key for a file is the leftmost key fields that are common across all record formats in the file. The common key is built from the data in the record description area using the first record format defined in the program for the file.

When the file is read in dynamic access mode, the next record made available is determined as follows:
Record FORMAT Phrase
Specified Omitted
NEXT The next record in the keyed sequence access path having the specified format is made available. The next record in the keyed sequence access path is made available regardless of its format.
PRIOR The record in the keyed sequence access path preceding the record identified by the file position indicator having the specified format is made available. The record in the keyed sequence access path preceding the record identified by the file position indicator is made available regardless of its format.
FIRST The first record in the keyed sequence access path having the specified format is made available. The first record in the keyed sequence access path is made available regardless of its format.
LAST The last record in the keyed sequence access path having the specified format is made available. The last record in the keyed sequence access path is made available regardless of its format.
None of the above The key as defined for the specified format is used to get a record of that format. If a record of that format is not found, an INVALID KEY condition is raised. This occurs even when there are records that have the defined key, but that have a different record format. The common key for the file is used to get the first record of any format that has that common key value. The common key for a file consists of the key fields common to all formats of a file for records residing on the database. The common key for a file consists of the leftmost key fields that are common across all record formats in the file. The common key is built from the data in the record description area using the first record format defined in the program for the file.
NULL-KEY-MAP IS Phrase
The NULL-KEY-MAP IS phrase indicates the value of the identifier, which corresponds to the null-byte map value supplied by data management for the key of the record to be processed. The identifier can be subscripted or reference modified.

The phrase can only be specified for an indexed file for which the ASSIGN clause specified DATABASE as the device type, and the ALWNULL attribute.

If the file has alternate keys, identifier-5 is associated with the null key map of the current key of reference.

For more information about using null-capable fields, refer to the IBM Rational Development Studio for i: ILE COBOL Programmer's Guide.

NULL-MAP IS Phrase
The NULL-MAP IS phrase indicates the value of the identifier, which corresponds to the null-byte map value supplied by data management for the record to be processed. The identifier can be subscripted or reference modified.

This phrase can be specified for any file for which the ASSIGN clause specified DATABASE as the device type, and the ALWNULL attribute.

For more information about using null-capable fields, refer to the IBM Rational Development Studio for i: ILE COBOL Programmer's Guide.

End of IBM Extension
End of IBM Extension
AT END Phrase
The AT END phrase applies only when a file is read in sequential access mode or dynamic access mode.
If a next record does not exist in the file when a sequential read is processed, an AT END condition occurs (the high order digit of the file status is 1), and READ statement processing is unsuccessful. The following actions take place:
  1. If the FILE STATUS clause is specified, the status key is updated to indicate an AT END condition.
  2. If the AT END phrase is specified, control is transferred to the AT END imperative statement. Any EXCEPTION/ERROR procedure for this file is not run.
  3. If the AT END phrase is not specified, any EXCEPTION/ERROR procedure for this file is run. Return from that procedure is to the next executable statement following the end of the READ statement.

When the AT END condition occurs, execution of the READ statement is unsuccessful. The contents of the associated record area are undefined and the file position indicator is set to indicate that no valid next record has been established.

If an AT END condition does not occur during the execution of a READ statement, the AT END phrase is ignored, if specified, 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 rules of the USE statement following the execution of any USE AFTER EXCEPTION procedure applicable to file-name-1.
  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 procedure 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.

Following the unsuccessful execution of a READ statement, the contents of the associated record area are undefined and the file position indicator is set to indicate that no valid next record has been established.

The AT END phrase must be specified if no explicit or implicit EXCEPTION/ERROR procedure is specified for the file.
Note: A sequential read is any READ statement for a file with sequential access, or a READ NEXT, READ PRIOR, READ FIRST, or READ LAST statement for a file with dynamic access.

A READ FIRST or READ LAST statement will result in an AT END condition if the file is empty, or if the FORMAT phrase has been used and no records in the file have the specified format.

When a file is being read in sequential access mode and the AT END condition is recognized, a successful CLOSE statement followed by a successful OPEN statement must be processed for this file before a further READ statement is attempted.

When a file is being read in dynamic access mode and the AT END condition is recognized, one of the following must be processed for the file before a further READ NEXT or READ PRIOR statement is attempted:
  • A successful CLOSE statement followed by a successful OPEN statement.
  • A successful START statement.
  • A successful random access READ statement.
  • A successful READ FIRST or READ LAST statement.

If a READ statement for a file with sequential access, or a READ NEXT or READ PRIOR statement for a file with dynamic access, is attempted after the AT END condition has occurred, and the file position indicator has not been reset by one of the specified methods, then a file status of 46 will be returned. Neither the AT END phrase nor the NOT AT END phrase will be executed.

NOT AT END Phrase
After each successful completion of a READ statement with the NOT AT END phrase (the high order digit of the file status is 0), control transfers to the imperative statement associated with the phrase.
INVALID KEY Phrase
The INVALID KEY phrase applies only when a relative or indexed file is read in random access mode or dynamic access mode.

The INVALID KEY phrase must be specified for files for which there is not an appropriate EXCEPTION/ERROR procedure.

For information about INVALID KEY phrase processing, see INVALID KEY Condition.

NOT INVALID KEY Phrase
The NOT INVALID KEY phrase applies only when a relative or indexed file is read in random access mode or dynamic access mode.

After the successful completion of a READ statement with the NOT INVALID KEY phrase, control transfers to the imperative statement associated with the phrase.

NEXT Phrase
The NEXT phrase applies only for dynamic access mode.

When a relative file is read dynamically and the NEXT phrase is specified, a sequential read is done. When omitted, a random read is done.

When an indexed file is read dynamically and the NEXT phrase is specified, a sequential read is done. If NEXT, FIRST, LAST and PRIOR are all omitted, a random access read is done.

If a READ NEXT operation is performed on a block of records, a READ PRIOR operation cannot occur until the block is empty. If a READ PRIOR operation is performed first, a READ NEXT operation cannot occur until the block is empty. If this is attempted, a file status of 9U will result. To recover from file status 9U, close the file, then open it again.

IBM Extension
IBM Extension
FIRST Phrase
The FIRST phrase applies only when indexed files are accessed dynamically. If NEXT, FIRST, LAST and PRIOR are all omitted, a random access read is done.
LAST Phrase
The LAST phrase applies only when indexed files are accessed dynamically. If NEXT, FIRST, LAST and PRIOR are all omitted, a random access read is done.
PRIOR Phrase
The PRIOR phrase applies only when indexed files are accessed dynamically. When specified, a sequential read is done. If NEXT, FIRST, LAST and PRIOR are all omitted, a random access read is done.

If a READ PRIOR operation is performed on a block of records, a READ NEXT operation cannot occur until the block is empty. If a READ NEXT operation is performed first, a READ PRIOR operation cannot occur until the block is empty. If this is attempted, a file status of 9U will result. To recover from file status 9U, close the file, then open it again.

End of IBM Extension
End of IBM Extension
END-READ Phrase
This explicit scope terminator serves to delimit the scope of the READ statement. END-READ permits a conditional READ statement to be nested in another conditional statement. END-READ may also be used with an imperative READ statement.

For more information, see Delimited Scope Statements.

Related Information