Skip to content

COBIL00C

Source: cbl/COBIL00C.cbl

Type: CICS transaction program

COBIL00C — Bill Payment Program

Purpose

COBIL00C implements the "Pay Current Balance" feature of the CardDemo online banking application. It lets a user enter an account ID, view the current balance, and confirm a full-balance payment, which is recorded as a new transaction and used to zero out (reduce) the account's balance. It is a CICS pseudo-conversational program driven by BMS map COBIL0A (mapset COBIL00).

How it works

  1. MAIN-PARA is the entry point on every CICS invocation.
  2. If EIBCALEN = 0 (first-ever entry, no commarea), it sets the return target to COSGN00C and performs RETURN-TO-PREV-SCREEN (an XCTL) — i.e., a program invoked with no context bounces back to sign-on.
  3. Otherwise it copies the commarea into working storage (CARDDEMO-COMMAREA).
    • First entry for this transaction (NOT CDEMO-PGM-REENTER): initializes the map, and if an account was pre-selected (CDEMO-CB00-TRN-SELECTED), it pre-fills the account field and immediately performs PROCESS-ENTER-KEY before sending the screen via SEND-BILLPAY-SCREEN.
    • Subsequent entries (re-entrant): performs RECEIVE-BILLPAY-SCREEN to read user input, then branches on EIBAID:
    • ENTER → PROCESS-ENTER-KEY
    • PF3 → returns to the calling program (or COMEN01C if none) via RETURN-TO-PREV-SCREEN
    • PF4 → CLEAR-CURRENT-SCREEN
    • anything else → sets an "invalid key" error and re-sends the screen
  4. PROCESS-ENTER-KEY is the core business logic:
  5. Validates the account ID isn't blank.
  6. Looks up the account via READ-ACCTDAT-FILE (CICS READ ... UPDATE for potential rewrite).
  7. Interprets the CONFIRM field:
    • Y/y → confirms payment, re-reads the account (READ-ACCTDAT-FILE again).
    • N/n → clears the screen and flags an error state (aborts the payment).
    • blank/low-values → just displays the current balance (no payment yet), via READ-ACCTDAT-FILE.
    • anything else → error, "Valid values are (Y/N)".
  8. Rejects payment if ACCT-CURR-BAL <= 0 ("You have nothing to pay...").
  9. If confirmed (CONF-PAY-YES):
    • READ-CXACAIX-FILE looks up the card cross-reference for the account (to get the card number).
    • STARTBR-TRANSACT-FILE / READPREV-TRANSACT-FILE / ENDBR-TRANSACT-FILE browse the transaction file backwards from HIGH-VALUES to find the highest existing transaction ID.
    • The new transaction ID is that value + 1.
    • A new transaction record is built (fixed values: type '02', category 2, source 'POS TERM', description 'BILL PAYMENT - ONLINE', merchant ID 999999999, merchant name 'BILL PAYMENT', city/zip 'N/A'), with the transaction amount set to the full current balance.
    • GET-CURRENT-TIMESTAMP obtains the current date/time (via ASKTIME/FORMATTIME) and stamps both TRAN-ORIG-TS and TRAN-PROC-TS.
    • WRITE-TRANSACT-FILE adds the record to the transaction file.
    • The account balance is reduced by the transaction amount and rewritten via UPDATE-ACCTDAT-FILE.
  10. Regardless of outcome, SEND-BILLPAY-SCREEN re-displays the map with a status/error message.
  11. SEND-BILLPAY-SCREEN always calls POPULATE-HEADER-INFO first (titles, program/transaction name, current date/time from FUNCTION CURRENT-DATE) before issuing the CICS SEND MAP.
  12. CLEAR-CURRENT-SCREEN / INITIALIZE-ALL-FIELDS reset the input fields and message, then redisplay the (blank) screen.

Inputs & outputs

Resource Type Used by Purpose
DFHCOMMAREA CICS commarea (linkage) MAIN-PARA Carries CARDDEMO-COMMAREA (navigation context, previous program, selected account) between pseudo-conversational calls.
COBIL0A map (mapset COBIL00) BMS screen SEND/RECEIVE-BILLPAY-SCREEN Bill-payment input/output screen: account ID, current balance, confirm Y/N, error message, header fields.
ACCTDAT (WS-ACCTDAT-FILE) VSAM file (via ACCOUNT-RECORD, copybook CVACT01Y) READ-ACCTDAT-FILE / UPDATE-ACCTDAT-FILE Read account balance (with UPDATE lock) and rewrite it after payment.
CXACAIX (WS-CXACAIX-FILE) VSAM alternate index file (via CARD-XREF-RECORD, copybook CVACT03Y) READ-CXACAIX-FILE Look up the card number cross-referenced to the account ID, needed for the transaction record.
TRANSACT (WS-TRANSACT-FILE) VSAM file (via TRAN-RECORD, copybook CVTRA05Y) STARTBR/READPREV/ENDBR/WRITE-TRANSACT-FILE Determine the next transaction ID (browse in reverse from high values) and write the new bill-payment transaction.
Various copybooks (COCOM01Y, COTTL01Y, CSDAT01Y, CSMSG01Y, DFHAID, DFHBMSCA) Working-storage layouts throughout Common commarea layout, titles, date/message constants, CICS AID/attribute constants.

No SQL tables are used (parser confirms sql_tables: []) — all persistence is via CICS file control (VSAM), not DB2.

Things to know

  • Hard-coded values in the generated transaction: type code '02', category 2, source 'POS TERM', description 'BILL PAYMENT - ONLINE', merchant ID 999999999, merchant name 'BILL PAYMENT', city/zip 'N/A'. Any change to bill-payment classification requires editing this code directly.
  • Transaction ID generation is not safe under concurrency: the highest transaction ID is found by browsing backwards from HIGH-VALUES and adding 1, with no locking between the browse and the WRITE. Simultaneous bill payments could theoretically collide (handled only reactively via DFHRESP(DUPKEY)/DUPREC producing a "Tran ID already exist..." error, not retried).
  • No SQL/DB2 use — this program is pure CICS/VSAM, differing from other CardDemo modules that use DB2.
  • Error handling pattern: nearly every file operation follows the same EVALUATE WS-RESP-CD pattern (NORMAL / NOTFND / OTHER), setting WS-ERR-FLG, building a message, and re-sending the screen. Unexpected errors are also written to DISPLAY (console/log), which is useful for problem diagnosis but not surfaced in any structured way.
  • Full-balance-only payment: there is no partial payment option — the entire ACCT-CURR-BAL is paid off in one transaction; if balance is zero or negative, payment is blocked with "You have nothing to pay...".
  • PF4 acts as "clear screen" and PF3 as "return to previous/calling program" (falls back to COMEN01C if no calling program is known); any other AID key yields a generic "invalid key" message — the specific set of allowed keys is limited to Enter, PF3, PF4.
  • Re-entrancy flag (CDEMO-PGM-REENTER) governs whether the program treats the call as first-time (auto-processing a preselected account) or as a subsequent screen interaction (receive + evaluate AID) — this logic is a common CardDemo convention but easy to misread without CICS pseudo-conversational background.
  • Confirmation field semantics (CONFIRMI) is overloaded: blank/low-values means "just show balance," Y means "confirm and pay," N means "cancel and clear," anything else is invalid — this three-way state logic is subtle and should be preserved carefully in any rewrite.
  • The copybook COBIL00 (referenced but not detailed in these facts) defines the COBIL0AI/COBIL0AO map record layouts; its field definitions (e.g., ACTIDINI, CURBALI, CONFIRMI, ERRMSGO) are essential to fully understanding screen field behavior but were not included in the extracted facts.

CICS commands

RETURN, ASKTIME, FORMATTIME, SEND, RECEIVE, READ, REWRITE, STARTBR, READPREV, ENDBR, WRITE

Copybooks

COBIL00, COCOM01Y, COTTL01Y, CSDAT01Y, CSMSG01Y, CVACT01Y, CVACT03Y, CVTRA05Y, DFHAID, DFHBMSCA

Paragraph flow

flowchart TD
    MAIN_PARA["MAIN-PARA"]
    PROCESS_ENTER_KEY["PROCESS-ENTER-KEY"]
    GET_CURRENT_TIMESTAMP["GET-CURRENT-TIMESTAMP"]
    RETURN_TO_PREV_SCREEN["RETURN-TO-PREV-SCREEN"]
    SEND_BILLPAY_SCREEN["SEND-BILLPAY-SCREEN"]
    RECEIVE_BILLPAY_SCREEN["RECEIVE-BILLPAY-SCREEN"]
    POPULATE_HEADER_INFO["POPULATE-HEADER-INFO"]
    READ_ACCTDAT_FILE["READ-ACCTDAT-FILE"]
    UPDATE_ACCTDAT_FILE["UPDATE-ACCTDAT-FILE"]
    READ_CXACAIX_FILE["READ-CXACAIX-FILE"]
    STARTBR_TRANSACT_FILE["STARTBR-TRANSACT-FILE"]
    READPREV_TRANSACT_FILE["READPREV-TRANSACT-FILE"]
    ENDBR_TRANSACT_FILE["ENDBR-TRANSACT-FILE"]
    WRITE_TRANSACT_FILE["WRITE-TRANSACT-FILE"]
    CLEAR_CURRENT_SCREEN["CLEAR-CURRENT-SCREEN"]
    INITIALIZE_ALL_FIELDS["INITIALIZE-ALL-FIELDS"]
    CLEAR_CURRENT_SCREEN --> INITIALIZE_ALL_FIELDS
    CLEAR_CURRENT_SCREEN --> SEND_BILLPAY_SCREEN
    MAIN_PARA --> CLEAR_CURRENT_SCREEN
    MAIN_PARA --> PROCESS_ENTER_KEY
    MAIN_PARA --> RECEIVE_BILLPAY_SCREEN
    MAIN_PARA --> RETURN_TO_PREV_SCREEN
    MAIN_PARA --> SEND_BILLPAY_SCREEN
    PROCESS_ENTER_KEY --> CLEAR_CURRENT_SCREEN
    PROCESS_ENTER_KEY --> ENDBR_TRANSACT_FILE
    PROCESS_ENTER_KEY --> GET_CURRENT_TIMESTAMP
    PROCESS_ENTER_KEY --> READ_ACCTDAT_FILE
    PROCESS_ENTER_KEY --> READ_CXACAIX_FILE
    PROCESS_ENTER_KEY --> READPREV_TRANSACT_FILE
    PROCESS_ENTER_KEY --> SEND_BILLPAY_SCREEN
    PROCESS_ENTER_KEY --> STARTBR_TRANSACT_FILE
    PROCESS_ENTER_KEY --> UPDATE_ACCTDAT_FILE
    PROCESS_ENTER_KEY --> WRITE_TRANSACT_FILE
    READ_ACCTDAT_FILE --> SEND_BILLPAY_SCREEN
    READ_CXACAIX_FILE --> SEND_BILLPAY_SCREEN
    READPREV_TRANSACT_FILE --> SEND_BILLPAY_SCREEN
    SEND_BILLPAY_SCREEN --> POPULATE_HEADER_INFO
    STARTBR_TRANSACT_FILE --> SEND_BILLPAY_SCREEN
    UPDATE_ACCTDAT_FILE --> SEND_BILLPAY_SCREEN
    WRITE_TRANSACT_FILE --> INITIALIZE_ALL_FIELDS
    WRITE_TRANSACT_FILE --> SEND_BILLPAY_SCREEN

Paragraphs

Paragraph Line Performs
MAIN-PARA 99 RETURN-TO-PREV-SCREEN, PROCESS-ENTER-KEY, SEND-BILLPAY-SCREEN, RECEIVE-BILLPAY-SCREEN, PROCESS-ENTER-KEY, RETURN-TO-PREV-SCREEN
PROCESS-ENTER-KEY 154 SEND-BILLPAY-SCREEN, READ-ACCTDAT-FILE, CLEAR-CURRENT-SCREEN, READ-ACCTDAT-FILE, SEND-BILLPAY-SCREEN, SEND-BILLPAY-SCREEN
GET-CURRENT-TIMESTAMP 249
RETURN-TO-PREV-SCREEN 273
SEND-BILLPAY-SCREEN 289 POPULATE-HEADER-INFO
RECEIVE-BILLPAY-SCREEN 306
POPULATE-HEADER-INFO 319
READ-ACCTDAT-FILE 343 SEND-BILLPAY-SCREEN, SEND-BILLPAY-SCREEN
UPDATE-ACCTDAT-FILE 377 SEND-BILLPAY-SCREEN, SEND-BILLPAY-SCREEN
READ-CXACAIX-FILE 408 SEND-BILLPAY-SCREEN, SEND-BILLPAY-SCREEN
STARTBR-TRANSACT-FILE 441 SEND-BILLPAY-SCREEN, SEND-BILLPAY-SCREEN
READPREV-TRANSACT-FILE 472 SEND-BILLPAY-SCREEN
ENDBR-TRANSACT-FILE 501
WRITE-TRANSACT-FILE 510 INITIALIZE-ALL-FIELDS, SEND-BILLPAY-SCREEN, SEND-BILLPAY-SCREEN, SEND-BILLPAY-SCREEN
CLEAR-CURRENT-SCREEN 552 INITIALIZE-ALL-FIELDS, SEND-BILLPAY-SCREEN
INITIALIZE-ALL-FIELDS 560