DB2 catalog migration and fallback

Why DB2 migration has several levels

The word level appears often in DB2 migration documentation, but the levels do not mean the same thing. Installed code can be ahead of the catalog level and active function level. Packages can also remain at an older application compatibility level. This separation is deliberate: it lets administrators install maintenance and stabilize the environment before applications are allowed to use changed SQL behavior.

Record all four values in the migration runbook. Saying “we are on the new release” is not precise enough. One member might run newer code while the group catalog and function level remain at a migration-safe state, and packages can still be bound with an older APPLCOMPAT value.

Catalog levels and CATMAINT

The DB2 catalog contains definitions for databases, table spaces, tables, indexes, packages, authorization, utilities, and many other DB2 objects. New releases and function levels sometimes require new columns, tables, indexes, or changed catalog definitions. The catalog level identifies which of those structural changes are present.

CATMAINT is the IBM utility used for catalog level changes. Migration jobs generated or supplied by IBM invoke CATMAINT in a controlled sequence. Run the exact jobs for the installed release and maintenance level, review their return codes, and retain the output as migration evidence. Do not substitute hand-written ALTER statements: the catalog is an internal DB2 interface with dependencies that ordinary application DDL does not manage.

1
2
3
4
5
6
7
8
Migration control flow (conceptual)
 
1. Verify prerequisite maintenance and current levels
2. Start DB2 with target-release code in the documented migration mode
3. Run the IBM-supplied CATMAINT migration job
4. Check CATMAINT messages and catalog consistency
5. Validate applications and operations
6. Activate a higher function level only after approval

Take catalog and directory backups at the documented checkpoints and verify that recovery material is usable. CATMAINT completion is not the end of migration; it is one controlled change inside a larger process.

Coexistence and fallback

Coexistence is a temporary state in which supported old-release and new-release code participate in the same migration process. It is especially visible in data sharing, where members are commonly migrated in stages. Coexistence is not an unlimited operating model. IBM defines which release combinations, maintenance levels, catalog states, and member sequences are supported, and the group must remain inside that window.

Fallback means returning to the prior release code while that return is still supported. It is not the same as restoring an arbitrary catalog backup after production work has continued. A fallback plan identifies the latest reversible point, the commands and startup modes involved, package considerations, data sharing order, and how changes made during migration are handled.

The critical boundary is function level 500 (FL500). After FL500 is activated, fallback to the prior DB2 release is no longer supported. Activation must therefore be a formal decision, not an automatic step attached to the end of a job stream. Keep the environment below that irreversible point while you run the agreed validation and fallback rehearsal.

Data sharing migration

A DB2 data sharing group has one shared catalog and directory, even though each member has its own code, logs, and execution environment. Consequently, all members must support the migration. Before the first member moves, apply required maintenance to every member, verify coupling facility and group prerequisites, and make sure automation recognizes both old and new release messages.

A controlled member sequence

• Confirm every member is healthy and can participate in the supported coexistence combination.
• Quiesce or drain work from the selected member, then migrate and restart it according to the IBM procedure.
• Validate that the migrated member joins the group, accesses shared objects, and communicates correctly with members still on old code.
• Move remaining members within the allowed coexistence window; do not leave the group mixed indefinitely.
• Run group-wide validation before activating FL500 or a later new function level.

Test member failure and restart during coexistence. A migration that works only while all members stay healthy has not tested the operational conditions that data sharing exists to survive.

Continuous delivery and new function activation

Modern DB2 for z/OS uses a continuous delivery model. IBM can deliver function through maintenance rather than waiting for a traditional full release. The installed code may understand a new function while the catalog remains at an earlier required level and the active function level remains lower. This is the practical meaning of “code can be ahead of catalog or function level.”

A function level has prerequisites: a minimum code level, sometimes a minimum catalog level, and successful DB2 checks. Activation makes the function level available to the subsystem or data sharing group, but applications may still be protected by APPLCOMPAT. Separate installation, catalog maintenance, activation, and application adoption into different change decisions whenever possible.

1
2
3
4
5
6
7
8
-- Display current group and function-level information
-DISPLAY GROUP
 
-- Validate a target function level before activation
-ACTIVATE FUNCTION LEVEL (V12R1M500) TEST
 
-- Activate only after migration acceptance and fallback approval
-ACTIVATE FUNCTION LEVEL (V12R1M500)

Command syntax and available levels depend on the DB2 release. Use the command output and IBM documentation for the installed code. Treat TEST validation as a prerequisite check, not as proof that business applications are correct.

Application compatibility levels

APPLCOMPAT is the compatibility level assigned when a package is bound or rebound. It controls the SQL function and behavior that the package can use. This gives application teams a safer adoption path: the subsystem can advance while a stable package remains at a previously tested SQL compatibility level.

Do not raise the subsystem default and rebind every package without testing. First select representative applications, bind or rebind them at the proposed APPLCOMPAT, execute regression and performance tests, and examine SQL results and access paths. Dynamic SQL also needs attention because its effective compatibility can depend on package and subsystem configuration.

1
2
3
4
5
6
7
-- Example only: use a level supported by your installed DB2 code
REBIND PACKAGE(PROD.CUSTOMER_API)
  APPLCOMPAT(V12R1M500)
  EXPLAIN(YES);
 
-- Keep a known package copy or version strategy for access-path recovery
-- according to your site's bind standards.

Safe APPLCOMPAT adoption

• Inventory the current APPLCOMPAT of important packages.
• Identify SQL whose semantics changed at later compatibility levels.
• Test a small package cohort before changing broad defaults.
• Compare results, SQLCODEs, access paths, CPU, elapsed time, and locking.
• Raise compatibility by application wave, with an owner and rollback procedure.

Catalog migration, package invalidation, and rebind

Packages contain executable forms of static SQL and optimizer access paths. Catalog changes, object changes, maintenance, and release migration can make a packageinvalid. DB2 may attempt automatic rebind when an invalid package next runs, but relying on that first-use event creates unpredictable production delay and can expose an access path change at the worst time.

Plan a REBIND after migration. Start with packages reported invalid, then process application groups according to risk and business schedule. Capture EXPLAIN information and compare important access paths. Preserve package copies or use the site's package version strategy so an unacceptable path can be corrected quickly. Rebind failure must be reported and resolved, not hidden by a job that continues through thousands of packages.

Why packages invalidate

• Referenced tables, indexes, routines, or privileges changed.
• Catalog migration changed metadata on which package validity depends.
• Pending DDL was materialized and changed the physical object definition.
• Maintenance or function activation introduced a documented rebind requirement.
• A package was bound at a level no longer valid for the intended environment.

Pending DDL and materialization

Some ALTER statements are accepted as pending DDL. DB2 records the requested definition, but the physical object is not immediately transformed. A later utility—commonly a REORG with the required options—materializes the pending change. Migration teams must inventory pending definitions because they can affect catalog interpretation, utility sequences, recovery plans, and package validity.

Decide whether each pending change should be materialized before migration, deliberately carried through the migration, or removed using the supported procedure. Do not discover pending DDL during a post-migration REORG. After materialization, check dependent packages and rebind those that became invalid.

Deprecated and removed features

A deprecated feature still works in the current level, but IBM warns that it should no longer be used and may disappear later. A removed featureis unavailable in the target release. These statuses are not interchangeable: a deprecated dependency is technical debt with a deadline, while a removed dependency is a migration blocker.

Search application source, DBRMs, packages, subsystem parameters, utility control statements, exits, stored procedures, vendor products, and automation. Repeat this review for every release boundary; something deprecated several releases ago may be removed in the target environment. Replace dependencies in production before the migration weekend whenever possible.

Migration testing strategy

A successful startup proves only that DB2 started. A useful migration test reproduces the target code, catalog level, maintenance, subsystem settings, and representative data. It includes online and batch applications, utilities, distributed access, security, monitoring, backup, recovery, and failure scenarios. Test both correctness and performance.

Migration testing checklist

• Confirm prerequisite maintenance, catalog level, code level, function level, and member health.
• Take and verify required catalog, directory, BSDS, and application recovery material.
• Run CATMAINT in a production-like copy and retain every message and return code.
• Exercise COBOL static SQL, dynamic SQL, CICS, IMS, DDF, JDBC, REST, stored procedures, triggers, and user-defined functions that the site uses.
• Run COPY, RECOVER, REORG, RUNSTATS, LOAD, CHECK utilities, and restart scenarios.
• Inventory invalid packages, perform controlled REBIND, and compare access paths.
• Test the proposed APPLCOMPAT on selected packages before raising defaults.
• Review pending DDL and prove the planned materialization sequence.
• Scan for deprecated and removed features in applications, exits, automation, and vendor products.
• In data sharing, test mixed-member coexistence, member restart, and group completion.
• Rehearse fallback before FL500 activation and document the decision that ends fallback.
• Compare baseline CPU, elapsed time, getpages, sort activity, locks, timeouts, and key SQL access paths.

A practical activation plan

Divide the work into gates. The first gate installs prerequisite maintenance. The next starts target code and performs catalog migration while fallback remains available. A validation gate proves applications and operations. Only then should management and technical owners approve FL500 activation. Later function levels and higher APPLCOMPAT values can be introduced in separate waves. This approach keeps the cause of a problem visible and avoids changing code, catalog, optimizer behavior, and SQL semantics at the same instant.

1
2
3
4
5
6
7
Gate 1  Prerequisites complete
Gate 2  Target code starts successfully
Gate 3  CATMAINT and catalog checks complete
Gate 4  Applications, utilities, recovery, and performance accepted
Gate 5  FL500 activation approved (prior-release fallback ends)
Gate 6  Later function levels activated as required
Gate 7  APPLCOMPAT raised by tested application waves

Explain It Like I'm Five

Imagine a school replacing its rulebook. The teachers can receive the new book first; that is the new code level. The office updates its filing cabinets; that is the catalog level and CATMAINT does the careful filing. The principal announces which new rules are officially in use; that is the function level. Each classroom can keep using an older, familiar set of lesson rules until it has practiced the new ones; that is APPLCOMPAT. Before the principal makes the big FL500 announcement, the school can still return to the old rulebook. After the announcement, going back is no longer allowed, so everyone tests first.

Exercises

1. Create a four-column inventory for code level, catalog level, function level, and APPLCOMPAT. Explain who approves each change.
2. Draft a data sharing sequence for three members. Include coexistence checks, workload draining, member validation, and the point at which all members must be complete.
3. Choose one application and design an APPLCOMPAT test that compares SQL results, SQLCODEs, and access paths before and after rebind.
4. Write a query and operational procedure for finding invalid packages, assigning owners, rebinding them, and handling access path regression.
5. Review your target release's deprecated and removed feature list. Classify each local dependency as replace before migration, replace later, or verified unused.
6. Build a go/no-go checklist for FL500 activation that includes recovery evidence, application acceptance, data sharing status, and explicit acknowledgment that prior-release fallback ends.