+-------------------------------IBM Extension--------------------------------+
The READ statement makes a record from a device available, using a named format. If the format is a subfile, the READ statement makes a specified record available from that subfile.
READ Statement - Format 4 - Transaction (Nonsubfile)
>>-READ--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-'
>--+---------------------------------+-------------------------->
'-NO DATA--imperative-statement-1-'
>--+-------------------------------------+---------------------->
'-+----+--END--imperative-statement-2-'
'-AT-'
>--+------------------------------------------+--+----------+--><
'-NOT--+----+--END--imperative-statement-3-' '-END-READ-'
'-AT-'
Format 4 is used only to read a format that is not a subfile record. The RELATIVE KEY data item, if specified in the FILE-CONTROL entry, is not used. The Format 4 READ statement is not valid for a subfile record; however, a Format 4 READ statement for the subfile control record format must be used to put those subfile records that were updated on a display into the subfile.
If the data is available, it is returned in the record area. The names of the record format and the program device are returned in the I-O-FEEDBACK area and in the CONTROL-AREA.
The READ statement is valid only when there are acquired devices for the file. If a READ is executed and there are no acquired devices, the file status is set to 92 (logic error).
The manner in which the Format 4 READ statement functions depends on whether:
In the following discussions, references to "data available or returned" include the situation where only the response indicators are set. This is so even when a separate indicator area is used and the indicators are not returned in the record area for the file.
The following chart shows the possible combinations of phrases, and the
function performed for a single device file or a multiple device file.
For example, if TERMINAL is N, FORMAT is N, and NO DATA is N, then the single
device is D and multiple device is A.
| Phrase | Y=Yes N=No | |
|---|---|---|
| Checked at Compilation |
TERMINAL3 FORMAT3 NO DATA |
N N N N Y Y Y Y N N Y Y N N Y Y N Y N Y N Y N Y |
| Determined at Execution |
Single Device Multiple Device |
D C D B D C D B A A D B D C D B |
Codes A through D are explained below.
Code A-Read From Invited Program Device (Multiple Device Files only)
This type of READ receives data from the first invited program device that has data available. An invited program device is a workstation or communications device (such as APPC, SNUF, BSCEL, Asynchronous Communications) that has been invited to send input. Inviting is done by writing to the program device with a format that has the DDS keyword INVITE specified. Once an invited program device is actually read from, it is no longer invited. That program device will not be used for input by another READ statement unless re-invited, or unless a READ is directed to it specifying the TERMINAL phrase or FORMAT phrase.
The record format returned from the program device is determined by the system. For information on how this is determined for work stations, refer to the File Systems and Management section of the Database and File Systems category in the iSeries Information Center at this Web site - http://www.ibm.com/eserver/iseries/infocenter. For communications devices, see the ICF Programming manual for more information on format selection processing for an ICF file.
This READ can complete without returning any data in the following cases:
If data is available, it is returned in the record area. The record format is returned in the I-O-FEEDBACK area and in the CONTROL-AREA. For more information about "reading from invited program devices," see the Application Display Programming manual for display stations, and the ICF Programming manual for communications devices.
Code B-Read From One Program Device (Invalid combination)
A compilation time message is issued and the NO DATA phrase is ignored. See the table entry for the same combination of phrases with the NO DATA phrase omitted.
Code C-Read From One Program Device (with NO DATA phrase)
This function of the READ statement never causes program execution to stop and wait until data is available. Either the data is immediately available or the NO DATA imperative statement is executed.
This READ function can be used to periodically check if data is available from a particular program device (either the default program device or one specified by the TERMINAL phrase). This checking for data is done in the following manner:
Code D-Read From One Program Device (without NO DATA Phrase)
This READ always waits for data to be made available. Even if the job receives a controlled cancellation, or a WAITRCD time is specified for the file, the program will never regain control from the READ statement. This READ operation is performed in the following manner:
OR
If the TERMINAL phrase is omitted for a READ of a Transaction file that has acquired multiple program devices, the default program device is used.
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.
For detailed information on the INDICATORS phrase, refer to Using Indicators with Transaction Files in the ILE COBOL for AS/400 Programmer's Guide.
The AT END phrase should be specified when 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 run.
For more information, see Delimited Scope Statements.
Related Information
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.
Format 5a or 5b cannot be used for communications devices. If the subfile format of the READ statement is used for a communications device, the READ fails and a file status of 90 is set.
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:
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.
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.
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.
For detailed information on the INDICATORS phrase, refer to Using Indicators with Transaction Files in the ILE COBOL for AS/400 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.
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.
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.
For more information, see Delimited Scope Statements.
Related Information
+----------------------------End of IBM Extension----------------------------+
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.