READ command reads a record from a file using primary key. READ command is used for random processing.
Below is the syntax for READ command.
EXEC CICS READ
FILE('filename')
INTO(data-area)
RIDFLD(data-area) [RBA|RRN]
LENGTH(data-value)
KEYLENGTH(data-value)
END-EXEC. |
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.
Let us see the parameters used in the READ command.
FILE(filename)
Specifies the name of the file to be accessed.
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
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.
Specifies the record identification field.
It has the name of the data area containing the key of the record which we want to read.
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.
Let us see an example of CICS program for READ command.
IDENTIFICATION DIVISION.
PROGRAM-ID. IBMMF.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-REC-LEN PIC S9(4) COMP.
01 WS-KEY-LEN PIC S9(4) COMP.
01 WS-REC-KEY PIC 9(6).
01 WS-REC-DATA PIC X(80).
PROCEDURE DIVISION.
MOVE +80 TO WS-REC-LEN.
MOVE ‘502258’ TO WS-REC-KEY.
MOVE 6 TO WS-KEY-LEN.
EXEC CICS READ
FILE('STDLST')
INTO(WS-REC-DATA)
LENGTH(WS-REC-LEN)
RIDFLD(WS-REC-KEY)
KEYLENGTH(WS-KEY-LEN)
END-EXEC. |
This program read the record in 'STDLST' file for the key value '502258' and written the data into WS-REC-DATA.
File name-'STDLST' is the name of the file which we want to read. This is the CICS symbolic file name which identifies the FCT(File control table) entry for the file. File names can be up to 8 characters long and should be enclosed in quotes if they are literals.
After execution, WS-REC-DATA will have the data record read from ‘STDLST’ whose key value is ‘502258’.
Let us see some of the frequently used options with READ command.
For partial key requests, the GENERIC option can be used. The length of the partial key must be specified in KEYLENGTH option.
It is used when we do not know the complete key value. For example, we want a record whose primary key starts with ‘999’ and the rest of the key can be anything. Although the key length is 6 characters, we are mentioning only 3. 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.
Specifies that the record is to be obtained for updating or deletion. If this option is omitted, a read-only operation is assumed. UPDATE guarantees read integrity.
Specifying UPDATE gives your transaction exclusive control of the requested record.
It specifies that we want only the record whose key exactly matches with what is specified by RIDFLD.
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. In other words, It specifies that we want the first record whose key is greater than or equal to the key specified in the RIDFLD.
Specifies that the file is ESDS and the RIDFLD option should be interpreted as the Relative Byte Address.
Specifies that the file is RRDS.
The following example shows you how to read a record from a file named STDFL into a specified data area.
EXEC CICS READ
INTO(WS-RECORD)
FILE('STDFL')
RIDFLD(WS-ACCTNO)
END-EXEC |
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('STDFL')
RIDFLD(ACCTNO)
KEYLENGTH(4)
GENERIC
GTEQ
UPDATE
END-EXEC |
| Exception | Description |
|---|---|
| DISABLED | A file is disabled |
| NOTFND | An attempt to retrieve a record based on the search argument provided is unsuccessful. |
| FILENOTFOUND | The file name supplied in the FILE option is not defined to CICS. |
| NOTAUTH | A resource security check has failed on FILE(filename).(i.e. User does not have enough permissions to access the file). |
| LENGERR | The length of a record read with the INTO option specified exceeds the value specified in the LENGTH option. |
| DUPKEY | If more than 1 record satisfy the condition on the alternate key. |
If you have any doubts or queries related to this chapter, get them clarified from our Mainframe experts on ibmmainframer Community!