Skip to content

COPAUS1C

Source: app-authorization-ims-db2-mq/cbl/COPAUS1C.cbl

Type: CICS transaction program

COPAUS1C — Authorization Detail View

Purpose

COPAUS1C is a CICS BMS screen program in the CardDemo Authorization module that displays the full details of a single pending card authorization message (the "Auth Detail View"). It lets a user step through pending authorizations one at a time (PF8 = next), and lets them flag or unflag a specific authorization as confirmed fraud (PF5), which triggers a call to a separate fraud-processing program. It reads/updates authorization data stored in an IMS database rather than DB2 (no SQL tables are used by this program).

How it works

  • MAIN-PARA is the entry point, invoked on every CICS transaction under TRANID CPVD.
  • If EIBCALEN = 0 (no commarea, i.e. program invoked cold), it initializes the commarea, sets the "return-to" program to the Auth Summary screen (COPAUS0C), and performs RETURN-TO-PREV-SCREEN (an XCTL back to the summary screen) — effectively refusing to run standalone.
  • Otherwise it copies in the passed commarea. On first entry (NOT CDEMO-PGM-REENTER) it marks the session re-entrant, runs PROCESS-ENTER-KEY, and sends the screen via SEND-AUTHVIEW-SCREEN.
  • On subsequent invocations it performs RECEIVE-AUTHVIEW-SCREEN to read the user's input, then branches on EIBAID:
    • ENTER → PROCESS-ENTER-KEY then SEND-AUTHVIEW-SCREEN.
    • PF3 → sets the return program to the Auth Summary screen and performs RETURN-TO-PREV-SCREEN (XCTL out).
    • PF5 → MARK-AUTH-FRAUD then SEND-AUTHVIEW-SCREEN (fraud flag toggle).
    • PF8 → PROCESS-PF8-KEY (advance to next auth record) then SEND-AUTHVIEW-SCREEN.
    • Any other key → treated as invalid; still re-runs PROCESS-ENTER-KEY, shows an "invalid key" message, and re-sends the screen.

  • Every path ends with EXEC CICS RETURN TRANSID('CPVD') COMMAREA(...), so the transaction is pseudo-conversational — it always returns control to CICS and waits for the next user action under the same TRANID.

  • PROCESS-ENTER-KEY — validates that an account ID and a selected authorization key are present, then calls READ-AUTH-RECORD to fetch the IMS segments. If the IMS PSB was scheduled during the read, it de-schedules logically and calls TAKE-SYNCPOINT to commit/release IMS resources. Finally calls POPULATE-AUTH-DETAILS to move the fetched data onto the screen fields.

  • READ-AUTH-RECORD — calls SCHEDULE-PSB to schedule the IMS PSB PSBPAUTB, then issues a DLI GU (Get Unique) against the root segment PAUTSUM0 keyed by account ID, followed by a DLI GNP (Get Next within Parent) against child segment PAUTDTL1 keyed by the authorization key. IMS status codes (DIBSTAT) are checked after each call; segment-not-found/end-of-database sets an EOF flag, and any other non-OK status is treated as a system error (sets an error flag, builds a message, and immediately sends the screen).

  • MARK-AUTH-FRAUD (PF5) — re-reads the current auth record, flips the in-memory fraud-status flag (PA-FRAUD-CONFIRMED ↔ PA-FRAUD-REMOVED), builds a small commarea (WS-FRAUD-DATA) with account/customer IDs and the auth record, and issues EXEC CICS LINK to program COPAUS2C (the fraud-processing program) to actually record/clear the fraud report. Based on the response:

  • If the LINK succeeds and the fraud program reports success, UPDATE-AUTH-DETAILS is performed to persist the change back to IMS (DLI REPL) and take a syncpoint.
  • If the fraud program reports failure, or the LINK itself fails, ROLL-BACK (EXEC CICS SYNCPOINT ROLLBACK) is performed instead, discarding the change.

  • Screen fields are then repopulated via POPULATE-AUTH-DETAILS.

  • PROCESS-PF8-KEY — re-reads the current record, then calls READ-NEXT-AUTH-RECORD (DLI GNP with no key, i.e. "get next" in IMS sequence) to advance to the following pending authorization detail under the same parent. If IMS reports end-of-data, it suppresses the screen-erase flag and shows a "last authorization" message instead of advancing; otherwise it updates the selected key and repopulates the screen.

  • POPULATE-AUTH-DETAILS — moves all the IMS segment fields (card number, auth date/time, amount, response code/reason, merchant info, fraud flag, etc.) into the BMS map output fields, only when no error flag is set. It formats dates/times, colors the approve/decline indicator (green for approved response code '00', red otherwise), and looks up a human-readable decline reason via a binary search (SEARCH ALL) of a hard-coded in-memory table (WS-DECLINE-REASON-TAB).

  • SEND-AUTHVIEW-SCREEN / RECEIVE-AUTHVIEW-SCREEN — wrap the CICS SEND MAP/RECEIVE MAP calls against mapset COPAU01, map COPAU1A. POPULATE-HEADER-INFO fills in the screen's static header (titles, transaction/program name, current date/time).

  • TAKE-SYNCPOINT / ROLL-BACK wrap EXEC CICS SYNCPOINT and EXEC CICS SYNCPOINT ROLLBACK respectively, used to commit or undo IMS database changes.

  • SCHEDULE-PSB issues EXEC DLI SCHD for PSB PSBPAUTB. If IMS reports the PSB was already scheduled (PSB-SCHEDULED-MORE-THAN-ONCE), it terminates (DLI TERM) and retries the schedule once. Any non-OK final status is treated as a fatal system error.

Inputs & outputs

Resource Type Usage
PENDING-AUTH-SUMMARY (segment PAUTSUM0) IMS DB segment (root) Read via DLI GU, keyed by account ID (ACCNTID), to locate the parent authorization summary.
PENDING-AUTH-DETAILS (segment PAUTDTL1) IMS DB segment (child) Read via DLI GNP keyed by authorization key (PAUT9CTS) or unkeyed (get-next) for PF8 paging; updated via DLI REPL when marking/unmarking fraud.
PSB PSBPAUTB IMS PSB Scheduled/terminated around each database access sequence.
COPAU01 / map COPAU1A (BMS) Terminal screen Displays authorization detail fields; receives user input (PF keys, ENTER).
CARDDEMO-COMMAREA / DFHCOMMAREA CICS commarea Carries session state between transactions: selected account/auth key, navigation flags, "from/to program" routing info, and fraud-related data (CDEMO-CPVD-* fields).
COPAUS0C (Auth Summary program) CICS program (XCTL target) Returned to via PF3 or when invoked with no commarea.
COPAUS2C (Auth Fraud program) CICS program (LINK target) Invoked synchronously to process fraud confirm/remove requests; passes WS-FRAUD-DATA commarea and receives a status/message back.
Copybooks: CIPAUDTY, CIPAUSMY IMS segment layouts Define PENDING-AUTH-DETAILS and PENDING-AUTH-SUMMARY record structures.
Copybooks: COCOM01Y, COPAU01, COTTL01Y, CSDAT01Y, CSMSG01Y, CSMSG02Y, DFHAID, DFHBMSCA Shared commarea, screen map, titles, date/time, message text, abend variables, and CICS constants. Support common commarea layout, screen definitions, and standard messages/attention identifiers.

Note: The parser found no SQL tables and no defined FILES/FD entries for this program — all persistent data access here is via IMS DL/I calls, consistent with the program header comment "CICS IMS BMS Program."

Things to know

  • Hard-coded values: transaction ID CPVD, PSB name PSBPAUTB, program names COPAUS0C (summary), COPAUS2C (fraud), and COPAUS1C (self) are all literal constants in working storage — any renaming of these programs/transactions in the environment requires a source change and recompile.
  • Hard-coded decline-reason table: the 10-row WS-DECLINE-REASON-TABLE (codes like 0000APPROVED, 5100CARD FRAUD, 9000UNKNOWN, etc.) is embedded in the program and searched with SEARCH ALL (binary search — the table must remain in ascending DECL-CODE order for correct results). Unrecognized codes fall through to a generic 9999-ERROR display. This table is not sourced from a database and would need a code change to add new decline reasons.
  • Error handling pattern is aggressive/immediate: several IMS error branches (in READ-AUTH-RECORD, READ-NEXT-AUTH-RECORD, UPDATE-AUTH-DETAILS, SCHEDULE-PSB) call PERFORM SEND-AUTHVIEW-SCREEN directly from deep within nested logic rather than returning control to a single common error path. This can cause the screen to be sent more than once in the same transaction (the paragraph flow shows SEND-AUTHVIEW-SCREEN performed repeatedly), and subsequent CICS SEND MAP calls after an error could behave unexpectedly depending on terminal/BMS state. This is worth verifying against CICS SEND MAP semantics before modernizing.
  • PSB scheduling assumptions: IMS-PSB-SCHD-FLG is used only in working storage to track whether the program itself scheduled the PSB, and it is reset to "not scheduled" and a syncpoint is taken right after each read sequence in PROCESS-ENTER-KEY and PROCESS-PF8-KEY. If any of the paragraphs that read IMS data are extended in the future without preserving this schedule/syncpoint pairing, IMS resource leaks or "already scheduled" errors (PSB-SCHEDULED-MORE-THAN-ONCE) could result — the code does defensively retry the schedule once

CICS commands

RETURN, LINK, SEND, RECEIVE, SYNCPOINT

Copybooks

CIPAUDTY, CIPAUSMY, COCOM01Y, COPAU01, COTTL01Y, CSDAT01Y, CSMSG01Y, CSMSG02Y, DFHAID, DFHBMSCA

Paragraph flow

flowchart TD
    MAIN_PARA["MAIN-PARA"]
    PROCESS_ENTER_KEY["PROCESS-ENTER-KEY"]
    MARK_AUTH_FRAUD["MARK-AUTH-FRAUD"]
    PROCESS_PF8_KEY["PROCESS-PF8-KEY"]
    POPULATE_AUTH_DETAILS["POPULATE-AUTH-DETAILS"]
    RETURN_TO_PREV_SCREEN["RETURN-TO-PREV-SCREEN"]
    SEND_AUTHVIEW_SCREEN["SEND-AUTHVIEW-SCREEN"]
    RECEIVE_AUTHVIEW_SCREEN["RECEIVE-AUTHVIEW-SCREEN"]
    POPULATE_HEADER_INFO["POPULATE-HEADER-INFO"]
    READ_AUTH_RECORD["READ-AUTH-RECORD"]
    READ_NEXT_AUTH_RECORD["READ-NEXT-AUTH-RECORD"]
    UPDATE_AUTH_DETAILS["UPDATE-AUTH-DETAILS"]
    TAKE_SYNCPOINT["TAKE-SYNCPOINT"]
    ROLL_BACK["ROLL-BACK"]
    SCHEDULE_PSB["SCHEDULE-PSB"]
    MAIN_PARA --> MARK_AUTH_FRAUD
    MAIN_PARA --> PROCESS_ENTER_KEY
    MAIN_PARA --> PROCESS_PF8_KEY
    MAIN_PARA --> RECEIVE_AUTHVIEW_SCREEN
    MAIN_PARA --> RETURN_TO_PREV_SCREEN
    MAIN_PARA --> SEND_AUTHVIEW_SCREEN
    MARK_AUTH_FRAUD --> POPULATE_AUTH_DETAILS
    MARK_AUTH_FRAUD --> READ_AUTH_RECORD
    MARK_AUTH_FRAUD --> ROLL_BACK
    MARK_AUTH_FRAUD --> UPDATE_AUTH_DETAILS
    PROCESS_ENTER_KEY --> POPULATE_AUTH_DETAILS
    PROCESS_ENTER_KEY --> READ_AUTH_RECORD
    PROCESS_ENTER_KEY --> TAKE_SYNCPOINT
    PROCESS_PF8_KEY --> POPULATE_AUTH_DETAILS
    PROCESS_PF8_KEY --> READ_AUTH_RECORD
    PROCESS_PF8_KEY --> READ_NEXT_AUTH_RECORD
    PROCESS_PF8_KEY --> TAKE_SYNCPOINT
    READ_AUTH_RECORD --> SCHEDULE_PSB
    READ_AUTH_RECORD --> SEND_AUTHVIEW_SCREEN
    READ_NEXT_AUTH_RECORD --> SEND_AUTHVIEW_SCREEN
    SCHEDULE_PSB --> SEND_AUTHVIEW_SCREEN
    SEND_AUTHVIEW_SCREEN --> POPULATE_HEADER_INFO
    UPDATE_AUTH_DETAILS --> ROLL_BACK
    UPDATE_AUTH_DETAILS --> SEND_AUTHVIEW_SCREEN
    UPDATE_AUTH_DETAILS --> TAKE_SYNCPOINT

Paragraphs

Paragraph Line Performs
MAIN-PARA 157 RETURN-TO-PREV-SCREEN, PROCESS-ENTER-KEY, SEND-AUTHVIEW-SCREEN, RECEIVE-AUTHVIEW-SCREEN, PROCESS-ENTER-KEY, SEND-AUTHVIEW-SCREEN
PROCESS-ENTER-KEY 208 READ-AUTH-RECORD, TAKE-SYNCPOINT, POPULATE-AUTH-DETAILS
MARK-AUTH-FRAUD 230 READ-AUTH-RECORD, UPDATE-AUTH-DETAILS, ROLL-BACK, ROLL-BACK, POPULATE-AUTH-DETAILS
PROCESS-PF8-KEY 268 READ-AUTH-RECORD, READ-NEXT-AUTH-RECORD, TAKE-SYNCPOINT, POPULATE-AUTH-DETAILS
POPULATE-AUTH-DETAILS 291
RETURN-TO-PREV-SCREEN 360
SEND-AUTHVIEW-SCREEN 373 POPULATE-HEADER-INFO
RECEIVE-AUTHVIEW-SCREEN 398
POPULATE-HEADER-INFO 409
READ-AUTH-RECORD 431 SCHEDULE-PSB, SEND-AUTHVIEW-SCREEN, SEND-AUTHVIEW-SCREEN
READ-NEXT-AUTH-RECORD 493 SEND-AUTHVIEW-SCREEN
UPDATE-AUTH-DETAILS 520 TAKE-SYNCPOINT, ROLL-BACK, SEND-AUTHVIEW-SCREEN
TAKE-SYNCPOINT 557
ROLL-BACK 565
SCHEDULE-PSB 574 SEND-AUTHVIEW-SCREEN