FILE STARTBR

STARTBR command sets the starting position for record browsing in a local or remote system. No records are actually read until you execute a READNEXT or READPREV command.

There are three types of direct browse operations available using STARTBR:

A direct browse of a key-sequenced data set (KSDS) either by record key or through an alternate index path.
A direct browse of an entry-sequenced data set (ESDS) using a relative byte address (RBA) or an alternate index path.
A direct browse of a relative record data set (RRDS) by relative record number (RRN).

Syntax -

EXEC CICS STARTBR
     FILE('file-name')
     [RIDFLD(record-id)]
     [KEYLENGTH(key-length)]
	 [GENERIC]
	 [REQID(value)]
	 [SYSID(system-name)]
     [RBA|RRN|XRBA]
	 [GETQ|EQUAL]
     [RESP(response-field)]
     [RESP2(response-field2)]
     END-EXEC.

FILE('file-name') - Specifies the VSAM file name from which the record will be read.
RIDFLD(record-id) - Defines the starting record key (for KSDS) or the record ID (for RRDS).
KEYLENGTH(key-length) - Defines the length of the key field (only needed for KSDS). KEYLENGTH is not applicable when RRN is coded. KEYLENGTH must be coded if using SYSID.
GENERIC - Allows partial key searches, repositioning the browse to the closest matching record.
REQID(value) - Specifies unique request identifier for a browse.
SYSID(system-name) - Specifies the system name to which the request is directed. If SYSID coded and omit RBA, XRBA and RRN, LENGTH and KEYLENGTH must be coded.
RBA|RRN|XRBA - Specifies the type of the file and data in the RIDFLD.
EQUAL - Specifies the record that matches the key coded in the RIDFLD should be retrieved.
GTEQ - SThis applies only to VSAM KSDS files. If an exact match is found, the corresponding record will be retrieved. If an exact match for the specified key in the RIDFLD is not found, the system will retrieve the first record with a key that is greater than the specified key.
RESP(response-variable) - Optional. It captures the response code of the RESETBR operation and used to check if the command executed successfully or encountered an error.
RESP2(response2-variable) - Optional. It captures the response2 code of the RESETBR operation when the error occured.

How it works?

The STARTBR command is executed to begin browsing the file.
If a specific key is provided (RIDFLD), the browse starts at that record.
Subsequent READNEXT or READPREV operations retrieve records sequentially.
The browse session is closed using ENDBR (END BROWSE) after reading records.

Short Examples -

Scenario - Browsing a KSDS File from a Specific Key.

...
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CUSTOMER-RECORD.
   05 WS-CUST-ID        PIC X(10).
   05 WS-CUST-NAME      PIC X(30).
   05 WS-CUST-ADDRESS   PIC X(50).
   05 WS-CUST-PHONE     PIC X(15).
   
...
PROCEDURE DIVISION.

    MOVE "12345" TO WS-CUST-ID.

    EXEC CICS STARTBR
         FILE('CUSTFILE')
		 RIDFLD(WS-CUST-ID)
         RESP(WS-RESP)
         END-EXEC.

    IF WS-RESP = DFHRESP(NORMAL) THEN
       PERFORM READ-NEXT-REC 
	      THRU READ-NEXT-EXIT
		 UNTIL EOF-CUST-FILE
	END-IF.

    EXEC CICS ENDBR
         FILE('CUSTFILE')
         END-EXEC.
		 
	...
READ-NEXT-REC.

    EXEC CICS READNEXT
         FILE('CUSTFILE')
         INTO(WS-CUST-RECORD)
         RESP(WS-RESP)
         END-EXEC.

    IF WS-RESP = DFHRESP(NORMAL) THEN
        ...
    ELSE IF WS-RESP = DFHRESP(ENDFILE) THEN
         SET EOF-CUST-FILE      TO TRUE
    ELSE
         ...
    END-IF.	
	
READ-NEXT-EXIT
     EXIT.
    ...

The STARTBR command starts the browse session for sequential access. The READNEXT command retrieves records one by one. The loop continues until the last record is reached (ENDFILE). The ENDBR command is issued to close the browse session.

Error Conditions -

XRBA was specified, and the value of RIDFLD was greater than 4 GB, but the data set is not an extended ESDS.

Eror Condition	RESP	RESP2	Reason
FILENOTFOUND	12	1	A file name in the FILE option is not defined to CICS and SYSID has not been specified.
NOTFND	13	80	An attempt to retrieve a record based on the search argument provided is unsuccessful.
NOTFND	13	81
INVREQ	16	20	Browse operations are not allowed according to the resource definition.
	16	25	The KEYLENGTH and GENERIC options are specified and the length in the KEYLENGTH option is greater than or equal to the length of a full key.
	16	26	The KEYLENGTH option is and the specified length does not equal the length defined for the data set.
	16	33	An attempt is made to start a browse with a REQID already in use for another browse.
	16	42	The KEYLENGTH and GENERIC options and the length specified in the KEYLENGTH option is less than zero.
	16	51	STARTBR command to a KSDS file that is being accessed in RLS mode specifies the RBA keyword.
	16	59	XRBA was specified but the data set is not an extended ESDS.
IOERR	17	120	There is an I/O error during the READ operation.
NOTOPEN	19	60	Below are the reasons for NOTOPEN The requested file is CLOSED and UNENABLED. The requested file is OPEN and in use by other transactions, but a CLOSE request against the file has been received. The requested file is CLOSED and ENABLED, so CICS has tried to open the file as part of executing the request.
ILLOGIC	21	110	VSAM error occurs that is not in one of the other CICS response categories.
SYSIDERR	53	130	The SYSID name specified is neither the local region nor a remote system or the link to the remote system is closed.
ISCINVREQ	54	70	The remote system indicates a failure that does not correspond to a known condition.
NOTAUTH	70	101	A resource security check has failed on FILE (filename).
DISABLED	84	50	A file is disabled.