Mainframe Application Dependency Mapping: The First Step Before Legacy Modernization
Dona Zacharias
Mainframe application dependency mapping is the process of tracing every program, job, file, table and transaction that connects to the application you plan to change, so you know what a change will touch before you make it. On a mainframe, those links hide in COBOL calls, shared copybooks, JCL job chains, scheduler rules and Db2 tables, and most of them are not written down anywhere.
The risks of skipping this step are reflected in 2026 industry forecasts. Gartner predicts that more than 70% of mainframe exit projects started in 2026 will fail to deliver their intended benefits, largely because teams overestimate what generative AI can do. For many organizations, Gartner recommends modernizing in place instead of leaving the platform. Either way, the work starts with knowing what you have. This guide covers what to map, how discovery works, what goes wrong when it is skipped, how to choose a tool, and how to turn the map into a modernization roadmap.
What is mainframe application dependency mapping, and why does it come first?
Mainframe application dependency mapping is a model of how programs, batch jobs, data stores, online transactions and interfaces depend on one another. It comes first because every later decision, from which application to move to which one to retire, depends on knowing what else breaks when something changes.
One distinction makes the map useful. A relationship means two components exchange data. A dependency means one cannot work correctly without the other. A program that reads a Db2 table has a relationship with it. A program that writes a table read by three batch jobs creates a dependency, and that dependency shapes how those four workloads are sequenced. A map that separates the two is a planning tool. A map that shows only connections is a diagram.
The alternative is to discover dependencies after cutover, when they appear as failed jobs and missing data. The map keeps paying off after the move, too, because it shortens root cause analysis and supports incident response.
Eight kinds of dependency hiding in a mainframe estate
Generic application dependency mapping guides focus on servers, network traffic and microservices. A mainframe estate has its own dependency types. The table lists eight, where each one lives, whether you can read it from source code alone, and what breaks if you miss it.
Dependency | Where it lives | Readable from source? | What breaks if missed |
| Program calls | CALL statements in COBOL, PL/I and Assembler | Mostly. Calls whose target name sits in a variable need extra resolution | A retired or moved subprogram stops its callers |
| Copybooks | Shared record and field definitions included at compile time | Yes, once the copy statements are expanded | One field change ripples into every program that includes it |
| JCL and procedure chains | Job steps, procedures and DD statements that tie jobs to datasets | Yes, after procedures are expanded | Batch steps run out of order or read the wrong file |
| Scheduler conditions | Job dependencies and calendars in Control-M or CA-7 | Only from scheduler definitions, not program source | A successor job starts early or never starts |
| Data stores | Db2 tables, VSAM files and IMS databases, and who reads or writes each | Largely. Embedded SQL and file definitions show access | Workloads that share writes get split across waves |
| Online transactions | CICS and IMS transactions and screen maps | Definitions yes. Usage volume needs operational data | A transaction is retired while users still call it |
| Interfaces and file transfers | MQ queues, Connect:Direct or SFTP transfers, partner feeds | Partly. Endpoints often live in configuration, not code | A downstream partner stops receiving a feed |
| Operational knowledge | Batch windows, month-end peaks, ownership | No. It comes from tickets, run history and people | A move lands in a peak window, or no one is accountable |
The third column highlights an important limitation of source analysis. Source analysis finds what the code states. It cannot tell you which job really matters at month-end or which feed a partner still uses. Apex Systems makes the same point from the discovery side: a useful map traces static and runtime-resolved links, and includes inactive code that still shapes behavior through dependency chains. Vendor documentation from IBM and Google lists the same families of artifacts: programs, JCL, CICS definitions, scheduler data and database access.
How does mainframe dependency discovery work, and where does AI help?
Discovery reads the artifacts that define the estate (source libraries, JCL, scheduler definitions and database definitions), resolves how they connect, and assembles the result into a queryable graph. People then validate what the tooling infers.
In practice the work runs in five steps:
- Ingest read-only. Source libraries, copybooks, JCL and database definitions arrive as a copy, a Git mirror or a read-only connection. Nothing changes on the mainframe.
- Resolve structure. Expand copybooks and procedures, map each DD statement to a real dataset, and resolve calls whose targets sit in variables. List every call that cannot be resolved.
- Build the graph. Link programs, jobs, files, tables, transactions and interfaces, and attach an owner to each.
- Add operational evidence. Tickets, change history and run records show which links are live, which are dormant and which fire only at month-end.
- Review with experts. People confirm what the tooling inferred and name an owner for each critical dependency.
It helps to think of this as three kinds of truth. The code and data definitions show what the system was designed to do. Documents show what people believe it does. Operational records show what it does under load. They rarely agree, and the gaps between them are where modernization surprises live.
Can AI do this work? It can do much of the reading. According to the Open Mainframe Project’s July 2026 write-up of Gartner’s position, generative AI is strong at code understanding, discovery and documentation, and weak at converting code while preserving exact business meaning. The practical takeaway is to use AI for discovery and documentation first, while keeping human review on everything it infers. Tooling that resolves structure before it reasons about meaning, and that reports what it could not resolve, earns more trust than a model that summarizes raw source.
What happens when dependencies are missed?
Missed dependencies turn into scope surprises, broken batch chains and data conflicts, usually after cutover, when fixing them costs the most. Four patterns recur:
- Orphaned successors. A job you retire is the only thing that triggered a downstream report. Nothing fails loudly. The report just stops arriving.
- Split writers. AWS planning guidance for shared Db2 environments advises grouping workloads that write to the same tables into the same wave, because moving them separately creates data conflicts and complex interim fixes.
- Copybook ripple. A changed field definition reaches every program that includes it, which hides how large the change really is.
- Timing buffers. Scheduler vendor JAMS notes that time-based buffers fail when an upstream job runs long, so the downstream job reads incomplete data and produces output that looks valid.
Here is an illustrative case, not a customer story. A team moves a read-only reporting job to the cloud in wave one. The job consumes a nightly file produced by a program scheduled for wave three. Nobody mapped the file, so the job runs on stale data until wave three lands. No alert fires, because nothing technically failed.
How do you turn the map into a modernization roadmap?
Use the map to sort every application by what depends on it and what it depends on. That ordering sets migration waves, exposes retirement candidates and shows where wrapping a program in an API is safer than moving it.
The same map supports application rationalization. It shows which applications have no dependents and which are tied into everything, so retire-or-keep decisions rest on evidence instead of opinion. QyrusAI’s discovery-first approach to legacy modernization starts from the same idea: understand what you have and how it connects before you choose what to retain, wrap, rebuild or retire.
How to evaluate mainframe dependency mapping tools
Choose a tool by what it can map, how it handles what it cannot resolve, and what you can do with the output. Coverage of your languages and schedulers matters more than the polish of the diagram. Vendors often file this category under application discovery and dependency mapping, so search under that name too. Use this checklist:
- Artifact coverage. COBOL, PL/I, Assembler, JCL and procedures, copybooks, CICS or IMS definitions, and Db2, VSAM or IMS data.
- Scheduler coverage. Control-M, CA-7 or whichever scheduler you run.
- Dynamic calls. Does the tool resolve them, and does it list the ones it could not?
- Read-only ingestion. Can it work from a copy or Git mirror, so security review moves quickly?
- Impact queries. Can you ask what touches a given field or table and get an answer across programs, jobs, files and tickets?
- Does every inferred link show its source and a confidence level?
- Does the output feed wave planning and test scoping, or stop at a diagram?
Here are tools worth shortlisting. QyrusAI is our product; the other rows come from vendor documentation and AWS guidance, so confirm current coverage with each vendor.
| Tool | What it covers | Platform note |
| QyrusAI | Enterprise Knowledge Graph linking programs, jobs, files, tables, transactions, dependencies, ownership and data lineage. Read-only ingestion by ZIP upload, Git, live discovery (Zowe CLI, z/OSMF, SFTP or FTPS) or a source-control bridge. Resolves copybook and procedure expansion, DD-to-dataset mapping and dynamic calls | Works today on z/OS and IBM i. Other platforms scoped per engagement |
| IBM Application Discovery and Delivery Intelligence | Program call graphs for CICS, impact analysis, batch scheduler support (CA7, IWS, Control-M, AAUTO) and Db2 data lineage | IBM Z |
| Google Mainframe Assessment Tool | Analyzes COBOL, JCL, HLASM, BMS maps, Db2, IMS DB, VSAM and CICS, supports Control-M, and groups assets into sequenced migratable units | Works from an uploaded archive of source |
| Rocket Enterprise Analyzer | Named in AWS guidance for showing application structure, dependencies and complexity | Cited for Db2 replatforming assessments |
How QyrusAI helps you map dependencies before you modernize
QyrusAI is an enterprise AI platform that helps organizations Modernize, Assure and Operate their critical systems. Dependency mapping sits in Modernize, where it builds an evidence-based picture of the application estate before anything changes.
For mainframe estates, QyrusAI reads source libraries, copybooks, JCL and database definitions through read-only paths and builds an Enterprise Knowledge Graph of programs, jobs, files, tables, transactions, dependencies, ownership and data lineage. It resolves copybook and procedure expansion, DD-to-dataset mapping and dynamic calls before it proposes business rules, and a person validates each rule. The comprehension tooling works today on z/OS and IBM i estates, and other platforms are scoped per engagement.
The output is a business-readable design document, a dependency graph and a business rules catalog. Assure then generates tests from the validated rules, so verification starts from the same record that shaped the plan. Teams that need to confirm migrated data matches the source can pair the work with unified data testing, and automated regression testing keeps release quality steady as each wave lands. After cutover, the same graph helps trace an incident to its cause.
QyrusAI works alongside the transformation engines and specialist tools you already use. You can start with a read-only proof of concept on a representative codebase and judge the dependency graph on your own application.
Map first, then decide
Mainframe modernization succeeds or stalls on what you know before you start. Separate relationships from dependencies, map all eight dependency types, insist that your tooling reports what it could not resolve, and let the graph set your waves and retirements.
QyrusAI helps you build that picture from your own code and carry it into testing. Request a demo to see how your mainframe estate can be mapped before you commit to a modernization path.
Frequently asked questions
How is dependency mapping different from a CMDB?
Can AI be used for mainframe dependency mapping?
Do you need production access to map dependencies?
How does dependency mapping support application rationalization?
How does dependency mapping reduce modernization risk and shape the roadmap?
What dependencies should be identified in a mainframe environment?
What happens if critical dependencies are missed?
Stay Ahead, Stay in the Loop with QyrusAI!
One Platform for Modernization, Quality Assurance and Intelligent IT Operations.
October 23, 2026 
11 min
