Ryz Labs/Migrations/COBOL to Python
Migrations

COBOL to Python: Mainframe Exit Runbook for API-First Services

How to rebuild COBOL and mainframe workloads as Python services: capture the interfaces, run old and new side by side, reconcile every record, then cut over.

A COBOL-to-Python migration takes the business logic behind CICS transactions, JCL batch jobs and MQ queues off the mainframe and rebuilds it as API-first Python services, one slice at a time, while the mainframe keeps running. The approach that works is a rebuild against captured interfaces, not a line-by-line translation: you copy the contracts (copybooks, file layouts, transaction inputs and outputs), re-implement behind them, and prove equivalence with a parallel run. Success is decided by one thing: whether you can reconcile old and new outputs record by record, to the cent, before any slice is switched over.

Why teams migrate now

The pressure is rarely that mainframes stop working. It is that the software stack under them keeps moving and the people who know the code keep leaving. IBM's own Mainframe Life Cycle History shows z/OS 2.4 reached end of service in September 2024, and z/OS 2.5 reached end of service in September 2026 (paid extended defect support runs to 2029). z/OS 3.1 is planned to reach end of service in September 2028, and z/OS 3.2, generally available since September 2025, is planned through September 2030. So any shop still on 2.5 is now facing an operating system upgrade anyway, and that upgrade is a natural decision point: re-platform the OS again, or start moving workloads off.

Public-sector audits describe the same pattern. In GAO-19-471 (June 2019), the GAO picked 10 critical federal legacy systems that were 8 to 51 years old, several running outdated languages on unsupported hardware and software with known vulnerabilities, and noted that about 80% of more than $90 billion in federal IT spend went to operations and maintenance. Its follow-up, GAO-25-107795 (July 2025), listed 11 systems at 10 agencies most in need of modernization, aged 23 to 60 years, with 8 of the 11 using outdated languages and both Treasury systems running on COBOL.

The business consequences are concrete. Every z/OS upgrade cycle is a project. Change requests queue behind a shrinking group of engineers who can read the JCL and copybooks. New channels (mobile apps, partner APIs, analytics) need data that lives in VSAM files and Db2 for z/OS tables, so teams build fragile extracts. And examiners and auditors increasingly ask how you would recover, change or explain a system when the last person who understands it retires.

Before you start: inventory and baseline

Most mainframe exits fail in discovery, not in coding. The interfaces are wider than anyone remembers. Inventory them before you write any Python.

The strangler-fig plan, phase by phase

The mainframe stays the system of record until each slice proves itself. New Python services grow around it, take traffic one transaction family or batch stream at a time, and the COBOL behind them is retired only after a clean parallel run.

Phase 0: Capture the interfaces

Turn each in-scope copybook into a machine-readable record definition and generate Python parsers from it. A field like PIC S9(7)V99 COMP-3 is five bytes of packed decimal with a sign nibble; PIC S9(5) DISPLAY is zoned decimal with the sign overpunched into the last byte. Your parser must decode both exactly, into Python's decimal.Decimal, never float. Decode EBCDIC text with the right code page (Python ships codecs such as cp037 and cp500; others need an explicit mapping). Write the characterization tests from the golden datasets now. Exit criteria: every in-scope record type round-trips byte for byte through your parser, and every golden input has a recorded expected output.

Phase 1: API facade and data sync

Put a stable API in front of the existing transactions before you replace anything. Options include IBM z/OS Connect or CICS web support exposing the current programs as REST endpoints, or an MQ request/reply bridge. Consumers switch to the facade, so later you can change what is behind it without touching them. In parallel, stand up change data capture from Db2 for z/OS (log-based CDC tooling) or scheduled VSAM unloads into PostgreSQL, so the new side has current data. Exit criteria: all new and migrated consumers call the facade, and replicated tables match source row counts and control totals daily.

Phase 2: First slice, read-only

Start with inquiry transactions: balance lookups, policy status, account history. Re-implement them as Python services (FastAPI or Django are both reasonable) reading the replicated data. Route a copy of production requests to both the CICS path and the Python path, return the mainframe answer, and diff the two responses field by field. Watch for EBCDIC collation: in EBCDIC, letters sort before digits, so any "first N records by key" logic returns different rows in ASCII-ordered PostgreSQL unless you sort explicitly. Exit criteria: the shadow diff stays at zero mismatches across a full business cycle, including month end.

Phase 3: Batch streams and write paths

Rebuild batch jobs as orchestrated Python pipelines (Airflow or Dagster, see our Airflow vs Dagster guide) that consume the same input files and produce the same output layouts, encoded back to EBCDIC where downstream systems still expect it. Reproduce COBOL arithmetic precisely: intermediate precision, truncation when no ROUNDED clause is present, half-up rounding when it is (Python's Decimal defaults to half-even, which will drift by a cent on enough records), and ON SIZE ERROR overflow behavior. Run both jobs every night on the same inputs and reconcile outputs record by record by key, plus control totals and hash totals per file. For write transactions, the mainframe remains the writer; the Python side computes in shadow and its results are compared, not committed. Exit criteria: zero unexplained differences for a full cycle (daily, month end, and quarter end if the slice touches it), and every explained difference signed off by the business owner.

Phase 4: Cut over slice by slice

Flip one slice at a time: the facade routes that transaction family to Python, or the scheduler runs the Python job as the producing job and the COBOL job as the shadow. Reverse the data direction for that slice (PostgreSQL becomes the source, CDC or a nightly extract feeds the mainframe copy for anything still reading it). Exit criteria: the slice runs on Python as system of record with the mainframe in shadow, reconciliation still at zero, and no consumer still reading the old dataset directly.

Phase 5: Decommission

When a slice has run cleanly with the COBOL shadow switched off, archive the old datasets in a readable format (with the copybook and a decoded copy), remove the programs and JCL, and shrink the mainframe footprint. Keep the reconciliation evidence. Exit criteria: programs removed from the load libraries, scheduler entries deleted, data archived with a documented retrieval path.

PhaseGoalKey techniqueExit criteria
0. CaptureKnow every contractCopybook-generated parsers, COMP-3 and zoned decoding to Decimal, golden datasetsByte-for-byte round trip; expected outputs recorded
1. Facade and syncDecouple consumers and dataz/OS Connect or CICS web support, MQ bridge, Db2 CDC to PostgreSQLConsumers on facade; daily control totals match
2. Read-only sliceProve the pattern safelyPython inquiry services, shadow requests, field-level response diffZero mismatches through month end
3. Batch and writesRebuild core logicOrchestrated pipelines, COBOL rounding rules, nightly record-level reconciliationZero unexplained differences for a full cycle
4. CutoverMove system of recordFacade routing per transaction family, reversed CDC, COBOL as shadowPython is writer; reconciliation still clean
5. DecommissionRetire the old sliceReadable archives with copybooks, load library and scheduler cleanupPrograms and jobs removed; retrieval path documented

Rebuild vs conversion tooling vs staying put

There are three honest options. Conversion tools translate COBOL into Java or another language automatically; you get running code quickly, but it usually keeps the COBOL program structure, so you still own a hard-to-change system, now in a new language. Keeping the mainframe (upgrading to z/OS 3.x, or moving to a hosted or managed mainframe) is the lowest-risk path when the code rarely changes. A rebuild, which is what our teams do, captures the interfaces and re-implements the logic as ordinary Python services your engineers can change, test and deploy like the rest of your stack. We do not sell conversion tooling and we do not operate mainframes. We mostly build new software from scratch, and that is exactly why taking a mainframe workload apart is tractable for us: copy the APIs, rebuild behind them, and prove it matches. We've been doing this for a while.

Cutover and rollback

Traffic moves through the facade and the scheduler, never through a big-bang switch.

Go/no-go checklist for each slice:

Rollback path by phase: in Phases 0 to 2 there is nothing to roll back, because the mainframe still answers every request. In Phase 3, turn off the Python shadow job. In Phase 4, flip the facade flag or scheduler entry back to COBOL; reverse CDC means the mainframe already has the records written since cutover. Keep the COBOL programs and JCL in place, shadowing, until Phase 5, so rollback stays a configuration change rather than a restore.

Risk matrix

RiskLikelihoodImpactMitigationEarly warning signal
Packed or zoned decimal decoded wronglyMediumHighGenerated parsers, Decimal only, byte round-trip tests on every record typeOff-by-sign or off-by-scale values in Phase 0 tests
Rounding drift (half-even vs half-up, truncation)HighHighMirror ROUNDED and truncation per COMPUTE statement; reconcile to the centOne-cent differences clustering in interest or fee fields
Hidden interface (undocumented feed or report)HighMediumDataset access logs, SMF records, partner list review before each sliceA downstream team asks where a file went
EBCDIC collation and code page mismatchMediumMediumExplicit sort keys, code page per feed recorded in the inventoryDifferent "top N" rows or garbled accented characters
Batch window overrun on the new sideMediumHighProfile pipelines early, parallelize by key range, keep the COBOL job as producer until timing holdsPython job elapsed time creeping toward the window
CDC lag or gapsMediumHighLag monitoring, daily control totals, replay from log positionsRow counts or totals diverge between Db2 and PostgreSQL
Business rules hidden in JCL, sort cards or REDEFINESHighMediumTreat sort control cards and job steps as code; trace field use across programsReconciliation differences only on certain record types
Mainframe SME availabilityMediumHighNamed SME per slice, recorded walkthroughs, specs written from golden dataQuestions waiting days for an answer
Audit finding on change evidenceLowHighStore reconciliation reports, approvals and test runs per slice from day oneAuditors asking for evidence you have to recreate

Typical team shape

A mainframe exit needs two kinds of reading skill and one kind of writing skill. Someone has to read COBOL, JCL and copybooks fluently; someone has to understand the data and the money; and a group of strong Python engineers has to build services that are boring to operate. A typical shape:

Many teams begin with a pod of 3 to 5 senior engineers (a tech lead plus engineers), and a full pod is about seven. Ryz engineers on your team start from $7,000 per month (our published range is $7,000–$15,000 per engineer per month, mostly mid-level to senior), quoted per team. Project cost is team size × months × monthly rate; the months depend on how many slices you move and how clean reconciliation is, so we scope that with you rather than quote a fixed project. Once you say go, engineers can typically start in under two weeks. Ryz engineers work on your team, reporting to your leads. When you are ready, scope your team with us, or read how our mainframe modernization work is structured.

Where an AI pod helps (and where it doesn't)

Large parts of a mainframe exit are reading and comparing, which is where AI-assisted tooling earns its keep. Our AI pod teams use language models to draft plain-English specs from COBOL paragraphs and JCL steps, to generate copybook parsers and the tests around them, to propose characterization test cases from golden datasets, and to triage reconciliation diffs by clustering thousands of mismatches into a handful of root causes (a rounding rule, a REDEFINES branch, a code page).

What AI does not do is decide that two outputs are equivalent. A model can misread a PERFORM VARYING loop or an implied decimal point and sound confident doing it. So every generated spec is checked by an engineer who reads the source, every generated parser must pass byte round-trip tests, and every rebuilt slice must pass the parallel run. The reconciliation harness is the judge, not the model.

When not to migrate (yet)

Ryz isn't the fit if you want a conversion tool license, someone to host and operate your mainframe, or a board-level transformation program from a management consultancy.

Related

FAQ

How long does a COBOL to Python migration take?

It depends on the number of slices you move, how many interfaces each slice touches, how well the copybooks and JCL are documented, how much business-rule logic hides in sort steps and REDEFINES, how long a full business cycle is for reconciliation (month end and quarter end often matter), and how quickly business owners can rule on differences. Because each slice cuts over on its own, you start getting value from the first slice rather than waiting for the whole program.

Can we run the mainframe and the Python services in parallel?

Yes, and you should. The plan depends on it. Online requests are shadowed through the API facade, batch jobs run on the same inputs on both sides every night, and outputs are reconciled record by record by key with control and hash totals. The COBOL side stays in place as the shadow after cutover, so rollback is a routing change.

Why not use an automated COBOL-to-Java converter instead?

Converters can be the right call when you need off the hardware fast and the code rarely changes. The trade-off is that translated code tends to keep COBOL's structure, so it stays hard to change and hard to hire for. A rebuild against captured interfaces gives you ordinary Python services, but it takes more engineering and needs a disciplined parallel run. Our teams do the rebuild; we do not sell conversion tooling.

How do you keep packed decimal amounts exact in Python?

Decode COMP-3 and zoned fields directly into decimal.Decimal using the scale from the copybook, never into float. Then mirror the COBOL arithmetic rules per statement: intermediate precision, truncation where no ROUNDED clause exists, half-up rounding where it does, and size-error handling. Reconciliation to the cent on every record is what proves it.

What does a mainframe exit cost?

Cost is team size multiplied by months multiplied by the monthly rate per engineer. The team is usually a tech lead, senior Python engineers, a COBOL and mainframe engineer, a data engineer and test automation, sized to how many slices run at once. We scope the team with you and give you a plan, a price and the names of the people before work starts, rather than a fixed project quote.

Questions we didn't answer? Email info@ryzlabs.com.

Thanks — your message has been sent. We’ll get back to you soon.

Something went wrong while sending your message. Please try again or email info@ryzlabs.com.

Explore Ryz Labs

Software development servicesAI development companyIndustriesStaff augmentationAI pod teamsNearshore software developmentHire engineers by roleEngineer ratesGuidesBuyer guidesCase studiesHow we vet engineers

Ryz Labs

Senior engineers on your team. AI pod teams that ship.

Tell us what you're building. You get a scoped plan, a price and the names of the people who would do the work.

  • Only the top 1% of tens of thousands interviewed make it
  • On US business hours, including New York hours
  • Trusted by Fortune 500 engineering teams

Tell us who you need

A Ryz partner replies with a scoped team plan.

Start a conversation →

Prefer to talk? Book a 15-min call →