Read a record from a file.

READ
>>-READ--FILE(filename)--+------------------------------+------->
+-UNCOMMITTED------------------+
+-CONSISTENT-------------------+
+-REPEATABLE-------------------+
'-UPDATE--+------------------+-'
'-TOKEN(data-area)-'
>--+-INTO(data-area)-+--RIDFLD(data-area)----------------------->
'-SET(ptr-ref)----'
>--+------------------------------------+----------------------->
'-KEYLENGTH(data-value)--+---------+-'
'-GENERIC-'
>--+--------------------------------------+--+--------+--------->
+-SYSID(systemname)--LENGTH(data-area)-+ +-RBA----+
'-LENGTH(data-area)--------------------' +-RRN----+
+-DEBKEY-+
'-DEBREC-'
.-EQUAL-.
>--+-------+--+-----------+------------------------------------><
'-GTEQ--' '-NOSUSPEND-'
Conditions: DISABLED, DUPKEY, FILENOTFOUND, ILLOGIC, INVREQ,
IOERR, ISCINVREQ, LENGERR, LOADING, LOCKED, NOTAUTH, NOTFND, NOTOPEN,
RECORDBUSY, SYSIDERR
Description
READ reads a record from a
file on a local or a remote system.
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.
Note: You cannot specify
an RBA for VSAM data sets greater than 4GB (that is, defined with
the extended format / extended addressability attribute). The only
VSAM data sets greater than 4GB supported by CICS® are
KSDS, and then only if they are accessed by key. CICS does not support
ESDS or RRDS data sets defined with the extended attribute.
Data table considerations
When the READ
command reads a CICS-maintained data table, a READ request with UPDATE
or RBA is always satisfied by a call to VSAM. A full key read that
is neither a generic read nor a READ UPDATE, is satisfied by a reference
to the data table if possible. If the record is not found in the table,
the source data set is accessed, unless the table is known to be complete,
that is, all records in the source are also present in the table (which
is the case if loading is finished and none has been rejected by a
user exit).
If
you carry out a generic read (using the GENERIC option) on a CICS-maintained
data table, and CICS returns a NOTFND condition because the record
is not found in the table, CICS clears the INTO() and RIDFLD() areas
to ensure that an incorrect record is not returned. This behavior
optimizes performance, but it differs from the behavior for a generic
read of a VSAM file, when the INTO() and RIDFLD() areas are left unchanged
in the event of a NOTFND condition. When you convert a VSAM file to
a CICS-maintained data table, ensure that any applications that carry
out generic reads of the data take appropriate action if a NOTFND
condition is returned and the INTO() and RIDFLD() areas are cleared.
When
the READ command reads a user-maintained data table, only the data
table is accessed once loading is complete; the VSAM file is not changed
in any way.
When the READ command reads a coupling-facility
data table, only the data table is accessed, even if the table is
initially loaded from a VSAM source data set.
If a file that
refers to a user-maintained or coupling facility data table is defined
with RLSACCESS(YES), the RLS-specific API options CONSISTENT, NOSUSPEND,
and REPEATABLE are not supported.
Reading files accessed in RLS mode
When
a file is accessed in RLS mode, non-update read requests can specify
one of the read integrity options: UNCOMMITTED, CONSISTENT, or REPEATABLE.
If
none of these keywords is specified, CICS uses the value specified
on the READINTEG parameter of the FILE resource definition, for which
the default is UNCOMMITTED.
If you want to use the level of
read integrity specified in the READINTEG keyword of the FILE definition,
and then you need to change from using a local file to a remote file,
or if you change the location of a remote file, ensure that:
- The remote file-owning region supports the read integrity options.
- The FILE definition in the remote system specifies:
- RLS mode
- The correct read integrity values for your application.
READ requests that specify the UPDATE keyword, or a CONSISTENT
or REPEATABLE read integrity option, (either explicitly or implicitly
in the FILE definition) 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. Thus, if an application program
specifies GTEQ or GENERIC on the READ request it cannot tell which
record key is locked.
If a request specifying read integrity
is function-shipped to a member of the CICS family of products that
does not support read integrity, the request fails:
Retained and active locks
RECORDBUSY
refers to active locks and LOCKED refers to retained locks:
These
locks affect READ requests which acquire locks; that is, update requests
and requests with read integrity. These are the kinds of READ requests
which are referred to in the following bullets. Other READ requests
are unaffected by the presence of retained or active locks.
- READ requests for records that have retained locks are
always rejected with a LOCKED response.
- READ requests for records that have active locks wait for
the lock to be released, except when the NOSUSPEND keyword is specified,
in which case CICS returns the RECORDBUSY response.
Options
- CONSISTENT (RLS only)
- The
record is read with a level of read integrity provided by a VSAM shared
lock that lasts for the duration of the request.
If the record
is being modified by another task, which therefore holds an exclusive
lock, the READ request waits until the update is complete (unless
NOSUSPEND is also specified) as follows:
- For a READ request against a non-recoverable file, the READ completes
as soon as any VSAM request performing the update completes.
- For a READ request against a recoverable file, the READ request
completes when the updating task completes its next syncpoint or rollback.
- DEBKEY
- (blocked
BDAM) specifies that deblocking is to occur by key. If neither DEBREC
nor DEBKEY is specified, deblocking does not occur.
- DEBREC
- (blocked
BDAM) specifies that deblocking is to occur by relative record (relative
to zero). If neither DEBREC nor DEBKEY is specified, deblocking does
not occur.
- 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(filename)
- specifies
the of the file to be accessed.
If SYSID is specified, the data
set to which this file refers is assumed to be on a remote system
irrespective of whether the name is defined in the FCT. Otherwise,
the FCT entry is used to find out whether the data set is on a local
or a remote system.
- GENERIC
- (VSAM
KSDS, paths and data tables) specifies that the search key is a generic
key whose length is specified in the KEYLENGTH option. The search
for a record is satisfied when a record is found that has the same
starting characters (generic key) as those specified.
- GTEQ
- (VSAM
KSDS, paths and data tables) 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
is retrieved.
- 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, or STG
and CSTG in PL/I. LENGTH must be specified explicitly in C.
- KEYLENGTH(data-value)
- 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
KEYLENGTH 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 is not less than that specified in the VSAM definition.
If
KEYLENGTH(0) is used with the object of reading the first record in
the data set, 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.
For remote
files, the KEYLENGTH can be specified in the FILE definition. If
KEYLENGTH is not defined there, and is not specified in the application
program, and the key is longer than 4 characters, the default value
is 4.
- LENGTH(data-area)
- specifies
the length, as a halfword binary value, of the data area where the
record is to be put. On completion of the READ command, the LENGTH
parameter contains the actual length of the record.
This option
must be specified if SYSID is specified.
If the file is on
a remote system, the LENGTH parameter need not be set here 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, using the INTO option, but not for fixed-length records.
It is, however, advisable to specify the length for fixed-length records
because:
- It causes a check to be made that the record being read is not
too long for the available data area.
- When reading fixed-length records into an area longer than the
record being accessed, the LENGERR condition is raised for COBOL,
C, PL/I, and assembler-language applications if the LENGTH option
is not specified. If the length specified exceeds the file record
length, CICS uses the longer length for the move. If the target area
in the application program is not large enough, storage is overlaid
beyond the target area.
If you specify the SET option, you do not need to specify
the LENGTH option.
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 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. In this case, the LENGTH data
area is set to the length of the record before truncation.
Note
that a file control command issued against a variable-length record
in a file defined on the local CICS system fails with a LENGERR condition
if a length is not specified. However, if the same command is issued
against a file defined on a remote system, the command does not fail.
- NOSUSPEND (RLS only)
- The
request does not wait if the record is locked by VSAM with an active
lock, including records locked as the result of a DEADLOCK.
- RBA
- (VSAM
KSDS or ESDS base data sets, or CICS-maintained data tables only,
but not paths) specifies that the record identification field specified
in the RIDFLD option contains a relative byte address. This option
should be used only when reading records from an ESDS base or when
reading from a KSDS base and using relative byte addresses instead
of keys to identify the records.
You cannot use RBA for:
- User-maintained data tables
- Coupling facility data tables
- KSDS and ESDS files that hold more than 4GB
- Any KSDS file opened in RLS access mode
- REPEATABLE (RLS only)
- The
record is read with a level of read integrity provided by a VSAM shared
lock that lasts for the duration of the unit of work in which the
read request is issued.
If the record is being modified by another
task, which therefore holds an exclusive lock, the READ request waits
until the update is complete (unless NOSUSPEND is also specified)
as follows:
- For a recoverable file, the READ request completes when the updating
transaction completes its next syncpoint or rollback.
- For a non-recoverable file, the READ completes as soon as the
VSAM request performing the update completes.
After the READ request has completed, the record remains
locked to the task that issued the READ. Other tasks may continue
to read the record but no other task is allowed to update the record
until the task that issued the READ performs its next syncpoint or
rollback.
- RIDFLD(data-area)
- specifies
the record identification field. The contents can be a key, 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). For a relative byte address or a relative record number,
the format of this field must be fullword binary. For a relative byte
address, the RIDFLD can be greater than or equal to zero. For a relative
record n'umber, the RIDFLD can be greater than or equal to 1.
See 'Identifying BDAM records' and 'VSAM record identification' in
the CICS Application Programming Guide for more information
about defining the record identification field.
Immediately
upon completion of the command, the RIDFLD data area is available
for reuse by the application program, even if UPDATE was specified.
Make
sure that the variable specified by RIDFLD is not shorter than the
KEYLENGTH 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
- (VSAM
RRDS) specifies that the record identification field specified in
the RIDFLD option contains a relative record number. This option should
only be used with files referencing relative record data sets.
- SET(ptr-ref)
- indicates
that CICS is to supply a buffer where the record is read, and specifies
the pointer reference that is to contain the address of the retrieved
record.
If the DUPKEY condition occurs in assembler language the
specified register has not been set. The specified register can be
loaded from DFHEITP1.
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, it should be moved to your own area.
If DATALOCATION(ANY)
is associated with the application program, the address of the data
can be above or below the 16MB line.
If DATALOCATION(BELOW)
is associated with the application program, the address of the data
is below the 16MB line.
If TASKDATAKEY (USER) is specified
for the executing transaction, the data returned is in a user-key;
otherwise it is in a CICS-key.
- SYSID(systemname)
- specifies
the name of the system the request is directed to.
If you specify
SYSID, and omit both RBA and RRN, you must also specify LENGTH and
KEYLENGTH; they cannot be found in the FCT.
- TOKEN(data-area)
- specifies,
as a fullword binary value, a unique identifier for this READ UPDATE
request. This is an output value returned by file control to the requesting
task, for use in associating a subsequent REWRITE or DELETE (or UNLOCK)
request with the record returned on this READ UPDATE request.
TOKEN
can be function shipped. However, if a request specifying TOKEN is
function shipped to a member of the CICS family of products that does
not recognize this keyword, the request fails.
Note: If you specify
TOKEN it implies update.
- UNCOMMITTED
- The
record is read without read integrity.
The current value of the
record, as known to VSAM, is returned. No attempt is made to serialize
this read request with any concurrent update activity for the same
record. The record may be in the process of being updated by another
task, and the record data may change later if that update is subsequently
backed out.
- UPDATE
- specifies
that the record is to be obtained for updating or (for VSAM and data
tables) deletion. If this option is omitted, a read-only operation
is assumed.
UPDATE guarantees read integrity. The mechanism used
to ensure data integrity depends on the type of file resource:
- For a VSAM file accessed in RLS mode, the record to be updated
is locked by the SMSVSAM server.
- For a VSAM file accessed in non-RLS mode, the record to be updated
is locked by CICS and, in addition, the control interval containing
the record is held in exclusive control by VSAM.
- For a VSAM file accessed
in non-RLS mode, and log(UNDO), CICS holds a record lock until the
task syncpoints.
- For a BDAM file, the record to be updated is held in exclusive
control by BDAM.
- For a user-maintained data table, the record to be updated is
locked by CICS.
- For a CICS-maintained data table, the record to be updated is
locked by CICS and, in addition, the control interval containing the
record is held in exclusive control by VSAM. The VSAM control interval
lock is required because changes to the data table are reflected in
the source data set, which is accessed in non-RLS mode.
- For a coupling facility data table using the locking model, the
record to be updated is locked by the coupling facility data table
server.
- For a coupling facility data table using the contention model,
records are not locked, enabling the records to be read for update
by more than one task. If a record read for update by one task is
then changed by another, the first task is notified, when it issues
a REWRITE or DELETE command, by the CHANGED exception condition. If
a record read for update by one task is then deleted by another, the
first task is notified, when it issues a REWRITE or DELETE command,
by the NOTFND condition.
If another task has issued a READ REPEATABLE request
against the same record, your READ UPDATE is made to wait until that
task reaches SYNCPOINT (unless you issued NOSUSPEND).
Conditions
- 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.
Default action: terminate the task abnormally.
- DUPKEY
- RESP2
values: (VSAM)
- 140
- A record is retrieved by way of an alternate index with the NONUNIQUEKEY
attribute, and another alternate index record with the same key follows
In assembler language, if the SET option is being used, the specified
register has not been set, but can be loaded from DFHEITP1.
Default action: terminate the task abnormally.
- FILENOTFOUND
- RESP2
values:
- 1
- The file name supplied in the FILE option cannot be found in the
FCT.
Default action: terminate the task abnormally.
- ILLOGIC
- RESP2
values: (VSAM)
- 110
- A VSAM error occurs that does not fall within one of the other
CICS response categories.
(See EIBRCODE in the description of
the EXEC interface block, EXEC interface block.)
For
user-maintained data tables, this condition occurs only for a non-UPDATE
READ during loading when CICS has attempted to retrieve the record
from the source data set.
Default action: terminate the task abnormally.
- INVREQ
- RESP2
values:
- 20
- READ is not allowed according to the file entry specification
in the FCT.
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.
- 25
- 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
- The KEYLENGTH option is specified (but the GENERIC option is not
specified), and the specified length does not equal the length defined
for the data set to which this file refers.
- 28
- Following a READ UPDATE command without TOKEN, another READ UPDATE
without TOKEN was issued against the same file without an intervening
REWRITE, DELETE without RIDFLD specified, UNLOCK, or SYNCPOINT command.
This condition may in some cases be raised despite the fact that the
first READ UPDATE was not successful, for example because it timed
out.
- 40
- A BDAM key conversion error occurred.
- 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.
- 51
- A READ to a KSDS file that is being accessed in RLS mode specifies
the RBA keyword. RLS mode does not support relative byte address access
to KSDS data sets.
- 52
- CONSISTENT is specified on a READ request to a non-RLS mode file,
or to a data table that is specified with RLSACCESS(YES). CONSISTENT
is not allowed if the file refers to a data table, even if the file
definition specifies RLSACCESS(YES).
- 53
- REPEATABLE is specified on a READ request to a non-RLS mode file
or to a data table that is specified with RLSACCESS(YES). REPEATABLE
is not allowed if the file refers to a data table, even if the file
definition specifies RLSACCESS(YES).
- 55
- NOSUSPEND is specified on a READ request to a non-RLS mode file
or to a data table that is specified with RLSACCESS(YES). NOSUSPEND
is not allowed if the file refers to a data table, even if the file
definition specifies RLSACCESS(YES).
- 56
- An attempt to update a recoverable coupling facility data table
has failed because the current unit of work has already updated 1024
recoverable coupling facility data tables. You cannot update more
than 1024 recoverable coupling facility data tables within a unit
of work
Default action: terminate the task abnormally.
- IOERR
- RESP2
values:
- 120
- There is an I/O error during the READ operation. An I/O error
is any unusual event that is not covered by a CICS condition.
For
VSAM files, IOERR normally indicates a hardware error.
For
user-maintained data tables, this condition occurs only for a non-UPDATE
READ during loading when CICS has attempted to retrieve the record
from the source data set.
For a coupling facility data table,
an IOERR indicates a bad response returned from a coupling facility
access.
(Further information is available in the EXEC interface
block, EXEC interface block.)
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 or for a BDAM
file with variable-length or undefined-format records.
- 11
- The length of a record read with the INTO option specified exceeds
the 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.
- 13
- An incorrect length is specified for a file with fixed-length
records.
Default action: terminate the task abnormally.
- LOADING
- RESP2
values:
- 104
- The request cannot be satisfied because it is issued against a
data table that is still being loaded. The condition can be raised
for one of the following reasons:
If your application programs encounter the LOADING condition
persistently or too frequently, check that this is not caused by conflicting
file definitions that reference the same data set.
Default action: terminate the task abnormally.
- LOCKED
- RESP2
values:
- 106
- An attempt is being made to read a record either specifying the
UPDATE keyword, or specifying (explicitly or implicitly) CONSISTENT
or REPEATABLE, but the record is locked by a retained lock (see Retained and active locks).
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. See the CICS Recovery
and Restart Guide for information about investigating retained
locks on records in a coupling facility data table.
Default action: abend the task with code AEX8.
- NOTAUTH
- RESP2
values:
- 101
- A resource security check has failed on FILE(filename).
Default action: terminate the task abnormally.
- NOTFND
- RESP2
values:
- 80
- An attempt to retrieve a record based on the search argument provided
is unsuccessful. For data tables, this condition occurs if an attempt
to read a record is unsuccessful because there is no entry with the
specified key in the data table. This does not mean that there is
no such record in the source data set (if the table was created from
one); it may be that such a record is present but was either rejected
during initial loading by the user exit XDTRD, or was subsequently
deleted from the data table. For remote files, this condition
occurs if an attempt to read a record is made without keylength specified
either in the application or the file definition, and the actual key
is longer than 4 characters.
Default action: terminate the task abnormally.
- NOTOPEN
- RESP2
values:
- 60
- NOTOPEN (RESP2 60) is returned for one of the following reasons:
- The requested file is CLOSED and UNENABLED. The CLOSED, UNENABLED
state is reached after a CLOSE request has been received against an
OPEN ENABLED file and the file is no longer in use. You can also make
CLOSED, UNENABLED the initial state, by specifying STATUS(UNENABLED)
and OPENTIME(FIRSTREF) on the FILE resource definition. (For BDAM
files, you use the FILSTAT parameter of DFHFCT TYPE=FILE.)
- The requested file is OPEN and in use by other transactions, but
a CLOSE request against the file has been received.
- A READ command is issued against a data set that is quiesced,
or is being quiesced, as a result of a SET DSNAME QUIESCED or IMMQUIESCED
command.
- The requested file is CLOSED and ENABLED, so CICS has tried to
open the file as part of executing the request. This file open has
failed for some reason. You should examine the console for messages
that explain why the file open has been unsuccessful.
This condition does not occur if the request is
made to a CLOSED, DISABLED file. In this case, the DISABLED condition
occurs.
Default action: terminate the task abnormally.
- RECORDBUSY
- RESP2
values:
- 107
- The NOSUSPEND keyword is specified and the record is locked by
an active lock (see Retained and active locks).
Default action: abend the task with code AEX9.
- SYSIDERR
- RESP2
values:
- 130
- The SYSID option specifies a name that is neither the local system
nor a remote system (made known to CICS by defining a CONNECTION).
SYSIDERR also occurs when the link to the remote system is closed.
- 131
- For a coupling facility data table, the connection to the coupling
facility data table server has failed. This could be because the server
itself has failed, or the server is available, but CICS has failed
to connect to it.
- 132
- The READ is issued for a coupling facility data table that no
longer exists, probably because of a coupling facility failure, in
which case the coupling facility data table server also fails. See
the CICS System
Definition Guide for information about restarting a coupling
facility data table server and reloading a table.
Default action: terminate the task abnormally.
Examples
The following example
shows you 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 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('MASTVSAM')
RIDFLD(ACCTNO)
KEYLENGTH(4)
GENERIC
GTEQ
UPDATE