Legacy Integration: Mainframe Modernisation Roadmap

Overview

Multi-year mainframe migrations fail not because the technology is hard but because the planning assumes a single team can hold the whole programme in its head across years, staffing changes, and budget cycles. The roadmap exists to break that dependency. A well-structured programme sequences work in waves, runs legacy and modern systems in parallel for long enough to build real confidence, and measures progress in units the business understands — not velocity points.

This article covers the planning and execution arc for a bank-scale mainframe modernisation: how to scope it, sequence it, run both systems in parallel, and prove progress month over month. The principles apply whether you are migrating a 1990s-era z/OS core running CICS and DB2 or an IBM i (AS/400) running RPG and DB2/400. The tools differ; the sequencing logic does not.

Dependency analysis

Before you sequence anything, you need to know what calls what. On a mature mainframe, this is harder than it sounds. CICS programs call other CICS programs via EXEC CICS LINK — a dependency invisible to most architecture docs. Batch jobs share VSAM files with online CICS programs through timing conventions, not explicit contracts. Some programs are invoked from 3270 screens that still have human operators who will tell you the program “never runs” until it runs at year-end.

Dependency analysis has three layers, and all three are required:

• Static analysis. Parse JCL, PROC, and COBOL source for CALL and EXEC CICS LINK statements. Build a directed graph of who calls whom.
• Runtime capture. IBM IIDR CDC or SMF (System Management Facilities) records during a peak week capture actual transaction IDs and DB2 table access patterns that static analysis misses because they are computed at runtime.
• Data lineage. Identify which VSAM files and DB2 tables are read/written by which programs. A program with no callers but exclusive write access to a file is not a candidate for early retirement — something upstream depends on that file being populated.

The output is a directed dependency graph. Run it through a visualisation tool (Neo4j or even dot from GraphViz) to identify clusters of tightly coupled programs — those clusters become candidate capability slices.

#!/usr/bin/env bash
# Extract EXEC CICS LINK targets from COBOL source and flag unknowns

# Step 1: collect all LINK targets
grep -rh 'EXEC CICS LINK PROGRAM' ./cbl/*.cbl \
  | awk '{for(i=1;i<=NF;i++) if($i=="PROGRAM(") print $(i+1)}' \
  | tr -d '()' \
  | sort -u \
  > link-targets.txt

# Step 2: cross-reference against registered transactions
comm -23 \
  <(sort link-targets.txt) \
  <(sort transaction-registry.txt) \
  > unknown-targets.txt

echo "$(wc -l < link-targets.txt) LINK targets found"
echo "$(wc -l < unknown-targets.txt) targets NOT in registry — investigate before slicing"

# Step 3: build adjacency list for Neo4j import
grep -rh 'EXEC CICS LINK PROGRAM' ./cbl/*.cbl \
  | awk '{src=FILENAME; gsub(/.*\//,"",src); gsub(/.cbl/,"",src);
    for(i=1;i<=NF;i++) if($i=="PROGRAM(") print src "|" $(i+1)}' \
  | tr -d '()' \
  > call-graph.csv

Capability slicing

With the dependency graph, group programs into bounded contexts. The rule: a capability slice is a set of CICS programs, DB2 tables, and VSAM files that form a coherent business function and have minimal cross-slice data coupling. Minimal, not zero — some coupling is inevitable and acceptable. The question is whether you can define a clear data contract at the boundary.

Clean slices migrate first. Messy slices get decomposed before migration:

The messy slices are not blockers; they are sequencing constraints. Migrate the clean slices first. Design the decomposition work for the messy ones in Year 1, execute it alongside Wave 1 migration, so the complex slices are ready for Wave 2.

Migration waves

A wave is a cohort of capabilities that share the same infrastructure: the same façade endpoint, the same ACL, the same routing toggle. Within a wave, shadow and dual-write windows run concurrently across the cohort. Cutover can happen capability-by-capability within the wave — you do not need to cut all capabilities in Wave 1 at the same instant.

Wave 0 is the foundation wave and it is often invisible to business stakeholders because no capability migrates. Everything happens in the integration layer: build the façade, implement the ACL, deploy the routing infrastructure, migrate every consumer from direct mainframe calls to the façade. Wave 0 takes six to nine months and is the most important wave. A poorly built façade blocks every subsequent wave; a well-built one lets Waves 1 through 3 move at pace.

Parallel run patterns

Three modes, used in sequence. The transition between modes requires an explicit gate decision, not a calendar date.

Shadow mode. Write to both systems; read exclusively from the mainframe; compare the new service’s response asynchronously. The new service is invisible to the business. Only goal: build confidence that the new service produces equivalent output. Do not promote a capability out of shadow until you have a meaningful sample across all transaction types, including edge cases and month-end volumes.

Dual-write mode. Write to both systems; read from the new service. The mainframe is still consistent. Daily reconciliation compares the two systems and reports drift. The new service is the functional system-of-record, but the mainframe remains the fallback. This is the highest-anxiety mode: you are trusting the new system with real traffic but keeping the safety net active, which means the safety net has to be healthy too.

Read-from-new (cutover). Stop writing to the mainframe entirely. The mainframe path is warm but idle. Monitor for 30 days before initiating retirement. Retirement means decommissioning the CICS transaction, dropping the DB2 tables, and releasing the MIPS. Only retirement produces real cost savings.

The shadow-to-dual-write gate requires a measurable condition, not a feeling. Define it before you build the shadow infrastructure. A typical gate: 14 consecutive calendar days with zero reconciliation breaks per capability, including at least one month-end window. Make the gate public in the programme plan so stakeholders know what “ready to promote” means before the question is live.

Toolchain: IIDR & CDC

IBM InfoSphere Data Replication (IIDR) is the production choice for CDC from z/OS DB2 and IBM i DB2/400. It is the only tool with IBM-supported log-based capture for both platforms, mature conflict detection, and a Kafka delivery target that integrates cleanly with the OpenShift-based integration layer.

Debezium with the community DB2 connector works for shadow read use cases where eventual consistency is acceptable, but it is not supported for DB2 z/OS CDC in production by IBM, and its log position recovery after a z/OS IPL is manual and fragile. Use IIDR for dual-write and cutover phases; use Debezium only if IIDR licensing is blocked by procurement timelines and the use case is read-only shadow.

# IBM IIDR 11.4 subscription definition for customer master CDC
# Apply via IIDR Management Console or REST API
subscription:
  name: CUSTMAST_TO_KAFKA
  source:
    datastore: SAIB_MAINFRAME_DB2  # z/OS DB2 12 subsystem
    schema: COREDB
    tables:
      - CUSTMAST
      - CUSTADDR
      - CUSTACC
    capture_mode: log_based
    begin_from: current  # set to bookmark for initial load resume

  target:
    datastore: KAFKA_OCP_CLUSTER
    format: avro
    topic_prefix: iidr.coredb  # topics: iidr.coredb.CUSTMAST etc
    include_before_image: true  # required for conflict detection
    schema_registry: http://schema-registry.integration.svc:8081

  conflict_detection:
    enabled: true
    strategy: source_wins  # mainframe wins during dual-write phase
    detection_window_ms: 5000

  latency_target_ms: 500  # p99 end-to-end; alert if exceeded
  error_action: stop      # never silently skip; stop and alert

IIDR’s initial load and CDC capture operate in two phases. The initial load takes a consistent snapshot of the source table with a log bookmark; CDC then replays changes from that bookmark forward. The initial load of a large CUSTMAST table (20M+ rows on a typical Saudi commercial bank) takes six to twelve hours under a batch window and must be coordinated with the mainframe operations team to avoid contention with the end-of-day batch.

-- Daily reconciliation: compare customer master row counts and checksums
-- Run in OpenShift Job at 02:00 AST after mainframe end-of-day batch

WITH mainframe_snapshot AS (
  SELECT
    COUNT(*)                   AS row_count,
    SUM(HASH(CUST_ID, CUST_STATUS, CUST_SEGMENT))
                               AS checksum
  FROM fdw_mainframe.CUSTMAST  -- foreign data wrapper to IIDR shadow table
  WHERE LAST_UPDATE < '2026-06-27 00:00:00'  -- yesterday boundary
),
modern_snapshot AS (
  SELECT
    COUNT(*)                   AS row_count,
    SUM(HASH(customer_id, status, segment))
                               AS checksum
  FROM customers.customer_master
  WHERE updated_at < '2026-06-27 00:00:00'
)
SELECT
  m.row_count        AS mainframe_rows,
  n.row_count        AS modern_rows,
  m.row_count - n.row_count
                     AS row_delta,
  CASE WHEN m.checksum = n.checksum THEN 'OK'
       ELSE 'BREAK'
  END                AS reconciliation_status
FROM mainframe_snapshot m, modern_snapshot n;

Metrics that prove progress

The metric that matters is MIPS consumed per quarter. Not story points, not percentage of programs migrated, not number of CICS transactions renamed. MIPS is the unit the CFO approved the programme to reduce. Every other metric is internal scaffolding; only MIPS appears on the boardroom slide.

Three secondary metrics make the MIPS number credible:

• Reconciliation break rate. Breaks per million transactions in dual-write mode. Target: zero. Any non-zero value is a bug that must be fixed before promotion. Track it by capability slice — a break in customer master does not block accounts from cutting over.
• Rollback incident count. How many times did you flip traffic back to the mainframe after a cutover? Zero is the target; two in a wave is a signal to slow down and investigate; three is a programme health issue.
• Mean time to detect regression. How long from a shadow deployment to the first reconciliation alert catching a divergence? Drives continuous improvement in the reconciliation pipeline. Sub-24 hours is the target; anything over 72 hours means you are flying blind.

Risk & governance

Three governance bodies need to be in the room for a mainframe modernisation programme, and all three need different content from you:

• Architecture Review Board (ARB). Owns the façade contract, approves capability slice boundaries, and gates new service architecture before it enters shadow mode. The ARB needs: slice boundary definitions, data contract specifications, anti-corruption layer design.
• Change Advisory Board (CAB). Gates each dual-write promotion and each mainframe retirement event. The CAB needs: reconciliation results for the gate period, rollback procedure evidence (rehearsal log), blast radius assessment for the capability being retired.
• Compliance / Risk. SAMA notification for material changes to core banking systems. Compliance needs: notification letter, audit trail continuity evidence, data residency confirmation, and the programme risk register updated to reflect the new risk posture after each wave.

Rollback criteria must be defined before each wave, not invented on the night. Typical triggers: reconciliation breaks exceeding threshold within the first 72 hours post-cutover; p99 latency of the new service exceeding 2× the mainframe baseline; any downstream system reporting data inconsistency. The on-call team must be able to re-route traffic to the mainframe without escalation — the runbook is the proof, and the CAB evidence package includes a rehearsal log showing sub-15-minute recovery.

KSA / SAMA context

Saudi banks face a compounding constraint. Vision 2030’s financial sector targets — open banking via SAMA Phase 2, real-time ISO 20022 payment rails, digital account origination — require API-native architectures. The mainframe as an integration bottleneck is not a technical preference; it is a strategic ceiling on competitive velocity. Modernisation is the prerequisite, not the goal.

SAMA’s Technology Risk Management framework (Circular 41038/BCR/2023) requires prior notification for material changes to core banking systems. A mainframe migration qualifies. The notification starts a 30-day review clock; plan for it in the programme timeline for each wave, not as an afterthought. The review does not typically block the programme, but late notification is a compliance finding that complicates the next wave.

Two SAMA-specific constraints shape sequencing decisions:

• Data residency. All customer data must remain within KSA borders throughout migration. Cross-region staging environments, even for non-production shadow copies, invalidate residency compliance if the data is real. Use synthetic data generators in development; use a Saudi-region cloud zone or on-premises OpenShift for shadow.
• Audit trail continuity. SAMA requires a complete, unbroken audit trail through any migration event. A gap in the audit log during shadow mode — where the new service is writing but not yet logging to the authoritative audit trail — is a compliance finding. Wire the new service into the enterprise audit trail on Day 1 of shadow, not on Day 1 of cutover.

Cutover checklist

These six conditions must all be true before any capability is promoted from dual-write to cutover. Document the evidence for each in the CAB package:

1. Reconciliation gate met

   30 consecutive calendar days in dual-write mode with zero reconciliation breaks per capability. The 30-day window must include at least one month-end batch run. Evidence: reconciliation job output from the period, signed off by the integration lead.

2. Performance validated under peak load

   New service p99 latency is within mainframe p99 at 2× peak load, sustained for 30 minutes. Tested in a load environment that mirrors production topology (same OpenShift cluster class, same IIDR replication latency). Evidence: load test report with latency percentile graphs.

3. Rollback rehearsal completed

   The on-call team completed a rollback rehearsal in the staging environment within the prior two weeks and achieved sub-15-minute re-route to mainframe. Evidence: rehearsal log with timestamps, names, and the specific runbook version used.

4. Audit trail verified end-to-end

   An independent audit trace from originating API call through the new service to settlement, with no gaps in the enterprise audit log, verified by Compliance. Evidence: sample trace report across five representative transaction types including exception paths.

5. SAMA notification acknowledged

   SAMA notification filed no later than 35 days before cutover. The 30-day review window has closed with no material findings. Evidence: SAMA acknowledgement letter or portal confirmation attached to CAB package.

6. On-call runbook signed off

   First-line support team can handle the top 10 expected incident types for the new service without escalation to the integration engineering team. The escalation matrix is updated. Evidence: runbook sign-off from the operations lead, updated in the incident management platform.