Use this template when documenting a single Db2 for z/OS utility (COPY, REORG, RUNSTATS, LOAD, RECOVER, and the rest). A strong utility page tells an operator what the utility does, when to choose it, when to refuse it, how to code SYSIN, which options matter, who may run it, what output to expect, and how failures present. Curriculum sub-bullets under each utility are sections for that utility’s page.
Create one page per utility (or per major utility mode when IBM documents sharply different behaviors). Fill every heading below with release-accurate content from the Utility Guide and Reference and your site standards. Include at least one complete SYSIN example and note LISTDEF/TEMPLATE patterns when they are the modern default.
Separate “what IBM allows” from “what our shop runs.” Document SHRLEVEL, drain, logging, and restart implications carefully—those are where production incidents hide. Link JCL pattern pages instead of duplicating every DD statement for every utility unless a DD is unique and dangerous to omit.
Start with a plain-language purpose statement in two or three sentences. Name the objects the utility accepts (table space, index, list, database) and whether it changes data, only statistics, only recovery history, or only diagnostic output. Mention catalog tables it reads or updates when that is central (SYSCOPY for COPY, SYSINDEXES statistics for RUNSTATS, and so on).
Describe the main phases at a teaching level (UTILINIT, unload/reload, build, log apply, and similar) so readers can interpret restart messages. Do not paste the entire phase table unless phase-specific restart rules are essential.
Give concrete triggers: after heavy insert activity, before a migration window, when SYSLGRNX growth demands cleanup, when REORG-pending appears, when recovering to current after media failure. Tie each trigger to an observable symptom or catalog condition.
Mention complementary utilities in the workflow (COPY after REORG, RUNSTATS after LOAD, CHECK DATA after PITR). Operators should leave the page knowing where this utility sits in a standard maintenance chain.
Document anti-uses explicitly. Examples: using RECOVER when you only need a logical undo available through application restore; running MODIFY RECOVERY until REPORT RECOVERY proves the chain; using LOAD REPLACE on a table that still needs its existing data; choosing SHRLEVEL NONE during peak when SHRLEVEL CHANGE or REFERENCE is required by availability targets.
Call out object states that block the utility (RECOVER-pending, utility-in-progress, advisory states that need a different first step). “When not to use it” prevents copy-paste JCL disasters.
Show the control-statement syntax with required keywords first. If LISTDEF and TEMPLATE are recommended, show both a classic single-object form and a list form. Keep hex and date sample values realistic but clearly fake.
Note whether the utility is invoked under DSNUTILB, as an online utility, or both, and whether it belongs to the Utilities Suite licensing boundary when relevant to readers evaluating options.
123456789// TEMPLATE pattern for teaching pages TEMPLATE COPYDS DSN &DB..&TS..COPY.&UQ. DISP (NEW,CATLG,CATLG) LISTDEF MAINTLIST INCLUDE TABLESPACE PAYDB.* COPY LIST MAINTLIST COPYDDN (COPYDS) SHRLEVEL CHANGE
Explain the options that change outcomes: SHRLEVEL, SCOPE, PARALLEL, LOG YES/NO, COPYDDN/RECOVERYDDN, SORTDEVT, STATISTICS, DISCARD, and utility-specific switches. For each option, state the default, the reason to override it, and a risk if misused.
When an option has many values, list each value with a one-line meaning. Do not hide mutually exclusive options—call the conflict out beside the values. Link deeper tuning pages when an option family is large (for example REORG drain and switch processing).
Document the privilege set IBM requires (for example IMAGCOPY, REORG, LOAD, RECOVERDB, DBADM, SYSCTRL, SYSADM, installation SYSOPR for catalog spaces). Note database-level versus system-level authority and any special case for DSNDB01 / DSNDB06.
Remind readers that z/OS data set profiles still gate image-copy and work data sets. A Db2 privilege without RACF access to COPYDDN data sets still fails. Mention audit expectations when utilities touch regulated data.
Describe SYSPRINT highlights, return codes (0, 4, 8, 12) and what RC 4 usually means for this utility, catalog side effects, and SMF or IFCID footprints if operators use them. Show how to confirm success with DISPLAY UTILITY, DISPLAY DATABASE, and a catalog query when applicable.
Include a short “evidence pack” list for change tickets: job name, RC, object list, SHRLEVEL, elapsed time, and follow-up utilities required.
List frequent failures: authority, data set allocation, sort capacity, claimers not drained, incompatible object state, wrong DSNUM, template variable mistakes, and restart misuse. For each, give the symptom and the first corrective action.
Document termination versus restart guidance at a high level and link the troubleshooting-utilities page for generic patterns. If this utility has a notorious non-restartable window, warn about it in strong terms.
A utility reference page is an instruction card for a big machine in the computer room. It says what the machine is for, when to turn it on, when to leave it alone, which buttons matter, who is allowed to press them, what a successful run looks like, and what weird noises mean when something goes wrong.
1. Why document “when not to use it”?
2. What should key options explain besides the value name?
3. Permissions for utilities include: