IMS Database Dependency Analysis: What Modernization Teams Must Know Before Moving Anything

IMS is not a legacy system in the sense of being obsolete. It is the database engine behind the accounts receivable of major banks, the policy administration of insurance companies, the claims processing of healthcare payers. IBM continues developing it. The problem is not that IMS stopped working, the problem is that every developer who knew how to navigate its hierarchical segment trees is retiring, every change to an IMS-backed system requires understanding a data model that has no SQL, and every migration plan that treats IMS like a relational database discovers the difference the hard way.

The hard way is discovering mid-migration that a COBOL program accesses IMS not through a simple key lookup but through a hierarchical traversal that must be replicated in the target system with equivalent navigation logic. Or discovering that a logical relationship between two physical IMS databases creates a dependency that neither database’s DBD documents fully, and that the migration converted both databases independently while silently breaking every program that used the logical relationship. Or discovering that a secondary index database, a structure most migration plans never inventory, was the only path by which a critical reporting program reached its data.

None of these surprises survive contact with rigorous pre-migration dependency analysis. They survive contact with assumptions.

What Makes IMS Dependency Analysis Different

Dependency analysis for a relational database environment, DB2, Oracle, SQL Server, follows a well-understood path. Parse the SQL in the application code, identify the table and column references, build a map of which programs access which tables, and use that map to determine migration scope and sequence. The structure is explicit. The dependencies are visible in the SQL text.

IMS dependency analysis is more complex along every dimension.

The structure is hierarchical, not relational. An IMS database is organized as a tree of segment types, where each segment type has a defined parent-child relationship. A COBOL program that reads patient records from an IMS database does not execute SELECT * FROM PATIENTS WHERE ID = ?. It issues a Get Unique call (GU) to navigate the hierarchy to the root segment, then Get Next Within Parent calls (GNP) to traverse the children. The program’s dependency is not on a table, it is on a specific path through a hierarchical structure, and changing that structure can break programs that navigate it in ways that no SQL-level analysis would detect.

The dependencies are distributed across three separate structures. The full picture of what a COBOL program does with IMS requires analyzing:

• The DBD (Database Descriptor): defines the physical segment hierarchy, the key fields, access methods (HDAM, HIDAM, HISAM, HSAM), and any secondary indexes or logical relationships
• The PSB (Program Specification Block): defines which databases a program is permitted to access, through which PCBs, with which sensitivity and intent specifications
• The COBOL source code: contains the actual DL/I calls that determine which segments are accessed, with what call functions, in what sequence, with what SSAs

No single source contains the complete picture. Analysis that reads only the COBOL source sees the call types and segment names but not the physical database structure. Analysis that reads only the DBD and PSB sees what the program is permitted to do but not what it actually does.

Navigation is position-dependent. In a relational database, every row is independently addressable by key. In IMS, a program’s current position in the hierarchy affects what subsequent calls return. A GN (Get Next) call returns the next segment in hierarchical sequence from wherever the program currently is. The dependency is not just on the segment type but on the traversal path that led to the current position. Programs that rely on IMS’s implicit hierarchical ordering have a dependency that disappears when the data is migrated to a relational database where no equivalent ordering is guaranteed.

The DL/I Call Inventory: What COBOL Source Code Reveals

The most directly useful pre-migration analysis is a complete inventory of every DL/I call in every COBOL program that accesses IMS. This inventory tells the migration team what each program does with IMS, not what it is permitted to do (which the PSB defines) but what it actually does.

DL/I calls in COBOL appear in two forms:

cobol

* Form 1: EXEC DLI interface (CICS-compatible, high-level syntax)
       EXEC DLI
           GU DB2PCB
           SEGMENT(CUSTROOT)
           WHERE(CUSTID = WS-CUST-ID)
       END-EXEC

* Form 2: xxxTDLI call interface (batch programs, assembler-compatible)
       CALL 'CBLTDLI' USING WS-FUNCTION-CODE
                            PCB-CUSTOMER
                            WS-CUSTOMER-SEGMENT
                            WS-SSA-CUSTOMER

Both forms carry the same analytical information: the function code, the PCB being used, the segment being targeted, and optionally the SSA (Segment Search Argument) that qualifies the call. A complete DL/I call inventory extracts all of this from every program.

The Function Code Taxonomy and Its Migration Implications

The DL/I function code is the most migration-significant element of each call. Each function code implies a different data access pattern that must be replicated in the target relational database:

Read-only functions: GU, Get Unique: navigate directly to a segment using qualified SSAs. Equivalent to a SELECT with WHERE clause in relational terms. Straightforward to migrate if the segment key maps cleanly to a relational primary key.

GN, Get Next: move to the next segment in hierarchical sequence. This is the function code that has no direct relational equivalent, it relies on IMS’s positional state and implicit ordering. Programs that use GN extensively require careful analysis of what ordering they depend on.

GNP, Get Next Within Parent: retrieve subsequent children of the current parent segment. Equivalent to fetching all rows in a foreign-key relationship. Generally maps cleanly to a SELECT with a foreign key WHERE clause.

Hold functions (prerequisites for update): GHU, GHN, GHNP, Get Hold equivalents of GU, GN, GNP. The “hold” flag indicates that an update (REPL) or delete (DLET) operation will follow. Programs that use hold calls are read-modify-write programs; the migration must preserve transactional integrity across the hold and the subsequent update.

Update functions: ISRT, Insert: adds a new segment occurrence. Equivalent to INSERT. DLET, Delete: removes the current held segment and all its dependents. The “all dependents” behavior is an IMS-specific cascade that must be explicitly implemented in the target system. REPL, Replace: updates the current held segment with new data. Equivalent to UPDATE.

Why this matters for migration scope: A program with only GU and GNP calls is a read-only consumer of IMS data, lower risk to migrate, simpler to validate. A program using GHU, REPL, and DLET is a transaction-processing program that modifies hierarchical structures; its migration requires preserving transactional integrity across operations that IMS currently enforces atomically.

The Three Dependency Types That Trip Up Every Migration

Logical Relationships

IMS logical relationships connect segments across two physically separate databases. A logical child segment in Database A has a logical parent in Database B. When a COBOL program navigates through a logical relationship, it traverses a path that physically crosses database boundaries, a traversal that IMS manages transparently but that disappears when the databases are migrated independently.

Logical relationships are the highest-risk dependency type in IMS migration for one reason: they are invisible in the COBOL source code. The COBOL program calls GNP to get children of a segment. Whether that GNP traverses a physical parent-child relationship or a logical relationship is determined by the PSB and DBD, not by the COBOL code. A migration team that analyzes only the COBOL source has no way to know that a GNP call is crossing a logical relationship boundary without separately analyzing the PSB and DBD.

Programs that use logical relationships require the migration to replicate the logical relationship’s semantics in the target system, typically a JOIN in the relational model, and to validate that every program using the relationship receives equivalent results from the JOIN that it received from the IMS logical traversal.

Secondary Index Databases

IMS secondary index databases provide an alternate access path to a primary database, allowing programs to retrieve segments by a field other than the root key. A secondary index database is a separate IMS database with its own DBD, but its data is derived from the primary database.

Migration teams frequently discover secondary index databases during analysis rather than during planning, because:

• They are defined in DBDs that are not always grouped with the primary database DBDs
• Programs that use secondary indexes name the index database in their PSBs, but programs that navigate to the primary database via a secondary index may not make this obvious in COBOL source
• Documentation may describe the primary database without mentioning its secondary indexes

A program that accesses IMS through a secondary index has an access pattern dependency that must be replicated in the target as a non-primary-key index or a different query strategy. Missing this during migration produces a program that runs without error but cannot find the records it is looking for.

GSAM Databases

GSAM (Generalized Sequential Access Method) databases are IMS’s interface for sequential batch processing, essentially allowing COBOL batch programs to use DL/I calls for what is functionally sequential file I/O. GSAM databases do not have segment hierarchies; they are flat sequential structures accessed through IMS to benefit from IMS’s recovery and restart capabilities.

Programs that use GSAM databases are batch programs that depend on IMS’s checkpoint/restart support for their recovery behavior. Migration must preserve this recovery behavior or replace it with an equivalent mechanism in the target platform.

Building the Pre-Migration Dependency Inventory

A complete IMS dependency analysis produces six deliverables that together define the migration scope, risk, and sequence.

Deliverable 1: PCB-to-Database Mapping

Every PCB in every PSB maps to a specific DBD (a specific IMS database). Listing every PCB across all PSBs and mapping each to its DBD produces the authoritative list of which programs are permitted to access which databases. This is the starting point for understanding scope, but it overstates actual dependencies because programs may have PSBs that include more databases than they actually use.

Deliverable 2: Actual Call Inventory per Program

Parsing every COBOL program’s DL/I calls produces the actual usage list: which PCBs each program actually calls, which function codes it uses, which segment types it accesses, and whether it uses qualified SSAs (segment key access) or unqualified navigation (positional traversal). This narrows the scope from PSB-defined permissions to actual program behavior.

Deliverable 3: Logical Relationship Usage Map

Cross-referencing the call inventory against the DBDs identifies which programs’ GNP or GN calls traverse logical relationships. This requires analyzing not just the COBOL source and PSB but the DBD structures that define which parent-child relationships are physical and which are logical.

Deliverable 4: Secondary Index Usage Map

Programs that name secondary index databases in their PSBs or issue calls with SSAs referencing non-root key fields are identified as secondary index users. The map documents which secondary indexes exist, which primary databases they support, and which programs depend on them.

Deliverable 5: Call Type Distribution per Database

For each IMS database in scope, the distribution of call types across all programs that access it indicates the complexity of its migration:

• Databases accessed only by read functions (GU, GN, GNP) are simpler to migrate
• Databases accessed by hold functions and updates (GHU + REPL, GHN + DLET) require transactional integrity replication
• Databases with high GN usage indicate positional navigation dependencies that require ordering analysis
• Databases with logical relationships require cross-database JOIN semantics in the target

Deliverable 6: Program Risk Classification

Using the call type distribution and dependency type inventory, each program is classified by migration risk:

Programs that use only GU and GNP with qualified SSAs, access a single database with no logical relationships, and have no hold/update calls are the lowest-risk candidates for early migration waves. Programs that use GN extensively, access multiple databases through logical relationships, or perform complex hold/update sequences are the highest-risk programs that require the most thorough analysis and validation before migration.

What the Analysis Changes About Migration Planning

The dependency analysis does not just document what exists, it changes the decisions that follow.

Sequence decisions. Programs that share IMS databases through logical relationships cannot be migrated independently. If Program A reads a logical child segment that has a logical parent in the same database as Program B’s root segment, migrating A without migrating B (or creating a bridge) breaks A. The dependency graph determines which programs must move together.

Target design decisions. The call type distribution informs how the target relational schema should be structured. A hierarchical parent-child relationship accessed exclusively through key-qualified GU and GNP calls translates cleanly to a foreign-key relationship in the target. The same relationship accessed through GN calls with positional dependencies requires the target schema to preserve equivalent ordering, either through explicit ORDER BY, a sequence field, or a different access pattern that achieves the same result.

Validation scope decisions. The analysis identifies which programs are read-only consumers of IMS data and which are transaction processors. Read-only programs can be validated by comparing output results between the original IMS system and the migrated system. Transaction processors require transactional equivalence testing, ensuring that the same sequence of operations against the target produces equivalent data state changes to the original.

Risk classification. The logical relationship and secondary index findings are the primary inputs to risk classification. Every migration program has a risk register. The IMS dependency analysis tells the team which entries to put in it.

How SMART TS XL Performs IMS Dependency Analysis

SMART TS XL’s static code analysis parses every COBOL program’s DL/I calls, both EXEC DLI and xxxTDLI call interface forms, extracting the function code, PCB reference, segment name, and SSA structure from each call. This produces the actual call inventory at the program level, across the entire COBOL portfolio, without requiring a running IMS system or manual code review.

The application dependency mapping extends this inventory into a cross-program dependency graph: which programs share access to which IMS databases, which programs use the same PCBs, which programs’ access patterns overlap in ways that require coordinated migration. When a logical relationship connects segments across databases, the dependency map represents this cross-database connection as an explicit relationship that must be preserved in the target system.

The impact analysis capability answers the question that every migration team must answer before any database is converted: if this IMS database is migrated, which programs are affected, which access patterns must be replicated, and which test cases must be validated to confirm equivalence. The answer is not an estimate, it is an enumerated list derived from the actual DL/I call inventory.

The JCL expansion capability adds the operational context: which JCL job steps invoke which programs that access IMS, in what sequence, with which PSB specifications. The operational dependency chain, the batch job sequence that processes IMS data through multiple programs, is as important to migration planning as the program-level access patterns. Migrating the database without migrating the batch job orchestration that surrounds it produces a system that processes records correctly in isolation and fails in production when the job sequence runs.

For teams conducting legacy modernization of IMS-backed systems, the structural evidence produced by SMART TS XL is the input to every subsequent migration decision: which programs migrate in which wave, which databases can be converted independently and which require coordinated conversion, which access patterns require re-architecture rather than direct translation. As described in the context of migrating IMS and VSAM structures alongside COBOL programs, the interconnection between COBOL programs and legacy data structures means that data migration and code analysis must proceed in parallel, the dependency inventory is the mechanism that makes parallel planning possible.

The Inventory Is Not the Migration

IMS dependency analysis produces knowledge. The migration still requires decisions, engineering, and validation. What the analysis changes is the quality of the decisions, the completeness of the engineering scope, and the confidence of the validation.

The organizations that migrate IMS databases successfully are not the ones with the most aggressive timelines or the largest migration budgets. They are the ones that knew what they had before they started moving it, every program that accessed each database, every function code that revealed each program’s access pattern, every logical relationship that created cross-database dependencies, every secondary index that provided an access path that would not survive conversion without explicit replication.

That knowledge does not come from documentation. It comes from parsing the code.