MainframeMaster
MainframeMaster

CICS Browse Operations

CICS browse operations provide a powerful mechanism for sequential file access in both forward and backward directions. These operations are essential for processing file records when you need to read multiple records sequentially without positioning to each one explicitly. Understanding browse operations enables efficient file processing, report generation, and data review functionality in CICS applications.

Understanding Browse Operations

Browse operations in CICS allow applications to read records sequentially from a file. Unlike direct reads that access specific records by key, browse operations maintain a current position pointer and enable forward (READNEXT) or backward (READPREV) movement through the file. This is particularly useful for generating reports, displaying data in lists, and performing batch processing within online transactions.

Think of browse operations like reading a book. STARTBR opens the book to a specific page (initial key). READNEXT is like reading the next page forward, and READPREV reads the previous page backward. ENDBR closes the book when you're done. RESETBR is like using a bookmark to jump to a different page and then continuing to read from there.

STARTBR Command - Beginning a Browse

The STARTBR (Start Browse) command initiates a browse operation and positions to an initial record. It establishes a browse cursor that tracks your current position in the file.

cobol
1
2
3
4
5
6
           EXEC CICS STARTBR
                FILE('CUSTOMER')
                RIDFLD(CUSTOMER-KEY)
                GTEQ
                RESP(WS-RESPONSE)
           END-EXEC.

The STARTBR command supports several important parameters:

  • FILE: The name of the file resource to browse
  • RIDFLD: The record identifier field (key) for VSAM files or RBA for non-indexed files
  • GTEQ (Greater Than or Equal): Start at the first record with a key greater than or equal to the specified key
  • EQUAL: Start at the exact matching record
  • REQID: Optional identifier to manage multiple browse sessions on the same file
  • RESP: Response code field

Common response codes for STARTBR include 0 (normal), 13 (not found), and 8 (file error). Always check the response code before proceeding with READ operations.

READNEXT - Reading Forward

READNEXT retrieves the next sequential record in the forward direction from the current browse position. Each READNEXT advances the cursor to the next record.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
       WORKING-STORAGE SECTION.
       01 WS-CUSTOMER-RECORD.
           05 WS-CUSTOMER-NUMBER PIC X(8).
           05 WS-CUSTOMER-NAME PIC X(30).
           05 WS-CUSTOMER-BALANCE PIC 9(9)V99.
       
       01 WS-DISPLAY-COUNT PIC 9(3) VALUE ZERO.
       
       PROCEDURE DIVISION.
       *> Start browse from first customer
           MOVE LOW-VALUES TO WS-CUSTOMER-NUMBER
           EXEC CICS STARTBR
               FILE('CUSTOMER')
               RIDFLD(WS-CUSTOMER-NUMBER)
               GTEQ
               RESP(WS-RESPONSE)
           END-EXEC
       
           IF WS-RESPONSE NOT = 0
               DISPLAY 'STARTBR failed: ' WS-RESPONSE
               EXEC CICS RETURN END-EXEC
           END-IF
       
       *> Read next 100 records for display
           PERFORM UNTIL WS-DISPLAY-COUNT >= 100
               EXEC CICS READNEXT
                   FILE('CUSTOMER')
                   INTO(WS-CUSTOMER-RECORD)
                   RIDFLD(WS-CUSTOMER-NUMBER)
                   LENGTH(LENGTH OF WS-CUSTOMER-RECORD)
                   RESP(WS-RESPONSE)
               END-EXEC
       
               IF WS-RESPONSE = 0
                   ADD 1 TO WS-DISPLAY-COUNT
                   DISPLAY WS-CUSTOMER-NUMBER ' ' WS-CUSTOMER-NAME
               ELSE IF WS-RESPONSE = 20
                   DISPLAY 'End of file reached'
                   EXIT PERFORM
               ELSE
                   DISPLAY 'Read error: ' WS-RESPONSE
                   EXIT PERFORM
               END-IF
           END-PERFORM
       
       *> Terminate browse
           EXEC CICS ENDBR FILE('CUSTOMER')
           END-EXEC.

The LENGTH parameter specifies the maximum number of bytes to return. If the actual record is shorter, CICS fills the remaining bytes with spaces for alphanumeric fields.

READPREV - Reading Backward

READPREV retrieves the previous sequential record in the backward direction. This allows you to move in reverse through the file, which is useful for reviewing previously processed records or implementing undo functionality.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
       *> Read records in reverse order
           MOVE HIGH-VALUES TO WS-CUSTOMER-NUMBER
           EXEC CICS STARTBR
               FILE('CUSTOMER')
               RIDFLD(WS-CUSTOMER-NUMBER)
               RESP(WS-RESPONSE)
           END-EXEC
       
           IF WS-RESPONSE NOT = 0 AND NOT = 13
               DISPLAY 'STARTBR error: ' WS-RESPONSE
               EXEC CICS RETURN END-EXEC
           END-IF
       
       *> If not found with GTEQ, position to last record
           IF WS-RESPONSE = 13
               EXEC CICS STARTBR
                   FILE('CUSTOMER')
                   RIDFLD(WS-CUSTOMER-NUMBER)
                   GTEQ
                   RESP(WS-RESPONSE)
               END-EXEC
               *> Read forward to get last record
               EXEC CICS READNEXT
                   FILE('CUSTOMER')
                   INTO(WS-CUSTOMER-RECORD)
                   RIDFLD(WS-CUSTOMER-NUMBER)
                   LENGTH(LENGTH OF WS-CUSTOMER-RECORD)
                   RESP(WS-RESPONSE)
               END-EXEC
           END-IF
       
       *> Now read backwards
           EXEC CICS READPREV
               FILE('CUSTOMER')
               INTO(WS-CUSTOMER-RECORD)
               RIDFLD(WS-CUSTOMER-NUMBER)
               LENGTH(LENGTH OF WS-CUSTOMER-RECORD)
               RESP(WS-RESPONSE)
           END-EXEC.

READPREV returns response code 20 (END OF FILE) when attempting to read before the beginning of the file, similar to how READNEXT returns 20 when reaching the end.

RESETBR - Repositioning the Browse

RESETBR allows you to change the browse position to a different key without ending and restarting the browse session. This is more efficient than ending and restarting the browse when you need to jump to a different position.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
       *> Start browse at middle of file
           EXEC CICS STARTBR
               FILE('CUSTOMER')
               RIDFLD(WS-CUSTOMER-NUMBER)
               GTEQ
               RESP(WS-RESPONSE)
           END-EXEC
       
           IF WS-RESPONSE NOT = 0
               DISPLAY 'Start browse failed'
               EXEC CICS RETURN END-EXEC
           END-IF
       
       *> Process some records
           PERFORM 50 TIMES
               EXEC CICS READNEXT
                   FILE('CUSTOMER')
                   INTO(WS-CUSTOMER-RECORD)
                   LENGTH(LENGTH OF WS-CUSTOMER-RECORD)
                   RESP(WS-RESPONSE)
               END-EXEC
               IF WS-RESPONSE NOT = 0
                   EXIT PERFORM
               END-IF
           END-PERFORM
       
       *> Now reset browse to customer 12345
           MOVE '12345   ' TO WS-CUSTOMER-NUMBER
           EXEC CICS RESETBR
               FILE('CUSTOMER')
               RIDFLD(WS-CUSTOMER-NUMBER)
               GTEQ
               RESP(WS-RESPONSE)
           END-EXEC
       
           IF WS-RESPONSE = 0
               EXEC CICS READNEXT
                   FILE('CUSTOMER')
                   INTO(WS-CUSTOMER-RECORD)
                   LENGTH(LENGTH OF WS-CUSTOMER-RECORD)
                   RESP(WS-RESPONSE)
               END-EXEC
           END-IF.

RESETBR uses the same positioning keywords as STARTBR (EQUAL, GTEQ). This is particularly useful in applications where users can jump to different sections of a list while maintaining the browse context.

ENDBR - Ending the Browse

ENDBR terminates the browse session and releases resources. It's critical to always pair ENDBR with STARTBR to ensure proper cleanup.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
       *> Normal browse termination
           EXEC CICS ENDBR
               FILE('CUSTOMER')
               RESP(WS-RESPONSE)
           END-EXEC
       
       *> Browse termination with error handling
           EXEC CICS ENDBR
               FILE('CUSTOMER')
               NOSUSPEND
               RESP(WS-RESPONSE)
           END-EXEC
       
       *> Always handle the browse termination, even on errors
           IF ABEND-OCCURRED
               EXEC CICS ENDBR
                   FILE('CUSTOMER')
                   NOSUSPEND
               END-EXEC
           END-IF.

The NOSUSPEND option prevents transaction suspension during ENDBR. This is important in error handling scenarios where you need to terminate the browse as part of cleanup without affecting transaction boundaries.

Error Handling in Browse Operations

Robust error handling is essential for browse operations. You must handle various error conditions including file errors, end of file conditions, and positioning errors.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
       WORKING-STORAGE SECTION.
       01 WS-FILE-STATUS PIC S9(8) COMP.
       01 WS-EOF PIC X VALUE 'N'.
       
       PROCEDURE DIVISION.
       *> Initialize browse
           MOVE ZERO TO WS-CUSTOMER-NUMBER
           EXEC CICS STARTBR
               FILE('CUSTOMER')
               RIDFLD(WS-CUSTOMER-NUMBER)
               GTEQ
               RESP(WS-FILE-STATUS)
           END-EXEC
       
           EVALUATE WS-FILE-STATUS
               WHEN 0
                   DISPLAY 'Browse started successfully'
               WHEN 13
                   DISPLAY 'No records found'
                   MOVE 'Y' TO WS-EOF
               WHEN OTHER
                   DISPLAY 'STARTBR error: ' WS-FILE-STATUS
                   MOVE 'Y' TO WS-EOF
           END-EVALUATE
       
       *> Read loop with comprehensive error handling
           PERFORM UNTIL WS-EOF = 'Y'
               EXEC CICS READNEXT
                   FILE('CUSTOMER')
                   INTO(WS-CUSTOMER-RECORD)
                   LENGTH(LENGTH OF WS-CUSTOMER-RECORD)
                   RESP(WS-FILE-STATUS)
               END-EXEC
       
               EVALUATE WS-FILE-STATUS
                   WHEN 0
                       PERFORM PROCESS-RECORD
                   WHEN 20
                       DISPLAY 'End of file reached'
                       MOVE 'Y' TO WS-EOF
 STOP               WHEN 8
                       DISPLAY 'File error - ending browse'
                       MOVE 'Y' TO WS-EOF
                   WHEN OTHER
                       DISPLAY 'Unexpected error: ' WS-FILE-STATUS
                       MOVE 'Y' TO WS-EOF
               END-EVALUATE
           END-PERFORM
       
       *> Always end the browse in cleanup
           EXEC CICS ENDBR
               FILE('CUSTOMER')
               NOSUSPEND
               RESP(WS-FILE-STATUS)
           END-EXEC
           
           IF WS-FILE-STATUS NOT = 0 AND WS-FILE-STATUS NOT = 13
               DISPLAY 'ENDBR error: ' WS-FILE-STATUS
           END-IF.

Always check response codes after each browse command. Response code 20 specifically indicates end of file for READ operations and should be handled as a normal condition rather than an error.

Browse Operations Best Practices

Follow these best practices to ensure efficient and reliable browse operations in your CICS applications:

  • Always pair STARTBR with ENDBR: Every STARTBR must have a corresponding ENDBR to release resources
  • Use appropriate positioning: Choose GTEQ when you want to start at or after a key, EQUAL for exact positioning
  • Handle end of file gracefully: Treat response code 20 as a normal condition that signals completion
  • Use REQID for multiple browses: When browsing the same file multiple times, use different REQID values
  • Leverage RESETBR for efficiency: Use RESETBR instead of ENDBR/STARTBR when repositioning within the same browse session
  • Check response codes immediately: Always check response codes after each browse command before proceeding
  • Use NOSUSPEND on ENDBR: Include NOSUSPEND when terminating browse in error handlers

Explain Like I'm 5: Browse Operations

Imagine you're reading a long list of names in a phone book. Browse operations work like this:

  • STARTBR is like opening the phone book to a specific page (maybe where "Smith" would be)
  • READNEXT is like reading the next name on the current page, then turning to the next page and reading the first name there
  • READPREV is like going back to the previous name
  • RESETBR is like putting a bookmark in and jumping to a completely different section (maybe "Johnson"), then continuing to read from there
  • ENDBR is like closing the phone book and putting it away when you're done

Just like you wouldn't want to leave a phone book open on the table when you're done, you always need to close your browse operations with ENDBR!

Practice Exercises

Complete these exercises to reinforce your understanding of CICS browse operations:

Exercise 1: Forward Browse

Write a COBOL program that starts a browse at the beginning of a CUSTOMER file and displays the customer name and number for the first 50 records. Handle end-of-file gracefully with appropriate error handling.

Exercise 2: Backward Browse

Create a program that browses a TRANSACTION file in reverse order, displaying the last 10 transaction records. Use STARTBR with HIGH-VALUES as the key and READPREV to navigate backward.

Exercise 3: Resetting Browse Position

Write a program that browses an ACCOUNT file from a mid-point key value, processes 20 records, then resets the browse position to a different customer's records using RESETBR. Display the new starting point.

Exercise 4: Multiple Browse Sessions

Create a program that maintains two separate browse sessions on the same file using different REQID values. Use one browse to display customer names longest to shortest, and another to show balance from highest to lowest.

Exercise 5: Error Handling Framework

Develop a robust browse operation with comprehensive error handling for all possible response codes (0, 4, 8, 13, 20). Include proper cleanup in all error scenarios and provide user-friendly error messages for each condition.

Test Your Knowledge

1. Which command is used to start a browse operation?

  • READ
  • STARTBR
  • BROWSE
  • OPEN

2. What happens if you attempt READNEXT after reaching the end of file?

  • It returns the last record
  • It sets EIBRESP to 20 (END OF FILE)
  • The program abends
  • It returns the first record

3. Which command resets the browse position to a different key?

  • REPOSBR
  • RESETBR
  • RESTART
  • READPREV

4. What is the purpose of the NOSUSPEND option with ENDBR?

  • To prevent transaction suspension
  • To allow reading in reverse direction
  • To skip error checking
  • To improve performance

5. Which response code indicates a record was not found during STARTBR?

  • 8
  • 12
  • 13
  • 20

6. What is the correct sequence of browse commands?

  • STARTBR → READPREV → ENDBR
  • READ → WRITE → DELETE
  • STARTBR → READNEXT → READPREV → ENDBR
  • OPEN → READ → CLOSE

7. Can you use READPREV immediately after STARTBR without any READNEXT?

  • Yes, it reads backwards from the start position
  • Yes, but only with REQID
  • No, you must read forwards first
  • Yes, if the file is indexed

8. What happens to the browse position if you issue RESETBR with the same key?

  • Position moves to the beginning of the file
  • Position resets to the same record (no-op)
  • Position moves to the end of the file
  • An error is generated

Related Concepts

File Operations

Complete guide to CICS file handling and I/O operations

Resource Cleanup

Proper resource management and cleanup in CICS applications

Transaction Management

Understanding transactions and syncpoints in CICS