Reset the start of a browse.
RESETBR >>-RESETBR--FILE(filename)--RIDFLD(data-area)-------------------> >--+------------------------------------+-----------------------> '-KEYLENGTH(data-value)--+---------+-' '-GENERIC-' .-GTEQ--. >--+-------------------+--+-------------------+--+-------+------> '-REQID(data-value)-' '-SYSID(systemname)-' '-EQUAL-' >--+------+---------------------------------------------------->< +-RBA--+ +-RRN--+ '-XRBA-'
Conditions: FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, NOTAUTH, NOTFND, SYSIDERR
- 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.
- 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.
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
- 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 the 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.
