Using CICS commands to read records

This section describes the facilities available to application programs for accessing data sets. Although VSAM data sets, are discussed, most of the facilities apply equally to BDAM. It describes:

A file can be defined in the file definition as containing either fixed-length or variable-length records. Fixed-length records should be defined only if:

For direct reading and browsing, if the file contains fixed-length records, and if the application program provides an area into which the record is to be read, that area must be of the defined length. If the file contains variable-length records, the command must also specify the length of the area provided to hold them (which should normally be the maximum length of records in the file).

For fixed-length records and for records retrieved into storage provided by CICS® (when you use the SET option), you need not specify the LENGTH argument. However, although the LENGTH argument is optional, you are recommended to specify it when using the INTO option, because it causes CICS to check that the record being read is not too long for the available data area. If you specify LENGTH, CICS uses the LENGTH field to return the actual length of the record retrieved.

Direct reading (using READ command)

You read a record in the file with the READ command. This must identify the record you want and say whether it is to be read into an area of storage provided by your application program (READ INTO), or into 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.

Direct reading from a KSDS

When reading from a KSDS, you can identify the record you want uniquely by specifying its full key, or you can retrieve the first (lowest key) record whose key meets certain requirements. There are two options that qualify your key value; GENERIC and GTEQ.

The GENERIC option indicates that you require a match on only a part of the key; when you specify the GENERIC option, you also must 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 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.

Direct reading from an ESDS

When reading from an ESDS, the individual record you want is identified by an RBA. 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 to position approximately in a KSDS.

Direct reading from an RRDS

When reading from an RRDS, the record to be retrieved is identified by its relative record number. 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 to position approximately in a KSDS.

Direct reading by way of a path

If a KSDS or an ESDS has an alternate index and an alternate index path (and an appropriate entry in the FCT), you can retrieve a record in the file by using the alternate key that you set up in the alternate index. The GENERIC option and the GTEQ (greater than or equal to) option still work in the same way as for a read from a KSDS using the primary key.

If the alternate key in a READ command 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.

Read integrity (in RLS mode)

CICS supports three options to control read integrity with RLS. You can specify these options on the file control API. Alternatively, if the application request does not specify any of the options (UNCOMMITTED, CONSISTENT, or REPEATABLE), the value from the file resource definition is used. These options are:

UNCOMMITTED
There is no read integrity and shared locks are not used for read requests. (See RLS Record level locking for information about 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.
CONSISTENT
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. UOWs and syncpoints are discussed in Syncpointing.
REPEATABLE
Processing of the read request is the same as for consistent read requests. However, in this case, 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.
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.

If you specify either CONSISTENT or REPEATABLE, you can also specify the NOSUSPEND option on a READ command to ensure that the request does not wait if the record is locked by VSAM with an active lock. See Active and retained states for locks for more information about active locks.

Sequential reading (browsing)

You start a browse with the STARTBR command, identifying a particular record in the same way as for a direct read. However, the STARTBR command only identifies the starting position for the browse; it does not retrieve a record.

The READNEXT command reads records sequentially from this starting point. On completion of each READNEXT command, CICS returns the full key of the record it retrieved in the field specified in the RIDFLD option. (Be sure to provide a field as long as the full key, even if you use a STARTBR command with a shorter generic key.)

As in the case of a direct read, the record may be read into an area supplied by the application program (when you use the INTO option), or into storage provided by CICS (when you use the SET option). In the latter case, the CICS storage addressed by the SET pointer remains valid until the next operation in the browse, or until the browse ends, syncpoint, or end of task, whichever occurs first.

You can also browse backwards in the file, by using READPREV commands instead of READNEXT commands, and you can switch from one direction to the other at any time. The READPREV command is like the READPREV command, except that the records are read sequentially backward from the current position. As you switch from one direction to the other, you retrieve the same record twice, unless you reposition.

When the browse has started, you can change the current browse position either by using a RESETBR command, or a READNEXT command, or a READPREV command. The RESETBR command can also be used for other purposes, however.

For VSAM, but not for BDAM, you can reposition simply by varying the value in RIDFLD when you issue the next READNEXT or READPREV command. When you change RIDFLD, the record identifier must be in the same form as on the previous STARTBR or RESETBR command (key, RBA, or RRN). In addition, you can change the length of a generic key by specifying a KEYLENGTH in your READPREV command, which is different from the current generic key length and not equal to the full length. If you change the length of a generic key in this way, you reposition to the generic key specified by RIDFLD option.

RESETBR command must be used to change the browse position in a BDAM file. If you wish to change the form of the key from key to RBA or vice versa, you must use a RESETBR command. You must also use a RESETBR command to switch between generic and full keys or between "equal to" and "greater than or equal to" searches. You can also only use X'FF' characters to point to the last record in the file if you are using a RESETBR or STARTBR command.

Under certain conditions, CICS uses VSAM skip-sequential processing when you change the key in this way, as explained in Skip-sequential processing.

Browsing through a KSDS

You can use a generic key on the STARTBR command when browsing through a KSDS. However, the browse can only continue forward through the file. If you process a READPREV command during such a browse, you get the INVREQ condition.

You can use the options "key equal to" and "key greater than or equal to" on the STARTBR command and they have the same meaning as on the READ command. However, the STARTBR command assumes that you want to position at the key specified or the first key greater if that key does not exist. That is, option GTEQ is the default for the STARTBR command, whereas EQUAL is the default for the READ command.

You can start a forward browse through a KSDS at the start of the file by specifying a key of hexadecimal zeros, or by specifying options GENERIC, GTEQ, and KEYLENGTH(0) on the STARTBR, RESETBR, READNEXT, or READPREV command. (In the latter case, you need the RIDFLD keyword although its value is not used and, after the command completes, CICS is using a generic key length of one.)

You can start from the end of the data set by specifying a complete key of X'FF' characters on the STARTBR or RESETBR command. This points to the last record in the file ready for a backward browse.

A STARTBR, RESETBR , or READNEXT command having the option KEYLENGTH(0) is always treated as if KEYLENGTH(1) and a partial key of one byte of binary zeros have been specified.

Browsing through an ESDS

Positioning for a browse in an ESDS is identical to that for reading. If you want to begin reading at the beginning of the data set, use an RBA of low values (X'00'), and to begin at the end, use high values (X'FF').

Browsing through an RRDS

You can use the GTEQ option on a STARTBR command when browsing through an RRDS. It is the default, even though on a direct READ this option has no effect. A direct read command with the GTEQ option that specifies an RRN that does not exist returns the NOTFND condition, because only the EQUAL option is taken. However, a STARTBR GTEQ command using the same RRN completes successfully, and sets a pointer to the relevant position in the data set for the start of the browse. The first record in the file is identified using an RRN of 1, and the last record by high values (X'FF').

Browsing using a path

Browsing can also use an alternate index path to a KSDS or an ESDS. The browse is just like that for a KSDS, but using the alternate key. The records are retrieved in alternate key order.

If the alternate key is not unique, the DUPKEY condition is raised for each retrieval operation except the last occurrence of the duplicate key. For example, if there are three records with the same alternate key, DUPKEY is raised on the first two, but not the third. The order in which records with duplicate alternate keys are returned is the order in which they were written to the data set. This is true whether you are using a READNEXT or a READPREV command. For this reason, you cannot retrieve records with the same alternate key in reverse order.

Browse integrity (in RLS mode)

The options UNCOMMITTED, CONSISTENT, REPEATABLE, and NOSUSPEND, discussed in Read integrity (in RLS mode), also apply to the CICS browse commands.

Ending the browse

Trying to browse past the last record in a file raises the ENDFILE condition. Stop a browse with the ENDBR command. You must issue the ENDBR command before performing an update operation on the same file (a READ UPDATE, DELETE with RIDFLD, or WRITE command). If you do not, you get unpredictable results, possibly including deadlock within your own transaction.

Simultaneous browse operations

CICS allows a transaction to perform more than one browse on the same file at the same time. You distinguish between browse operations by including the REQID option on each browse command.

Skip-sequential processing

When possible, CICS uses VSAM "skip-sequential" processing to speed browsing. Skip-sequential processing applies only to forward browsing of a file when RIDFLD is specified in key form. CICS uses it when you increase the key value in RIDFLD on your READNEXT command and make no other key-related specification, such as KEYLENGTH. In this situation, VSAM locates the next desired record by reading forward through the index, rather than repositioning from scratch. This method is faster if the records you are retrieving are relatively close to each other but not necessarily adjacent; it can have the opposite effect if the records are very far apart in a large file. If you know that the key you are repositioning to is much higher in the file, and that you may incur a long index scan, you may wish to consider using a RESETBR command which forces a reposition from scratch.

[[ Contents Previous Page | Next Page Index ]]