Use this template when documenting a Db2 command such as -DISPLAY DATABASE, -START DB2, -STOP DATABASE, -ARCHIVE LOG, or -ACTIVATE FUNCTION LEVEL. Command pages should make environment, authority, syntax, options, output interpretation, and safe examples obvious. For complex commands, the curriculum may split overview, syntax, major options, output, and troubleshooting into linked pages—this template is the shared skeleton for each.
Create a page per command, or per major option group when a single page would be unreadable (DISPLAY DATABASE is the classic example). Keep console punctuation clear: document the subsystem recognition character and show examples with a leading hyphen as operators see them on the z/OS console, and note TSO DSN and DB2I equivalents.
Always state group versus member scope in data sharing. A command that looks local can affect the whole group. Link object-state and troubleshooting pages instead of redefining every status flag on every command page.
Describe where the command can be issued: z/OS console, SDSF, TSO DSN session, DB2I COMMANDS panel, IFI programs, CICS or IMS terminals when applicable. Note any environment that is read-only or disallowed for destructive forms.
Explain subsystem selection: how the command routes to the correct Db2 member, how data sharing group scope behaves, and whether the command can be issued while Db2 is partially up. If the command requires a specific Db2 address space to be active, say so.
List the Db2 privileges or installation authorities required. Separate display-only authority from start/stop/change authority. Call out installation SYSOPR versus SYSADM when IBM draws that line for operational commands.
Mention RACF consoles and OPERCMDS profiles when site security gates who may enter Db2 commands from a console. A user can have Db2 DISPLAY privilege yet still be blocked by console command classes—document both layers at a high level.
Provide a teaching syntax block with required keywords and the most common optional keywords. For commands with many operands, show the core syntax here and dedicate following sections or child pages to each major operand (DB, SPACENAM, RESTRICT, CLAIMERS, DETAIL, GROUP).
Document abbreviation rules IBM allows, positional versus keyword forms, and limits on list length or wildcards. Note differences between subsystem commands and DSN subcommands when both exist.
1234-DISPLAY DATABASE(PAYDB) SPACENAM(*) RESTRICT -DISPLAY DATABASE(PAYDB) SPACENAM(PAYTS) CLAIMERS -START DATABASE(PAYDB) SPACENAM(PAYTS) ACCESS(RW) -STOP DATABASE(PAYDB) SPACENAM(PAYTS)
Explain each important option with meaning, default, and when to use it. For DISPLAY-family commands, options often filter output (RESTRICT, USE, CLAIMERS, LOCKS, OVERVIEW). For START/STOP, options change access mode and drain behavior.
When an option has multiple values, list every value and what it does. Ambiguous values (ACCESS(UT), ACCESS(RO), ACCESS(RW)) deserve explicit availability and utility-impact notes. Flag options that are group-wide or irreversible enough to need a change ticket.
Teach readers how to read the response: message IDs, column meanings in multi-line displays, status abbreviations, and which lines indicate a problem versus normal activity. Include a sample of realistic output with annotations in surrounding paragraphs (not as unexplained walls of text).
Document common message numbers returned on success and failure. Explain how to correlate command output with DISPLAY UTILITY, DISPLAY THREAD, or DISPLAY GROUP when the command is part of an operational checklist.
Give three examples: the simplest safe display or inquiry, a common operational change, and a data-sharing-aware variant. State the preconditions (who drained claimers, which window is open) for any command that changes access.
Include at least one negative example: a command that is syntactically valid but operationally wrong (stopping the wrong space, starting RW while RECP remains, activating a function level without TEST). Explain what goes wrong so copy-paste is less likely.
123456789/* Inquiry first */ -DISPLAY DATABASE(PAYDB) SPACENAM(PAYTS) CLAIMERS /* Change only after claimers are clear and ticket approved */ -STOP DATABASE(PAYDB) SPACENAM(PAYTS) -DISPLAY DATABASE(PAYDB) SPACENAM(PAYTS) /* Data sharing: confirm group impact intentionally */ -DISPLAY GROUP DETAIL
When a command is huge, use an overview page plus child pages for syntax, each major option, output interpretation, and troubleshooting. Every child page should still state environment and authority briefly or link upward, so deep links remain safe entry points.
Keep option pages consistent: meaning, values, sample command, sample output snippet, failure modes. That consistency is what makes the granular command layer searchable and trainable.
A Db2 command page is like a labeled remote control card. It tells you which TV you are pointing at (environment), who is allowed to hold the remote (authority), which buttons exist (syntax and options), what the screen shows when it worked (output), and a few practice presses (examples). Big remotes get one card per button group.
1. Why document environment on a command page?
2. What should option value lists include?
3. When should a command be split across pages?