cobol-modernization

name	cobol-modernization
description	Guidance for converting COBOL programs to modern languages (Python, Java, etc.) while preserving exact behavior and data format compatibility. This skill should be used when modernizing legacy COBOL applications, converting COBOL business logic to modern languages, or ensuring byte-for-byte output compatibility between COBOL and its replacement.

COBOL Modernization

Overview

This skill provides a systematic approach for converting COBOL programs to modern languages while ensuring exact behavioral equivalence. The key challenge in COBOL modernization is not just translating logic, but preserving precise data formats, fixed-width record structures, and byte-level output compatibility.

Workflow

Phase 1: Analysis and Documentation

Before writing any code, thoroughly analyze the COBOL source and data files:

1. Read the complete COBOL source code - Understand the program structure including:

   • WORKING-STORAGE SECTION for variable definitions and sizes
   • FILE SECTION for record layouts and field definitions
   • PROCEDURE DIVISION for business logic

2. Document all data formats explicitly - Create a specification for each file:

   • Record length (total bytes per record)
   • Field positions (starting byte, length)
   • Field types (numeric with COMP-3, alphanumeric, packed decimal)
   • Padding and alignment requirements

3. Resolve format discrepancies before implementation - If input files don't match expected formats (e.g., file is 15 bytes but COBOL expects 22 bytes), investigate and document how the COBOL program actually handles this before proceeding.

Phase 2: Testing Harness Setup

Create reusable testing infrastructure before implementing the conversion:

1. Create a state reset script - Automate restoring original data files:

   # Example: reset_state.sh
   cp data/ACCOUNTS.DAT.orig data/ACCOUNTS.DAT
   cp data/BOOKS.DAT.orig data/BOOKS.DAT
   cp data/TRANSACTIONS.DAT.orig data/TRANSACTIONS.DAT
   

2. Create a comparison script - Automate output comparison:

   # Example: compare_outputs.sh
   diff data/ACCOUNTS_PYTHON.DAT data/ACCOUNTS_COBOL.DAT
   diff data/BOOKS_PYTHON.DAT data/BOOKS_COBOL.DAT
   diff data/TRANSACTIONS_PYTHON.DAT data/TRANSACTIONS_COBOL.DAT
   

3. Preserve original COBOL outputs - Run the COBOL program first and save outputs as reference baselines before any conversion work.

Phase 3: Implementation

When writing the modern language equivalent:

1. Match COBOL data handling exactly:

   • Use fixed-width string formatting, not variable-length
   • Implement proper padding (spaces for alphanumeric, zeros for numeric)
   • Handle COBOL's implicit decimal points in numeric fields
   • Match COBOL's truncation behavior for oversized values

2. Verify file writes immediately - After writing code files, read them back to confirm complete content was saved correctly before testing.

3. Use consistent naming - Avoid creating excessive temporary files. Use a clear naming scheme:

   • *_COBOL.DAT for COBOL program outputs
   • *_PYTHON.DAT for Python program outputs
   • Clean up between test iterations

Phase 4: Systematic Testing

Test all code paths, not just the happy path:

1. Create a test matrix covering all validation scenarios:

   • Valid transactions (success case)
   • Non-existent primary entities (buyer, seller, book, etc.)
   • Ownership/permission validation failures
   • Insufficient balance/resource conditions
   • Boundary conditions (zero balance, maximum values)

2. Test each scenario independently:

   • Reset state before each test
   • Run both COBOL and modern implementation
   • Compare outputs byte-for-byte using diff

3. Document test results - Track which scenarios passed and any discrepancies found.

Common Pitfalls

Data Format Issues

• Fixed-width fields: COBOL uses fixed-width fields padded with spaces or zeros. Modern languages default to variable-length strings.
• Numeric formatting: COBOL's PIC 9(4)V99 means 4 digits, implied decimal, 2 decimal places - stored as 6 characters with no decimal point.
• Record terminators: COBOL fixed-length records may not use line terminators. Verify whether newlines are expected.

Testing Mistakes

• Incomplete edge case coverage: Testing only success and one failure case leaves validation paths untested.
• Not verifying written code: Tool responses may be truncated. Always read back written files to confirm completeness.
• State pollution: Running tests without resetting state causes cascading failures.

Process Inefficiencies

• Repeating commands: Create shell scripts for operations performed more than twice.
• Cluttered workspace: Create a consistent file naming scheme and clean up temporary files.
• Unresolved discrepancies: If data formats don't match expectations, investigate fully before proceeding.

Verification Checklist

Before declaring the modernization complete:

• All required output files are generated
• All data files match COBOL output byte-for-byte (diff returns no output)
• All validation paths have been tested (success + each failure type)
• Boundary conditions have been verified
• No temporary or debug files remain
• Code has been read back to verify complete and correct content