READ

Read a record from a file.

READ

Conditions: DISABLED, DUPKEY, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, LOADING, LOCKED, NOTAUTH, NOTFND, NOTOPEN, RECORDBUSY, SYSIDERR

This command is threadsafe if the file to which it refers is:

Defined as remote and the command is function shipped over an IPIC connection to a remote CICS® region.
Defined as either local VSAM or RLS.

This command is not threadsafe if the file to which it refers is:

Defined as remote and the command is function shipped over a non-IPIC connection.
Defined as a shared data table, coupling facility data table, or BDAM file.

Description

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.

Data table considerations

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.

Reading files accessed in RLS mode

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.

If you want to use the level of read integrity specified in the READINTEG keyword of the FILE definition, and then you need to change from using a local file to a remote file, or if you change the location of a remote file, ensure that:

The remote file-owning region supports the read integrity options.
The FILE definition in the remote system specifies:
- RLS mode
- The correct read integrity values for your application.

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.

If a request specifying read integrity is function-shipped to a member of the CICS family of products that does not support read integrity, the request fails:

If an ISC link is used, the request receives an ATNI abend.
If an MRO link is used, the request receives an AXF8 abend.
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.

Retained and active locks

RECORDBUSY refers to active locks and LOCKED refers to retained locks.

These locks affect READ requests which acquire locks; that is, update requests and requests with read integrity. These are the kinds of READ requests which are referred to in the following bullets. Other READ requests are unaffected by the presence of retained or active locks.

READ requests for records that have retained locks are always rejected with a LOCKED response.
READ requests for records that have active locks wait for the lock to be released, except when the NOSUSPEND keyword is specified, in which case CICS returns the RECORDBUSY response.

Options

CONSISTENT (RLS only)

The record is read with a level of read integrity provided by a VSAM shared lock that lasts for the duration of the request.

If the record is being modified by another task, which therefore holds an exclusive lock, the READ request waits until the update is complete (unless NOSUSPEND is also specified) as follows:

For a READ request against a non-recoverable file, the READ completes as soon as any VSAM request performing the update completes.
For a READ request against a recoverable file, the READ request completes when the updating task completes its next sync point or rollback.

DEBKEY

(blocked BDAM) specifies that deblocking is to occur by key. If neither DEBREC nor DEBKEY is specified, deblocking does not occur.

DEBREC

(blocked BDAM) specifies that deblocking is to occur by relative record (relative to zero). If neither DEBREC nor DEBKEY is specified, deblocking does not occur.

EQUAL

specifies that the search is satisfied only by a record having the same key (complete or generic) as that specified in the RIDFLD option.

FILE(filename)

specifies the name of the file to be accessed.

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.

GENERIC

(VSAM KSDS, paths and data tables) specifies that the search key is a generic key whose length is specified in the KEYLENGTH option. The search for a record is satisfied when a record is found that has the same starting characters (generic key) as those specified.

GTEQ

(VSAM KSDS, paths and data tables) specifies that, if the search for a record that has the same key (complete or generic) as that specified in the RIDFLD option is unsuccessful, the first record that has a greater key is retrieved.

INTO(data-area)

specifies the data area into which the record retrieved from the data set is to be written.

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.

KEYLENGTH(data-value)

specifies the length (halfword binary) of the key that has been specified in the RIDFLD option, except when RBA or RRN is specified, in which case the KEYLENGTH value is not valid. This option must be specified if GENERIC is specified, and it can be specified whenever a key is specified. However, if the length specified is different from the length defined for the data set and the operation is not generic, the INVREQ condition occurs.

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.

LENGTH(data-area)

specifies the length, as a halfword binary value, of the data area where the record is to be put. On completion of the READ command, the LENGTH parameter contains the actual length of the record.

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 the file is on a local system, the LENGTH parameter must be set for variable-length records, using the INTO option, but not for fixed-length records. It is, however, advisable to specify the length for fixed-length records because:

It causes a check to be made that the record being read is not too long for the available data area.
When reading fixed-length records into an area longer than the record being accessed, the LENGERR condition is raised for COBOL, C, PL/I, and assembler-language applications if the LENGTH option is specified. If the LENGTH option is not explicitly specified, then the LENGERR condition is returned if the length can be inferred from the data area. If the length specified exceeds the file record length, CICS uses the longer length for the move. If the target area in the application program is not large enough, storage is overlaid beyond the target area.

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.

NOSUSPEND (RLS only)

The request does not wait if the record is locked by VSAM with an active lock, including records locked as the result of a DEADLOCK.

Note: Requests that specify NOSUSPEND wait for at least 1 second before CICS returns the RECORDBUSY response.

RBA

(VSAM KSDS or ESDS base data sets, or CICS-maintained data tables only, but not paths) specifies that the record identification field specified in the RIDFLD option contains a relative byte address. This option should be used only when reading records from an ESDS base or when reading from a KSDS base and using relative byte addresses instead of keys to identify the records.

You cannot use RBA for:

User-maintained data tables
Coupling facility data tables
Any KSDS file opened in RLS access mode
KSDS files that use extended addressing

Also, you are recommended not to use RBA for ESDS files that hold more than 4GB. (Use XRBA instead.)

REPEATABLE (RLS only)

The record is read with a level of read integrity provided by a VSAM shared lock that lasts for the duration of the unit of work in which the read request is issued.

If the record is being modified by another task, which therefore holds an exclusive lock, the READ request waits until the update is complete (unless NOSUSPEND is also specified) as follows:

For a recoverable file, the READ request completes when the updating transaction completes its next syncpoint or rollback.
For a non-recoverable file, the READ completes as soon as the VSAM request performing the update completes.

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.

RIDFLD(data-area)

specifies the record identification field. The contents can be a key, a relative byte address, or relative record number (for VSAM data sets), or a block reference, a physical key, and a deblocking argument (for BDAM data sets). For a relative byte address or a relative record number, the format of this field must be fullword binary. For a relative byte address, the RIDFLD value can be greater than or equal to zero. For a relative record number, the RIDFLD value must be greater than or equal to 1, even when the GTEQ option is specified.

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.

RRN

(VSAM RRDS) specifies that the record identification field specified in the RIDFLD option contains a relative record number. This option should only be used with files that reference relative record data sets.

SET(ptr-ref)

indicates that CICS is to supply a buffer where the record is read, and specifies the pointer reference that is to contain the address of the retrieved record.

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.

SYSID(systemname)

specifies the name of the system the request is directed to.

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(data-area)

specifies, as a fullword binary value, a unique identifier for this READ UPDATE request. This is an output value returned by file control to the requesting task, for use in associating a subsequent REWRITE or DELETE (or UNLOCK) request with the record returned on this READ UPDATE request.

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.

Note: If you specify TOKEN it implies update.

UNCOMMITTED

The record is read without read integrity.

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.

UPDATE

specifies that the record is to be obtained for updating or (for VSAM and data tables) deletion. If this option is omitted, a read-only operation is assumed.

UPDATE guarantees read integrity. The mechanism used to ensure data integrity depends on the type of file resource:

For a VSAM file accessed in RLS mode, the record to be updated is locked by the SMSVSAM server.
For a VSAM file accessed in non-RLS mode, the record to be updated is locked by CICS and, in addition, the control interval containing the record is held in exclusive control by VSAM.
For a VSAM file accessed in non-RLS mode, and log(UNDO), CICS holds a record lock until the task syncpoints.
For a BDAM file, the record to be updated is held in exclusive control by BDAM.
For a user-maintained data table, the record to be updated is locked by CICS.
For a CICS-maintained data table, the record to be updated is locked by CICS and, in addition, the control interval containing the record is held in exclusive control by VSAM. The VSAM control interval lock is required because changes to the data table are reflected in the source data set, which is accessed in non-RLS mode.
For a coupling facility data table using the locking model, the record to be updated is locked by the coupling facility data table server.
For a coupling facility data table using the contention model, records are not locked, enabling the records to be read for update by more than one task. If a record read for update by one task is then changed by another, the first task is notified, when it issues a REWRITE or DELETE command, by the CHANGED exception condition. If a record read for update by one task is then deleted by another, the first task is notified, when it issues a REWRITE or DELETE command, by the NOTFND condition.

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).

XRBA

specifies that the record identification field specified in the RIDFLD option contains an extended relative byte address. This option should be used when reading records from an ESDS extended addressing data set.

KSDS data sets cannot be accessed by XRBA.

Conditions

84 DISABLED

RESP2 values:

50: A file is disabled because it was initially defined as disabled and has not since been enabled.
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.

15 DUPKEY

RESP2 values: (VSAM)

140: A record is retrieved by way of an alternate index with the NONUNIQUEKEY attribute, and another alternate index record with the same key follows
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.

12 FILENOTFOUND

RESP2 values:

1: The file name supplied in the FILE option is not defined to CICS.

Default action: terminate the task abnormally.

21 ILLOGIC

RESP2 values: (VSAM)

110

A VSAM error occurs that is not in one of the other CICS response categories.

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.

16 INVREQ

RESP2 values:

20: READ is not allowed according to the resource definition.
A READ command with the UPDATE option is issued to a file where update operations are not allowed according to the resource definition.
25: The KEYLENGTH and GENERIC options are specified, and the length specified in the KEYLENGTH option is greater than or equal to the length of a full key.
26: The KEYLENGTH option is specified (but the GENERIC option is not specified), and the specified length does not equal the length defined for the data set to which this file refers.
28: Following a READ UPDATE command without TOKEN, another READ UPDATE without TOKEN was issued against the same file without an intervening REWRITE, DELETE without RIDFLD specified, UNLOCK, or SYNCPOINT command. This condition may in some cases be raised despite the fact that the first READ UPDATE was not successful, for example because it timed out.
40: A BDAM key conversion error occurred.
42: The KEYLENGTH and GENERIC options are specified, and the length specified in the KEYLENGTH option is less than zero.
44: The command does not conform to the format of READ for a user-maintained or coupling facility data table; for example, if RBA is specified.
51: A READ to a KSDS file that is being accessed in RLS mode specifies the RBA keyword. RLS mode does not support relative byte address access to KSDS data sets.
52: CONSISTENT is specified on a READ request to a non-RLS mode file, or to a data table that is specified with RLSACCESS(YES). CONSISTENT is not allowed if the file refers to a data table, even if the file definition specifies RLSACCESS(YES).
53: REPEATABLE is specified on a READ request to a non-RLS mode file or to a data table that is specified with RLSACCESS(YES). REPEATABLE is not allowed if the file refers to a data table, even if the file definition specifies RLSACCESS(YES).
55: NOSUSPEND is specified on a READ request to a non-RLS mode file or to a data table that is specified with RLSACCESS(YES). NOSUSPEND is not allowed if the file refers to a data table, even if the file definition specifies RLSACCESS(YES).
56: An attempt to update a recoverable coupling facility data table has failed because the current unit of work has already updated 1024 recoverable coupling facility data tables. You cannot update more than 1024 recoverable coupling facility data tables within a unit of work.
59: XRBA was specified, but the data set is not an extended ESDS.

Default action: terminate the task abnormally.

17 IOERR

RESP2 values:

120

There is an I/O error during the READ operation. An I/O error is any unusual event that is not covered by a CICS condition.

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.

54 ISCINVREQ

RESP2 values:

70: The remote system indicates a failure that does not correspond to a known condition.

Default action: terminate the task abnormally.

22 LENGERR

RESP2 values:

10: Neither the LENGTH option nor the SET option is specified on a READ command for a file with variable-length records or for a BDAM file with variable-length or undefined-format records.
11: The length of a record read with the INTO option specified exceeds the value specified in the LENGTH option; the record is truncated, and the data area supplied in the LENGTH option is set to the actual length of the record.
13: An incorrect length is specified for a file with fixed-length records.

Default action: terminate the task abnormally.

94 LOADING

RESP2 values:

104

The request cannot be satisfied because it is issued against a data table that is still being loaded. The condition can be raised for one of the following reasons:

The READ specifies a record that has not yet been loaded into a coupling facility data table. Records can be read or modified while a CFDT is loading only if the requested key is within the range of those records already loaded.
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 .
The READ specifies the UPDATE option for a user-maintained data table. A user-maintained data table cannot be modified during loading.
The READ specifies the GENERIC or GTEQ options for a user-maintained data table. While a UMT is being loaded, you can use read requests with precise keys only.

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.

100 LOCKED

RESP2 values:

106: An attempt is being made to read a record either specifying the UPDATE keyword, or specifying (explicitly or implicitly) CONSISTENT or REPEATABLE, but the record is locked by a retained lock (see Retained and active locks).
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.

70 NOTAUTH

RESP2 values:

101: A resource security check has failed on FILE(filename).

Default action: terminate the task abnormally.

13 NOTFND

RESP2 values:

80: An attempt to retrieve a record based on the search argument provided is unsuccessful. For data tables, this condition occurs if an attempt to read a record is unsuccessful because there is no entry with the specified key in the data table. This does not mean that there is no such record in the source data set (if the table was created from one); it may be that such a record is present but was either rejected during initial loading by the user exit XDTRD, or was subsequently deleted from the data table. For remote files, this condition occurs if an attempt to read a record is made without keylength specified either in the application or the file definition, and the actual key is longer than 4 characters.
81: XRBA was specified, and the value of RIDFLD was greater than 4 GB, but the data set is not an extended ESDS.

Default action: terminate the task abnormally.

19 NOTOPEN

RESP2 values:

60

NOTOPEN (RESP2 60) is returned for one of the following reasons:

The requested file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file and the file is no longer in use. You can also make CLOSED, UNENABLED the initial state, by specifying STATUS(UNENABLED) and OPENTIME(FIRSTREF) on the FILE resource definition. (For BDAM files, you use the FILSTAT parameter of DFHFCT TYPE=FILE.)
The requested file is OPEN and in use by other transactions, but a CLOSE request against the file has been received.
A READ command is issued against a data set that is quiesced, or is being quiesced, as a result of a SET DSNAME QUIESCED or IMMQUIESCED command.
The requested file is CLOSED and ENABLED, so CICS has tried to open the file as part of executing the request. This file open has failed for some reason. You should examine the console for messages that explain why the file open has been unsuccessful.

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.

101 RECORDBUSY

RESP2 values:

107: The NOSUSPEND keyword is specified and the record is locked by an active lock (see Retained and active locks).

Default action: abend the task with code AEX9.

53 SYSIDERR

RESP2 values:

130: The SYSID option specifies a name that is neither the local system nor a remote system that is defined by a CONNECTION or IPCONN definition. SYSIDERR also occurs when the link to the remote system is known but unavailable. In the case of an IPCONN, SYSIDERR occurs if the link is known but either the local or remote systems do not support file control commands that are function shipped using IP interconnectivity.
131: For a coupling facility data table, the connection to the coupling facility data table server has failed. This could be because the server itself has failed, or the server is available, but CICS has failed to connect to it.
132: The READ is issued for a coupling facility data table that no longer exists, probably because of a coupling facility failure, in which case the coupling facility data table server also fails. See the Setting up and running a coupling facility data table server for information about restarting a coupling facility data table server and reloading a table.

Default action: terminate the task abnormally.

Examples

The following example shows you how to read a record from a file named MAIN into a specified data area:

EXEC CICS READ
     INTO(RECORD)
     FILE('MAIN')
     RIDFLD(ACCTNO)

The following example shows you how to read a record for update from a VSAM file using a generic key and specifying a greater-or-equal key search.

EXEC CICS READ
     INTO(RECORD)
     LENGTH(RECLEN)
     FILE('MASTVSAM')
     RIDFLD(ACCTNO)
     KEYLENGTH(4)
     GENERIC
     GTEQ
     UPDATE