Direct reading (using READ command)
Records in a file can be read using the READ command with the RIDFLD (record identification field) option to specify a record. Further options are available which describe the content and length of the record identification field.
About this task
Procedure
- Use the RIDFLD (record identification field) option to
specify the record you want, and add further options to describe the
content of the record identification field. The exact method
of identifying the record depends on the type of data set:
- For a KSDS, you can identify the record you want uniquely
by specifying its full key, or you can specify a generic key and
retrieve
the first (lowest key) record whose key meets those requirements.
- The GENERIC option indicates that you require a match on only a part of the key. When you specify the GENERIC option, you must also specify the KEYLENGTH option, to say how many positions of the key, starting from the left, must match. For the READ command, CICS uses only the first KEYLENGTH option characters.
- The GTEQ (greater than or equal to) option indicates that you want the first record whose key is "greater than or equal to" the key you have specified. You can use GTEQ with either a full or a generic key.
- The opposite of the GTEQ option is the EQUAL option (the default), which means that you want only a record whose key matches exactly that portion (full or generic) of the key that you have specified.
- For a
standard (non-extended)
ESDS, you can
identify the record by specifying its relative byte address (RBA).
Add the RBA option to inform CICS that an RBA is being used. Because the RBA of a record in an ESDS cannot change, your application program can keep track of the values of the RBAs corresponding to the records it wants to access. An RBA must always point to the beginning of a record. There is no equivalent to the GENERIC or GTEQ options that you can use for a KSDS.
- For an extended ESDS, you can identify
the record by specifying its extended relative byte address (XRBA).
Add the XRBA option to inform CICS that an XRBA is being used. Because the XRBA of a record in an ESDS cannot change, your application program can keep track of the values of the XRBAs corresponding to the records it wants to access. An XRBA must always point to the beginning of a record. There is no equivalent to the GENERIC or GTEQ options that you can use for a KSDS.
- For a KSDS or a
standard
ESDS with an alternate
index
(an extended ESDS cannot have an alternate index)
,
you can retrieve a record in the file by specifying the alternate
key that you set up in the alternate index.
When you use
an alternate key:
- The GENERIC option and the GTEQ option can be used for both KSDS and ESDS records, in the same way as for a read from a KSDS using the primary key.
- If the alternate key is not unique, the first record in the file with that key is read and you get the DUPKEY condition. To retrieve other records with the same alternate key, you have to start a browse operation at this point.
- If no matching record is found, the record identified is the one with the next higher alternate key.
- For an RRDS, identify the record by specifying its relative record number (RRN). Add the RRN option to inform CICS that an RRN is being used. The application program must know the RRN values of the records it wants. There is no equivalent to the GENERIC or GTEQ options that you can use for a KSDS, and you cannot use an alternate key.
- For a KSDS, you can identify the record you want uniquely
by specifying its full key, or you can specify a generic key and
retrieve
the first (lowest key) record whose key meets those requirements.
- Specify the KEYLENGTH option if required, to state the
length of the key which you specified in the RIDFLD option.
- If you specify an RBA or RRN for the record identification field, and specify the RBA or RRN option, the KEYLENGTH option is not required.
- If you specify the GENERIC option, the KEYLENGTH option is required. Specify the length of the generic key, which must be less than the key length specified in the VSAM definition.
- If you are reading a remote file and specify the SYSID
option, the key length can be identified by any of the following
means:
- Specified in the file definition.
- Specified by the application program using the KEYLENGTH option.
- Defaulted to 4, if the key is longer than 4 characters, and the key length is not specified in the file definition or by the application program.
- In other situations, the KEYLENGTH option may be specified or omitted. If you specify a KEYLENGTH which is different from the length defined for the data set and the operation is not generic, the INVREQ condition occurs.
- Use the INTO or SET option to state whether the record is to be read into an area of main storage provided by your application program (READ INTO), or into an area of main storage CICS SET storage acquired by file control (READ SET). If the latter, the address of the data in the CICS SET storage is returned to your program. CICS SET storage normally remains valid until the next syncpoint, or the end of the task, or until next READ against the same file, whichever comes first.
- Make sure that the LENGTH parameter is set if required:
- If you have used the SET option, you do not have to specify the LENGTH option. However, you may specify it if you want to check whether the record length agrees with that originally defined to VSAM. The data area specified is set to the actual record length after the record has been retrieved.
- For fixed-length records, you do not have to specify the LENGTH option, but it is advisable to do so. If you specify the option, CICS checks that the record is not too long for the available data area. The length you specify should exactly match the record length specified at the time the file was created.
- If you have used the INTO option for reading variable-length
records, a length parameter must be provided. However,
the LENGTH option does not always need to be specified explicitly
on the command:
- For a file on a remote system, the LENGTH parameter need not be set here, but it must be set in the file resource definition.
- If you are using assembler language or PL/I, instead of specifying LENGTH explicitly, you can allow it to be defaulted using the length attribute reference in assembler language, or STG and CSTG in PL/I. LENGTH must be specified explicitly in C.
- If the file is open in RLS mode, use the UNCOMMITTED,
CONSISTENT, REPEATABLE and NOSUSPEND options to control read
integrity.
- If you specify the UNCOMMITTED option, there is no read integrity and shared locks are not used for read requests. RLS Record level locking explains shared and exclusive locks. This is the default and is the way in which file control works for files that are opened in non-RLS mode.
- If you specify the CONSISTENT option, a request to read a record is queued if the record is being updated by another task. The read completes only when the update is complete, and the updating unit of work (UOW) relinquishes its exclusive lock. Syncpointing explains UOWs and syncpoints.
- If you specify the REPEATABLE option, processing of the read request is the same as for consistent read requests, except that the reader holds on to its shared lock until syncpoint. This applies to both recoverable and non-recoverable files. This ensures that a record read in a UOW cannot be modified while the UOW makes further read requests. It is particularly useful when you issue a series of related read requests and you want to ensure that none of the records is modified before the last record is read.
- If you specify either CONSISTENT or REPEATABLE, you can also specify the NOSUSPEND option to ensure that the request does not wait if the record is locked by VSAM with an active lock. Active and retained states for locks explains active locks.
Note: Specify read integrity only when an application cannot tolerate 'stale' data. This is because RLS uses locks to support read integrity, and as a result your applications could encounter deadlocks that do not occur in releases of CICS that do not support read integrity. This is particularly important if you define read integrity on file resource definitions. The application programs that reference these files may have been written for releases of CICS that do not support read integrity, and are not designed to deal with deadlock conditions on read-only file accesses.
dfhp3u6.html |
Last updated: Monday, 5 June 2017