AI Rules for COBOL and Mainframe Code

Why COBOL Needs AI Rules

COBOL processes an estimated $3 trillion in daily commerce, runs 95% of ATM transactions, and powers the core banking systems of most major financial institutions. It's the most consequential code AI will ever touch — and AI assistants are spectacularly bad at it. The training data for COBOL is tiny compared to Python or JavaScript, and the patterns AI generates are often from textbooks rather than real mainframe production systems.

The stakes are existential: a COBOL bug in a banking system can affect millions of transactions. A COBOL change that breaks a batch job can halt an entire bank's overnight processing. And unlike web applications where you deploy and monitor, mainframe changes go through rigorous change management with scheduled maintenance windows. There is no 'move fast and break things' in mainframe.

These rules target COBOL on IBM z/OS (the dominant mainframe platform). They cover COBOL-85 (most production code) and COBOL 2014 (modern features). Adjust for your specific mainframe environment, CICS version, and DB2 level.

Rule 1: COBOL Coding Standards

The rule: 'Use structured programming: PERFORM for iteration and subroutine calls, EVALUATE for multi-branch decisions (not nested IF). Never use GO TO except for standard error handling patterns (GO TO paragraph-exit). Never use ALTER. Use meaningful paragraph names that describe the action: 1000-VALIDATE-CUSTOMER, 2000-CALCULATE-INTEREST, 9000-ERROR-HANDLER.'

For data definitions: 'Define all data in the WORKING-STORAGE SECTION or LINKAGE SECTION. Use COPY statements for shared data structures (copybooks). Use level-88 condition names for boolean checks: 88 ACCOUNT-ACTIVE VALUE "A". Use COMP-3 (packed decimal) for financial calculations — never binary or floating point for money. Define PIC clauses with explicit decimal positions: PIC S9(7)V99 COMP-3.'

For naming: 'Use hyphens in names: CUSTOMER-ACCOUNT-NUMBER, not underscores or camelCase. Prefix data items with a 2-3 character abbreviation of the copybook or section: WS- for working storage, LK- for linkage, CA- for COMMAREA. Paragraph names start with a numeric prefix for ordering: 0100-, 0200-, etc.'

• PERFORM for iteration and subroutines — no GO TO except error handling
• EVALUATE for multi-branch — no deeply nested IF/ELSE
• Paragraph names: numeric prefix + action: 1000-VALIDATE-INPUT
• COMP-3 for all financial data — never binary or float for money
• Level-88 condition names for booleans: 88 IS-ACTIVE VALUE 'Y'
• COPY for shared structures — never duplicate copybook definitions

Rule 2: Copybook Conventions

The rule: 'All shared data structures live in copybooks (COPY members). Never define the same record layout in multiple programs — COPY it from a single source. Copybook names follow the naming convention: CUSTCPY (customer copybook), ACCTCPY (account copybook). When a copybook changes, recompile all programs that COPY it. Use REPLACING to adapt copybook field prefixes when needed.'

For versioning: 'When changing a copybook that affects multiple programs, add new fields at the end of the record — never insert in the middle (it shifts all subsequent field offsets). If a field size must change, create a new version of the copybook and migrate programs gradually. Never change the length of a record layout used in existing VSAM files without a file conversion.'

Copybooks are COBOL's module system — they're the only mechanism for shared type definitions. AI assistants often inline record layouts instead of using COPY, creating maintenance nightmares when the layout needs to change.

Rule 3: CICS and DB2 Patterns

For CICS online programs: 'Use EXEC CICS commands for all CICS services. Handle every CICS RESP code — never assume a command succeeds. Use EXEC CICS RETURN for program termination. Use BMS (Basic Mapping Support) for screen I/O. Store session state in the COMMAREA or container — never in WORKING-STORAGE (it's not preserved across pseudo-conversational transactions).'

For DB2 access: 'Use embedded SQL with host variables. Check SQLCODE after every SQL statement: 0 = success, 100 = not found, negative = error. Use cursor processing for multi-row results: DECLARE CURSOR, OPEN, FETCH, CLOSE. Use COMMIT at logical transaction boundaries. Never hold cursors across CICS RETURN — it locks database resources.'

For batch programs: 'Check file status codes after every file operation: 00 = success, 10 = end of file, 35 = file not found. Use SORT for large-scale data ordering. Use checkpoint/restart for long-running batches — write a restart point every N records so the job can resume from the last checkpoint on failure.'

• CICS: check every RESP code — COMMAREA for session state — BMS for screens
• DB2: check SQLCODE after every statement — cursor for multi-row — COMMIT at boundaries
• Batch: check file status — SORT for ordering — checkpoint/restart for long jobs
• Never hold DB2 cursors across CICS transactions — resource lock risk
• EXEC CICS HANDLE CONDITION or RESP checking — never ignore return codes

Rule 4: JCL (Job Control Language) Conventions

The rule: 'JCL procedures (PROCs) for reusable job steps. Parameterize with symbolic parameters: SET variables for environment-specific values (dataset names, volume serial numbers). Use COND parameters or IF/THEN/ELSE for conditional step execution. Use GDG (Generation Data Groups) for versioned datasets — never hardcode generation numbers. Include SYSOUT specifications for all output.'

For dataset management: 'Use meaningful dataset names following your shop's naming convention: HLQ.PROJECT.TYPE.NAME. Specify DISP (disposition) explicitly on every DD statement: NEW for creation, SHR for shared read, OLD for exclusive. Always specify SPACE for new datasets — never rely on defaults. Use SMS classes where available.'

AI assistants generate JCL that looks syntactically correct but uses wrong DISP parameters, wrong SPACE allocations, or hardcoded dataset names that only work in one environment. JCL errors prevent job submission — there's no 'almost correct' in JCL.

Rule 5: Safe Mainframe Code Maintenance

The rule: 'Never change production code without a change ticket in the change management system. Test in DEV → QA → UAT → PROD environment progression. Run the full regression test suite (batch test jobs) before promoting to QA. For COBOL changes: compare compile listings (SYSPRINT) before and after to verify expected changes. Keep previous versions available for immediate rollback.'

For debugging: 'Use DISPLAY statements for temporary debugging — remove before promotion to QA. Use IBM Debug Tool or Xpediter for interactive debugging in test environments. Check SYSOUT datasets for ABEND information: S0C7 = data exception (usually bad decimal data), S0C4 = protection exception (bad pointer), S806 = load module not found.'

For modernization: 'Modernize incrementally: extract business logic into called programs (CALL), wrap batch processes with APIs (CICS web services or z/OS Connect), and add unit testing with zUnit. Never rewrite a working mainframe program from scratch unless you can prove the rewrite passes every test the original passes.'

Complete COBOL Rules Template

Consolidated rules for COBOL mainframe development.

• Structured: PERFORM, EVALUATE — no GO TO except error handling, no ALTER
• COMP-3 for money — PIC S9(7)V99 — never binary or float for financial data
• COPY for all shared structures — add fields at end, never insert in middle
• Check every return code: SQLCODE for DB2, RESP for CICS, file status for I/O
• JCL PROCs with symbolic parameters — GDG for versioned datasets — explicit DISP
• Cursor OPEN/FETCH/CLOSE — COMMIT at boundaries — no cursors across CICS RETURN
• DEV → QA → UAT → PROD — regression tests — compare compile listings
• Incremental modernization: CALL for modularity, web services for APIs, zUnit for testing