STARTBR

Start browse of a file.

STARTBR

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:

The STARTBR specifies a record that has not yet been loaded into a coupling facility data table. Records can be read while a CFDT is loading only if the requested key is within the range of those records already loaded.
The LOADING response can also be returned for a coupling facility data table that has failed during loading. For more information about what happens if the load for a coupling facility data table fails, see the description of the XDTLC global user exit in Data tables management exits XDTRD, XDTAD, and XDTLC.
The READ specifies the GENERIC or GTEQ options for a user-maintained data table. While a UMT is being loaded, you can issue start browse requests with precise keys only.

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 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.