Start browse of a file.

STARTBR
>>-STARTBR--FILE(filename)--RIDFLD(data-area)------------------->
>--+------------------------------------+----------------------->
'-KEYLENGTH(data-value)--+---------+-'
'-GENERIC-'
>--+-------------------+--+-------------------+--+--------+----->
'-REQID(data-value)-' '-SYSID(systemname)-' +-RBA----+
+-RRN----+
+-DEBKEY-+
'-DEBREC-'
>--+-------+---------------------------------------------------><
+-GTEQ--+
'-EQUAL-'
Conditions: DISABLED, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ,
LOADING, NOTAUTH, NOTFND, NOTOPEN, SYSIDERR
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.
A browse operation, where direct means
browse of the base data set (using the primary key), may be:
- 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.
Note: The only VSAM data sets greater than 4GB supported by CICS® are KSDS,
and then only if they are accessed by key. CICS does not support ESDS or RRDS
data sets defined with the extended attribute.
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.
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 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
or 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 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 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 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
base, or a KSDS base when 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 files opened in RLS access mode
- KSDS or ESDS files that hold more than 4GB
- 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 can be greater than
or equal to zero. For a relative record number, the RIDFLD can be greater
than or equal to 1.
See 'Identifying
BDAM records' and 'VSAM
record identification' in the CICS Application Programming Guide 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.
Conditions
- 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.
- FILENOTFOUND
- RESP2
values:
- 1
- A file name referred to in the FILE option cannot be found in the FCT
and SYSID has not been specified.
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; refer to EXEC interface block for details.)
Default action: terminate the task abnormally.
- INVREQ
- RESP2
values:
- 20
- Browse operations are not allowed according to the file entry specification
in the FCT.
- 25
- The KEYLENGTH and GENERIC options are specified, and the length defined
for the data set to which this file 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.
- 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.
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; refer to EXEC interface block for
details.
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.
- 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.
- 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 position on a record based on the search argument provided
is unsuccessful.
NOTFND can also occur if a generic STARTBR with KEYLENGTH(0)
specifies the EQUAL option.
Default action: terminate the task abnormally.
- 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.
- SYSIDERR
- RESP2
values:
- 130
- The SYSID option specifies a name that is neither the local CICS region
nor a remote system 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 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 CICS System Definition Guide for
information about restarting a coupling facility data table server and reloading
a table.
Default action: terminate the task abnormally.