-ALTER UTILITY command (Db2)

The -ALTER UTILITY command changes the values of certain parameters of an execution of the REORG utility that uses SHRLEVEL REFERENCE or CHANGE and the REBUILD utility that uses SHRLEVEL CHANGE.

Specifically, this command changes the values of DEADLINE, MAXRO, LONGLOG, and DELAY.

REBUILD and REORG can be altered only from the Db2 subsystem on which ALTER UTILITY is running.

ALTER UTILITY applies to a single utility control statement. It has no effect on other utility control statements that are later in the same job step. If a LISTDEF control statement is being processed, ALTER UTILITY applies only to the subset of list items that are currently being processed.

Abbreviation: -ALT UTIL

Environment for -ALTER UTILITY

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

Data sharing scope : Member

Authorization for -ALTER UTILITY

To execute this command, you must use the primary or some secondary authorization ID of the process that originally submitted the utility job. Alternatively, you must use a privilege set of the process that includes one of the following authorities:
  • DATAACCESS authority
  • DBCTRL authority
  • DBADM authority
  • System DBADM authority
  • DATAACCESS authority
  • SYSOPR authority
  • SYSCTRL authority
  • 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 changeA 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 a user has sufficient authority over each object that the utility job accesses.

Syntax for -ALTER UTILITY

Read syntax diagramSkip visual syntax diagramALTER UTILITY ( utility-id) REBUILDREORG DEADLINE(NONEtimestamp)MAXRO(integerDEFER)LONGLOG(CONTINUETERMDRAIN)DELAY( integer)

Option descriptions for -ALTER UTILITY

(utility-id)
Is the utility identifier, or the UID parameter, used when creating the utility job step.

This job must execute REBUILD SHRLEVEL CHANGE, REORG with SHRLEVEL CHANGE, or SHRLEVEL REFERENCE.

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 that executed DSNUTILB, it has the form userid.jobname.

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

REBUILD
Specifies that a REBUILD SHRLEVEL CHANGE utility is being altered.
REORG
Specifies that a REORG SHRLEVEL REFERENCE or REORG SHRLEVEL CHANGE utility is being altered.
DEADLINE
Specifies the deadline by which the user wants the switch phase of reorganization to start.

Only valid when altering a REORG SHRLEVEL REFERENCE or REORG SHRLEVEL CHANGE utility.

If Db2 estimates that the switch phase will not start by the deadline, Db2 terminates reorganization. The default is the value of DEADLINE that is currently in effect.

The pre-switch processing might continue until after the deadline.
( NONE )
Specifies that there is no deadline for the read-only iteration of log processing.
( timestamp )
Specifies the deadline by which the user wants the switch phase to start processing. This deadline must not have been reached when ALTER UTILITY executes.
MAXRO
Specifies the maximum amount of time that is tolerated for the last iteration of log processing during reorganization. During that iteration, applications have read-only access.

The actual execution time of the last iteration can exceed the value specified for MAXRO.

The default is the value of MAXRO that is currently in effect.

( integer )
Specifies the number of seconds.
( DEFER )
Specifies that the log phase is deferred indefinitely.
LONGLOG
Specifies the action that Db2 performs (after sending the LONGLOG message to the console) if the number of log records that are processed during the next iteration is not sufficiently lower than the number of log records that were processed during the previous iterations. The default is the value of LONGLOG that is currently in effect.
( CONTINUE )
Specifies that Db2 continues the log phase.
( TERM )
Specifies that Db2 terminates the utility after the delay.
( DRAIN )
Specifies that Db2 drain the write claim class after the delay (if specified). The number of log records, and thus the estimated time, for a future iteration of log processing will be 0.
DELAY ( integer )
Specifies a lower bound for the interval between the time when the utility sends the LONGLOG message to the console and the time when the utility performs the action specified by the LONGLOG parameter.

integer is the delay in seconds. The value must be nonnegative. The default is the value of DELAY that is currently in effect.

Examples for -ALTER UTILITY

Example: Alter several options for an execution of the REORG utility
The following commands alters the execution of the REORG utility for the utility job step whose utility identifier is REORGEMP: 
-ALTER UTILITY (REORGEMP) REORG MAXRO(240) LONGLOG(DRAIN)
The following list explains what each option does in the preceding example:
  • MAXRO(240) changes the maximum tolerable time for the last iteration of log processing to 240 seconds (4 minutes).
  • LONGLOG(DRAIN) specifies that Db2 drain the write claim class (if reading of the log during REORG is not catching up to the speed at which the application is writing the log).
  • DELAY is not specified so this example does not change the existing delay between sending the LONGLOG message to the console and performing the action specified by LONGLOG.
  • DEADLINE is not specified so this example does not change the deadline (if any) that was defined in the last iteration of log processing.