Skip to content

COUSR00C

Source: cbl/COUSR00C.cbl

Type: CICS transaction program

COUSR00C — User List Screen

Purpose

COUSR00C is a CICS transaction program in the CardDemo application that displays a paginated list of user security records (from the USRSEC file) to an administrator. It lets the operator page forward/backward through the list (10 users per screen page) and select a user to either update (routes to COUSR02C) or delete (routes to COUSR03C). It is the "browse users" screen invoked from the admin menu (COADM01C) and reached via transaction code CU00.

How it works

MAIN-PARA is the entry point and behaves differently depending on how the transaction was invoked:

  • If EIBCALEN = 0 (no commarea, e.g. abnormal invocation), it sets the return target to COSGN00C and calls RETURN-TO-PREV-SCREEN — effectively bouncing the user back to sign-on.
  • If a commarea is present but this is the first entry into the program (NOT CDEMO-PGM-REENTER), it initializes the output map, calls PROCESS-ENTER-KEY to load the first page of users, then SEND-USRLST-SCREEN to display it.
  • On subsequent invocations (re-entrant, user pressed a key), it calls RECEIVE-USRLST-SCREEN to read the submitted map, then dispatches based on EIBAID:
  • ENTER → PROCESS-ENTER-KEY (process a row selection, or re-filter by typed user ID, then reload page 1 forward)
  • PF3 → set return target to COADM01C and RETURN-TO-PREV-SCREEN
  • PF7 → PROCESS-PF7-KEY (page backward)
  • PF8 → PROCESS-PF8-KEY (page forward)
  • Any other key → error flag set, "invalid key" message, redisplay

PROCESS-ENTER-KEY first checks all 10 select fields (SEL0001I…SEL0010I) for a non-blank value entered by the user next to a row. If found, it captures the selection flag (U/u or D/d) and the corresponding user ID, then does a CICS XCTL to COUSR02C (update) or COUSR03C (delete), passing the commarea. If the flag is anything else, it shows a validation message. Regardless, it also picks up whatever user ID was typed into the filter field, resets the page number to 0, and calls PROCESS-PAGE-FORWARD to (re)load the first page starting from that key.

PROCESS-PAGE-FORWARD / PROCESS-PAGE-BACKWARD implement the paging logic using CICS browse commands against the USRSEC VSAM file: 1. STARTBR-USER-SEC-FILE — position the browse at the current key. 2. READNEXT-USER-SEC-FILE / READPREV-USER-SEC-FILE — read one record to "skip" past the anchor record from the previous page. 3. INITIALIZE-USER-DATA — blank out all 10 screen row slots. 4. A loop reads up to 10 more records via READNEXT/READPREV, calling POPULATE-USER-DATA to fill each screen row (WS-IDX 1–10) with SEC-USR-ID, SEC-USR-FNAME, SEC-USR-LNAME, SEC-USR-TYPE. The first and last row's user IDs are also saved into CDEMO-CU00-USRID-FIRST/-LAST for future page-forward/backward key positioning. 5. One more read attempts to detect whether there is a next/previous page, setting NEXT-PAGE-YES/NO and incrementing/decrementing CDEMO-CU00-PAGE-NUM accordingly. 6. ENDBR-USER-SEC-FILE closes the browse, and SEND-USRLST-SCREEN redisplays the map.

PF7 (backward) refuses to page past page 1 ("You are already at the top of the page…"); PF8 (forward) refuses to page past the last page ("...bottom of the page..."), both without touching the file.

SEND-USRLST-SCREEN always calls POPULATE-HEADER-INFO (title, transaction/program name, current date/time from FUNCTION CURRENT-DATE) before sending the map, using ERASE on first display or normal (non-erase) redisplay depending on WS-SEND-ERASE-FLG.

Inputs & outputs

Resource Type Usage
USRSEC (via WS-USRSEC-FILE) VSAM file, accessed with STARTBR/READNEXT/READPREV/ENDBR Source of user security records; keyed by SEC-USR-ID. Read-only browse — no writes.
DFHCOMMAREA CICS commarea (CARDDEMO-COMMAREA, via COCOM01Y) Carries session/navigation state between programs: from/to program, tranid, page context, and the CDEMO-CU00-INFO paging state (first/last user ID on page, page number, next-page flag, selection flag/ID).
COUSR0A map / COUSR00 mapset BMS screen (SEND/RECEIVE) Displays the 10-row user list, header info, error message line, and filter/select input fields.
Copybooks COCOM01Y, COTTL01Y, CSDAT01Y, CSMSG01Y, CSUSR01Y Working-storage layouts Common commarea, title text, date/time fields, message constants, and user-record layout (SEC-USER-DATA, SEC-USR-ID/FNAME/LNAME/TYPE).
COUSR00, DFHAID, DFHBMSCA Copybooks Map symbolic layout and CICS attention-key/attribute constants.
No SQL tables — Confirmed by parser: sql_tables is empty; this program uses only VSAM/CICS file control, not DB2.

Outbound navigation (XCTL): - COUSR02C — update selected user - COUSR03C — delete selected user - COADM01C — return via PF3 - COSGN00C — return when commarea is missing (EIBCALEN=0) or as default fallback

Things to know

  • Hard-coded transaction/program identifiers: WS-TRANID = 'CU00', WS-PGMNAME = 'COUSR00C', and file name WS-USRSEC-FILE = 'USRSEC ' are fixed constants in working storage, not configurable.
  • Fixed page size of 10 rows is baked into the logic via OCCURS 10 TIMES and the hard-coded EVALUATE WS-IDX WHEN 1 … WHEN 10 structure in both POPULATE-USER-DATA and INITIALIZE-USER-DATA. Adding/removing rows would require touching multiple paragraphs and the map.
  • No SQL/DB2 use — despite being part of a "CardDemo" app that elsewhere uses DB2, this program relies purely on VSAM browse (STARTBR/READNEXT/READPREV/ENDBR) against USRSEC.
  • Error handling is coarse-grained: any unexpected CICS response code (WHEN OTHER in STARTBR/READNEXT/READPREV) sets WS-ERR-FLG to 'Y' and shows a generic "Unable to lookup User..." message; the actual RESP/REAS codes are only sent to DISPLAY (i.e., a CICS console/log), not surfaced in detail to the user or captured for programmatic diagnostics.
  • Redundant reads on paging boundaries: PROCESS-PAGE-FORWARD/BACKWARD each perform an extra READNEXT/READPREV beyond the 10 needed, purely to detect whether another page exists — this pattern is intentional but adds file I/O per page turn.
  • Selection logic scans fields in a fixed textual order (SEL0001I…SEL0010I) and only honors the first non-blank selection found; if a user marks multiple rows, only the first is processed.
  • Selection flag validation accepts U/u (update) or D/d (delete) only; anything else in the selection field triggers an inline error message but does not block the subsequent page reload (PROCESS-PAGE-FORWARD still executes even after an invalid selection).
  • The commarea is truncated/read via EIBCALEN: DFHCOMMAREA(1:EIBCALEN) is moved into CARDDEMO-COMMAREA, so if the commarea passed in is shorter than expected, fields could be uninitialized — this depends on the calling program passing a properly sized commarea (worth verifying against COCOM01Y's length elsewhere in the docs).
  • Send/erase toggling (WS-SEND-ERASE-FLG) controls whether the terminal screen is cleared (ERASE) or not; PF7/PF8 boundary messages explicitly suppress ERASE, meaning the screen is redrawn without clearing first — a minor display-refresh optimization/quirk to be aware of when reproducing screen behavior in a modern UI.
  • No explicit GTEQ on STARTBR — the GTEQ option is commented out (* GTEQ), meaning the browse defaults to an exact-key start; behavior on a non-matching key relies on CICS's default positioning, which should be confirmed against CICS file-control semantics if reimplementing this logic.

CICS commands

RETURN, SEND, RECEIVE, STARTBR, READNEXT, READPREV, ENDBR

Copybooks

COCOM01Y, COTTL01Y, COUSR00, CSDAT01Y, CSMSG01Y, CSUSR01Y, DFHAID, DFHBMSCA

Paragraph flow

flowchart TD
    MAIN_PARA["MAIN-PARA"]
    PROCESS_ENTER_KEY["PROCESS-ENTER-KEY"]
    PROCESS_PF7_KEY["PROCESS-PF7-KEY"]
    PROCESS_PF8_KEY["PROCESS-PF8-KEY"]
    PROCESS_PAGE_FORWARD["PROCESS-PAGE-FORWARD"]
    PROCESS_PAGE_BACKWARD["PROCESS-PAGE-BACKWARD"]
    POPULATE_USER_DATA["POPULATE-USER-DATA"]
    INITIALIZE_USER_DATA["INITIALIZE-USER-DATA"]
    RETURN_TO_PREV_SCREEN["RETURN-TO-PREV-SCREEN"]
    SEND_USRLST_SCREEN["SEND-USRLST-SCREEN"]
    RECEIVE_USRLST_SCREEN["RECEIVE-USRLST-SCREEN"]
    POPULATE_HEADER_INFO["POPULATE-HEADER-INFO"]
    STARTBR_USER_SEC_FILE["STARTBR-USER-SEC-FILE"]
    READNEXT_USER_SEC_FILE["READNEXT-USER-SEC-FILE"]
    READPREV_USER_SEC_FILE["READPREV-USER-SEC-FILE"]
    ENDBR_USER_SEC_FILE["ENDBR-USER-SEC-FILE"]
    MAIN_PARA --> PROCESS_ENTER_KEY
    MAIN_PARA --> PROCESS_PF7_KEY
    MAIN_PARA --> PROCESS_PF8_KEY
    MAIN_PARA --> RECEIVE_USRLST_SCREEN
    MAIN_PARA --> RETURN_TO_PREV_SCREEN
    MAIN_PARA --> SEND_USRLST_SCREEN
    PROCESS_ENTER_KEY --> PROCESS_PAGE_FORWARD
    PROCESS_PAGE_BACKWARD --> ENDBR_USER_SEC_FILE
    PROCESS_PAGE_BACKWARD --> INITIALIZE_USER_DATA
    PROCESS_PAGE_BACKWARD --> POPULATE_USER_DATA
    PROCESS_PAGE_BACKWARD --> READPREV_USER_SEC_FILE
    PROCESS_PAGE_BACKWARD --> SEND_USRLST_SCREEN
    PROCESS_PAGE_BACKWARD --> STARTBR_USER_SEC_FILE
    PROCESS_PAGE_FORWARD --> ENDBR_USER_SEC_FILE
    PROCESS_PAGE_FORWARD --> INITIALIZE_USER_DATA
    PROCESS_PAGE_FORWARD --> POPULATE_USER_DATA
    PROCESS_PAGE_FORWARD --> READNEXT_USER_SEC_FILE
    PROCESS_PAGE_FORWARD --> SEND_USRLST_SCREEN
    PROCESS_PAGE_FORWARD --> STARTBR_USER_SEC_FILE
    PROCESS_PF7_KEY --> PROCESS_PAGE_BACKWARD
    PROCESS_PF7_KEY --> SEND_USRLST_SCREEN
    PROCESS_PF8_KEY --> PROCESS_PAGE_FORWARD
    PROCESS_PF8_KEY --> SEND_USRLST_SCREEN
    READNEXT_USER_SEC_FILE --> SEND_USRLST_SCREEN
    READPREV_USER_SEC_FILE --> SEND_USRLST_SCREEN
    SEND_USRLST_SCREEN --> POPULATE_HEADER_INFO
    STARTBR_USER_SEC_FILE --> SEND_USRLST_SCREEN

Paragraphs

Paragraph Line Performs
MAIN-PARA 98 RETURN-TO-PREV-SCREEN, PROCESS-ENTER-KEY, SEND-USRLST-SCREEN, RECEIVE-USRLST-SCREEN, PROCESS-ENTER-KEY, RETURN-TO-PREV-SCREEN
PROCESS-ENTER-KEY 149 PROCESS-PAGE-FORWARD
PROCESS-PF7-KEY 237 PROCESS-PAGE-BACKWARD, SEND-USRLST-SCREEN
PROCESS-PF8-KEY 260 PROCESS-PAGE-FORWARD, SEND-USRLST-SCREEN
PROCESS-PAGE-FORWARD 282 STARTBR-USER-SEC-FILE, READNEXT-USER-SEC-FILE, INITIALIZE-USER-DATA, READNEXT-USER-SEC-FILE, POPULATE-USER-DATA, READNEXT-USER-SEC-FILE
PROCESS-PAGE-BACKWARD 336 STARTBR-USER-SEC-FILE, READPREV-USER-SEC-FILE, INITIALIZE-USER-DATA, READPREV-USER-SEC-FILE, POPULATE-USER-DATA, READPREV-USER-SEC-FILE
POPULATE-USER-DATA 384
INITIALIZE-USER-DATA 446
RETURN-TO-PREV-SCREEN 506
SEND-USRLST-SCREEN 522 POPULATE-HEADER-INFO
RECEIVE-USRLST-SCREEN 549
POPULATE-HEADER-INFO 562
STARTBR-USER-SEC-FILE 586 SEND-USRLST-SCREEN, SEND-USRLST-SCREEN
READNEXT-USER-SEC-FILE 619 SEND-USRLST-SCREEN, SEND-USRLST-SCREEN
READPREV-USER-SEC-FILE 653 SEND-USRLST-SCREEN, SEND-USRLST-SCREEN
ENDBR-USER-SEC-FILE 687