FILE RESETBR

The CICS RESETBR (Reset Browse) statement repositions a current active file browse session initiated using STARTBR (Start Browse). It allows changing the current browse position within a VSAM KSDS or ESDS file without ending the browse session.

Syntax -

EXEC CICS RESETBR
     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 being browsed.
RIDFLD(record-id) - Defines the new starting record key or relative record number.
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?

A STARTBR (Start Browse) command is issued to begin the browsing session.
A RESETBR command repositions the browse cursor to a different record.
Subsequent READNEXT or READPREV operations retrieve records from the new position.
The browse session continues without interruption.
The browse session is closed using ENDBR (End Browse) when completed.

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 "11111" 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
        IF WS-CUST-ID = "22222"
			PERFORM RESET-BROWSE 
			   THRU RESET-BROWSE-EXIT
		END-IF
		...
    ELSE IF WS-RESP = DFHRESP(ENDFILE) THEN
         SET EOF-CUST-FILE      TO TRUE
    ELSE
         ...
    END-IF.	
	
READ-NEXT-EXIT.
     EXIT.

RESET-BROWSE.

    MOVE "33333" TO WS-CUST-ID.

    EXEC CICS RESETBR
         FILE('CUSTFILE')
         RIDFLD(WS-CUST-ID)
         KEYLENGTH(10)
         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.	
	
RESET-BROWSE-EXIT.
     EXIT.
    ...

The STARTBR command starts the browse session for sequential access. The READNEXT command retrieves records one by one. If the retrived record key is "22222" then skips the records and reset the browsing position to "33333" using RESETBR. The loop continues until the last record is reached (ENDFILE). The ENDBR command is issued to close the browse session.

Error Conditions -

Eror Condition	RESP	RESP2	Reason
FILENOTFOUND	12	1	A file name in the FILE option is not defined to CICS.
NOTFND	13	80	An attempt to retrieve a record based on the search argument provided is unsuccessful.
NOTFND	13	81	XRBA was specified and the value of RIDFLD was greater than 4 GB but the data set is not an extended addressing ESDS.
INVREQ	16	25	The KEYLENGTH and GENERIC options are specified. The length specified in the KEYLENGTH option is greater than or equal to the length of a full key.
	16	26	The KEYLENGTH option is specified and the length does not equal the length defined for the data set.
	16	36	The REQID, SYSID or file name does not match that of any successful STARTBR command.
	16	37	The type of record identification used to access a data set during the browse has been changed.
	16	42	The KEYLENGTH and GENERIC options are specified. The length specified in the KEYLENGTH option is less than zero.
	16	51	A RESETBR command to a KSDS file accessed in RLS mode specifies the RBA keyword.
IOERR	17	120	There is an I/O error during the RESETBR operation.
ILLOGIC	21	110	VSAM error occurs that is not in one of the other CICS response categories.
ISCINVREQ	54	70	The remote system indicates a failure that does not correspond to a known condition.
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.
70 NOTAUTH	70	101	A resource security check has failed on FILE (filename).