READ

Summary

Syntax
Parameters
Error Conditions

Read a record from a file. READ reads a record from a file on a local or a remote system. For both UPDATE and non-UPDATE commands, the record to be retrieved identified by the RIDFLD option information.

The RIDFLD data area is available immediately upon completion of a READ UPDATE command for reuse by the application program. READ requests with UPDATE keyword or a CONSISTENT or REPEATABLE read integrity option, return the LOCKED condition if they reference a record that has a retained lock.

The key of a locked record is not returned to the application program. If an application program specifies GTEQ or GENERIC on the READ request its not easy to identify which record key is locked.

Syntax -

Parameters -

EQUAL -

Specifies the record having the exactly same key that specified in the RIDFLD option should be retrieved.

FILE(file-name) -

Specifies the name of the file to be accessed. If SYSID is specified, the data set is on a remote system irrespective of the name is defined to CICS.

If SYSID is not specified, the data set assumed to be on the local system. Otherwise, the resource definition is used to find out whether the data set is on a local or a remote system.

GENERIC -

This option is valid for VSAM KSDS only. Specifies the search key is a generic key with a length specified in the KEYLENGTH option.

GTEQ -

This option is valid for VSAM KSDS only. Specifies the first record that has a greater key than the specified key in the RIDFLD option if the exact match not found. If the exact match found, it retrieves the matched record.

INTO(data-area) -

Specifies the data area to where the retrieved data 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.

KEYLENGTH(data-value) -

data-value is a halfword binary value. Specifies the key length. The value specified in KEYLENGTH is same as the value specified in the RIDFLD option except when RBA or RRN is specified.

KEYLENGTH is not valid when RBA or RRN is specified. KEYLENGTH must be specified if GENERIC is specified or key is specified. 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 specified and the KEYLENGTH is not less than the length specified in the VSAM definition.If KEYLENGTH(0) and GETQ must be specified to read the first record in the data set. If EQUAL is specified with KEYLENGTH(0) the results of the READ are unpredictable.

For remote files, specify the KEYLENGTH in the FILE definition. If KEYLENGTH is not defined and is not specified in the application program and the key is longer than 4 characters, the default value is 4.

LENGTH(length-value) -

length-value is a halfword binary value. Specifies the data area (record) length to where the record is to be put. The LENGTH parameter contains the actual length of the record on completion of the READ command. This option is mandatory if SYSID is specified.

If the file is on a remote system and SYSID is not specified, the LENGTH parameter should be set in the file resource definition. If the file is on a local system, the LENGTH option must be specified for variable-length records, but is optional for fixed-length records.

However, it is advisable to specify the length of fixed-length records. If the LENGTH option is specified and the data area longer than the record being accessed while reading fixed-length records, the LENGERR condition is raised.

If the LENGTH option is not explicitly specified, then the LENGERR condition is returned if the length can be inferred from the data area.

If the retrieved record is longer than the value specified in the LENGTH option, the record is truncated to the specified value and the LENGERR condition occurs.If the SET option specified, do not need to specify the LENGTH option.

NOSUSPEND (RLS only) -

The request does not wait if the record is locked by VSAM with an active lock.

RBA -

This option is for VSAM KSDS or ESDS base data sets only. Specifies the RIDFLD option field contains a relative byte address.

RIDFLD(data-area) -

Specifies the record identification field. The contents can be a key or a relative byte address, or relative record number (for VSAM data sets), or a block reference, a physical key, and a deblocking argument (for BDAM data sets).

The field is full word binary for a relative byte address or a relative record number. If RBA is specified, the RIDFLD can be greater than or equal to zero.

If RRN is specified, the RIDFLD can be greater than or equal to 1 even when the GTEQ option is specified. RIDFLD should specify if the GENERIC option specified.

RRN -

This option is valid for VSAM RRDS. Specifies the RIDFLD option contains a relative record number.

SET(ptr-ref) -

Specifies the pointer reference to contain the address of the retrieved record.The pointer reference is valid until the next READ command for the same file or until completion of a corresponding REWRITE, DELETE or UNLOCK command or a SYNCPOINT in the case of READ UPDATE SET.

SYSID(system-name) -

Specifies the system name to which the request is directed. If SYSID specified and omit RBA and RRN, LENGTH and KEYLENGTH must be specified.

TOKEN(data-area) -

data-value is a fullword binary value. Specifies a unique request identifier for a READ UPDATE request.This is an output value returned by file control, for use in associating a subsequent REWRITE or DELETE (or UNLOCK) request with the record returned on READ UPDATE request.

UNCOMMITTED -

The record is read without read integrity. No attempt is made to serialize READ request with any concurrent update activity for the same record.

UPDATE -

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.

XRBA -

Specifies the RIDFLD option field contains an extended relative byte address. This option should be used when reading records from an ESDS extended addressing data set. KSDS data sets cannot be accessed by XRBA.

Error Conditions -

Below are the list of error conditions may occur in combination. If more than one occurs, only the first is passed to the application program.

Error Condition	RESP2, Description & Solution	System Action
84 DISABLED	50 - A file is disabled. Solution -Check the file status and enable the file using SET FILE or CEMT SET FILE	Task abnormally terminated
15 DUPKEY	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. Solution -Verify the record key and use READ with UPDATE to delete specific record or use generic key to delete both if the second record is not important.	Task abnormally terminated
12 FILENOTFOUND	1 - A file name in the FILE option is not defined to CICS. Solution -Contact support team to define the FILE in CICS region.	Task abnormally terminated
21 ILLOGIC	110 - VSAM error occurs that is not in one of the other CICS response categories. Solution -This might be due to the non-sequence of file operations. Debug the program to correct the logic.	Task abnormally terminated
16 INVREQ	20 - READ is not allowed according to the resource definition. Solution -Change the resource definitions if the deletion is valid or do not perform delete if the file definitions are correct. 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. Solution -When a KEYLENGTH and GENERIC options specified, it is a generic key and the length value should be less than the length of the full key. Change the program to modify the length value. 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. Solution -If only KEYLENGTH option specified, the length value should match the dataset full key. Change the program to modify the length value. 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. Solution -Two READ UPDATE commands should not be issued side by side without specified TOKEN value. Because the same TOKEN value assumed. Change the program to modify the logic. 42 - The KEYLENGTH, GENERIC options and the length specified in the KEYLENGTH option is less than zero. Solution -When a KEYLENGTH and GENERIC options specified, it is a generic key and the length value should be less than the length of the full key and should be greater than zero. Change the program to modify the length value. 51 - A READ to a KSDS file that is being accessed in RLS mode specifies the RBA keyword. Solution -RBA option is not valid for KSDS file accessing in RLS mode. Modify the program to remove RBA option for files which are accessing in RLS mode. 55 - NOSUSPEND is specified on a READ request to a non-RLS mode file. Solution -NOSUSPEND option is valid for only VSAM files accessed in RLS mode. Modify the program to remove NOSUSPEND option for files which are not accessing in RLS mode. 59 - XRBA was specified, but the data set is not an extended ESDS. Solution -XBRA only for extended ESDS. Modify the program to remove XBRA option for writing the files other than extended ESDS.	Task abnormally terminated
17 IOERR	120 - There is an I/O error during the READ operation. Solution -An I/O error is any unusual event that is not covered by a CICS condition. For VSAM files, IOERR usually indicates a hardware error.	Task abnormally terminated
54 ISCINVREQ	70 - The remote system indicates a failure that does not correspond to a known condition. Solution -Contact remote system support team to resolve the issue.	Task abnormally terminated
100 LOCKED	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. Solution -The record might get locked for some other reason. Wait for some time and try again.	abend the task with code AEX8.
70 NOTAUTH	101 - A resource security check has failed on FILE (filename). Solution -Contact system administrator team to check whether the appropriate access added for the user or group. It will resolve the problem.	Task abnormally terminated
19 NOTOPEN	60 - Below are the reasons for NOTOPEN The requested file is CLOSED and UNENABLED. Solution -Open and enable the file using SET FILE or a CEMT SET FILE command. If no access, contact support team to enable the file. The requested file is OPEN and in use by other transactions, but a CLOSE request against the file has been received. Solution -The CLOSE request might for using the file in batch environment. Wait for some time and try again later once the file enabled. The requested file is CLOSED and ENABLED, so CICS has tried to open the file as part of executing the request. Solution -Open the file using SET FILE or a CEMT SET FILE command. If no access, contact support team to open the file.	Task abnormally terminated
101 RECORDBUSY	107 - The NOSUSPEND keyword is specified and the record is locked by an active lock. Solution -This might occur very rarely. Wait for some time and try again.If this occurring on regular basis, modify the application program to remove NOSUSPEND.	Abend the task with code AEX9
53 SYSIDERR	130 - The SYSID name specified is neither the local region nor a remote system or the link to the remote system is closed. Solution -The specified SYSID name is not related to any system. Correct it.If the link to the remote system is closed, that might be due to the remote system is not up and running. Contact remote system support team.	Task abnormally terminated
13 NOTFND	80 - An attempt to retrieve a record based on the search argument provided is unsuccessful. Solution -This might occur due to the record already gets deleted or the record doesn’t exist. Handle the error programmatically. 81 - XRBA was specified and the value of RIDFLD was greater than 4 GB, but the data set is not an extended ESDS. Solution -XBRA option only used for extended ESDS. If the dataset is not extended ESDS, do not use XBRA. Modify program to remove the XBRA.	Task abnormally terminated
22 LENGERR	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. Solution -Either LENGTH option or SET option should be specified for the files in the above case. Modify the program to specify either LENGTH or SET option. 11 - The length of a record read with the INTO option exceeds the value specified in the LENGTH option. Solution -The length option specified with LENGTH option should equal to the record read length. If you are not aware of the length, specify it as a MAXLENGTH. 13 - An incorrect length is specified for a file with fixed-length records. Solution -Modify the program to specify the file fixed length as a length value to resolve the issue.	Task abnormally terminated