RESETBR

Reset the start of a browse.

RESETBR

Conditions: FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, NOTAUTH, NOTFND, SYSIDERR

This command is threadsafe if the file to which it refers is:

Defined as remote and the command is function shipped over an IPIC connection to a remote CICS® region.
Defined as either local VSAM or RLS.

This command is not threadsafe if the file to which it refers is:

Defined as remote and the command is function shipped over a non-IPIC connection.
Defined as a shared data table, coupling facility data table, or BDAM file.

Description

RESETBR specifies, during a browse, the record in a file or data table on a local or a remote system, where you want the browse to be repositioned.

When browsing a VSAM file or data table, you can use the RESETBR command to reposition the browse (which you can also achieve by modifying the RIDFLD data area on a READNEXT or READPREV command) and you can also change the browse characteristics from those specified on STARTBR, without ending the browse. The characteristics that can be changed are those specified by the GENERIC, GTEQ, and RBA options.

When browsing a BDAM file, you can include this command at any time before issuing any other browse command. It is similar to an ENDBR–STARTBR sequence (but with less function), and gives the BDAM user the sort of skip sequential capability that is available to VSAM users through use of the READNEXT command.

If a RESETBR request specifies the precise key at which the browse is to start (that is, it specifies a full key and the EQUAL keyword) the record returned on the following READNEXT (or READPREV) command might not be the same as the record specified by the RESETBR command for a file opened in VSAM NSR or RLS mode. This can occur because the initial record specified on the RESETBR command can be deleted by another transaction in between the RESETBR completing and a READNEXT or READPREV command being issued. In VSAM LSR mode, the initial record cannot be deleted between the RESETBR and the READNEXT.

Note: RESETBR invalidates a TOKEN set by a previous READ or READNEXT command.

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(filename)

(VSAM and data table) specifies the name 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 to CICS. Otherwise, the resource definition is used to find out whether the data set is on a local or a remote system.

GENERIC

(VSAM KSDS, path or data table) 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 and data table) specifies that if the search for a record that has the same key (complete or generic) as that specified in the RIDFLD option is unsuccessful, the first record that has a greater key is retrieved. Use this option only with keyed or RRN.

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. 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 a RESETBR command specifies GENERIC, and the KEYLENGTH value 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 STARTBR 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.

RBA

(VSAM KSDS or ESDS base data sets, or CICS-maintained data tables only, not paths) specifies that the record identification field specified in the RIDFLD option contains a relative byte address. Use this option only when browsing an ESDS or 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
Any KSDS file opened in RLS access mode
KSDS files that use extended addressing

Also, you are recommended not to use RBA for ESDS files that hold more than 4 GB. (Use XRBA instead.)

REQID(data-value)

specifies as a halfword binary value a unique request identifier for a browse, used to control multiple browse operations on a data set. If this option is not specified, a default value of zero is assumed.

RIDFLD(data-area)

specifies the record identification field. The contents can be a key, a relative byte address, or a relative record number (for VSAM data sets), or a block reference, 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 value can be greater than or equal to zero. For a relative record number, the RIDFLD value can be greater than or equal to 1.

For VSAM, a full record ID of X'FF's indicates that the browse is to be positioned at the end of the data set in preparation for a backwards browse using READPREV commands.

RRN

(VSAM RRDS) specifies that the record identification field specified in the RIDFLD option contains a relative record number.

SYSID(systemname)

specifies the name of the system to which the request is directed.

If you specify SYSID, and omit both RBA and RRN, you must also specify KEYLENGTH; it cannot be found in the resource definition.

XRBA

specifies that the record identification field specified in the RIDFLD option contains an extended relative byte address. This option should be used when browsing records in an ESDS extended addressing data set.

You cannot specify XRBA on a RESETBR command unless the associated STARTBR command also specified XRBA.

Conditions

12 FILENOTFOUND

RESP2 values:

1: A file name referred to in the FILE option is not defined to CICS.

Default action: terminate the task abnormally.

21 ILLOGIC

RESP2 values VSAM):

110: A VSAM error occurs that is not in one of the other CICS response categories.
See EIBRCODE in the EXEC interface block; for details, see EIB fields.

Default action: terminate the task abnormally.

16 INVREQ

RESP2 values:

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.
36: The REQID, SYSID, or file name does not match that of any successful STARTBR command.
37: The type of record identification (for example, key or relative byte address) used to access a data set during the browse has been changed. You cannot specify one type of addressing on STARTBR and another on RESETBR.
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 RESETBR for a user-maintained or coupling facility data table; for example, RBA is specified.
51: A RESETBR command to a KSDS file that is being accessed in RLS mode specifies the RBA keyword. RLS mode does not support RBA access to KSDS data sets.

Default action: terminate the task abnormally.

17 IOERR

RESP2 values:

120

There is an I/O error during the file control operation. An I/O error is any unusual event that is not covered by a CICS condition.

For VSAM files, IOERR usually indicates a hardware error. Further information is available in the EXEC interface block; for details, see EIB fields.

For a coupling facility data table, an IOERR indicates a bad response returned from a coupling facility access.

Default action: terminate the task abnormally.

54 ISCINVREQ

RESP2 values:

70: The remote system indicates a failure that does not correspond to a known condition.

Default action: terminate the task abnormally.

70 NOTAUTH

RESP2 values:

101: A resource security check has failed on FILE(filename).

Default action: terminate the task abnormally.

13 NOTFND

RESP2 values:

80: An attempt to retrieve a record based on the search argument provided is unsuccessful.
NOTFND can also occur if a generic RESETBR with KEYLENGTH(0) specifies the EQUAL option.
81: XRBA was specified, and the value of RIDFLD was greater than 4 GB, but the data set is not an extended addressing ESDS.

Default action: terminate the task abnormally.

53 SYSIDERR

RESP2 values:

130: The SYSID option specifies a name that is neither the local CICS region nor a remote system (as defined by a CONNECTION definition). 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 RESETBR is issued against 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 Setting up and running a coupling facility data table server for information about restarting a coupling facility data table server and reloading a table.

Default action: terminate the task abnormally.