Skip to content

COTRN01C

Source: cbl/COTRN01C.cbl

Type: CICS transaction program

COTRN01C — Transaction View Program

Purpose

This is a CICS COBOL screen program from the CardDemo application that lets a user look up and view the details of a single credit card transaction by its Transaction ID. It displays transaction fields such as amount, type, category, source, description, timestamps, and merchant information on a formatted terminal screen (COTRN1A map). It is a read-only inquiry screen — no updates to the transaction are made even though the underlying read uses UPDATE.

How it works

Processing is driven by MAIN-PARA, which behaves differently depending on whether the program is being entered fresh or re-entered after a user action:

  • First entry (EIBCALEN = 0): there is no commarea, so the program treats this as an invalid direct invocation and immediately routes back to the sign-on screen (COSGN00C) via RETURN-TO-PREV-SCREEN.
  • Entry with a commarea, not yet "re-entered": the incoming commarea is loaded into CARDDEMO-COMMAREA. If a transaction ID was already selected (passed in from a prior screen, e.g. a transaction list), it's moved into the input field and PROCESS-ENTER-KEY is performed automatically to look it up. Otherwise the blank screen is simply displayed via SEND-TRNVIEW-SCREEN.
  • Subsequent re-entry (user pressed a key on the displayed screen): RECEIVE-TRNVIEW-SCREEN reads the user's screen input, then EIBAID (the key pressed) is evaluated:
  • Enter → PROCESS-ENTER-KEY — validates the entered Transaction ID and looks it up.
  • PF3 → returns to the previous program (CDEMO-FROM-PROGRAM, or COMEN01C if none is set) via RETURN-TO-PREV-SCREEN.
  • PF4 → CLEAR-CURRENT-SCREEN — blanks all screen fields and redisplays.
  • PF5 → navigates to COTRN00C (transaction list) via RETURN-TO-PREV-SCREEN.
  • Any other key → sets an error flag, shows an "invalid key" message, and redisplays the screen.

PROCESS-ENTER-KEY validates that a Transaction ID was entered (rejecting blanks/low-values with an error message and cursor positioning), then calls READ-TRANSACT-FILE to fetch the record and populates all the output fields on the map before performing SEND-TRNVIEW-SCREEN.

READ-TRANSACT-FILE issues a CICS READ against the TRANSACT dataset keyed by Transaction ID and handles three response cases: normal (continue), not found (error message + redisplay), and any other CICS error (generic error message, response/reason codes written to console via DISPLAY, + redisplay).

SEND-TRNVIEW-SCREEN always performs POPULATE-HEADER-INFO first (which stamps the screen with titles, program name, and the current date/time from FUNCTION CURRENT-DATE) before sending the map to the terminal.

At the end of MAIN-PARA, control always returns to CICS with EXEC CICS RETURN TRANSID(WS-TRANID) COMMAREA(CARDDEMO-COMMAREA), keeping the transaction "pseudo-conversational" for the next user interaction.

Inputs & outputs

Name Type Usage
TRANSACT (via WS-TRANSACT-FILE) CICS-managed dataset Read (with UPDATE option) by Transaction ID to retrieve transaction details for display. No write/rewrite is performed in this program.
DFHCOMMAREA CICS commarea Carries CARDDEMO-COMMAREA (via copybook COCOM01Y) between program invocations — tracks reentry state, from/to program routing, and a possibly pre-selected transaction ID (CDEMO-CT01-TRN-SELECTED).
COTRN1A map (mapset COTRN01) CICS BMS screen Displayed via SEND (formats: transaction ID input, transaction details, merchant info, header/date/time, error message) and read via RECEIVE (captures user's typed Transaction ID and key pressed).
Copybooks: COCOM01Y, COTRN01, COTTL01Y, CSDAT01Y, CSMSG01Y, CVTRA05Y, DFHAID, DFHBMSCA Data structures Provide the commarea layout, screen (map) layout, title/date/message constants, transaction record layout (TRAN-RECORD/TRAN-ID etc. from CVTRA05Y), and CICS AID/attribute constants.

No SQL tables are used (parser confirms sql_tables: []) — this program is file/CICS-based, not DB2-based.

Things to know

  • READ ... UPDATE without a rewrite: The transaction read is issued with the UPDATE option, which normally implies intent to modify the record, but this program never performs a REWRITE or UNLOCK. This holds an exclusive lock on the record until the CICS task ends (or a subsequent transaction on the same task explicitly releases it), which is unusual for a pure "view" program and could cause contention if reused as a pattern.
  • Error handling is message-based, not exception-based: READ-TRANSACT-FILE checks WS-RESP-CD against DFHRESP(NORMAL)/DFHRESP(NOTFND)/other, using CICS RESP/RESP2 — no abend on failure. Unexpected errors are only logged via DISPLAY (visible in CICS console/log, not to the user beyond a generic message).
  • Hard-coded values: transaction ID WS-TRANID = 'CT01', program name WS-PGMNAME = 'COTRN01C', dataset name WS-TRANSACT-FILE = 'TRANSACT', and default fallback programs 'COSGN00C' (sign-on), 'COMEN01C' (menu), and 'COTRN00C' (transaction list) are all embedded directly in code rather than configured externally.
  • Reentry logic relies on CDEMO-PGM-REENTER flag: this flag (part of the commarea, from COCOM01Y) distinguishes a fresh call from a pseudo-conversational continuation. If this flag or the commarea structure is corrupted/mismatched between programs, the flow could misbehave (e.g., skip the initial screen population).
  • Cursor positioning via -1 length trick: Several paragraphs set TRNIDINL OF COTRN1AI to -1 to force the cursor to the Transaction ID field on redisplay — a standard BMS/CICS convention but easy to misread as a plain data assignment.
  • No SQL/DB2 usage: unlike other CardDemo programs that use DB2, this one relies purely on a CICS VSAM-style file (TRANSACT) accessed via EXEC CICS READ.
  • WS-TRAN-DATE field declared but appears unused in the shown procedure logic — worth confirming whether it's referenced elsewhere (e.g., in a copybook-driven MOVE) or is dead code.
  • Only three navigation targets are hard-wired (PF3/PF4/PF5) plus Enter; any other key is treated uniformly as invalid input, regardless of CICS AID meaning.

CICS commands

RETURN, SEND, RECEIVE, READ

Copybooks

COCOM01Y, COTRN01, COTTL01Y, CSDAT01Y, CSMSG01Y, CVTRA05Y, DFHAID, DFHBMSCA

Paragraph flow

flowchart TD
    MAIN_PARA["MAIN-PARA"]
    PROCESS_ENTER_KEY["PROCESS-ENTER-KEY"]
    RETURN_TO_PREV_SCREEN["RETURN-TO-PREV-SCREEN"]
    SEND_TRNVIEW_SCREEN["SEND-TRNVIEW-SCREEN"]
    RECEIVE_TRNVIEW_SCREEN["RECEIVE-TRNVIEW-SCREEN"]
    POPULATE_HEADER_INFO["POPULATE-HEADER-INFO"]
    READ_TRANSACT_FILE["READ-TRANSACT-FILE"]
    CLEAR_CURRENT_SCREEN["CLEAR-CURRENT-SCREEN"]
    INITIALIZE_ALL_FIELDS["INITIALIZE-ALL-FIELDS"]
    CLEAR_CURRENT_SCREEN --> INITIALIZE_ALL_FIELDS
    CLEAR_CURRENT_SCREEN --> SEND_TRNVIEW_SCREEN
    MAIN_PARA --> CLEAR_CURRENT_SCREEN
    MAIN_PARA --> PROCESS_ENTER_KEY
    MAIN_PARA --> RECEIVE_TRNVIEW_SCREEN
    MAIN_PARA --> RETURN_TO_PREV_SCREEN
    MAIN_PARA --> SEND_TRNVIEW_SCREEN
    PROCESS_ENTER_KEY --> READ_TRANSACT_FILE
    PROCESS_ENTER_KEY --> SEND_TRNVIEW_SCREEN
    READ_TRANSACT_FILE --> SEND_TRNVIEW_SCREEN
    SEND_TRNVIEW_SCREEN --> POPULATE_HEADER_INFO

Paragraphs

Paragraph Line Performs
MAIN-PARA 86 RETURN-TO-PREV-SCREEN, PROCESS-ENTER-KEY, SEND-TRNVIEW-SCREEN, RECEIVE-TRNVIEW-SCREEN, PROCESS-ENTER-KEY, RETURN-TO-PREV-SCREEN
PROCESS-ENTER-KEY 144 SEND-TRNVIEW-SCREEN, READ-TRANSACT-FILE, SEND-TRNVIEW-SCREEN
RETURN-TO-PREV-SCREEN 197
SEND-TRNVIEW-SCREEN 213 POPULATE-HEADER-INFO
RECEIVE-TRNVIEW-SCREEN 230
POPULATE-HEADER-INFO 243
READ-TRANSACT-FILE 267 SEND-TRNVIEW-SCREEN, SEND-TRNVIEW-SCREEN
CLEAR-CURRENT-SCREEN 301 INITIALIZE-ALL-FIELDS, SEND-TRNVIEW-SCREEN
INITIALIZE-ALL-FIELDS 309