Sequential reading (browsing)

Use the STARTBR, READNEXT, READPREV, and RESETBR commands to browse records in a file. You can browse forwards or backwards, and change the position or characteristics of the browse while the browse is in progress. Use the ENDBR, SYNCPOINT and SYNCPOINT ROLLBACK commands to end the browse.

About this task

When browsing records, you generally identify and read the records in the same way as for a direct read using the READ command (see Direct reading (using READ command)). You specify the record identification field (RIDFLD option), and select a destination for the read records. If the file is open in RLS mode, you can use the UNCOMMITTED, CONSISTENT, REPEATABLE and NOSUSPEND options to control read integrity. Some additional special cases for browsing are noted in this topic.

The same types of key are used for browsing as for a direct read:

For a KSDS, a full key, a generic key, or an alternate key can be used.
For a standard (non-extended) ESDS, an RBA or an alternate key can be used.
For an extended ESDS, an extended RBA (XRBA) can be used.
Note: In some circumstances, a 32-bit RBA can be used to access an extended (64-bit) ESDS: see Relative record number (RRN), relative byte address (RBA) and extended relative byte address (XRBA).
For an RRDS, an RRN is used.

If you use an alternate key for browsing, 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.

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.

The instructions in this topic cover general principles for browsing, and specific information for the different types of VSAM data set. For specific information about browsing BDAM data sets, see Browsing records from BDAM data sets.

Procedure

To start a browse, use the STARTBR command.
The STARTBR command only identifies the starting position for the browse; it does not retrieve a record.
Identify a particular record in the same way as for a direct read, and use the RIDFLD option to specify the record identification. See Direct reading (using READ command), and also note the following considerations:
1. To position the browse at the start of the file, for a KSDS or ESDS, specify a RIDFLD of hexadecimal zeros.
  For a standard ESDS, also specify the RBA option. For an extended ESDS, specify the XRBA option.
2. To position the browse at the start of the file, for an RRDS, specify an RRN of 1 using the RIDFLD option, and also the RRN option.
3. For a KSDS only, as an alternative method to position the browse at the start of the file, you may specify the options GENERIC, GTEQ, and KEYLENGTH(0).
  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.
  A browsing command with the option KEYLENGTH(0) is always treated as if KEYLENGTH(1) and a partial key of one byte of binary zeros have been specified.
4. To position the browse at the last record in the file, ready for a backward browse, specify a RIDFLD of X'FF' characters.
  This applies to starting a browse of a KSDS, ESDS, or RRDS. For a standard ESDS, specify the RBA option. For an extended ESDS, specify the XRBA option. For an RRDS, specify the RRN option.
5. For starting a browse of a KSDS, you may specify a generic key using the RIDFLD option.
  However, if you use a generic key, you can only browse forwards through the file, not backwards.
6. For starting a browse of a KSDS, you may use the options EQUAL (key equal to) and GTEQ (key greater than or equal to), and they have the same meaning as on the READ command.
  However, option GTEQ is the default for the STARTBR command, whereas EQUAL is the default for the READ command. The STARTBR command assumes that you want to position at the key specified or the first key greater if that key does not exist.
7. For starting a browse of an RRDS, the GTEQ (key greater than or equal to) option is the default on a STARTBR command.
  When this option is in effect, if the specified RRN does not exist, a pointer is set to the first record having a greater key.
  Note that the GTEQ option has no effect on a direct READ command for a RRDS, and if a direct READ command specifies an RRN that does not exist, the NOTFND condition is returned.
To browse through the records, use the READNEXT command.
The READNEXT command reads records sequentially from the starting point specified by the STARTBR command. It operates in a similar way to a direct read. See Direct reading (using READ command), and also note the following considerations:
1. Include the RIDFLD option to give CICS® a way to return the identifier of each record retrieved, but do not set the field, unless you want to reposition the browse.
  On completion of each READNEXT command, CICS returns the full key of the record it retrieved. Be sure to provide a field as long as the full key, even if you use a STARTBR command with a shorter generic key.
2. You only need the KEYLENGTH option if you are providing a key using the RIDFLD option, to reposition the browse.
  Otherwise, the current key length is used, as set on the STARTBR command or during the last repositioning of the browse.
3. For remote files for which the SYSID option has been specified, the KEYLENGTH option must be specified if the RIDFLD option is passing a key to file control. If the remote file is being browsed, the KEYLENGTH option is not required for the READNEXT or READPREV commands.
4. As for a direct read, you can read the record 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.
To browse backwards in the file, use READPREV commands instead of READNEXT commands.
The READPREV command is like the READNEXT command, except that the records are read sequentially backward from the current position. You can switch from one direction to the other at any time.
Note the following considerations:
1. As you switch from one direction to the other, you retrieve the same record twice, unless you reposition.
2. If you issue a READPREV command immediately following a STARTBR command, your STARTBR command RIDFLD must specify the key of a record that exists on the data set; otherwise the NOTFND condition occurs.
  To avoid this response, you could issue a READNEXT command following the STARTBR command, to return a record that exists on the data set. Then issue the READPREV command, which retrieves the same record that was retrieved by the READNEXT command.
3. For a KSDS, if you used a generic key on the STARTBR command, you cannot use the READPREV command. An INVREQ condition is returned if you try to use the command in this case.
To change the current browse position when the browse has started (reposition the browse), use either the RESETBR command, or the READNEXT command, or the READPREV command.
1. For VSAM, you can reposition the browse by setting a value in RIDFLD when you issue the next READNEXT or READPREV command.
  - When you set RIDFLD to reposition a browse, the record identifier must be in the same form as on the previous STARTBR or RESETBR command (key, RBA, XRBA, or RRN). You can use a key, or use hexadecimal zeroes to indicate the beginning of the file, or for a KSDS, specify the options GENERIC, GTEQ, and KEYLENGTH(0) to indicate the beginning of the file. If you use the KEYLENGTH(0) option, note that 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. (X'FF' characters cannot be used for repositioning with the READNEXT or READPREV command.)
  - 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 the RIDFLD option.
  If you also want to change characteristics of the browse, use the RESETBR command instead.
2. The RESETBR command can specify a new browse position in the same ways as the STARTBR command.
  You can:
  - Identify a specific record.
  - Use a key of hexadecimal zeros to indicate the beginning of the file.
  - Use a key of X'FF' characters to indicate the end of the file.
  - For a KSDS, use the options GENERIC, GTEQ, and KEYLENGTH(0) to indicate the beginning of the file. If you use the KEYLENGTH(0) option, note that 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.
To change the characteristics of the browse (for example, to search with a generic key instead of an exact match), use the RESETBR command.
You can use the command to:
- Change the form of the key from key to RBA.
- Switch between generic and full keys, or between equal to and greater than or equal to searches.
Under certain conditions, CICS uses VSAM skip-sequential processing when you change the key, as explained in Skip-sequential processing.
To end the browse, use the ENDBR command. There is no RIDFLD for this command.
Trying to browse past the last record in a file raises the ENDFILE condition. 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. You can also end the browse by using the SYNCPOINT and SYNCPOINT ROLLBACK commands. If an implicit sync point occurs at the end of a task, the browse also ends.