AWS CardDemo: Developer Overview

Welcome to the AWS CardDemo developer documentation! This guide serves as your comprehensive entry point to understanding and working with this mainframe credit card management system.

Introduction

What is AWS CardDemo?

AWS CardDemo is a production-quality mainframe credit card management system that demonstrates modern patterns for AWS Mainframe Modernization. This comprehensive COBOL/CICS application showcases real-world enterprise development including:

• Online Transaction Processing (OLTP) with CICS
• Batch Processing with JCL
• Multi-platform Data Storage (VSAM, IMS, DB2)
• Asynchronous Messaging with IBM MQ
• User Interface with BMS (Basic Mapping Support)

Purpose of This Documentation

This documentation provides developers with everything needed to:

• Understand the architecture and design patterns
• Navigate the 44 COBOL programs and supporting code
• Modify existing functionality safely
• Add new features following established patterns
• Modernize the application for cloud deployment

Who Should Use This Documentation

This developer documentation is designed for:

• COBOL Developers maintaining or enhancing the system
• Mainframe Developers learning CICS patterns
• Java/Modern Developers modernizing mainframe applications
• Solutions Architects designing migration strategies
• DevOps Engineers setting up build and deployment pipelines
• Technical Leads reviewing code and architecture

System Overview

Key Capabilities

The system processes credit card operations at scale:

Technology Stack Summary

Programming & Runtime:

• Language: Enterprise COBOL (COBOL-85 with extensions)
• Online Processing: CICS Transaction Server (pseudo-conversational)
• Batch Processing: JCL-driven batch jobs
• Screen Management: BMS (3270 terminal protocol)

Data Management:

• Primary Storage: VSAM (9 KSDS files with alternate indexes)
• Relational Database: DB2 for z/OS (optional - transaction types)
• Hierarchical Database: IMS DB (optional - authorization data)
• Messaging: IBM MQ (optional - asynchronous processing)

System Architecture

Architecture Overview

CardDemo implements a classic three-tier mainframe architecture:

Component Architecture

Presentation Tier:

• 21 BMS screen definitions (3270 terminal protocol)
• Standardized screen layout with title, content, and function key areas
• Color-coded fields (protected, unprotected, numeric, error highlighting)

Online Transaction Processing Tier:

• 24 CICS online programs following pseudo-conversational pattern
• Menu-driven navigation (User Menu and Admin Menu)
• Transaction categories: Account, Card, Transaction, User Admin, Billing, Reports
• COMMAREA-based state management across pseudo-conversational cycles
• XCTL-based program chaining for efficient memory use

Business Logic Tier:

• 16 batch processing programs for bulk operations
• Common utility programs (date/time, validation, formatting)
• Shared business logic through copybooks
• Standardized error handling patterns

Data Tier:

• 9 VSAM KSDS files (indexed sequential)
• 3 alternate indexes for secondary key access
• Optional DB2 integration (2 tables for transaction types)
• Optional IMS integration (1 HIDAM database for authorizations)
• Optional MQ integration (4 queues for asynchronous messaging)

Data Flow Architecture

Online Transaction Flow:

Batch Processing Flow:

Key Architectural Patterns

1. Pseudo-Conversational Programming:

• Programs terminate between user interactions
• State preserved in COMMAREA (Communication Area)
• Resources released during user "think time"
• Enables high concurrency (100+ simultaneous users)

2. Program Control via XCTL:

• Transfer control without returning (memory efficient)
• Maintains transaction context via COMMAREA
• Chaining pattern: Menu → Function → Detail → Update

3. File Access Patterns:

• Direct access by primary key (READ, WRITE, REWRITE, DELETE)
• Browse patterns for list screens (STARTBR, READNEXT, READPREV, ENDBR)
• Alternate index access for secondary keys
• Consistent error handling with RESP codes

4. State Management:

• Standard COMMAREA structure (COCOM01Y - 90 bytes base)
• Contains user context (user ID, user type, transaction IDs)
• Extended by programs for screen-specific state (browse position, page keys)
• Passed on every RETURN and XCTL

5. Screen Standardization:

• Common title area (transaction ID, program name, date/time)
• Consistent function key usage (PF3=Exit, PF7=Prev, PF8=Next)
• Standard error message line (line 23)
• Field attribute management (protected, numeric, color coding)

Key Concepts for Developers

CICS Pseudo-Conversational Programming

What is it? A programming technique where programs terminate between user interactions, releasing system resources while maintaining user context.

How it works:

* First entry (EIBCALEN = 0)
IF EIBCALEN = 0
    PERFORM FIRST-TIME-PROCESSING
    MOVE 'Initial Screen' TO OUTPUT-AREA
ELSE
    * Restart from COMMAREA
    MOVE DFHCOMMAREA TO WS-COMMAREA
    PERFORM PROCESS-USER-INPUT
END-IF

* Send screen and terminate
EXEC CICS SEND MAP('MAPNAME')
    MAPSET('MAPSET')
    FROM(OUTPUT-AREA)
    ERASE
END-EXEC

* Return with state for restart
EXEC CICS RETURN
    TRANSID('CAVW')
    COMMAREA(WS-COMMAREA)
    LENGTH(90)
END-EXEC

Key Benefits:

• Scalability: Supports 100+ concurrent users
• Resource Efficiency: No resources held during user think time
• Reliability: Task isolation prevents resource leaks
• Performance: Fast response times (< 2 seconds)

State Management:

• Standard COMMAREA (90 bytes) defined in COCOM01Y.cpy
• Contains user context: user ID, user type, transaction flow
• Extended by programs for screen-specific data
• Preserved across pseudo-conversational cycles

VSAM File Structure

File Organization:

CardDemo uses VSAM (Virtual Storage Access Method) for primary data storage:

Key Concepts:

• KSDS (Key Sequenced Data Set): Indexed files with unique or non-unique keys
• Primary Key: Main access path (e.g., Account Number)
• Alternate Index (AIX): Secondary access paths (e.g., Card Number → Account)
• Path: Connection between base file and AIX

Primary Files:

Access Patterns:

* Direct Read
EXEC CICS READ
    DATASET('ACCTDAT')
    INTO(ACCOUNT-RECORD)
    RIDFLD(WS-ACCOUNT-ID)
    RESP(WS-RESP-CD)
END-EXEC

* Update
EXEC CICS READ UPDATE
    DATASET('ACCTDAT')
    INTO(ACCOUNT-RECORD)
    RIDFLD(WS-ACCOUNT-ID)
END-EXEC

* Modify record
COMPUTE ACCOUNT-BALANCE = ACCOUNT-BALANCE - PAYMENT-AMOUNT

EXEC CICS REWRITE
    DATASET('ACCTDAT')
    FROM(ACCOUNT-RECORD)
END-EXEC

* Browse Pattern (for lists)
EXEC CICS STARTBR
    DATASET('CARDDAT')
    RIDFLD(WS-SEARCH-KEY)
    KEYLENGTH(16)
    GTEQ
END-EXEC

PERFORM UNTIL END-OF-FILE OR PAGE-FULL
    EXEC CICS READNEXT
        DATASET('CARDDAT')
        INTO(CARD-RECORD)
        RIDFLD(WS-CARD-KEY)
    END-EXEC

    * Process record
    PERFORM ADD-TO-SCREEN-LIST
END-PERFORM

EXEC CICS ENDBR
    DATASET('CARDDAT')
END-EXEC

Batch Processing Patterns

Daily Processing Cycle:

Common Batch Patterns:

1. Transaction Posting (CBTRN02C):

• Read daily transaction file (DALYTRAN)
• Validate card and account
• Update transaction file (TRANSACT)
• Update category balance (TCATBALF)
• Generate rejection file for invalid transactions

2. Interest Calculation (CBACT04C):

• Read category balance file (TCATBALF)
• Calculate interest based on disclosure group
• Generate interest transaction
• Update account balance
• Create fee transactions

3. Statement Generation (CBSTM03A):

• Read account file (ACCTDAT)
• Retrieve all transactions for billing period
• Format statement (text and HTML)
• Write to output file
• Generate delivery instructions

Batch Job Dependencies:

Programs coordinate through JCL job chains:

• CLOSEFIL → Close VSAM files for batch processing
• Batch Jobs → Process data
• WAITSTEP → Synchronization point
• OPENFIL → Reopen files for online access

Transaction Processing

Online Transaction Flow:

1. User Entry:

   • User enters transaction code (e.g., CAVW for Account View)
   • CICS routes to program (COACTVWC)
   • Program initializes (EIBCALEN = 0)

2. Screen Display:

   • Program displays input screen
   • RETURN with TRANSID and COMMAREA
   • Task terminates

3. User Input:

   • User fills in data and presses ENTER
   • CICS restarts transaction with COMMAREA

4. Processing:

   • Program restores state from COMMAREA
   • Validates input
   • Reads/updates VSAM files
   • Prepares output screen

5. Navigation:

   • PF3: XCTL back to menu
   • Selection: XCTL to detail program
   • ENTER: Return with updated COMMAREA

Batch Transaction Flow:

1. Input Collection:

   • External systems deposit transaction files
   • Files organized as GDG (Generation Data Group)

2. Validation:

   • Card number existence
   • Account status check
   • Credit limit validation
   • Expiration date check

3. Posting:

   • Add to transaction file
   • Update account balance
   • Update category balance
   • Create audit trail

4. Reconciliation:

   • Balance checks
   • Exception reporting
   • Rejection file generation

Key Terminology

CICS Terms:

• COMMAREA: Communication area for passing data between programs
• EIBCALEN: Length of COMMAREA (0 = first entry)
• XCTL: Transfer control to another program (no return)
• LINK: Call a program as subroutine (returns to caller)
• TRANSID: Transaction identifier (4 characters, e.g., CAVW)
• MAPSET: Collection of BMS maps
• Pseudo-conversational: Task termination pattern

VSAM Terms:

• KSDS: Key Sequenced Data Set (indexed file)
• AIX: Alternate Index (secondary key access)
• Path: Logical connection to AIX
• STARTBR: Start browse (cursor positioning)
• READNEXT/READPREV: Sequential access
• ENDBR: End browse (release cursor)

Batch Terms:

• JCL: Job Control Language
• JES: Job Entry Subsystem
• GDG: Generation Data Group (versioned datasets)
• IDCAMS: Utility for VSAM file management
• SORT: Utility for sorting data
• SYSOUT: System output (reports, logs)

Program Terms:

• Copybook: Reusable code/data structure
• Working Storage: Program variables
• File Section: File record layouts
• Procedure Division: Executable code
• PERFORM: Execute a paragraph/section
• CALL: Invoke external program

Data Terms:

• COMP: Binary numeric (computational)
• COMP-3: Packed decimal (efficient storage)
• PIC X: Alphanumeric field
• PIC 9: Numeric field
• REDEFINES: Multiple views of same memory

Common Developer Tasks

Adding a New Transaction

Scenario: Add a new inquiry transaction to view customer details.

Steps:

1. Create BMS Map (COCUSDET.bms):

COCUSDET DFHMSD TYPE=&SYSPARM,MODE=INOUT,LANG=COBOL,             X
               TIOAPFX=YES,STORAGE=AUTO
CUSDET   DFHMDI SIZE=(24,80),LINE=1,COLUMN=1
         DFHMDF POS=(01,01),LENGTH=04,ATTRB=(ASKIP,BRT),          X
                INITIAL='CUST'
         * Add field definitions
         DFHMDF POS=(10,10),LENGTH=09,ATTRB=(ASKIP,NORM),         X
                INITIAL='CUSTOMER ID:'
         DFHMDF POS=(10,25),LENGTH=09,ATTRB=(UNPROT,NUM,IC)
         * More fields...
         DFHMSD TYPE=FINAL
         END

2. Create COBOL Program (COCUSDET.cbl):

       IDENTIFICATION DIVISION.
       PROGRAM-ID. COCUSDET.

       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  WS-COMMAREA.
           COPY COCOM01Y.

       01  CUSTOMER-RECORD.
           COPY CVCUS01Y.

       LINKAGE SECTION.
       01  DFHCOMMAREA                  PIC X(90).

       PROCEDURE DIVISION.
           IF EIBCALEN = 0
               PERFORM FIRST-TIME-PROCESSING
           ELSE
               PERFORM PROCESS-USER-INPUT
           END-IF.

       FIRST-TIME-PROCESSING.
           MOVE LOW-VALUES TO OUTPUT-AREA
           EXEC CICS SEND MAP('CUSDET')
                MAPSET('COCUSDET')
                FROM(OUTPUT-AREA)
                ERASE
           END-EXEC

           EXEC CICS RETURN
                TRANSID('CUSD')
                COMMAREA(WS-COMMAREA)
                LENGTH(90)
           END-EXEC.

       PROCESS-USER-INPUT.
           MOVE DFHCOMMAREA TO WS-COMMAREA

           EXEC CICS RECEIVE MAP('CUSDET')
                MAPSET('COCUSDET')
                INTO(INPUT-AREA)
           END-EXEC

           PERFORM READ-CUSTOMER
           PERFORM DISPLAY-CUSTOMER-DETAILS.

3. Define Transaction in CICS CSD:

DEFINE TRANSACTION(CUSD)
    GROUP(CARDDEMO)
    PROGRAM(COCUSDET)
    DESCRIPTION('Customer Detail Inquiry')

4. Add to Menu (COMEN02Y.cpy):

05  FILLER.
    10  MENU-OPTION             PIC X(02)   VALUE '12'.
    10  MENU-OPTION-NAME        PIC X(35)
        VALUE 'Customer Detail Inquiry'.
    10  MENU-OPTION-PGMNAME     PIC X(08)   VALUE 'COCUSDET'.
    10  MENU-OPTION-TRANID      PIC X(04)   VALUE 'CUSD'.

5. Test:
   • Compile BMS map
   • Compile COBOL program
   • Install in CICS
   • Test from menu

Modifying a Batch Job

Scenario: Add a new validation to transaction posting.

Steps:

1. Locate Program: Find CBTRN02C (transaction posting)

2. Review Program Documentation:

   • Read CBTRN02C.md
   • Understand current validation logic
   • Identify insertion point

3. Add Validation Logic:

PROCESS-TRANSACTION.
    * Existing validations
    PERFORM VALIDATE-CARD-NUMBER
    PERFORM VALIDATE-ACCOUNT-STATUS

    * New validation
    PERFORM VALIDATE-TRANSACTION-AMOUNT

    IF VALIDATION-ERROR
        PERFORM WRITE-REJECTION-RECORD
        GO TO PROCESS-NEXT-TRANSACTION
    END-IF

    PERFORM POST-TRANSACTION.

VALIDATE-TRANSACTION-AMOUNT.
    * Check amount is within reasonable range
    IF TRAN-AMOUNT < 0.01 OR TRAN-AMOUNT > 99999.99
        MOVE 'Invalid transaction amount' TO ERROR-MSG
        SET VALIDATION-ERROR TO TRUE
    END-IF.

4. Update JCL:

   • No changes needed (program logic only)

5. Test:

   • Create test transaction file with edge cases
   • Run job in test environment
   • Verify rejection file for invalid amounts
   • Check posted transactions

Debugging CICS Programs

Common Debugging Techniques:

1. CICS Trace:

CETR,ON      - Turn on CICS trace
CETR,OFF     - Turn off CICS trace

2. Display Variables:

EXEC CICS SEND TEXT
    FROM(WS-DEBUG-MESSAGE)
    LENGTH(80)
    ERASE
END-EXEC

3. Write to TD Queue:

EXEC CICS WRITEQ TD
    QUEUE('CSMT')
    FROM(DEBUG-MESSAGE)
    LENGTH(80)
END-EXEC

4. ABEND Analysis:

* Intentional abend for debugging
EXEC CICS ABEND
    ABCODE('USR1')
END-EXEC

5. Trace File I/O:

READ-ACCOUNT-RECORD.
    EXEC CICS READ
        DATASET('ACCTDAT')
        INTO(ACCOUNT-RECORD)
        RIDFLD(WS-ACCOUNT-ID)
        RESP(WS-RESP-CD)
        RESP2(WS-REAS-CD)
    END-EXEC

    IF WS-RESP-CD NOT = DFHRESP(NORMAL)
        STRING 'READ ERROR: ' WS-RESP-CD ' ' WS-REAS-CD
            DELIMITED BY SIZE INTO DEBUG-MSG
        PERFORM WRITE-DEBUG-MESSAGE
    END-IF.

Debugging Workflow:

1. Reproduce Issue:

   • Capture input data
   • Note transaction sequence
   • Document error symptoms

2. Analyze Code:

   • Review program documentation
   • Trace logic flow
   • Identify suspect areas

3. Add Instrumentation:

   • Insert debug messages
   • Enable CICS trace
   • Log file operations

4. Test Fix:

   • Apply fix
   • Recompile
   • Test with original scenario
   • Verify no side effects

5. Clean Up:

   • Remove debug code
   • Update documentation
   • Commit changes

Testing Changes

Unit Testing:

* Test framework pattern
IDENTIFICATION DIVISION.
PROGRAM-ID. TEST-CBTRN02C.

PROCEDURE DIVISION.
    PERFORM TEST-VALIDATE-CARD
    PERFORM TEST-VALIDATE-AMOUNT
    PERFORM TEST-POST-TRANSACTION
    STOP RUN.

TEST-VALIDATE-CARD.
    * Setup
    MOVE '1234567890123456' TO TEST-CARD-NUM

    * Execute
    PERFORM VALIDATE-CARD-NUMBER

    * Assert
    IF VALIDATION-OK
        DISPLAY 'TEST PASSED: Card validation'
    ELSE
        DISPLAY 'TEST FAILED: Card validation'
    END-IF.

Integration Testing:

• Use test VSAM files
• Load test data
• Execute transactions
• Verify results
• Check error handling

System Testing:

• Full end-to-end scenarios
• Multiple user simulation
• Batch job execution
• Performance testing
• Recovery testing

Resources and Links

AWS Mainframe Modernization:

• AWS M2 Documentation - Official AWS documentation
• AWS M2 Developer Guide - Developer resources
• AWS M2 Best Practices - Best practices

COBOL Resources:

• Enterprise COBOL for z/OS Documentation - IBM COBOL docs
• Micro Focus COBOL Documentation - Micro Focus docs

CICS Resources:

• CICS TS Documentation - IBM CICS documentation
• CICS Application Programming Guide - Programming guide

GitHub Repository:

• AWS CardDemo GitHub - Source code repository