CICS FILE READ

CICS FILE Delete CICS File Readnext


Advertisements


Read a record from a file.

Read command is safe when


  1. Defined as remote and the command function shipped over an IPIC connection to a remote CICS region.
  2. Defined as local VSAM.

READ command used to read file and retrieve the data based on the key passed.

The file can be local file or file from remote region.

For both UPDATE and non-UPDATE commands, RIDFLD option is required to identify the record to be retrieved.

After the READ UPDATE command, the RIDFLD data area is available for reuse by the application program.

RECORDBUSY refers to active locks and LOCKED refers to retained locks.

These kind of locks affect READ UPDATE requests which acquire locks.


Syntax:

EXEC CICS 
     READ FILE (filename)
          UNCOMMITTED
          UPDATE
          TOKEN (data-area)    
          INTO (data-area) RIDFLD (data-area)
          SET (ptr-ref)                      
          KEYLENGTH (data-value)
          GENERIC
          SYSID (system-name)
          LENGTH (data-area)
          RBA   
          RRN   
          EQUAL
          GTEQ 
          NOSUSPEND
END-EXEC. 

FILE (filename)

Specifies the name of the file.

If SYSID is specified, the file is from the remote region.

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


UNCOMMITTED

The record is read without read integrity.

No attempt is made to serialize this read request with any concurrent update activity for the same record.


UPDATE

Specifies that the record is to be obtained for updating.

For VSAM and data tables deletion.

If this option is omitted, a read-only operation is assumed.

UPDATE promises read integrity.

If another task has issued a READ REPEATABLE request against the same record, READ UPDATE request is made to wait until that task reaches SYNCPOINT (unless issued NOSUSPEND).


TOKEN (data-area)

Specifies the unique identifier for this READ request.

The data area length is a full word binary value.

TOKEN is an optional field.


INTO (data-area)

Specifies the data area that needs to be written with the record after the READ successful.

The INTO is specified, the LENGTH is not mandatory.

But the INTO data area should be capable of placing the default record length.


RIDFLD (data-area)

Specifies the record identification field.

Contains the key value used to identify the record to delete.

Contents can be a key value, RBA, RRN.

For RRN, the format of the field is full word binary.

For RBA, the RIDFLD can be greater than or equal to zero.

For RRN, the RIDFLD can be greater than or equal to 1.

RIDFLD is mandatory if GENERIC option specified.


SET (ptr-ref)

specifies the pointer reference that is 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, or a SYNCPOINT.

If DATALOCATION (ANY) is associated with the application program, the address of the data can be above or below the 16 MB line.

If DATALOCATION (BELOW) is associated with the application program, the address of the data is below the 16 MB line.


KEYLENGTH (data-value)

Specifies the length of the key specified in the RIDFLD option.

The length field definition is of length half word binary.

KEYLENGTH is not applicable for RBA or RRN specified.

KEYLENGTH option is mandatory if GENERIC is specified.

If the length value specified is different from the length defined for the data set without GENERIC, the INVREQ condition occurs.

If the KEYLENGTH is not less than the length specified in the VSAM definition with GENERIC option, The INVREQ condition occurs.

If zero value specified for KEYLENGTH, the results are unpredictable.

If KEYLENGTH (0) is used with the reading the first record in the data set and the GTEQ option must also be specified.

If EQUAL is specified either explicitly or by default with KEYLENGTH (0), the results of the READ are unpredictable.


GENERIC:

Specifies that the search key is a partial key/generic key.

The key is with a length specified in the KEYLENGTH option.

The search for a record is to get the same starting characters records from the file.

The search result might be a single record or multiple records.


SYSID (system-name)

Specifies the name of the remote system/local system.

System-name declaration length is 1-4 characters.

If SYSID specified, RBA and RRN can be omitted.


LENGTH (data-area-length)

Specifies the length of data area after the record retrieved successfully.

Data-area-length in declaration is a half word binary value.

Once the READ command completed, the LENGTH parameter contains the actual length of the record.

LENGTH must be specified if SYSID is specified.

If the file is on a remote system, the LENGTH parameter need not be set in application program but must be set in the file resource definition.

If the file is on a local system, the LENGTH parameter must be set for variable-length records.

If SET option is specified, it’s not needed to specify the LENGTH option.

If specify the INTO option, the LENGTH argument must be a data area that specifies the largest record the program accepts.

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.


RBA

Specifies RIDFLD contains a relative byte address.

For VSAM KSDS base data sets.

This option used only when deleting records using RBA instead of keys to identify the records.


RRN

Option is for VSAM RRDS only

Specifies that the RIDFLD contains a relative record number.

This option can be used only with files referencing relative record data sets.


EQUAL

Specifies that the search is satisfied only for the record which has the same key which is provided in RIDFLD.

The data provided in RIDFLD may be a full key or partial key.


GTEQ

GTEQ is valid for VSAM KSDS.

Specifies CICS to retrieve the next available record if the equal key record not found which is specified in RIDFLD.

If match not found, READ will retrieve next record which is greater than to key.


NOSUSPEND (RLS only)

Specifies that the request is not to wait if VSAM is holding by another task.

NOSUSPEND wait for at least 1 second before CICS returns the RECORDBUSY response.


ERROR Conditions


12 FILENOTFOUND

RESP2 values:
1

The file name provided in the FILE option is not defined in CICS.

Task will be terminated abnormally.


13 NOTFND

RESP2 values:
80

A retrieve record based on the search argument provided is unsuccessful.

For remote files, this condition occurs if an attempt to read a record is made without key length specified.

Task will be terminated abnormally.


16 INVREQ

RESP2 values:
20

READ is not allowed according to the resource definition.

A READ command with the UPDATE option is issued to a file where update operations are not allowed.

25

Error occurs, if the KEYLENGTH is not less than the length specified in the VSAM definition with GENERIC option

26

Error occurs, if the length value specified is different from the length defined for the data set without GENERIC.

42

The KEYLENGTH and GENERIC options are specified and the length specified in the KEYLENGTH option is less than zero.

44

The command does not conform to the format of READ for a user-maintained or coupling facility data table; for example, if RBA is specified.

Task will be terminated abnormally.


17 IOERR

RESP2 values:
120

I/O error during the READ operation.

For VSAM files, IOERR normally indicates a hardware error.

Task will be terminated abnormally.


19 NOTOPEN

RESP2 values:
60

Below are the possible reasons for getting this error.

The requested file is CLOSED and UNENABLED.

The requested file is OPEN and in use by other transactions, but a CLOSE request against the file has been received.

The requested file is CLOSED and ENABLED, so CICS has tried to open the file as part of executing the request.

Task will be terminated abnormally.


22 LENGERR

RESP2 values:
11

The length of a record read with the INTO option specified exceeds the value specified in the LENGTH option.

If the record is truncated, and the data area supplied in the LENGTH option is set to the actual length of the record.

13

An incorrect length is specified for a file with fixed-length records.

Task will be terminated abnormally.


53 SYSIDERR

RESP2 values:
130

The SYSID option specifies a name that is neither the local system nor a remote system.

Task will be terminated abnormally.


70 NOTAUTH

RESP2 values:
101

A resource security check has failed on FILE (filename).

Task will be terminated abnormally.


84 DISABLED

RESP2 values:
50

A file is disabled because it was initially defined as disabled and has not since been enabled.

A file is disabled because it has been disabled by a SET FILE or a CEMT SET FILE command.

Task will be terminated abnormally.


100 LOCKED

RESP2 values:
106

An attempt is being made to read a record specifying the UPDATE keyword, but the record is locked by a retained lock.

The LOCKED condition can also occur for a READ UPDATE request to a recoverable CFDT that uses the locking model, if the record being read is locked by a retained lock.

Task will be terminated abnormally with code AEX8.


CICS FILE Delete CICS File Readnext

Advertisements