READ command reads data from a file using primary key. Following is the syntax of the READ command −
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|
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.
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.
It has the name of the data area containing the key of the record which we want to read.
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.
It specifies the length of the key.
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.
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.
The following table shows the list of exceptions that arise during READ statement −
|Sr.No||Exception & Description|
File is not open.
Record that is being searched does not exist in the dataset.
File entry is not made in FCT.
Mismatch between the length specified in command and actual length of the record.
If the user does not have enough permissions to use the file.
If more than 1 record satisfy the condition on the alternate key.