Skip to content

COCRDLIC

Source: cbl/COCRDLIC.cbl

Type: CICS transaction program

COCRDLIC — Credit Card List Program

Purpose

COCRDLIC is a CICS BMS transaction (CCLI) that displays a scrollable list of credit cards to the user. Administrators (or users without an account filter) see all cards on file; regular users only see the cards tied to their account, as passed in via the commarea. The user can page through results (PF7/PF8), select a card row with S (view) or U (update), and be transferred to the corresponding detail (COCRDSLC) or update (COCRDUPC) program, or exit back to the main menu (COMEN01C) via PF3.

How it works

Entry and context setup (0000-MAIN) - On first entry (EIBCALEN = 0), the program initializes its commarea, sets itself as the "from" program/transaction, and marks itself at the first page (CA-FIRST-PAGE) with no last page yet shown. - On subsequent entries, it splits the incoming DFHCOMMAREA into the shared CARDDEMO-COMMAREA (copybook COCOM01Y) and its own private state block, WS-THIS-PROGCOMMAREA (holds first/last card keys, current screen number, and pagination flags). - If control arrives from the menu (a fresh CDEMO-PGM-ENTER from a different program), the program's private state is reset and the page counters restart at page 1. - YYYY-STORE-PFKEY translates the raw AID key pressed into a normalized value, then 0000-MAIN validates it is one of ENTER, PF3, PF7, or PF8 (PFK-VALID/PFK-INVALID); anything else is coerced into ENTER.

Input receipt and validation (only if returning from itself) - 2000-RECEIVE-MAP calls 2100-RECEIVE-SCREEN (raw RECEIVE MAP) then 2200-EDIT-INPUTS, which in turn validates: - 2210-EDIT-ACCOUNT — account number filter field. - 2220-EDIT-CARD — card number filter field. - 2250-EDIT-ARRAY — the row selection flags (S/U) entered by the user, tracking which row (if any) was selected via I-SELECTED.

Main dispatch (EVALUATE TRUE in 0000-MAIN) — based on validation result and PF key pressed: - Input error → redisplay screen with error message (1000-SEND-MAP), no file read. - PF7 on first page → re-read forward from the first card key (9000-READ-FORWARD), redisplay. - PF3, or re-entering from another program → reset context, reload page 1, redisplay. - PF8 with a next page available → read forward from last displayed card, increment WS-CA-SCREEN-NUM, redisplay. - PF7, not on first page → read backward (9100-READ-BACKWARDS) from the first card, decrement page number, redisplay. - ENTER with a row flagged S (view) → set target program to COCRDSLC, pass selected account/card number, XCTL to it. - ENTER with a row flagged U (update) → same but target COCRDUPC. - OTHER (default) → re-read forward from the first card key and redisplay.

Reading and filtering records - 9000-READ-FORWARD and 9100-READ-BACKWARDS use CICS STARTBR/READNEXT/READPREV/ENDBR against the card file (via key WS-CARD-RID, comprising card number + account ID) to browse the CARDDAT/CARDAIX file/alternate index (see Inputs below), filling the WS-SCREEN-ROWS array (up to 7 rows) for one page. - Each candidate record is passed through 9500-FILTER-RECORDS, which presumably applies the account-based restriction for non-admin users (exact filter logic not shown in the excerpt but referenced by both read paragraphs).

Displaying the screen (1000-SEND-MAP) - 1100-SCREEN-INIT — clears the map, stamps current date/time, transaction/program name, and page number. - 1200-SCREEN-ARRAY-INIT — copies each of up to 7 in-memory rows (account, card number, status, select flag) into the corresponding BMS map fields, skipping rows that are LOW-VALUES (i.e., unused). - 1250-SETUP-ARRAY-ATTRIBS — sets field attributes (e.g., protect/unprotect) for the row select fields. - 1300-SETUP-SCREEN-ATTRS — sets other screen-level attributes. - 1400-SETUP-MESSAGE — builds the info/error message text shown to the user. - 1500-SEND-SCREEN — issues the actual SEND MAP.

Returning control - All paths converge on COMMON-RETURN, which re-stamps the commarea with this program/transaction as the "from" context, repackages the shared commarea plus the private WS-THIS-PROGCOMMAREA block into WS-COMMAREA, and issues EXEC CICS RETURN TRANSID(...) COMMAREA(...) — i.e., control returns to CICS pseudo-conversationally, waiting for the next user action under the same transaction ID (CCLI).

Inputs & outputs

Resource Type Purpose
CARDDAT (literal LIT-CARD-FILE) VSAM file (implied by STARTBR/READNEXT/READPREV) Primary card data file, browsed to build the list of cards.
CARDAIX (literal LIT-CARD-FILE-ACCT-PATH) VSAM alternate index (implied) Used to browse cards by account ID for the account-based filter path.
DFHCOMMAREA CICS commarea (in/out) Carries shared CARDDEMO-COMMAREA state (copybook COCOM01Y) plus this program's private pagination state (WS-THIS-PROGCOMMAREA) across pseudo-conversational calls.
CCRDLIA map (mapset COCRDLI) BMS screen The card list screen — displays 7 rows of account/card/status plus select flags, and info/error messages.
COCRDSLC Called program (XCTL) Card detail view, invoked when a row is selected with S.
COCRDUPC Called program (XCTL) Card update, invoked when a row is selected with U.
COMEN01C Called program (XCTL) Main menu, invoked on PF3 exit.
Copybooks: COCOM01Y, COCRDLI, COTTL01Y, CSDAT01Y, CSMSG01Y, CSUSR01Y, CVACT02Y, CVCRD01Y, DFHAID, DFHBMSCA Data/screen/control-block definitions Common commarea layout, screen layout, titles, date/time, messages, signed-on user info, card record layout, and IBM-supplied CICS constants (AID keys, BMS attributes).

No SQL tables are used (parser found none) — this program relies entirely on VSAM file access via CICS file control commands.

Things to know

  • Hard-coded literals: program name (COCRDLIC), transaction ID (CCLI), mapset/map names, and the names/transids/maps of the menu, detail, and update programs are all embedded as WS-CONSTANTS — any rename of those programs/transactions requires a source change and recompile here.
  • Fixed page size of 7 rows (WS-MAX-SCREEN-LINES VALUE 7) is baked into both the working-storage array (WS-SCREEN-ROWS OCCURS 7 TIMES) and the screen layout paragraph (1200-SCREEN-ARRAY-INIT), which explicitly handles rows 1–7 individually rather than in a loop — increasing page size would require rewriting this paragraph.
  • Row-selection ambiguity: 2250-EDIT-ARRAY tracks a single I-SELECTED index; the dispatch logic assumes only one row was selected. The message WS-MORE-THAN-1-ACTION ("PLEASE SELECT ONLY ONE RECORD TO VIEW OR UPDATE") suggests multi-select is explicitly disallowed, but the exact validation for that is in 2250-EDIT-ARRAY, not shown in this excerpt.
  • No visible error handling for CICS file operations (STARTBR/READNEXT/READPREV/ENDBR) in the given source excerpt — WS-FILE-ERROR-MESSAGE structure exists for building file error messages, implying RESP/RESP2 checking occurs somewhere in 9000-READ-FORWARD/9100-READ-BACKWARDS/9500-FILTER-RECORDS, but the actual response-code branching isn't shown here and should be verified in the full paragraph bodies.
  • Duplicate/dead WHEN clause: in the EVALUATE TRUE in 0000-MAIN, WHEN CCARD-AID-PFK07 AND CA-FIRST-PAGE appears twice in a row (lines are consecutive) — the first is a no-op fallthrough with no statements, immediately followed by the real logic; this looks like a leftover/dead clause but is harmless since COBOL EVALUATE takes the first true match, and here both clauses have the same condition.
  • Commented-out account ID moves: in several places (e.g., page-up/page-down/PF3 paths) the line MOVE WS-CA-xxx-CARD-ACCT-ID TO WS-CARD-RID-ACCT-ID is commented out, meaning only the card number portion of the browse key is being reset, not the account ID — this could be intentional (account ID filter handled elsewhere) or a latent bug; not enough context in this excerpt to be certain.
  • PF key remapping: YYYY-STORE-PFKEY (not shown in detail here) translates raw AID codes before validation — the actual PF key mapping logic lives outside this excerpt and should be checked separately if PF key behavior seems inconsistent.
  • Security/admin filtering: the business rule "admin sees all cards, regular user sees only their own" is implemented via 9500-FILTER-RECORDS, but the actual filter condition (what field distinguishes admin vs. user) is not visible in the supplied source — confirm against CSUSR01Y / CDEMO-USRTYP-* fields before relying on this description for security-sensitive changes.
  • Commarea size risk: the program manually splits/reassembles a fixed-size WS-COMMAREA PIC X(2000) using LENGTH OF CARDDEMO-COMMAREA offsets; if either copybook's size changes without corresponding updates here, this could silently truncate or misalign data.

Files

Logical file DD name
PIC
ONLY

CICS commands

XCTL, RETURN, SEND MAP, RECEIVE MAP, STARTBR, READNEXT, ENDBR FILE, READPREV, SEND TEXT

Copybooks

COCOM01Y, COCRDLI, COTTL01Y, CSDAT01Y, CSMSG01Y, CSUSR01Y, CVACT02Y, CVCRD01Y, DFHAID, DFHBMSCA

Paragraph flow

flowchart TD
    0000_MAIN["0000-MAIN"]
    COMMON_RETURN["COMMON-RETURN"]
    0000_MAIN_EXIT["0000-MAIN-EXIT"]
    1000_SEND_MAP["1000-SEND-MAP"]
    1000_SEND_MAP_EXIT["1000-SEND-MAP-EXIT"]
    1100_SCREEN_INIT["1100-SCREEN-INIT"]
    1100_SCREEN_INIT_EXIT["1100-SCREEN-INIT-EXIT"]
    1200_SCREEN_ARRAY_INIT["1200-SCREEN-ARRAY-INIT"]
    1200_SCREEN_ARRAY_INIT_EXIT["1200-SCREEN-ARRAY-INIT-EXIT"]
    1250_SETUP_ARRAY_ATTRIBS["1250-SETUP-ARRAY-ATTRIBS"]
    1250_SETUP_ARRAY_ATTRIBS_EXIT["1250-SETUP-ARRAY-ATTRIBS-EXIT"]
    1300_SETUP_SCREEN_ATTRS["1300-SETUP-SCREEN-ATTRS"]
    1300_SETUP_SCREEN_ATTRS_EXIT["1300-SETUP-SCREEN-ATTRS-EXIT"]
    1400_SETUP_MESSAGE["1400-SETUP-MESSAGE"]
    1400_SETUP_MESSAGE_EXIT["1400-SETUP-MESSAGE-EXIT"]
    1500_SEND_SCREEN["1500-SEND-SCREEN"]
    1500_SEND_SCREEN_EXIT["1500-SEND-SCREEN-EXIT"]
    2000_RECEIVE_MAP["2000-RECEIVE-MAP"]
    2000_RECEIVE_MAP_EXIT["2000-RECEIVE-MAP-EXIT"]
    2100_RECEIVE_SCREEN["2100-RECEIVE-SCREEN"]
    2100_RECEIVE_SCREEN_EXIT["2100-RECEIVE-SCREEN-EXIT"]
    2200_EDIT_INPUTS["2200-EDIT-INPUTS"]
    2200_EDIT_INPUTS_EXIT["2200-EDIT-INPUTS-EXIT"]
    2210_EDIT_ACCOUNT["2210-EDIT-ACCOUNT"]
    2210_EDIT_ACCOUNT_EXIT["2210-EDIT-ACCOUNT-EXIT"]
    2220_EDIT_CARD["2220-EDIT-CARD"]
    2220_EDIT_CARD_EXIT["2220-EDIT-CARD-EXIT"]
    2250_EDIT_ARRAY["2250-EDIT-ARRAY"]
    2250_EDIT_ARRAY_EXIT["2250-EDIT-ARRAY-EXIT"]
    9000_READ_FORWARD["9000-READ-FORWARD"]
    9000_READ_FORWARD_EXIT["9000-READ-FORWARD-EXIT"]
    9100_READ_BACKWARDS["9100-READ-BACKWARDS"]
    9100_READ_BACKWARDS_EXIT["9100-READ-BACKWARDS-EXIT"]
    9500_FILTER_RECORDS["9500-FILTER-RECORDS"]
    9500_FILTER_RECORDS_EXIT["9500-FILTER-RECORDS-EXIT"]
    SEND_PLAIN_TEXT["SEND-PLAIN-TEXT"]
    SEND_PLAIN_TEXT_EXIT["SEND-PLAIN-TEXT-EXIT"]
    SEND_LONG_TEXT["SEND-LONG-TEXT"]
    SEND_LONG_TEXT_EXIT["SEND-LONG-TEXT-EXIT"]
    0000_MAIN --> 1000_SEND_MAP
    0000_MAIN --> 2000_RECEIVE_MAP
    0000_MAIN --> 9000_READ_FORWARD
    0000_MAIN --> 9100_READ_BACKWARDS
    0000_MAIN -.-> COMMON_RETURN
    1000_SEND_MAP --> 1100_SCREEN_INIT
    1000_SEND_MAP --> 1200_SCREEN_ARRAY_INIT
    1000_SEND_MAP --> 1250_SETUP_ARRAY_ATTRIBS
    1000_SEND_MAP --> 1300_SETUP_SCREEN_ATTRS
    1000_SEND_MAP --> 1400_SETUP_MESSAGE
    1000_SEND_MAP --> 1500_SEND_SCREEN
    2000_RECEIVE_MAP --> 2100_RECEIVE_SCREEN
    2000_RECEIVE_MAP --> 2200_EDIT_INPUTS
    2200_EDIT_INPUTS --> 2210_EDIT_ACCOUNT
    2200_EDIT_INPUTS --> 2220_EDIT_CARD
    2200_EDIT_INPUTS --> 2250_EDIT_ARRAY
    2210_EDIT_ACCOUNT -.-> 2210_EDIT_ACCOUNT_EXIT
    2220_EDIT_CARD -.-> 2220_EDIT_CARD_EXIT
    2250_EDIT_ARRAY -.-> 2250_EDIT_ARRAY_EXIT
    9000_READ_FORWARD --> 9500_FILTER_RECORDS
    9100_READ_BACKWARDS -.-> 9100_READ_BACKWARDS_EXIT
    9100_READ_BACKWARDS --> 9500_FILTER_RECORDS
    9500_FILTER_RECORDS -.-> 9500_FILTER_RECORDS_EXIT

Paragraphs

Paragraph Line Performs
0000-MAIN 298 YYYY-STORE-PFKEY, 2000-RECEIVE-MAP, 9000-READ-FORWARD, 1000-SEND-MAP, 9000-READ-FORWARD, 1000-SEND-MAP
COMMON-RETURN 604
0000-MAIN-EXIT 621
1000-SEND-MAP 624 1100-SCREEN-INIT, 1200-SCREEN-ARRAY-INIT, 1250-SETUP-ARRAY-ATTRIBS, 1300-SETUP-SCREEN-ATTRS, 1400-SETUP-MESSAGE, 1500-SEND-SCREEN
1000-SEND-MAP-EXIT 639
1100-SCREEN-INIT 642
1100-SCREEN-INIT-EXIT 674
1200-SCREEN-ARRAY-INIT 678
1200-SCREEN-ARRAY-INIT-EXIT 745
1250-SETUP-ARRAY-ATTRIBS 748
1250-SETUP-ARRAY-ATTRIBS-EXIT 834
1300-SETUP-SCREEN-ATTRS 837
1300-SETUP-SCREEN-ATTRS-EXIT 890
1400-SETUP-MESSAGE 895
1400-SETUP-MESSAGE-EXIT 933
1500-SEND-SCREEN 938
1500-SEND-SCREEN-EXIT 948
2000-RECEIVE-MAP 951 2100-RECEIVE-SCREEN, 2200-EDIT-INPUTS
2000-RECEIVE-MAP-EXIT 959
2100-RECEIVE-SCREEN 962
2100-RECEIVE-SCREEN-EXIT 981
2200-EDIT-INPUTS 985 2210-EDIT-ACCOUNT, 2220-EDIT-CARD, 2250-EDIT-ARRAY
2200-EDIT-INPUTS-EXIT 999
2210-EDIT-ACCOUNT 1003
2210-EDIT-ACCOUNT-EXIT 1032
2220-EDIT-CARD 1036
2220-EDIT-CARD-EXIT 1069
2250-EDIT-ARRAY 1073
2250-EDIT-ARRAY-EXIT 1119
9000-READ-FORWARD 1123 9500-FILTER-RECORDS
9000-READ-FORWARD-EXIT 1261
9100-READ-BACKWARDS 1264 9500-FILTER-RECORDS
9100-READ-BACKWARDS-EXIT 1374
9500-FILTER-RECORDS 1382
9500-FILTER-RECORDS-EXIT 1409
SEND-PLAIN-TEXT 1422
SEND-PLAIN-TEXT-EXIT 1433
SEND-LONG-TEXT 1441
SEND-LONG-TEXT-EXIT 1452