EXEC CICS STARTBR, READNEXT, READPREV, ENDBR for VSAM

Browse operations let a transaction walk VSAM records in key order starting from a chosen position. STARTBR establishes the browse cursor, READNEXT moves forward, READPREV moves backward when supported, and ENDBR tears down the session. Compared to a single READ by key, browse is how you implement scrolling lists, duplicate-key walks, and “next ten after this key” APIs. This page explains positioning modes, REQID usage for multiple cursors, RESP handling for end-of-data conditions, and why forgetting ENDBR is one of the fastest ways to destabilize a region during month-end reporting. Always pair architectural talk of browse with transaction timeout design: long browses under user think time still hold resources.

EQUAL versus GTEQ

Generic browse APIs sometimes expose only GTEQ because callers pass a partial key prefix. Retail examples include “list SKUs starting at 4500” where 4500 may or may not exist as an actual record. Document whether your service returns zero rows as success with empty payload versus NOTFOUND depending on RESP strategy; inconsistent APIs confuse mobile clients.

Minimal forward browse

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
           MOVE START-KEY TO WS-KEY
           EXEC CICS STARTBR
                FILE('CUSTMAS')
                RIDFLD(WS-KEY)
                KEYLENGTH(10)
                GTEQ
                RESP(WS-RESP)
           END-EXEC
           PERFORM UNTIL WS-STOP = 'Y'
               EXEC CICS READNEXT
                    FILE('CUSTMAS')
                    INTO(WS-REC)
                    LENGTH(WS-LEN)
                    RIDFLD(WS-KEY)
                    KEYLENGTH(10)
                    RESP(WS-RESP)
               END-EXEC
               IF WS-RESP = 0
                   PERFORM HANDLE-ROW
               ELSE
                   MOVE 'Y' TO WS-STOP
               END-IF
           END-PERFORM
           EXEC CICS ENDBR
                FILE('CUSTMAS')
                RESP(WS-RESP)
           END-EXEC

After the last row, READNEXT returns a non-zero RESP indicating end of data or end of browse scope; compare against your manual or copybook constants rather than assuming a particular integer in examples. READNEXT often returns updated key images in RIDFLD so subsequent iterations continue forward. Always branch non-normal RESP values to logging; swallowing them produces infinite loops or partial pages with no diagnostics.

REQID for multiple browses

When one program must scan two independent key ranges concurrently—perhaps comparing active versus archived customers—assign distinct REQID values on STARTBR and pass the same REQID on each READNEXT and ENDBR for that session. Mixing REQIDs between sessions is undefined behavior territory. Document maximum concurrent browses per task because table sizes are finite.

RESETBR and repositioning

RESETBR repositions an existing browse without allocating a second session. Use it when user interface paging requests jump to a new anchor key without exiting the program. Misuse patterns call STARTBR repeatedly without ENDBR; that is the leak pattern already warned about. Pair RESETBR with clear RESP handling when the new anchor does not exist.

Duplicates and browse

• After STARTBR EQUAL on a duplicate key, READNEXT walks duplicate records until the key changes.
• Decide business exit criteria before coding; do not rely on accidental key changes from upstream sorting bugs.
• Combine browse with file control maintenance windows; disabled files end browse with errors users should see as maintenance messages.

Paging APIs and performance

Mobile and web front ends request pages of twenty rows. Implement paging with STARTBR plus a limited READNEXT loop rather than reading the entire file for each screen paint. Cache the last RIDFLD returned as the next page cursor token. Guard against users hammering next page during slow queries by applying transaction priorities or limiting concurrent browses per user session. Each extra READNEXT multiplies CPU under load; measure with APM before promising sub-second page loads on billion-row files.

Error recovery mid-browse

If a non-end RESP occurs mid-browse, decide whether to ENDBR immediately or retry after a short delay for transient VSAM errors. Document the decision because on-call engineers will not invent consistent behavior at three in the morning. For user-cancelled screens, always ENDBR in the clear path so the task frees resources even when the user presses cancel during a slow network.

Comparison to batch START

COBOL batch START positions a QSAM or VSAM file for READ NEXT in language I/O. CICS STARTBR is the analogous positioning operation but uses EXEC CICS semantics and browse tokens. Knowing both names reduces confusion when senior developers use “start” casually without specifying batch versus online context in meetings.

Internationalization and keys

When keys include national characters or mixed case, ensure EBCDIC code page consistency between terminals, programs, and VSAM data loads. Browse sessions that use GTEQ on partial keys may behave differently if upstream normalization strips spaces differently than CICS expects. Add encoding tests to your regression suite instead of discovering issues only in overseas pilot regions.

Pair those tests with SYSLOG captures so you can prove which code page was active during any failed browse in production reviews.

Hands-on exercises

1. Implement a sandbox browse of ten rows and log RESP for each READNEXT.
2. Intentionally omit ENDBR in a throwaway program and observe region diagnostic messages your LPAR emits under load tests.
3. Compare STARTBR GTEQ versus EQUAL for the same partial key and document different first rows returned.

Explain Like I'm Five

STARTBR is putting your finger on the shelf between two toys where you want to start walking. READNEXT is sliding your finger to the right, one toy at a time. READPREV slides left. ENDBR is taking your hand off the shelf so other kids can use the same aisle number for their own treasure hunt. REQID is giving each kid a different colored glove so the librarian knows which hunt belongs to whom when many hunts happen at once.

Test Your Knowledge