FILE READ

The CICS FILE READ statement retrieves a record from a VSAM dataset or a CICS-maintained file. READ also reads a record from a local or remote system file.

Key Features -

Reads a single record from a VSAM file (KSDS, ESDS, RRDS).
Uses relative byte address (RBA), key or relative record number (RRN) to fetch the record.
Supports reading fixed-length or variable-length records by specifying LENGTH.

Syntax -

EXEC CICS READ
     FILE('file-name')
	 [UPDATE]
	 [TOKEN(value)]
     INTO(data-area)
     [RIDFLD(record-id)]
     [KEYLENGTH(key-length)]
	 [GENERIC]
	 [SYSID(system-name)]
     [LENGTH(length)]
     [RBA|RRN|XRBA]
     [EQUAL | GTEQ]
     [RESP(response-field)]
     [RESP2(response-field2)]
     END-EXEC.

FILE('file-name') - Specifies the VSAM file name from which the record will be read.
UPDATE - Specifies that the record is to be retrievedfor updating (REWRITE) or deletion (DELETE). If this option is omitted, a read-only operation is assumed. UPDATE guarantees read integrity.
TOKEN(value) - Specifies a unique identifier for this READ with UPDATE request.
INTO(data-area) - Output. Defines the data area (variable) where the fetched record is stored.
RIDFLD(record-id) - Input. Specifies the record ID (primary key) used to locate the record (used for KSDS and RRDS).
KEYLENGTH(key-length) - Defines the length of the key field (only needed for KSDS). KEYLENGTH is not applicable when RRN is coded. KEYLENGTH must be coded if using SYSID.
GENERIC - Input. Allows partial key searches (used for KSDS when reading sequentially). Group of records can be selected for read by using the GENERIC option with generic key and the option is available to KSDS only.
LENGTH(length) - Input. Specifies the length of the record being read (used for variable-length records).
SYSID(system-name) - Specifies the system name to which the request is directed. If SYSID coded and omit RBA, XRBA and RRN, LENGTH and KEYLENGTH must be coded.
RBA|RRN|XRBA - Specifies the type of the file and data in the RIDFLD.
EQUAL - Specifies the record that matches the key coded in the RIDFLD should be retrieved.
GTEQ - SThis applies only to VSAM KSDS files. If an exact match is found, the corresponding record will be retrieved. If an exact match for the specified key in the RIDFLD is not found, the system will retrieve the first record with a key that is greater than the specified key.
RESP(response-variable) - Optional. It captures the response code of the READ operation and used to check if the command executed successfully or encountered an error.
RESP2(response2-variable) - Optional. It captures the response2 code of the READ operation when the error occured.

Short Examples -

Scenario1 - Reading a Record by Key from a KSDS File.

...
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CUSTOMER-RECORD.
   05 WS-CUST-ID        PIC X(10).
   05 WS-CUST-NAME      PIC X(30).
   05 WS-CUST-ADDRESS   PIC X(50).
   05 WS-CUST-PHONE     PIC X(15).
   
...
PROCEDURE DIVISION.

    MOVE "12345" TO WS-CUST-ID.

    EXEC CICS READ
         FILE('CUSTFILE')
         INTO(WS-CUST-RECORD)
         RIDFLD(WS-CUST-ID)
         RESP(WS-RESP)
         END-EXEC.

    IF WS-RESP NOT = 0 THEN
       ...
	END-IF.
	
    ...

The record key (WS-CUST-ID) is provided in the RIDFLD parameter. The READ command fetches the record from the CUSTFILE dataset.

Scenario2 - Reading a Record for Update.

...
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CUSTOMER-RECORD.
   05 WS-CUST-ID        PIC X(10).
   05 WS-CUST-NAME      PIC X(30).
   05 WS-CUST-ADDRESS   PIC X(50).
   05 WS-CUST-PHONE     PIC X(15).
   
...
PROCEDURE DIVISION.

    MOVE "12345" TO WS-CUST-ID.

    EXEC CICS READ
         FILE('CUSTFILE')
         INTO(WS-CUST-RECORD)
         RIDFLD(WS-CUST-ID)
         UPDATE
         RESP(WS-RESP)
         END-EXEC.

    IF WS-RESP NOT = 0 THEN

        MOVE "9876543210" TO WS-CUST-PHONE

        EXEC CICS REWRITE
             FILE('CUSTFILE')
             FROM(WS-CUST-RECORD)
             RESP(WS-RESP)
             END-EXEC

        IF WS-RESP = 0 THEN
			...
		END-IF
	END-IF.
	
    ...

The READ command is executed with the UPDATE option, meaning the record can be modified. The customer's phone number is updated. The REWRITE command updates the record in the VSAM file.

Error Conditions -

Eror Condition	RESP	RESP2	Reason
FILENOTFOUND	12	1	A file name in the FILE option is not defined to CICS.
NOTFND	13	80	An attempt to retrieve a record based on the search argument provided is unsuccessful.
NOTFND	13	81	XRBA was specified and the value of RIDFLD was greater than 4 GB, but the data set is not an extended ESDS.
DUPKEY	15	140	A record is accessed by way of an alternate index with the NONUNIQUEKEY attribute and another alternate index record with the same key follows.
INVREQ	16	20	READ is not allowed according to the resource definition.
	16	25	The KEYLENGTH, GENERIC options specified and the length in the KEYLENGTH option is greater than or equal to the length of a full key.
	16	26	The KEYLENGTH option is specified but the GENERIC option is not specified, and the length specified does not equal the length defined for the data set.
	16	28	Following a READ UPDATE command without TOKEN, another READ UPDATE without TOKEN was issued against the same file without an REWRITE, DELETE without RIDFLD, UNLOCK, or SYNCPOINT command in middle.
	16	42	The KEYLENGTH, GENERIC options and the length specified in the KEYLENGTH option is less than zero.
	16	51	A READ to a KSDS file that is being accessed in RLS mode specifies the RBA keyword.
	16	55	NOSUSPEND is specified on a READ request to a non-RLS mode file.
	16	59	XRBA was specified, but the data set is not an extended ESDS.
IOERR	17	120	There is an I/O error during the READ operation.
NOTOPEN	19	60	Below are the reasons for NOTOPEN - The requested file is CLOSED and UNENABLED. The requested file is OPEN and in use by other transactions, but a CLOSE request against the file has been received. The requested file is CLOSED and ENABLED, so CICS has tried to open the file as part of executing the request.
ILLOGIC	21	110	VSAM error occurs that is not in one of the other CICS response categories.
22 LENGERR	22	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.
	22	11	The length of a record read with the INTO option exceeds the value specified in the LENGTH option.
	22	13	An incorrect length is specified for a file with fixed-length records.
53 SYSIDERR	53	130	The SYSID name specified is neither the local region nor a remote system or the link to the remote system is closed.
54 ISCINVREQ	54	70	The remote system indicates a failure that does not correspond to a known condition.
70 NOTAUTH	70	101	A resource security check has failed on FILE (filename).
84 DISABLED	84	50	A file is disabled.
100 LOCKED	100	106	An attempt is being made to read a record either specifying the UPDATE keyword or specifying CONSISTENT or REPEATABLE, but the record is locked by a retained lock.
101 RECORDBUSY	101	107	The NOSUSPEND keyword is specified and the record is locked by an active lock.