CICS - READ

READ command reads data from a file using primary key. Following is the syntax of the READ command −

Syntax

EXEC CICS READ
   FILE('name')
   INTO(data-area)
   RIDFLD(data-area)
   LENGTH(data-value)
   KEYLENGTH(data-value)
END-EXEC.

The following table lists the parameters used in the READ command −

Sr.No	Parameter & Description
1	FILE File name is the name of the file which we want to read. This is the CICS symbolic file name which identifies the FCT entry for the file. File names can be up to 8 characters long and should be enclosed in quotes if they are literals.
2	INTO Data area is the variable into which the record is to be read, usually a structure in working storage. The INTO is required for the uses of the READ command.
3	RIDFLD It has the name of the data area containing the key of the record which we want to read.
4	LENGTH It specifies the maximum number of characters that may be read into the data area specified. It must be a halfword binary value (PIC S9(4) COMP). After the READ command is completed, CICS replaces the maximum value we specify with the true length of the record. For this reason, we must specify LENGTH as the name of a data area rather than a literal and must re-initialize this data area if we use it for LENGTH more than once in the program. An longer record will raise an error condition.
5	KEYLENGTH It specifies the length of the key.

Example

The following example shows how to read a record from 'FL001' file where Student-id is the primary key −

IDENTIFICATION DIVISION.                                         
PROGRAM-ID. HELLO.                                               
DATA DIVISION. 
WORKING-STORAGE SECTION.
01 WS-STD-REC-LEN    PIC S9(4) COMP.
01 WS-STD-KEY-LEN    PIC S9(4) COMP.
01 WS-STD-REC-KEY    PIC 9(3).
01 WS-STD-REC        PIC X(70).
PROCEDURE DIVISION.
MOVE +70           TO WS-STD-REC-LEN.
MOVE ‘100’         TO WS-STD-REC-KEY.
MOVE 3             TO WS-STD-KEY-LEN.
EXEC CICS READ
   FILE ('FL001')
   INTO (WS-STD-REC)
   LENGTH (WS-STD-REC-LEN)
   RIDFLD (WS-STD-REC-KEY)
   KEYLENGTH (WS-STD-KEY-LEN)
END-EXEC.

Read Command Options

Following options can be used with READ command −

GENERIC − It is used when we do not know the complete key value. For example, we want a record whose primary key starts with ‘10’ and the rest of the key can be anything. Although the key length is 3 characters, we are mentioning only 2. It is important to mention the key-length which gives the length for which it needs to do the matching. The first record that satisfies the criteria will get picked up.
UPDATE − It specifies that we intend to update the record in the current transaction. Specifying UPDATE gives your transaction exclusive control of the requested record. It should be used when we want to rewrite the record.
EQUAL − It specifies that we want only the record whose key exactly matches with what is specified by RIDFLD.
GTEQ − It specifies that we want the first record whose key is greater than or equal to the key specified.

EXEC CICS READ
   FILE('name')
   INTO(data-area)
   RIDFLD(data-area)
   LENGTH(data-value)
   KEYLENGTH(data-value)
   GENERIC
   UPDATE
   EQUAL
   GTEQ
END-EXEC.

Read Command Exceptions

The following table shows the list of exceptions that arise during READ statement −

Sr.No	Exception & Description
1	NOTOPEN File is not open.
2	NOTFND Record that is being searched does not exist in the dataset.
3	FILENOTFOUND File entry is not made in FCT.
4	LENGERR Mismatch between the length specified in command and actual length of the record.
5	NOTAUTH If the user does not have enough permissions to use the file.
6	DUPKEY If more than 1 record satisfy the condition on the alternate key.

cics_file_handling.htm