Skip to content

COTRN00C

Source: cbl/COTRN00C.cbl

Type: CICS transaction program

COTRN00C — Transaction List Screen Handler

Purpose

COTRN00C is a CICS transaction (CT00) that implements the "List Transactions" screen in the CardDemo application. It lets a user browse the TRANSACT file page-by-page (10 transactions per screen), select a transaction to drill into, and navigate forward/backward through the transaction list using PF7/PF8. It is a screen-driven, pseudo-conversational CICS program — it does not perform any batch or SQL processing (no SQL tables are involved; all data access is via CICS file control against a VSAM-style dataset).

How it works

MAIN-PARA (line 95) is the entry point on every invocation of transaction CT00:

  • If EIBCALEN = 0 (first-ever call, no commarea), it routes back to the sign-on screen COSGN00C via RETURN-TO-PREV-SCREEN.
  • Otherwise it copies the incoming commarea into CARDDEMO-COMMAREA.
  • On first entry into this program (NOT CDEMO-PGM-REENTER), it initializes the output map, calls PROCESS-ENTER-KEY to load the first page, and sends the screen via SEND-TRNLST-SCREEN.
  • On subsequent entries (user pressed a key), it calls RECEIVE-TRNLST-SCREEN to read the map, then dispatches based on EIBAID:
    • ENTER → PROCESS-ENTER-KEY (validate/select a transaction or filter by Tran ID, reload page 1 forward)
    • PF3 → RETURN-TO-PREV-SCREEN (back to COMEN01C)
    • PF7 → PROCESS-PF7-KEY (page backward)
    • PF8 → PROCESS-PF8-KEY (page forward)
    • any other key → error message "Invalid Key Pressed" and redisplay

The program ends every path with EXEC CICS RETURN TRANSID('CT00') COMMAREA(...), making it pseudo-conversational (state persists in the commarea between calls).

PROCESS-ENTER-KEY (146) scans the 10 selection fields (SEL0001I–SEL0010I) to see if the user marked a row with S/s. If so, it XCTLs to COTRN01C (transaction detail) passing the selected Tran ID in the commarea. If an invalid selection code was entered, it sets an error message. It also validates that the typed Tran ID filter is numeric (rejecting non-numeric input with an error and re-send). It then resets the page number to 0 and calls PROCESS-PAGE-FORWARD to (re)load the first page of results.

PROCESS-PF7-KEY (234) and PROCESS-PF8-KEY (257) implement backward/forward paging: - PF7 blocks the user if already on page 1 ("You are already at the top of the page..."), otherwise calls PROCESS-PAGE-BACKWARD. - PF8 blocks the user if NEXT-PAGE-NO was set ("You are already at the bottom of the page..."), otherwise calls PROCESS-PAGE-FORWARD.

PROCESS-PAGE-FORWARD (279) and PROCESS-PAGE-BACKWARD (333) both: 1. STARTBR-TRANSACT-FILE — start a browse on TRANSACT keyed on TRAN-ID. 2. Clear the 10 display rows via INITIALIZE-TRAN-DATA. 3. Loop READNEXT-TRANSACT-FILE (or READPREV-TRANSACT-FILE) up to 10 times, calling POPULATE-TRAN-DATA to format each record into the output map. 4. Peek one record further to determine whether there's a next/previous page (sets NEXT-PAGE-YES/NEXT-PAGE-NO and adjusts CDEMO-CT00-PAGE-NUM). 5. ENDBR-TRANSACT-FILE to close the browse. 6. SEND-TRNLST-SCREEN to redisplay.

POPULATE-TRAN-DATA (381) formats one TRANSACT record (amount, description, converted date) into the row indicated by WS-IDX (1–10), and also stashes the first and last Tran IDs of the page (CDEMO-CT00-TRNID-FIRST/-LAST) for use in subsequent paging.

SEND-TRNLST-SCREEN (527) calls POPULATE-HEADER-INFO (title, program name, current date/time) then does a CICS SEND MAP — with ERASE unless SEND-ERASE-NO was explicitly set (used when just showing a "top/bottom of page" message without redrawing the whole map).

RECEIVE-TRNLST-SCREEN (554) reads the map input into COTRN0AI via CICS RECEIVE.

Inputs & outputs

Resource Type Usage
TRANSACT (WS-TRANSACT-FILE) CICS dataset (VSAM, accessed via STARTBR/READNEXT/READPREV/ENDBR) Source of transaction records; browsed by TRAN-ID key to build each page of up to 10 rows
DFHCOMMAREA CICS commarea (linkage section) Carries CARDDEMO-COMMAREA (program-to-program) state between calls: source/destination program, tran ID, page context, first/last Tran ID on current page, next-page flag
COTRN0A map / COTRN00 mapset BMS screen Input/output screen: Tran ID filter, selection flags (SEL0001–10), 10 rows of Tran ID/date/description/amount, page number, error message
Copybook COCOM01Y Working storage Defines CARDDEMO-COMMAREA and common CardDemo flags/fields
Copybook COTRN00 Working storage Screen (map) layout COTRN0AI/COTRN0AO
Copybook CVTRA05Y Working storage TRAN-RECORD/TRAN-ID/TRAN-AMT/TRAN-DESC/TRAN-ORIG-TS layout for TRANSACT records
Copybooks COTTL01Y, CSDAT01Y, CSMSG01Y Working storage Titles, date/time work fields, standard messages (e.g., CCDA-MSG-INVALID-KEY)
Copybooks DFHAID, DFHBMSCA Working storage CICS AID key constants (DFHENTER, DFHPF7, etc.) and BMS attribute constants

Outbound program transfers (XCTL): - COSGN00C — when no commarea present, or as generic fallback in RETURN-TO-PREV-SCREEN - COMEN01C — on PF3 (return to previous menu) - COTRN01C — on selecting a transaction (Tran ID passed via commarea) for detail view

Things to know

  • No SQL/DB2 usage — this program relies entirely on CICS file control (VSAM-style) against the TRANSACT dataset; there are no SQL tables in scope.
  • Hard-coded literals: transaction ID 'CT00', program name 'COTRN00C', dataset name 'TRANSACT', and default fallback program 'COSGN00C' are all hard-coded in working storage rather than configured externally.
  • Fixed page size of 10 — the screen and paging logic are hard-wired to exactly 10 rows/selection fields (SEL0001I…SEL0010I, TRNID01I…TRNID10I, etc.), driven by repetitive EVALUATE WS-IDX blocks in both POPULATE-TRAN-DATA and INITIALIZE-TRAN-DATA rather than a table/array — any change to page size requires touching many places.
  • Error handling is message-based, not exception-based: CICS RESP/RESP2 codes are checked after every STARTBR/READNEXT/READPREV; on unexpected errors the code just sets WS-ERR-FLG, displays a generic "Unable to lookup transaction..." message, and calls SEND-TRNLST-SCREEN — there's no distinct recovery path, and unexpected RESP codes are only logged via DISPLAY (visible in CICS transient log/console, not to the end user beyond the generic message).
  • Selection validation is minimal: only 'S'/'s' is accepted as a valid selection flag; anything else in a non-blank selection field produces "Invalid selection. Valid value is S" but some cleanup code is commented out (*SET TRANSACT-EOF..., *PERFORM SEND-TRNLST-SCREEN), suggesting incomplete or historically modified error handling.
  • SEND-ERASE flag toggling: SEND-ERASE-NO is used to suppress the ERASE option on the CICS SEND MAP when just showing "top of page"/"bottom of page" informational messages — if this flag isn't properly reset elsewhere, stale screen content could remain visible; worth confirming reset logic covers all paths.
  • Numeric validation only applies to the Tran ID filter field, not to selection flags or other input; non-numeric Tran ID triggers a re-send with a specific error message and cursor positioning (TRNIDINL = -1).
  • Pseudo-conversational design: state (current page number, first/last Tran ID on page, next-page flag) is carried entirely in the commarea between CICS RETURNs — if the commarea is lost or corrupted between calls, paging state may be incorrect.
  • Date conversion: POPULATE-TRAN-DATA converts TRAN-ORIG-TS into a MM/DD/YY-style display date via intermediate WS-TIMESTAMP/WS-CURDATE-* fields — the exact source layout of TRAN-ORIG-TS is defined in copybook CVTRA05Y (not shown here), so field-level meaning should be verified against that copybook.

CICS commands

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

Copybooks

COCOM01Y, COTRN00, COTTL01Y, CSDAT01Y, CSMSG01Y, CVTRA05Y, 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_TRAN_DATA["POPULATE-TRAN-DATA"]
    INITIALIZE_TRAN_DATA["INITIALIZE-TRAN-DATA"]
    RETURN_TO_PREV_SCREEN["RETURN-TO-PREV-SCREEN"]
    SEND_TRNLST_SCREEN["SEND-TRNLST-SCREEN"]
    RECEIVE_TRNLST_SCREEN["RECEIVE-TRNLST-SCREEN"]
    POPULATE_HEADER_INFO["POPULATE-HEADER-INFO"]
    STARTBR_TRANSACT_FILE["STARTBR-TRANSACT-FILE"]
    READNEXT_TRANSACT_FILE["READNEXT-TRANSACT-FILE"]
    READPREV_TRANSACT_FILE["READPREV-TRANSACT-FILE"]
    ENDBR_TRANSACT_FILE["ENDBR-TRANSACT-FILE"]
    MAIN_PARA --> PROCESS_ENTER_KEY
    MAIN_PARA --> PROCESS_PF7_KEY
    MAIN_PARA --> PROCESS_PF8_KEY
    MAIN_PARA --> RECEIVE_TRNLST_SCREEN
    MAIN_PARA --> RETURN_TO_PREV_SCREEN
    MAIN_PARA --> SEND_TRNLST_SCREEN
    PROCESS_ENTER_KEY --> PROCESS_PAGE_FORWARD
    PROCESS_ENTER_KEY --> SEND_TRNLST_SCREEN
    PROCESS_PAGE_BACKWARD --> ENDBR_TRANSACT_FILE
    PROCESS_PAGE_BACKWARD --> INITIALIZE_TRAN_DATA
    PROCESS_PAGE_BACKWARD --> POPULATE_TRAN_DATA
    PROCESS_PAGE_BACKWARD --> READPREV_TRANSACT_FILE
    PROCESS_PAGE_BACKWARD --> SEND_TRNLST_SCREEN
    PROCESS_PAGE_BACKWARD --> STARTBR_TRANSACT_FILE
    PROCESS_PAGE_FORWARD --> ENDBR_TRANSACT_FILE
    PROCESS_PAGE_FORWARD --> INITIALIZE_TRAN_DATA
    PROCESS_PAGE_FORWARD --> POPULATE_TRAN_DATA
    PROCESS_PAGE_FORWARD --> READNEXT_TRANSACT_FILE
    PROCESS_PAGE_FORWARD --> SEND_TRNLST_SCREEN
    PROCESS_PAGE_FORWARD --> STARTBR_TRANSACT_FILE
    PROCESS_PF7_KEY --> PROCESS_PAGE_BACKWARD
    PROCESS_PF7_KEY --> SEND_TRNLST_SCREEN
    PROCESS_PF8_KEY --> PROCESS_PAGE_FORWARD
    PROCESS_PF8_KEY --> SEND_TRNLST_SCREEN
    READNEXT_TRANSACT_FILE --> SEND_TRNLST_SCREEN
    READPREV_TRANSACT_FILE --> SEND_TRNLST_SCREEN
    SEND_TRNLST_SCREEN --> POPULATE_HEADER_INFO
    STARTBR_TRANSACT_FILE --> SEND_TRNLST_SCREEN

Paragraphs

Paragraph Line Performs
MAIN-PARA 95 RETURN-TO-PREV-SCREEN, PROCESS-ENTER-KEY, SEND-TRNLST-SCREEN, RECEIVE-TRNLST-SCREEN, PROCESS-ENTER-KEY, RETURN-TO-PREV-SCREEN
PROCESS-ENTER-KEY 146 SEND-TRNLST-SCREEN, PROCESS-PAGE-FORWARD
PROCESS-PF7-KEY 234 PROCESS-PAGE-BACKWARD, SEND-TRNLST-SCREEN
PROCESS-PF8-KEY 257 PROCESS-PAGE-FORWARD, SEND-TRNLST-SCREEN
PROCESS-PAGE-FORWARD 279 STARTBR-TRANSACT-FILE, READNEXT-TRANSACT-FILE, INITIALIZE-TRAN-DATA, READNEXT-TRANSACT-FILE, POPULATE-TRAN-DATA, READNEXT-TRANSACT-FILE
PROCESS-PAGE-BACKWARD 333 STARTBR-TRANSACT-FILE, READPREV-TRANSACT-FILE, INITIALIZE-TRAN-DATA, READPREV-TRANSACT-FILE, POPULATE-TRAN-DATA, READPREV-TRANSACT-FILE
POPULATE-TRAN-DATA 381
INITIALIZE-TRAN-DATA 450
RETURN-TO-PREV-SCREEN 510
SEND-TRNLST-SCREEN 527 POPULATE-HEADER-INFO
RECEIVE-TRNLST-SCREEN 554
POPULATE-HEADER-INFO 567
STARTBR-TRANSACT-FILE 591 SEND-TRNLST-SCREEN, SEND-TRNLST-SCREEN
READNEXT-TRANSACT-FILE 624 SEND-TRNLST-SCREEN, SEND-TRNLST-SCREEN
READPREV-TRANSACT-FILE 658 SEND-TRNLST-SCREEN, SEND-TRNLST-SCREEN
ENDBR-TRANSACT-FILE 692