Mainframe Tutorial-File Control Commands-READ Command

File Control Commands The READ command EXEC CICS { READ DATASET(filename) | FILE(name) } { INTO(data-area) | SET(pointer-ref) } ...

File Control Commands

The READ command

EXEC CICS

{ READ DATASET(filename) | FILE(name) }

{ INTO(data-area) | SET(pointer-ref) }

[ LENGTH(data-area) ]

RIDFLD(data-area)

[ KEYLENGTH(data-value) [ GENERIC ]]

[ SYSID(name) ]

[ RRN | RBA ]

[ GTEQ | EQUAL ]

[ UPDATE ]

END-EXEC

Options

DATASET or FILE Specifies a 1 to 8 character name for the data set as specified using CEDA DEFINE FILE(name)

INTO The target data area

SET Specifies a pointer data item (or register) to hold the address of the data record

LENGTH Specifies in a half word PIC S9(4) COMP field. This is an input / output field. On input it specifies the length of the data area. On return CICS sets into this field the length of the data returned. Required if you are dealing with variable length records.

RIDFLD If RRN or RBA is specified refers to relative record number of a RRDS or RBA of a ESDS file. If neither is specified this field contains the key of the KSDS record. This field must be as big as the full defined key length. After a generic read, CICS always sets the field with the full key of the record just read. For this reason the length of the field should be the full key length.

KEYLENGTH Specifies in a half word field ( PIC S9(4) COMP) or a literal, the length of the generic key. The value specified must be less than the files defined key length. Used only with GENERIC or SYSID option. Valid only for a KSDS and therefore invalid if the RRN or RBA keywords are specified.

GENERIC Specifies that only a part of the key (left part, whose length is indicated by KEYLENGTH) is supplied in the RIDFLD. The first record with a key whose leftmost positions(as many as specified by this field) match the RIDFLD is returned.

SYSID Specifies a 1 to 4 character connection name that represents a remote system.

RBA Full word PIC S9(8) COMP field which specifies the relative byte address of the record for a KSDS or ESDS file.

RRN Full word PIC S9(8) COMP field which specifies the relative record number of the record for a RRDS file.

GTEQ Specifies that the first record whose key equal to or higher than what is specified in the RIDFLD will be returned to the application.

EQUAL Specifies that only a record whose key exactly matches the value in the RIDFLD will be returned to the application.

UPDATE Specifies that you Intend to update the record by rewriting or deleting it. CICS locks the whole CI containing the record and does not allow any other task access to this CI until one of the following occurs:1) you issue a REWRITE, DELETE or UNLOCK command or 2)additionally if the file is defined as recoverable you have to issue a syncpoint or your task must end (implied syncpoint).

Conditions:

The RESP field can have the following values:-

DISABLED file is disabled using CEMT SET

DSIDERR File is not defined to CICS. In later systems also indicated by FILENOTFOUND.

LENGERR The buffer provided is too small to hold the record.

DUPKEY Occurs when you READ via an alternate index and indicate that at least one more record with the same key exists. The read command fetches only the first record with the same key.

ENDFILE End of file condition.

ILLOGIC A serious VSAM error occurred.

INVREQ The read request is prohibited by the resource definition for this resource.

IOERR An IOERR occurred

NOTAUTH The transactions definition specified resource Checking and the operator is not authorized to Access the data set.

NOTFND The specified record could not be located.

NOTOPEN the data set is not open

SYSIDERR The system identified by SYSID could not be found.

Notes:

• To read from an alternate index specify the PATH name instead of the file name when you define the file using CEDA. Only the first of many records with the same key can be read by the READ command. If you want to read all records with the same key you must use READNEXT.

• If accessing via an alternate index DUPKEY is possible if the alternate key is not unique. The other exception condition you can get is NOTFND if you do not find a record with the same key.