Read a record from a file.
READ >>-READ--FILE(filename)--+------------------------------+-------> +-UNCOMMITTED------------------+ +-CONSISTENT-------------------+ +-REPEATABLE-------------------+ '-UPDATE--+------------------+-' '-TOKEN(data-area)-' >--+-INTO(data-area)-+--RIDFLD(data-area)-----------------------> '-SET(ptr-ref)----' >--+------------------------------------+-----------------------> '-KEYLENGTH(data-value)--+---------+-' '-GENERIC-' >--+--------------------------------------+--+--------+---------> +-SYSID(systemname)--LENGTH(data-area)-+ +-DEBKEY-+ '-LENGTH(data-area)--------------------' +-DEBREC-+ +-RBA----+ +-RRN----+ '-XRBA---' .-EQUAL-. >--+-------+--+-----------+------------------------------------>< '-GTEQ--' '-NOSUSPEND-'
Conditions: DISABLED, DUPKEY, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, LOADING, LOCKED, NOTAUTH, NOTFND, NOTOPEN, RECORDBUSY, SYSIDERR
READ reads a record from a file on a local or a remote system.
For both UPDATE and non-UPDATE commands, you must identify the record to be retrieved by the record identification field specified in the RIDFLD option. Immediately upon completion of a READ UPDATE command, the RIDFLD data area is available for reuse by the application program.
When the READ command reads a CICS-maintained data table, a READ request with UPDATE or RBA is always satisfied by a call to VSAM. A full key read that is neither a generic read nor a READ UPDATE, is satisfied by a reference to the data table if possible. If the record is not found in the table, the source data set is accessed, unless the table is known to be complete, that is, all records in the source are also present in the table (which is the case if loading is finished and none has been rejected by a user exit).
If you carry out a generic read (using the GENERIC option) on a CICS-maintained data table, and CICS returns a NOTFND condition because the record is not found in the table, CICS clears the INTO() and RIDFLD() areas to ensure that an incorrect record is not returned. This behavior optimizes performance, but it differs from the behavior for a generic read of a VSAM file, when the INTO() and RIDFLD() areas are left unchanged in the event of a NOTFND condition. When you convert a VSAM file to a CICS-maintained data table, ensure that any applications that carry out generic reads of the data take appropriate action if a NOTFND condition is returned and the INTO() and RIDFLD() areas are cleared.
When the READ command reads a user-maintained data table, only the data table is accessed once loading is complete; the VSAM file is not changed in any way.
When the READ command reads a coupling-facility data table, only the data table is accessed, even if the table is initially loaded from a VSAM source data set.
If a file that refers to a user-maintained or coupling facility data table is defined with RLSACCESS(YES), the RLS-specific API options CONSISTENT, NOSUSPEND, and REPEATABLE are not supported.
When a file is accessed in RLS mode, non-update read requests can specify one of the read integrity options: UNCOMMITTED, CONSISTENT, or REPEATABLE.
If none of these keywords is specified, CICS uses the value specified on the READINTEG parameter of the FILE resource definition, for which the default is UNCOMMITTED.
READ requests that specify the UPDATE keyword, or a CONSISTENT or REPEATABLE read integrity option (either explicitly or implicitly in the FILE definition), return the LOCKED condition if they reference a record that has a retained lock. The key of a locked record is not returned to the application program. Thus, if an application program specifies GTEQ or GENERIC on the READ request it cannot tell which record key is locked.
The AXF8 abend code indicates that your program has attempted to function-ship a request that specifies file control options to a remote CICS region that does not support these options.
RECORDBUSY refers to active locks and LOCKED refers to retained locks.
If SYSID is specified, the data set to which this file refers is assumed to be on a remote system irrespective of whether the name is defined to CICS. Otherwise, the resource definition is used to find out whether the data set is on a local or a remote system.
When INTO is specified, LENGTH must either be specified explicitly or must be capable of being defaulted from the INTO option using the length attribute reference in assembler language, or STG and CSTG in PL/I. LENGTH must be specified explicitly in C.
The INVREQ condition also occurs if GENERIC is specified and the KEYLENGTH value is not less than that specified in the VSAM definition.
If KEYLENGTH(0) is used with the object of reading the first record in the data set, the GTEQ option must also be specified. If EQUAL is specified either explicitly or by default with KEYLENGTH(0), the results of the READ are unpredictable.
For remote files, the KEYLENGTH value can be specified in the FILE definition. If KEYLENGTH is not defined there, and is not specified in the application program, and the key is longer than 4 characters, the default value is 4.
This option must be specified if SYSID is specified.
If the file is on a remote system, the LENGTH parameter need not be set here but must be set in the file resource definition.
If you specify the SET option, you do not need to specify the LENGTH option.
When reading into a target data area that is longer than the record being read, the contents of the target data area, from the end of the retrieved record to the end of the target data area, are unpredictable.
If you specify the INTO option, the LENGTH argument must be a data area that specifies the largest record the program accepts. If the retrieved record is longer than the value specified in the LENGTH option, the record is truncated to the specified value and the LENGERR condition occurs. In this case, the LENGTH data area is set to the length of the record before truncation.
Note that a file control command issued against a variable-length record in a file defined on the local CICS system fails with a LENGERR condition if a length is not specified. However, if the same command is issued against a file defined on a remote system, the command does not fail.
After the READ request has completed, the record remains locked to the task that issued the READ. Other tasks may continue to read the record but no other task is allowed to update the record until the task that issued the READ performs its next syncpoint or rollback.
See Identifying BDAM records and Identifying VSAM records for more information about defining the record identification field.
Immediately upon completion of the command, the RIDFLD data area is available for reuse by the application program, even if UPDATE was specified.
Make sure that the variable specified by RIDFLD value is not shorter than the KEYLENGTH specified in this command or, if KEYLENGTH is not specified, the key length of the file you are reading; otherwise, the results are unpredictable.
If the DUPKEY condition occurs in assembler language the specified register has not been set. The specified register can be loaded from DFHEITP1.
The pointer reference is valid until the next READ command for the same file or until completion of a corresponding REWRITE, DELETE, or UNLOCK command, or a SYNCPOINT in the case of READ UPDATE SET. If you want to retain the data within the field addressed by the pointer, it should be moved to your own area.
If DATALOCATION(ANY) is associated with the application program, the address of the data can be above or below the 16 MB line.
If DATALOCATION(BELOW) is associated with the application program, the address of the data is below the 16 MB line.
If TASKDATAKEY (USER) is specified for the executing transaction, the data returned is in a user-key; otherwise it is in a CICS-key.
If you specify SYSID, and omit both RBA and RRN, you must also specify LENGTH and KEYLENGTH; they cannot be found in the resource definition.
TOKEN can be function shipped. However, if a request specifying TOKEN is function shipped to a member of the CICS family of products that does not recognize this keyword, the request fails.
The current value of the record, as known to VSAM, is returned. No attempt is made to serialize this read request with any concurrent update activity for the same record. The record may be in the process of being updated by another task, and the record data may change later if that update is subsequently backed out.
If another task has issued a READ REPEATABLE request against the same record, your READ UPDATE request is made to wait until that task reaches SYNCPOINT (unless you issued NOSUSPEND).
KSDS data sets cannot be accessed by XRBA.
A file is disabled because it has been disabled by a SET FILE or a CEMT SET FILE command.
Default action: terminate the task abnormally.
In assembler language, if the SET option is being used, the specified register has not been set, but can be loaded from DFHEITP1.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
See EIBRCODE in the EXEC interface block; for details, see EIB fields.
For user-maintained data tables, this condition occurs only for a non-UPDATE READ during loading when CICS has attempted to retrieve the record from the source data set.
Default action: terminate the task abnormally.
A READ command with the UPDATE option is issued to a file where update operations are not allowed according to the resource definition.
Default action: terminate the task abnormally.
For VSAM files, IOERR normally indicates a hardware error.
For user-maintained data tables, this condition occurs only for a non-UPDATE READ during loading when CICS has attempted to retrieve the record from the source data set.
For a coupling facility data table, an IOERR indicates a bad response returned from a coupling facility access.
Further information is available in the EXEC interface block; for details, see EIB fields.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
The LOADING response can also be returned for a coupling facility data table that has failed during loading. For more information about what happens if the load for a coupling facility data table fails, see the description of the XDTLC global user exit in Data tables management exits .
If your application programs encounter the LOADING condition persistently or too frequently, check that this is not caused by conflicting file definitions that reference the same data set.
Default action: terminate the task abnormally.
The LOCKED condition can also occur for a READ UPDATE request to a recoverable CFDT that uses the locking model, if the record being read is locked by a retained lock. See the Coupling facility data table retained locks for information about investigating retained locks on records in a coupling facility data table.
Default action: abend the task with code AEX8.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
This condition does not occur if the request is made to a CLOSED, DISABLED file. In this case, the DISABLED condition occurs.
Default action: terminate the task abnormally.
Default action: abend the task with code AEX9.
Default action: terminate the task abnormally.
EXEC CICS READ
INTO(RECORD)
FILE('MASTER')
RIDFLD(ACCTNO)
EXEC CICS READ
INTO(RECORD)
LENGTH(RECLEN)
FILE('MASTVSAM')
RIDFLD(ACCTNO)
KEYLENGTH(4)
GENERIC
GTEQ
UPDATE