The DB2 CATMAINT utility

When CATMAINT runs

IBM: run CATMAINT during migration to a new release, before you activate a function level that requires a new catalog level, or when IBM Support instructs you. Output of UPDATE is the updated catalog. Phases are UTILINIT and UTILTERM—there is no long “copy pages” phase like COPY. CATMAINT is in the base utilities set. Authorization is installation SYSADM or installation SYSOPR only.

Important: do not attempt to start Db2 at a lower code level after any part of the CATMAINT job for a higher function level completes. The code that tolerates the new catalog structures lives in the code level that delivered that CATMAINT job. Restriction: before you tailor the catalog for a function level, activate function level 500. DISPLAY GROUP shows HIGHEST ACTIVATED FUNCTION LEVEL.

Job DSNTIJTC is the supported wrapper. It issues CATMAINT UPDATE and writes DSNU777I at several points. Abend diagnostics may include DSNU776I or DSNU778I. Identify incompatible applications before an online catalog migration. Size the work file database; migration CATMAINT sorts there.

1
2
3
4
5
6
7
8
9
CATMAINT UPDATE LEVEL(V12R1M502);
 
CATMAINT UPDATE SCHEMA SWITCH(OLDNAME,NEWNAME);
 
CATMAINT UPDATE OWNER FROM (PAYADM) TO ROLE;
 
CATMAINT UPDATE VCAT SWITCH(OLDVCAT,NEWVCAT);
 
CATMAINT UPDATE UTILX EXTENDED;

UPDATE LEVEL

LEVEL(level) uses format VvvRrMmmm (version, release, modification). If you specify a function level, Db2 chooses the catalog level that function actually needs—which might be lower than the function level you named, because not every function level changes the catalog. DSNU777I tells you what happened.

If the target requires multiple catalog-level updates, CATMAINT processes them in order. A later failure does not roll back earlier successes; the catalog stays at the highest level reached. Fix the cause and resubmit the same CATMAINT job. That is why you never “try LEVEL and hope to undo it by starting old code.”

Plans and packages bound with DBPROTOCOL(PRIVATE) do not stop CATMAINT, but they cannot execute remote access on Db2 10 and later until you rebind them to DRDA.

SCHEMA SWITCH

SCHEMA SWITCH(schema-name, new-schema-name) changes every matching owner, creator, or schema in the catalog and directory. If the old name is a grantor or grantee on those objects, the new name takes that place too. Creator/owner IDs on plans and packages that use the objects are not changed. You may repeat SWITCH for several pairs but not reuse the same name twice. Names cannot exceed 8 bytes in EBCDIC. SYSIBM is not allowed on either side. Ownership is not changed when the owner is already a role.

IBM will ignore a schema-name that identifies no owner/creator/schema. It will refuse a schema that qualifies objects on which any of these depend: triggers, views, SQL functions, materialized query tables, native SQL procedures, expression-based indexes, column masks, row permissions. The old schema cannot appear in a check constraint condition. New-schema-name cannot already qualify existing objects.

SCHEMA SWITCH and OWNER FROM are mutually exclusive on one statement. After a schema rename, dependent packages are invalidated and autobind on next execution. Autobind fails if the application still hard-codes the old schema—change the SQL and rebind. Find victims with SYSPACKDEP on BQUALIFIER in the old names.

1
2
3
4
SELECT DISTINCT DCOLLID, DNAME, DTYPE
FROM SYSIBM.SYSPACKDEP
WHERE BQUALIFIER IN ('OLDNAME')
ORDER BY DCOLLID, DNAME;

OWNER FROM … TO ROLE

OWNER FROM (owner-name) TO ROLE moves ownership from a user authorization ID to a role. You must run under a trusted context with a role; IBM also requires that a trusted context was created for INSTALL SYSADM before this form of CATMAINT. The current role becomes owner. Privileges on the object transfer from the original owner to the role except for plans and packages. Afterward the original owner has no remaining privileges on the object.

You can list multiple owner-names; duplicates are not allowed; names that own nothing are ignored; SYSIBM is not allowed. Role ownership is processed like other objects, except a role cannot own itself: if the trusted-context role is owned by owner-name, that role’s ownership is left unchanged.

VCAT SWITCH

VCAT SWITCH(catalog-name, new-catalog-name) changes the integrated catalog facility name stored for storage groups and for user-managed table spaces and indexes. It is similar in spirit to ALTER TABLESPACE … USING VCAT, but CATMAINT does it in bulk. You must still move the data to data sets cataloged in the new ICF catalog in a separate step—the utility does not copy VSAM clusters.

Choose a new-catalog-name that other Db2 subsystems sharing ICF catalogs will not collide with. Non-alphanumeric characters need quotes around each name. VCAT SWITCH does not change system indexes and table spaces in DSNDB01 or DSNDB06; those catalog names come from subsystem parameters. Repeat SWITCH for multiple pairs; do not repeat the same name.

UTILX BASIC, EXTENDED, and RESET

UTILX updates the catalog and OBD for DSNDB01.SYSUTILX (the directory space that tracks utilities):

• BASIC — initialize SYSUTILX and its indexes to basic 6-byte RBA format
• EXTENDED — initialize to extended 10-byte RBA format
• RESET — reinitialize SYSUTILX to empty

If the space is already in the requested BASIC/EXTENDED state, CATMAINT succeeds and changes nothing. If the state differs and the space is not empty, the job fails with DSNU777I. If it differs and the space is empty, Db2 resets it to the new state. Complete or terminate all utilities before BASIC or EXTENDED or the command fails with DSNU777I. After RESET, DISPLAY UTILITY and TERM UTILITY have no history: resolve utility-in-progress and restrictive states on objects yourself. IBM also documents RESET when SYSUTILX is so damaged that DISPLAY/TERM cannot run and LOGAPPLY recovery of SYSUTILX is not possible.

UNLDDN action-token is only for a PTF or IBM Support instruction. Do not invent tokens.

Concurrency, termination, and restart

While CATMAINT runs, many catalog and directory indexes are unavailable. Expect timeouts (DSNT318I, DSNT376I, DSNT501I) in other work that needs those indexes. In data sharing, members can stay up through a migrate, but catalog-heavy SQL still feels the outage of those indexes.

You can TERM UTILITY, but termination might leave indexes in REBUILD-pending. CATMAINT cannot be restarted: restart produces DSNU181I. Terminate and rerun from the beginning. Combined with non-rollback of completed LEVEL steps, that means your runbook is: take catalog/directory copies IBM requires for the migrate, run DSNTIJTC, if it fails read DSNU777I/776I/778I, repair, resubmit DSNTIJTC—not RECOVER to undo a partial catalog level.

Explain It Like I'm Five

The catalog is the library’s master notebook that lists every book. CATMAINT is the special pen IBM uses when the notebook needs new columns, when every sticker that says OLDNAME must say NEWNAME, or when the “who is running a photocopier right now” page (SYSUTILX) must be erased because it got wet. Ordinary kids (application DBAs) do not use that pen. You do not photocopy novels with it (that is COPY). You do not translate novels into another language with it (Unicode conversion is a different project). If the pen finishes three new notebook pages and then skips, those three pages stay—you do not rip them out by opening yesterday’s notebook software.

Exercises

1. Find DSNTIJTC in your SDSNINSTL (or equivalent) library and identify the CATMAINT statement it would run for your function level.
2. Write CATMAINT UPDATE LEVEL for a function level that your shop has not activated yet, and explain what DISPLAY GROUP must show first.
3. A schema rename is planned from PAY1 to PAYAPP. List object types that can block SCHEMA SWITCH and the SYSPACKDEP query you would run afterward.
4. Contrast UTILX EXTENDED with UTILX RESET. When is RESET the only remaining option?
5. Why is “we will just IPL with last month’s Db2 libraries if CATMAINT fails” a dangerous idea after DSNU777I has already reported a catalog-level change?