Case Study 1: The Copybook Change That Broke 47 Programs

Background

GlobalBank's ACCT-REC copybook — the account master record layout — is used by 340 programs. It has been stable for years, with the last change made fourteen months ago. When the business requested a new field to store customer email addresses, the change seemed straightforward: add a 50-byte alphanumeric field for the email and reduce the FILLER at the end of the record by 50 bytes to keep the total record length at 200 bytes.

Maria Chen made the change, tested it with three representative programs, and promoted the updated copybook to the shared library. The next morning, the nightly batch cycle failed. Forty-seven programs had abended.

What Happened

The copybook change itself was technically correct — the record length remained 200 bytes, and the new field was properly defined. The problem lay in how some programs used the copybook.

Problem 1: FILLER Dependency (12 programs)

Twelve programs had been written years ago by a developer who, instead of using the copybook's FILLER field, had defined their own version of the last portion of the record, overlaying the FILLER with program-specific working fields using REDEFINES:

       01  WS-ACCT-WORK-AREA.
           COPY ACCT-REC.
       01  WS-ACCT-OVERLAY REDEFINES WS-ACCT-WORK-AREA.
           05  FILLER              PIC X(69).
           05  WS-CUSTOM-FLAGS     PIC X(131).

When the FILLER shrank from 131 to 81 bytes, the overlay no longer aligned. The programs attempted to access 131 bytes of WS-CUSTOM-FLAGS, but only 81 bytes existed — resulting in memory overrun and S0C4 abends.

Problem 2: Hardcoded Offsets (8 programs)

Eight programs used reference modification with hardcoded positions based on the old record layout:

      * Hardcoded position: byte 70 through 200 was the "unused" area
           MOVE WS-ACCT-RECORD(70:131) TO WS-WORK-AREA

After the copybook change, byte 70 was now the middle of a meaningful field, not the start of unused space.

Problem 3: Uncompiled Programs (27 programs)

Twenty-seven programs compiled cleanly with the new copybook but had not been recompiled. They were running with old load modules that expected the previous record layout. When they read records written by newly compiled programs — records where the email field overlapped what used to be part of FILLER — they interpreted the data incorrectly. Some produced wrong output; others abended on data exceptions.

Resolution

James Okafor coordinated with Maria to execute the following recovery:

  1. Immediate rollback: The old ACCT-REC copybook was restored, and all affected programs were recompiled with the old layout and redeployed.

  2. Impact analysis: A full analysis identified every program that used ACCT-REC, including how each program referenced the record fields. This analysis took two days.

  3. Phased deployment: The copybook change was re-implemented with a migration plan: - All REDEFINES overlays were updated before the copybook change - All reference modifications were changed to use named fields - All 340 programs were recompiled and tested - The deployment was staged over one weekend with rollback procedures

  4. Process changes: - A mandatory impact analysis step was added for all copybook changes - A "full recompile" procedure was documented for copybook modifications - Coding standards were updated to prohibit REDEFINES on copybook FILLER areas - Reference modification with hardcoded offsets into copybook records was banned

Analysis Questions

  1. Maria tested with three programs before promoting the copybook change. What testing strategy would have caught the problems earlier?

  2. The 27 programs that were not recompiled represent a compilation management failure. What processes or tools could prevent programs from running with stale load modules after a copybook change?

  3. The developer who used REDEFINES on the FILLER area was solving a real problem (needing program-specific working fields based on record positions). What would be a better approach?

  4. Should copybook changes be treated like database schema migrations — with versioning, impact analysis, and phased rollout? What would that process look like?

  5. How does this incident illustrate both the power and the risk of COBOL's copybook mechanism?

Lessons

  • Copybooks are powerful precisely because they create coupling. A single change propagates everywhere — which is the point, but also the risk.
  • Every program that uses a copybook must be recompiled when the copybook changes. There are no exceptions to this rule.
  • Coding practices that depend on the internal layout of a copybook (REDEFINES on FILLER, hardcoded reference modification) create hidden dependencies that break when the copybook changes.
  • Impact analysis before copybook changes is not optional. It is a critical safety step.