TERM commands in DB2 for z/OS

What -TERM UTILITY does

-TERM UTILITY (abbreviation -TER UTIL) terminates execution of a Db2 utility job step and releases all resources associated with that step. An active utility does not stop until it periodically checks whether TERM was issued. A stopped utility (already interrupted) has its remaining Db2 resources released when you TERM it.

Issue the command from a z/OS console, DSN session, DB2I COMMANDS or DB2 UTILITIES panels, an IMS or CICS terminal, or IFI. Message DSN9022I is normal completion.

Data sharing: active versus stopped

Scope is member or group depending on state:

• An active utility can be terminated only from the Db2 member on which it is running
• A stopped utility can be terminated from any active member of the data sharing group (implicit group scope)

DISPLAY UTILITY with MEMBER(member-name) helps you see which member owns the job before you TERM from the wrong prefix.

Authorization

You may TERM a utility if you are using the primary or a secondary authorization ID of the process that originally submitted the job, or if your privilege set includes one of:

• DBMAINT, DBCTRL, or DBADM (only when Db2 can verify you have authority on each object the utility accesses)
• SYSOPR
• System DBADM
• DATAACCESS
• SYSCTRL
• SYSADM

For utilities on objects in implicitly created databases, the database privilege may be held on that database or on DSNDB04. Ownership of the table spaces or index spaces is also sufficient when the command names those spaces. DIAGNOSE, REPORT, and STOSPACE can be terminated only by the original submitter or by SYSOPR, SYSCTRL, or SYSADM.

Database DSNDB06 holds the catalog spaces used to check authorization. If a utility is running against a catalog/directory space required for that check, you need installation SYSADM to terminate it.

Syntax and UID forms

You must specify one of:

• (utility-id) — the UID used when the job was created
• (partial-utility-id*) — every UID that begins with that string, including two-part IDs such as ABCD.EFGH when you specify ABCD*
• (*) — every utility job step known to Db2 for which you are authorized

Default UID from the EXEC of DSNUTILB is userid.jobname. Default from the DSNU CLIST is tso-userid.control-file-name. Always DISPLAY UTILITY first so you TERM the UID you think you are terminating—prefix wildcards are powerful and easy to over-use.

1
2
3
4
-DISPLAY UTILITY(*)
-TERM UTILITY(*)
-TERM UTILITY(SMITH*)
-TERM UTILITY(PAYREORG.STEP1)

You cannot restart after TERM

This is the sentence shops forget: a terminated utility job step cannot be restarted. RESTART(CURRENT) or RESTART(PHASE) applies to a utility that stopped (abend, cancel of the job after a controlled stop, or a condition the Utility Guide allows you to restart). After TERM, you resubmit as a new utility execution. Decide before you TERM whether you wanted restart or a true throw-away.

What TERM does to particular utilities

IBM documents special effects for several utilities. Where the Command Reference lists “none,” TERM still ends the job and releases utility resources; objects may already have been left in a state by the phase that was running.

After TERM, DISPLAY DATABASE for RECP, RBDP, CHKP, UTRO, and related statuses. COPY’s T SYSCOPY record is easy to miss: your next incremental COPY fails until you take a full image copy. UNLOAD’s output file is not a complete unload—delete it rather than feeding it to LOAD.

TERM UTILITY versus CANCEL THREAD versus STOP DATABASE

• TERM UTILITY — ends a DSNUTILB (or equivalent) utility by UID
• CANCEL THREAD — ends an application or allied thread; a utility is also a thread, but TERM is the supported way to release utility control blocks
• STOP DATABASE — drains claimers including utilities; STOP can wait on a utility’s drain locks. TERM the utility if it is the blocker
• STOP DB2 MODE(FORCE) — terminates utilities as part of bringing the member down; expect indoubt and pending states
• -ALTER UTILITY — changes options of a running REORG (for example LONGLOG); it does not terminate the job

Practical sequence for a stuck REORG: DISPLAY UTILITY (phase, UID, member), DISPLAY DATABASE CLAIMERS, attempt ALTER UTILITY if you only need to change drain behavior, TERM UTILITY if the job must die, DISPLAY DATABASE for pending, then a new REORG or RECOVER/REBUILD as the pending state requires.

Explain It Like I'm Five

A utility is a construction crew with a work order number (the UID) taped to the library door. TERM UTILITY is the manager tearing up that work order and sending the crew home. You cannot tell them “continue tomorrow from page 47”—you have to issue a brand-new work order. Sometimes they leave wet paint (RECP/RBDP) that another crew must finish. DISPLAY UTILITY is reading the work order number before you tear it up so you do not send the wrong crew home.

Exercises

1. DISPLAY UTILITY shows UID PAYNIGHT.REORG on member DB2B while you are on DB2A. Can you TERM it if it is still active? What if it is already stopped?
2. Write the command to terminate every utility whose UID starts with PAYNIGHT.
3. After TERM of COPY, your next COPY incremental fails. Which catalog table and record type should you look for, and what copy type restores a normal incremental cycle?
4. A colleague wants to RESTART(PHASE) after TERM UTILITY. Explain why that will not work and what they should do instead.
5. Which three utilities can a DBADM who did not submit the job still be unable to TERM, and which authorities can?