-TERM UTILITY (Db2)

The Db2 command TERM UTILITY terminates execution of a Db2 utility job step and releases all resources associated with the step.

When executing, a utility does not terminate until it checks to see that the TERM UTILITY command was issued. Active utilities perform this check periodically. If the utility is stopped, all its resources are released by the TERM UTILITY command. An active utility can be terminated only from the Db2 on which it is running. A stopped utility can be terminated from any active member of the data sharing group.

Abbreviation: -TER UTIL

Environment

This command can be issued from a z/OS® console, a DSN session, DB2I panels DB2 COMMANDS and Db2 UTILITIES, an IMS or CICS® terminal, or a program using the instrumentation facility interface (IFI).

Data sharing scope: Group or member

The utility is implicitly of group scope when the utility is stopped.

Authorization

To execute this command, you must use the primary or some secondary authorization ID of the process that originally submitted the utility job, or you must use a privilege set of the process that includes one of the following authorities:

DBMAINT authority
DBCTRL authority
DBADM authority
SYSOPR authority
System DBADM authority
DATAACCESS authority
SYSCTRL authority
SYSADM authority

For utilities that run on objects in implicitly created databases, the database privilege or authority can be held on the implicitly created database or on DSNDB04. Ownership of the table spaces or index spaces on which the utility operates is also sufficient to terminate the utility. This means that the owner can display information about an implicitly created table space or index space if the command explicitly specifies that table space or index space name.

The utilities DIAGNOSE, REPORT, and STOSPACE can be terminated only by the job submitter or by a holder of SYSOPR, SYSCTRL, or SYSADM authority.

Db2 commands that are issued from a logged-on z/OS console or TSO SDSF can be checked by Db2 authorization using primary and secondary authorization IDs. Start of change A logged-on z/OS user ID must be defined in RACF or a similar security server. End of change

For users with DBMAINT, DBCTRL, or DBADM authority, the command takes effect only when Db2 can determine that the user has sufficient authority over each object that the utility job accesses.

Database DSNDB06 contains the table spaces and index spaces that are required to check authorization. If a table or index space that is required for authorization checking is affected by a utility that you need to terminate, installation SYSADM authority is required to terminate that utility.

Syntax

Option descriptions

One of the following parameters must be specified.

( utility-id )

Is the utility identifier, or the UID parameter used when creating the utility job step.

If utility-id was created by the DSNU CLIST by default, it has the form tso-userid.control-file-name.

If utility-id was created by default by the EXEC statement invoking DSNUTILB, then the token has the form userid.jobname.

If utility-id contains lowercase letters or special characters, it must be enclosed in single quotation marks (').

( partial-utility-id* )

Terminates every utility job that begins with partial-utility-id . For example, TERM UTILITY(ABCD*) terminates every utility job step whose utility identifier begins with the letters ABCD. If you have a two-part utility ID, such as ABCD.EFGH, TERM UTILITY(ABCD*) also terminates that utility.

( * )

Terminates every utility job step known to Db2 for which you are authorized.

Usage notes

Restarting utilities

A terminated utility job step cannot be restarted. You must resubmit the step as a new utility job.

What happens to particular utilities

In some cases, terminating a utility job can leave work in an undesirable state, requiring special processing before the job can be resubmitted. The following list describes the effects of TERM UTILITY on jobs for each of the utilities:

CATMAINT: Places indexes in REBUILD-pending status.
CHECK DATA: Table spaces remain in CHECK-pending status.
CHECK INDEX: None.
CHECK LOB: Places LOB table spaces and indexes in the utility read-only (UTRO) state.
COPY: Inserts T record in SYSIBM.SYSCOPY. When you run COPY, COPY does not allow an incremental image copy if the T record exists.
DIAGNOSE: None.
LOAD: Termination of LOAD
MERGECOPY: None.
MODIFY RECOVERY: If MODIFY RECOVERY, in the DELETEDS phase, detects that the TERM command has been issued, MODIFY RECOVERY stops deleting image copy data sets and proceeds to the UTILTERM phase. If the TERM command was issued on a MODIFY RECOVERY utility that abended in the DELETEDS phase, the TERM command terminates the MODIFY RECOVERY utility and the image copy data sets are not be deleted.
MODIFY STATISTICS: None.
QUIESCE: None.
REBUILD INDEX: Places the object that is being rebuilt in REBUILD-pending status.
RECOVER: Places the object that is being recovered in RECOVER-pending status.
REORG INDEX: Termination of REORG INDEX
REORG TABLESPACE: Termination of REORG TABLESPACE
REPAIR: None.
REPORT: None.
RUNSTATS: None.
STOSPACE: None.
UNLOAD: The output data set remains incomplete until you restart the utility job or delete the data set.

Trace information for commands issued with group scope

If this command is issued with options that specify group scope in a Db2 data sharing member, it also runs on all other active members. IFICID 090 trace records for other group members can show that the same command was issued by the SYSOPR authorization ID from the 016.TLPKN5F correlation ID, in addition to the trace records from the member where the original command was issued. See Command scope in Db2 data sharing.

Examples

Example 1: Terminate all utility jobs for which you are authorized.

-TERM UTILITY (*)

Example 2: Terminate all utility jobs whose utility ID begins with SMITH.

-TERM UTILITY
  (SMITH*)