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:
+-------------------------------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----------------------------+
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:
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.
+-------------------------------IBM Extension--------------------------------+
+----------------------------End of IBM Extension----------------------------+
+-------------------------------IBM Extension--------------------------------+
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 ILE COBOL for AS/400 Programmer's Guide.
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. |
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 ILE COBOL for AS/400 Programmer's Guide.
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 ILE COBOL for AS/400 Programmer's Guide.
+----------------------------End of IBM Extension----------------------------+
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:
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:
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.
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:
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.
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.
After the successful completion of a READ statement with the NOT INVALID KEY phrase, control transfers to the imperative statement associated with the phrase.
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--------------------------------+
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----------------------------+
For more information, see Delimited Scope Statements.
Related Information
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.