READ
READ FILE (
name
Read a record from a file on a local or a remote system.
(1)
)
UPDATE
INTO
SET (
(
data-area ptr-ref
)
)
LENGTH (
data-area
)
RIDFLD (
data-area
)
KEYLENGTH (
data-value
)
RBA
RRN
GENERIC
SYSID (
name
)
EQUAL
GTEQ
Notes:
1
DATASET is also accepted, but FILE is the preferred term (see “DATASET option” on page 311).
Conditions:
DISABLED, DUPKEY, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR,
NOTAUTH, NOTFND, NOTOPEN, SYSIDERR
Description
For both UPDATE and nonupdate commands, you must identify the record to be retrieved by the record identification field specified in the RIDFLD option.
Immediately on completion of a READ UPDATE command, the RIDFLD data area is available for reuse by the application program.
You can specify only one update operation for each file within a transaction at any given time. To avoid deadlock when accessing a file, your next command to the file must be REWRITE, DELETE without RIDFLD, or UNLOCK.
Refer to Chapter 10, “File control,” on page 115 for more information.
Options
EQUAL
specifies that the search is satisfied only by a record having the same key
(complete or generic) as that specified in the RIDFLD option.
FILE(
name
)
specifies the name of the file to be accessed. The name must be alphanumeric, up to 8 characters long, and must have been defined in the file control table
(FCT) unless the SYSID option specifies a remote system.
If a nonlocal SYSID is specified, the underlying file is assumed to be on a remote system irrespective of whether the name is defined in the local FCT.
Otherwise, the FCT entry is used to determine whether the underlying file is on a local or a remote system.
GENERIC
specifies that the search key is a generic key whose length is specified in the
KEYLENGTH option. This option can be used only with a KSDS or a path over a KSDS or ESDS. The search for a record is satisfied when a record is found that has the same starting characters (generic key) as those specified.
390
CICS for iSeries Application Programming Guide V5
GTEQ
specifies that, if the search for a record having the same key (complete or generic) as that specified in the RIDFLD option is unsuccessful, the first record having a greater key satisfies the search. Use this option only with a KSDS or a path over a KSDS or ESDS.
INTO(
data-area
)
specifies the data area into which the record retrieved from the file is to be written.
KEYLENGTH(
data-value
)
specifies as a halfword binary value the length of the key supplied in the
RIDFLD option. If a specified KEYLENGTH value differs from the length defined for the underlying file and the operation is not generic, the INVREQ condition occurs.
INVREQ also occurs if you specify GENERIC, and the KEYLENGTH value is not less than that defined for the file.
If KEYLENGTH(0) is used with the object of reading the first record in the file, 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.
LENGTH(
data-area
)
specifies as a halfword binary value the length of the data area where the retrieved record is to be placed. On completion of the READ command, the
LENGTH argument (which must be a data area) contains the actual length of the record.
This option must be specified with the INTO option on READ commands involving variable-length records. It need not be specified for fixed-length records, but its inclusion is recommended because: v
It causes a check to be made that the record being read is not too long for the available data area. v
When reading fixed-length records into an area longer or shorter than the record being accessed, the LENGERR condition occurs if the LENGTH option is not specified.
When reading into a target data area longer than the record being read, the contents of the target data area, from the end of the retrieved record to the end of the target data area, are unpredictable.
If you specify the INTO option, the LENGTH argument must specify the largest record that 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. In this case, the LENGTH argument is set to the length of the record before truncation.
If you specify the SET option, the LENGTH option need not be specified. if the
SET option is specified, the argument must be a data area.
RBA
specifies that the record identification field specified in the RIDFLD option contains a relative byte address. This option can be used only when reading records directly from an ESDS. The RIDFLD value can be from 0 upward.
RIDFLD(
data-area
)
specifies the record identification field. The contents can be a key, a relative
Chapter 32. Application programming commands - reference
391
byte address, or a relative record number. For a relative byte address or a relative record number, the format of this field must be fullword binary.
Make sure that the RIDFLD data area is not shorter than the KEYLENGTH value specified in this command or, if KEYLENGTH is not specified, the key length of the file you are reading; otherwise, the results are unpredictable.
RRN
specifies that the record identification field specified in the RIDFLD option contains a relative record number. Use this option only when reading records from an RRDS. The RIDFLD value can be from 1 upward.
SET(
ptr-ref
)
specifies a pointer reference to be set to 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. If you want to retain the data within the field addressed by the pointer, you should move it to your own area.
SYSID(
name
)
specifies the name of the system to which the request is directed. The name can be up to 4 characters long.
If you specify SYSID, and omit both RBA and RRN, you must also specify
LENGTH and KEYLENGTH; they cannot be found in the FCT.
UPDATE
specifies that the record is to be obtained for updating or deletion. If this option is omitted, a read-only operation is assumed.
Exception Conditions
Note:
RESP2 values are not set for files that are on remote systems.
DISABLED
RESP2 values:
50
A file is disabled.
A file may be disabled because: v
It was initially defined as disabled and has not since been enabled. v
It has been disabled by an EXEC CICS SET FILE command. v
It has been disabled by the CEMT transaction.
Default action: Terminate the task abnormally.
DUPKEY
RESP2 values:
140
occurs if a record is retrieved from a VSAM emulated file that allows duplicate keys, and another record with the same key follows.
Default action: Terminate the task abnormally.
FILENOTFOUND
RESP2 values:
1
The name specified in the FILE option cannot be found in the FCT.
Default action: Terminate the task abnormally.
392
CICS for iSeries Application Programming Guide V5
ILLOGIC
RESP2 values:
110
There is an error that does not fall within one of the other CICS response categories. (Further information is available in the EIBRCODE
field; refer to Appendix A, “EXEC interface block,” on page 529 for
details.)
Default action: Terminate the task abnormally.
INVREQ
RESP2 values:
20
READ is not allowed according to the file entry specification in the
FCT.
20
25
A READ command with the UPDATE option is issued to a file where update operations are not allowed according to the file entry specification in the FCT.
The KEYLENGTH and GENERIC options are specified, and the length specified in the KEYLENGTH option is greater than or equal to the length of a full key.
26
28
42
The KEYLENGTH option is specified (but the GENERIC option is not specified), and the specified length differs from the length defined for the underlying file.
Following a READ UPDATE command for a file, another READ
UPDATE command is issued for the same file before exclusive control is released by a REWRITE, UNLOCK, or DELETE command.
The KEYLENGTH and GENERIC options are specified, and the length specified in the KEYLENGTH option is less than zero.
Default action: Terminate the task abnormally.
IOERR
RESP2 values:
120
There is an I/O error during the READ. An I/O error is any unusual event that is not covered by a CICS exception condition.
(Further information is available in the EIBRCODE field; refer to
Appendix A, “EXEC interface block,” on page 529 for details.)
Default action: Terminate the task abnormally.
ISCINVREQ
RESP2 values:
70
The remote system indicates a failure that does not correspond to a known condition.
Default action: Terminate the task abnormally.
LENGERR
RESP2 values:
10
Neither the LENGTH option nor the SET option is specified on a
READ command for a file with variable-length records.
11
The length of a record read with the INTO option specified exceeds the
Chapter 32. Application programming commands - reference
393
13
value specified in the LENGTH option; the record is truncated, and the data area supplied in the LENGTH option is set to the actual length of the record.
An incorrect length is specified for a file with fixed-length records.
Default action: Terminate the task abnormally.
NOTAUTH
RESP2 values:
101
A resource security check has failed on FILE(
name
).
Default action: Terminate the task abnormally.
NOTFND
RESP2 values:
80
An attempt to retrieve a record based on the search argument provided is unsuccessful.
Default action: Terminate the task abnormally.
NOTOPEN
does not arise in CICS/400 but is mentioned here for compatibility with other versions of CICS. If the file is CLOSED and ENABLED it is opened as part of the READ command. If the file is CLOSED and DISABLED, the DISABLED condition is raised. In CICS/400 there is no file UNENABLED state as there is in other versions of CICS.
SYSIDERR
RESP2 values:
130
The SYSID option specifies either a name that is not defined in the terminal control system table (TCS), or a system to which the link is closed.
Default action: Terminate the task abnormally.
Examples
The following example shows how to read a record from a file named MASTER into a specified data area:
EXEC CICS READ
INTO(RECORD)
FILE(’MASTER’)
RIDFLD(ACCTNO)
.
.
The following example shows how to read a record for update from a file, using a generic key and specifying a greater-than-or-equal key search:
394
CICS for iSeries Application Programming Guide V5
