Reset start of browse.

RESETBR
>>-RESETBR--FILE(filename)--RIDFLD(data-area)------------------->
>--+------------------------------------+----------------------->
'-KEYLENGTH(data-value)--+---------+-'
'-GENERIC-'
.-GTEQ--.
>--+-------------------+--+-------------------+--+-------+------>
'-REQID(data-value)-' '-SYSID(systemname)-' '-EQUAL-'
>--+-----+-----------------------------------------------------><
+-RBA-+
'-RRN-'
Conditions: FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, NOTAUTH,
NOTFND, SYSIDERR
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 this command not only to reposition the browse (which can
be achieved more simply by modifying the RIDFLD data area on a READNEXT or
READPREV command), but also to change its characteristics from those specified
on STARTBR, without ending the browse. The characteristics that may 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 prior to 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) may not be the same as the record
specified by the RESETBR 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 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 in the FCT. Otherwise,
the FCT entry 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 having the same
key (complete or generic) as that specified in the RIDFLD option is unsuccessful,
the first record having 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 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 a KSDS
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
- KSDS or ESDS files that hold more than 4GB
- Any KSDS files opened in RLS access mode
- 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 can be greater than
or equal to zero. For a relative record number, the RIDFLD 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 FCT.
Conditions
- FILENOTFOUND
- RESP2
values:
- 1
- A file name referred to in the FILE option cannot be found in the FCT.
Default action: terminate the task abnormally.
- ILLOGIC
- RESP2
values VSAM):
- 110
- A VSAM error occurs that does not fall within one of the other CICS response
categories.
(See EIBRCODE in the EXEC interface block, atEXEC interface block.)
Default action: terminate the task abnormally.
- 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, if any, does not match that of any successful STARTBR command.
- 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.
- 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 normally indicates a hardware error.
(Further information
is available in the EXEC interface block, see EXEC interface block.)
For
a coupling facility data table, an IOERR indicates a bad response returned
from a coupling facility access.
Default action: terminate the task abnormally.
- ISCINVREQ
- RESP2
values:
- 70
- The remote system indicates a failure that does not correspond to a known
condition.
Default action: terminate the task abnormally.
- NOTAUTH
- RESP2
values:
- 101
- A resource security check has failed on FILE(filename).
Default action: terminate the task abnormally.
- 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.
Default action: terminate the task abnormally.
- 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 CICS System Definition Guide for
information about restarting a coupling facility data table server and reloading
a table.
Default action: terminate the task abnormally.