Browser commands in cics - STARTBR Command

The STARTBR command EXEC CICS              STARTBR DATASET(file-name)             RIDFLD(data-area)              [ RRN | RBA ]         ...

The STARTBR command

EXEC CICS

             STARTBR DATASET(file-name)

            RIDFLD(data-area)

             [ RRN | RBA ]

              [ GTEQ | EQUAL ]

              [ GENERIC ]

              [ KEYLENGTH(data-value) ]

              [ REQID(data-value) ]

              [ SYSID(name) ]

END-EXEC

Options:

DATASET Specifies the file name as defined using CEDA DEFINE FILE(file-name) GROUP(group-name)

RIDFLD For a KSDS specifies the key of the record where the browse

Will start. For a RRDS it specifies the relative record number and for an ESDS it specifies the RBA (PIC S9(8) COMP).

RRN Specifies that the file is a RRDS and the RIDFLD should be interpreted as a relative record number.

RBA Specifies that the file is an ESDS and the RIDFLD should be interpreted as a Relative Byte Address.

GTEQ Specifies that the browse operation will start with a record whose key is greater than or equal to the RIDFLD.

EQUAL Specifies that the browse operation will start with a record whose key is equal to the RIDFLD.

GENERIC Specifies that only a part of the key (left part, whose length is indicated by KEYLENGTH) is supplied in the RIDFLD. The first record that matches this key is the point of start of the browse.

KEYLENGTH is a PIC S9(4) COMP field that specifies the length of the generic key. The value must be less than the length of the key defined for the file.

REQID Specifies a binary half word or literal value that identifies this browse operation. Useful when more than one browse is started on same file. You can then explicitly direct further browse operations to a specific browse instance.

SYSID Specifies a 1 to 4 character connection name that represents a remote system.

Conditions:

The RESP field can have the following values:-

DISABLED file is disabled using CEMT SET

DSIDERR File is not defined to CICS

ILLOGIC A serious VSAM error occurred

INVREQ The browse operation is not enabled for this File when it was defined using CEDA, the REQID already exists, the KEYLENGTH value is incorrect, or the file is a user maintained table.

IOERR An IOERR occurred

NOTAUTH The transactions definition specified resource Checking and the operator is not authorized to Access the data set.

NOTFND The specified record could not be located.

NOTOPEN the data set is not open

SYSIDERR The system identified by SYSID could not be found.

Notes:

• You must issue a STARTBR command before you issue READNEXT or READPREV.

• To browse via a alternate index specify a path name for the data set when you define the file.

• You need to define a string for each browse operation. A string is in this case one index and one data buffer. The string is held right from STARTBR to ENDBR.

• You can skip records when browsing simply by changing the RIDFLD value when you browse using READNEXT or READPREV on the file. This is called skip sequential processing. You can also do this by RESETBR but with this command the string resource is released and reacquired. There is therefore a possibility of the transaction going into string wait.

• CICS sets the data area corresponding to the RIDFLD field with the key of the record fetched using READNEXT or READPREV.

• In the case of a KSDS you can start at the beginning of the file by moving low values to the RIDFLD when you issue STARTBR. If you have defined a numeric key field, move zeroes to the key field, as the compiler wont allow you to move low values to the key field. In the case of an ESDS move 0 to the RIDFLD. In the case of a RRDS move 1 to the RIDFLD.

• To start the browse at the end of a file, for a KSDS move high values (X’FF’) to the RIDFLD. High values is a special case, it does not cause a NOTFND condition. Unfortunately moving all 9’s to a numeric key field will cause a NOTFND condition if the record is not found. In this case redefine the field as a alphanumeric field and move high values to it to start the browse at the end of the file. For an ESDS or a RRDS move HIGH VALUES to the RIDFLD.

• To start a browse at a specific record that must exist in the file, code the EQUAL keyword and move the key of the record to the RIDFLD.