READ Statement - Format 5 - Transaction (Subfile)
READ - Format 5a - Transaction (Subfile Sequential) >>-READ SUBFILE--file-name--+------+--MODIFIED--+--------+------> '-NEXT-' '-RECORD-' >--+--------------------+---------------------------------------> '-INTO--identifier-1-' >--+----------------------------------+-------------------------> '-FORMAT--+----+--+-identifier-2-+-' '-IS-' '-literal-1----' >--+------------------------------------+-----------------------> '-TERMINAL--+----+--+-identifier-3-+-' '-IS-' '-literal-2----' >--+---------------------------------------+--------------------> '-+-INDICATOR--+--+-----+--identifier-4-' +-INDICATORS-+ +-IS--+ '-INDIC------' '-ARE-' >--+-------------------------------------+----------------------> '-+----+--END--imperative-statement-3-' '-AT-' >--+------------------------------------------+--+----------+-->< '-NOT--+----+--END--imperative-statement-4-' '-END-READ-' '-AT-'
Format 5a is used to read a format that is a subfile record, in sequential access mode. The NEXT MODIFIED phrase must be specified to access subfile records sequentially. The AT END phrase can only be specified with the NEXT MODIFIED phrase.
READ - Format 5b - Transaction (Subfile Random) >>-READ SUBFILE--file-name--+--------+--------------------------> '-RECORD-' >--+--------------------+---------------------------------------> '-INTO--identifier-1-' >--+----------------------------------+-------------------------> '-FORMAT--+----+--+-identifier-2-+-' '-IS-' '-literal-1----' >--+------------------------------------+-----------------------> '-TERMINAL--+----+--+-identifier-3-+-' '-IS-' '-literal-2----' >--+---------------------------------------+--------------------> '-+-INDICATOR--+--+-----+--identifier-4-' +-INDICATORS-+ +-IS--+ '-INDIC------' '-ARE-' >--+------------------------------------------+-----------------> '-INVALID--+-----+--imperative-statement-1-' '-KEY-' >--+----------------------------------------------+-------------> '-NOT INVALID--+-----+--imperative-statement-2-' '-KEY-' >--+----------+------------------------------------------------>< '-END-READ-'
Format 5b is used to read a format that is a subfile record, in random access mode. The INVALID KEY phrase can only be used for random access of subfile records. The NEXT MODIFIED phrase must not be used to randomly access subfile records.
- NEXT MODIFIED Phrase
- When NEXT MODIFIED is not specified, the data record made available
is the record in the subfile with a relative record number that corresponds
to the value of the RELATIVE KEY data item.
When the NEXT MODIFIED phrase is not specified, and if the RELATIVE KEY data item contains a value other than the relative record number of a record in the subfile, the INVALID KEY condition exists and the execution of the READ statement is unsuccessful.
When the NEXT MODIFIED phrase is specified, the record made available is the first record in the subfile that has been modified (has the Modified Data Tag on).
The search for the next modified record begins:- At the beginning of the subfile if:
- An I-O operation has been performed for the subfile control record.
- The I-O operation cleared, initialized, or displayed the subfile.
- For all other cases, with the record following the record that was read by a previous read operation.
The value of the RELATIVE KEY data item is updated to reflect the relative record number of the record made available to the program.
If NEXT MODIFIED is specified and there is no user-modified record in the subfile with a relative record number greater than the relative record number contained in the RELATIVE KEY data item, the AT END condition exists, the file status is set to 12, and the value of the RELATIVE KEY data item is not updated. Imperative-statement-2, or any applicable USE AFTER ERROR/EXCEPTION procedure, is then executed.
- At the beginning of the subfile if:
- FORMAT Phrase
- When a format-name is not specified, the format used is the last
record format written to the display device that contains input fields,
input/output fields, or hidden fields. If no such format exists for
the display file, the format used is the record format of the last
WRITE operation to the display device.
If the FORMAT phrase is specified, literal-1 or the contents of identifier-2 must specify a format which is active for the appropriate program device. The READ statement reads a data record of the specified format.
The FORMAT phrase must always be specified for multiple format files to ensure correct results.
- TERMINAL Phrase
- See Format 4 above for general considerations concerning the TERMINAL
phrase.
For a Format 5a or 5b READ, if the TERMINAL phrase is omitted for a file that has multiple devices acquired for it, a record is read from the subfile associated with the default program device.
- INDICATOR Phrase, INDICATORS Phrase, INDIC Phrase
- Specifies which indicators are to be read when a data record is
read. Indicators can be used to pass information about the data record
and how it was entered into the program.
For detailed information on the INDICATORS phrase, refer to Using Indicators with Transaction Files in the IBM® Rational® Development Studio for i: ILE COBOL Programmer's Guide .
Identifier-4 must be either an elementary Boolean data item specified without the OCCURS clause or a group item that has elementary Boolean data items subordinate to it.
- INVALID KEY Phrase
- If the RELATIVE KEY data item at the time of the execution of
the READ statement contains a value that does not correspond to a
relative record number for the subfile, the INVALID KEY condition
exists and the execution of the READ statement is unsuccessful.
The INVALID KEY phrase must be specified if the NEXT MODIFIED phrase is not specified and there is no applicable USE procedure specified for the file-name.
For information about what happens when the invalid key condition occurs, see INVALID KEY Condition.
- NOT INVALID KEY Phrase
- This phrase specifies the procedures that will be performed when an invalid key condition does not exist for the statement that is used.
- AT END Phrase
- If NEXT MODIFIED is specified and there is no user-modified record
in the subfile, the AT END condition exists, and the execution of
the READ statement is unsuccessful.
The AT END phrase should be specified when the NEXT MODIFIED phrase is used, and no applicable USE procedure is specified for the file-name. If the AT END phrase and a USE procedure are both specified for a file, and the AT END condition arises, control transfers to the AT END imperative statement and the USE procedure is not executed.
- NOT AT END Phrase
- This phrase allows you to specify procedures that will be performed when the AT END condition does not exist for the statement that is used.
- 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.
