Start browse of a file.
STARTBR
>>-STARTBR--FILE(filename)--RIDFLD(data-area)------------------->
>--+------------------------------------+----------------------->
'-KEYLENGTH(data-value)--+---------+-'
'-GENERIC-'
>--+-------------------+--+-------------------+--+--------+----->
'-REQID(data-value)-' '-SYSID(systemname)-' +-DEBKEY-+
+-DEBREC-+
+-RBA----+
+-RRN----+
'-XRBA---'
>--+-------+---------------------------------------------------><
+-GTEQ--+
'-EQUAL-'
Conditions: DISABLED, FILENOTFOUND, ILLOGIC, INVREQ, IOERR,
ISCINVREQ, LOADING, NOTAUTH, NOTFND, NOTOPEN, 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
STARTBR specifies the record
in a file, or in a data table, on a local or a remote system, where
you want the browse to start. No records are read until a READNEXT
command (or, for VSAM and tables, a READPREV command) is executed.
The
following browse operations are possible. A direct browse is a browse
of the base data set by using the primary key.
- A direct browse of a key sequenced data set (KSDS or data-table)
by record key.
- A direct browse of an entry sequenced data set (ESDS) by relative
byte address (RBA).
- A direct browse of a relative record data set (RRDS) by relative
record number (RRN).
- A browse of a key sequenced data set (KSDS) using an alternate
index path.
- A browse of an entry sequenced data set (ESDS) using an alternate
index path. In this case, an ESDS is browsed by key in the same way
as a KSDS. Some of the options that are not valid for a direct ESDS
browse are valid for an alternate index browse.
- A browse of a KSDS by RBA.
The options specified on the STARTBR command define the
characteristics that apply throughout the subsequent browse operation.
Specifically, if GENERIC or GTEQ are specified, they are used not
only when determining the starting point of the browse, but also whenever
the value of RIDFLD is changed before issuing a READNEXT command.
If
you specify the RBA option, it applies to every READNEXT or READPREV
command in the browse, and causes CICS to return the relative byte
address of each retrieved record.
None of these options can
be changed during a browse, except by means of the RESETBR command.
If
a STARTBR 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 STARTBR for a file opened
in VSAM NSR or RLS mode. This can occur because the initial record
specified on the STARTBR command can be deleted by another transaction
in between the STARTBR completing and a READNEXT or READPREV being
issued. In VSAM LSR mode, the initial record cannot be deleted between
the STARTBR and the READNEXT.
A browse can end by using the
ENDBR, SYNCPOINT, or SYNCPOINT ROLLBACK commands. Also an implicit
sync point at the end of task ends the browse.
Options
- DEBKEY
- (blocked
BDAM) specifies that deblocking is to occur by key. If neither DEBREC
nor DEBKEY is specified, deblocking does not occur.
- DEBREC
- (blocked
BDAM) specifies that deblocking is to occur by relative record (relative
to zero). If neither DEBREC nor DEBKEY is specified, deblocking does
not occur.
- EQUAL
- (VSAM
and data table) specifies that the search is satisfied only by a record
having the same key (complete or generic) as that specified in the
RIDFLD option.
This option is the default field for a direct ESDS
browse.
- FILE(filename)
- 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
or 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 satisfies
the search.
This option is the default for directly browsing through
a KSDS or an RRDS. It is not valid for directly browsing an ESDS,
although it is valid for browsing through an ESDS using a path.
- 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 STARTBR 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 positioning
on 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 is unpredictable.
For
remote files, the KEYLENGTH value 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 4GB. (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 the same or different
data sets. 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 relative record number (for VSAM data sets), or a
block reference, physical key, and 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.
See Identifying BDAM records and Identifying VSAM records for
more information about defining the record identification field.
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. This option should
only be used with files referencing relative record data sets.
- 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.
- 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.
If
you specify XRBA on a STARTBR command, all other commands within the
same browse must also specify XRBA.
KSDS data sets cannot be
accessed by XRBA.
Conditions
- 84 DISABLED
- RESP2
values:
- 50
- A file is disabled. A file may be disabled because:
- It was initially defined as disabled and has not since been enabled.
- It has been disabled by a SET FILE or a CEMT SET FILE command.
Default action: terminate the task abnormally.
- 12 FILENOTFOUND
- RESP2
values:
- 1
- A file name referred to in the FILE option is not defined to CICS,
and SYSID has not been specified.
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:
- 20
- Browse operations are not allowed according to the resource definition.
- 25
- The KEYLENGTH and GENERIC options are specified, and the length
defined for the data set to which this file refers 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.
- 33
- An attempt is made to start a browse with a REQID already in use
for another browse.
- 42
- The KEYLENGTH and GENERIC options are specified, and the length
specified in the KEYLENGTH option is less than zero.
- 44
- The specified file is a user-maintained or coupling facility data
table and the command does not conform to the format of STARTBR for
such a data table (for example, RBA is specified).
- 51
- A STARTBR 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 files.
- 59
- XRBA was specified, but the data set is not an extended ESDS.
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.
- 94 LOADING
- RESP2
values:
- 104
- The request cannot be satisfied because it is issued against a
data table that is still being loaded. The condition can be raised
for one of the following reasons:
If your application programs encounter the LOADING condition
persistently or too frequently, check that this is not caused by conflicting
file definitions that reference the same data set.
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 position on a record based on the search argument
provided is unsuccessful.
- 81
- XRBA was specified, and the value of RIDFLD was greater than 4
GB, but the data set is not an extended addressing ESDS.
NOTFND can also occur if a generic STARTBR with
KEYLENGTH(0) specifies the EQUAL option.
Default action: terminate
the task abnormally.
- 19 NOTOPEN
- RESP2
values:
- 60
- NOTOPEN (RESP2 60) is returned for one of the following reasons:
- The requested file is CLOSED and UNENABLED. The CLOSED, UNENABLED
state is reached after a CLOSE request has been received against an
OPEN ENABLED file and the file is no longer in use. You can also make
CLOSED, UNENABLED the initial state, by specifying STATUS(UNENABLED)
and OPENTIME(FIRSTREF) on the FILE resource definition. (For BDAM
files, you use the FILSTAT parameter of the DFHFCT TYPE=FILE macro.)
- The requested file is OPEN and in use by other transactions, but
a CLOSE request against the file has been received.
- A STARTBR command is issued against a data set that is quiesced,
or is being quiesced, as a result of a SET DSNAME QUIESCED or IMMQUIESCED
command.
- The requested file is CLOSED and ENABLED, so CICS has tried to
open the file as part of executing the request. This file open has
failed for some reason. You should examine the console for messages
that explain why the file open has been unsuccessful.
This condition does not occur if the request is
made to a CLOSED, DISABLED file. In this case, the DISABLED condition
occurs.
Default action: terminate the task abnormally.
- 53 SYSIDERR
- RESP2
values:
- 130
- The SYSID option specifies a name that is neither the local system
nor a remote system that is defined by a CONNECTION or IPCONN definition.
SYSIDERR also occurs when the link to the remote system is known but
unavailable. In the case of an IPCONN, SYSIDERR occurs if the link
is known but either the local or remote systems do not support file
control commands that are function shipped using IP interconnectivity.
- 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 start browse is operating on 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.