IBM DB2 Query Patroller Administration Guide

Control Command (iwm_cmd)

The control command (iwm_cmd) enables the system administrator to monitor and control DB2 Query Patroller from the operating system shell. It also enables end users to monitor their jobs.

Specifically, the system administrator and end user can use iwm_cmd when:

• Monitoring jobs
• Controlling jobs
• Monitoring and controlling nodes
• Listing and controlling data sources
• Listing and controlling system parameters

Common iwm_cmd Parameters

Each function of iwm_cmd has a different syntax. Parameters that are common to all functions are described in the following table. Following this are syntax diagrams and parameter descriptions for each iwm_cmd function.

Table 2. iwm_cmd Common Parameter Descriptions

Parameter	Description
-u user_id	User identification. This parameter provides either the DB2 Query Patroller user ID for the user whose jobs will be monitored or controlled, or the DB2 Query Patroller system administrator's ID (iwm). By default, DB2 Query Patroller uses the current system user ID.
-p password	User password. If the user provides the -u parameter and the current user is not the DB2 Query Patroller system administrator, the password parameter must also be specified. The password must be the user's database password.

Monitoring Jobs

iwm_cmd allows users to monitor their jobs and the system administrator to monitor the status of all incomplete jobs. DB2 Query Patroller provides an interface to make it easy for programs invoking iwm_cmd to process information about each job. If a user invokes iwm_cmd without any parameters, all jobs for that user display.

Syntax:

>>-iwm_cmd----+------------------------------+------------------>
              '--u--user--+---------------+--'
                          '--p--password--'
 
>-----+-------------+---+---------------+---+---------+--------><
      +--s--status--+   '--x--max_jobs--'   '-fields--'
      +--S--status--+
      '--j--job_id--'
 

Table 3. iwm_cmd Parameters for Monitoring Jobs

Parameter	Description
-s status	User job status. This parameter specifies that jobs belonging to the user with the given status should display. The status must be one of the following: Q - Queued S - Scheduled H - Held R - Running U - Unfinished D - Done A - Aborted C - Canceled F - Finished Only the first letter is significant. It can be in either uppercase or lowercase. The unfinished status includes any queued, scheduled, held, or running jobs. The finished status includes any done, aborted, or canceled jobs.
-S status	Unfinished job status. This parameter specifies that all DB2 Query Patroller jobs with the given status should display. The status must be one of the following: Q - Queued S - Scheduled H - Held R - Running U - Unfinished Only the first letter is significant. It can be in either uppercase or lowercase. The Unfinished status includes queued, scheduled, held, or running jobs. This parameter may only be used by the DB2 Query Patroller system administrator.
-j job_id	Job identifier. This parameter specifies that only the requested job should display. If someone other than the DB2 Query Patroller system administrator uses this parameter, the user must be the owner of the job.
-x max_jobs	Maximum job count. This parameter specifies the maximum number of jobs to be listed. If this parameter is not specified, a maximum of 100 jobs display. If max_jobs contains the value 0, no limit is applied.
fields	Job fields. There are two job fields: Job and Status. You can enter these fields together or separately. This parameter is case sensitive. If you provide a field parameter, the jobs do not display in an easy-to-read format. Instead, the values of the fields are written to STDOUT in a format that other programs can easily process. A horizontal tab character separates each field from the next. Newline characters separate each job's fields from the next.

Controlling Jobs

iwm_cmd allows users to cancel their jobs. It also allows the system administrator to cancel or release a job.

Syntax:

>>-iwm_cmd----+------------------------------+------------------>
              '--u--user--+---------------+--'
                          '--p--password--'
 
>-----+--c--job_id------+--------------------------------------><
      +--r--+-job_id--+-+
      |     '-user_id-' |
      '--R--------------'
 

Table 4. iwm_cmd Parameters for Controlling Jobs

Parameter	Description
-c job_id	Cancel a job. This parameter specifies that the given job should be canceled. A job need not have finished in order for it to be canceled. If the user is not the DB2 Query Patroller system administrator, the job must be owned by the user.
-r job_id	Release a job. This parameter specifies that the given job should be released. The job must currently have a status of held. This parameter may only be used by the DB2 Query Patroller system administrator.
-r user_id	Release all jobs for a user. This parameter specifies that all jobs owned by a user with a current status of held should be released. This parameter may only be used by the DB2 Query Patroller system administrator.
-R	Release all jobs. This parameter specifies that all held jobs should be released. This parameter may only be used by the DB2 Query Patroller system administrator.

Monitoring and Controlling Nodes

iwm_cmd enables the DB2 Query Patroller system administrator to monitor and control the status and activity of agent nodes.

Syntax:

>>-iwm_cmd----+------------------------------+------------------>
              '--u--user--+---------------+--'
                          '--p--password--'
 
>-----+--n--node_id--+---+-------------+-----------------------><
      '--N-----------'   '--s--status--'
 

Table 5. iwm_cmd Parameters for Monitoring and Controlling Nodes

Parameter	Description
-n node_id	Node identifier. This parameter specifies that the status of the given node should be displayed or be altered.
-N	All nodes. This parameter specifies that the status of all agent nodes should be displayed or be altered.
-s status	Node status. This parameter specifies that the status of the node(s) should be altered and provides the new requested status. The status must be from the following list. Only the first letter is significant. It can be either uppercase or lowercase. Active. The server component can schedule new jobs to run on the node. Quiesced. Jobs already scheduled to run on the node continue to run, but no more will be scheduled. Inactive. Jobs already scheduled to run on the node continue to run, but no more will be scheduled to run on the node. After all previously scheduled jobs complete, the node manager process running on the node will terminate. Force. The node manager process running on the node will terminate immediately without waiting for jobs already running on the node to complete. Note: If iwm_cmd is used to terminate node manager processes, the server or agent component must be stopped and restarted in order to turn the node manager processes on again.

Listing and Controlling Data Sources

iwm_cmd enables the DB2 Query Patroller system administrator to list and change the data source parameters for one or all data sources.

Syntax:

>>-iwm_cmd----+---------------------------------+--------------->
              '--u--user_id--+---------------+--'
                             '--p--password--'
 
>-----+-| data_source options |-+------------------------------><
      '--D----------------------'
 
data_source options
 
|----d--data_source----+------------------+--------------------->
                       '-Status=--status--'
 
>-----+-----------------------+---+------------------------+---->
      '-JobCostLimit=--value--'   '-JobCountLimit=--value--'
 
>-----+-----------------------+---+------------------------+----|
      '-NodeCpuLimit=--value--'   '-NodeDiskLimit=--value--'
 

Table 6. iwm_cmd Parameters for Listing and Controlling Data Sources

Parameter	Description
-d data_source	Data source name. This parameter specifies the name of the data source to be listed or altered. In the current release, the only valid value is IWM.
Status=status	Data source status. This parameter specifies that the status of the data source should be altered and provides the new status. The status must be one of the following: Active. Jobs will be scheduled normally. Hold. All incoming jobs will be held, but any jobs already in the queue will be allowed to proceed. Inactive. All requests to submit a new job will be rejected. ReleaseAll. All jobs in the data source with a status of held will be released and the data source status will be set to active. HoldAll. All jobs in the data source that are not yet running will be held. The status of the data source will be set to hold.
JobCostLimt=value	Alter job cost limit. This parameter specifies that the limit of the total estimated cost of running jobs against this data source should be altered. The new value must be at least zero.
JobCountLimt=value	Alter job count limit. This parameter specifies that the limit of the total number of jobs running against this data source should be altered. The new value must be at least zero. If zero, scheduling of new jobs is disabled.
NodeCpuLimt=value	Alter node CPU limit. This parameter specifies that the per-node CPU utilization maximum for scheduling new jobs against this data source should be altered. The new value must be between 0 and 100. If CPU utilization is not being collected, the value of this parameter is ignored.
NodeDiskLimit=value	Alter node disk space limit. This parameter specifies that the per-node disk space minimum for scheduling new jobs against this data source should be altered. The value is in bytes and must be at least zero. If disk space utilization is not being collected, the value of this parameter is ignored.
-D	List data sources. This parameter specifies that summary information on all data sources should display.

Listing and Controlling System Parameters

iwm_cmd enables the DB2 Query Patroller system administrator to list and change system parameters.

Syntax:

>>-iwm_cmd----+------------------------------+----P------------->
              '--u--user--+---------------+--'
                          '--p--password--'
 
>-----+-----------------------+---+------------------------+---->
      '-JobCostLimit=--value--'   '-JobCountLimit=--value--'
 
>-----+-----------------------+---+---------------------------+->
      '-JobPurgeDays=--value--'   '-ResultsPurgeDays=--value--'
 
>-----+----------------------------+---------------------------><
      '-AccountingStatus=--status--'
 

Table 7. iwm_cmd Parameters for Listing and Controlling System Parameters

Parameter	Description
-P	System parameters. This parameter specifies that the values of the DB2 Query Patroller system parameters should be displayed or altered.
JobCostLimit=value	Alter job cost limit. This parameter specifies that the limit of the total estimated cost of running jobs should be altered. The new value must be at least zero.
JobCountLimit=value	Alter job count limit. This parameter specifies that the limit of the total number of running jobs should be altered. The new value must be at least zero. If zero, scheduling of new jobs is disabled.
JobPurgeDays=value	Alter job information purging. This parameter specifies that the purge age for DB2 Query Patroller jobs should be altered. The new value must be between 0 and 999. If zero, automatic purging of job information is disabled. If not zero, the value of JobPurgeDays must be equal to or greater than the value of ResultsPurgeDays.
ResultsPurgeDays=value	Alter result table purging. This parameter specifies that the purge age for result tables should be altered. The new value must be between 0 and 999. If zero, automatic purging of result tables information is disabled. If the value of JobPurgeDays does not equal zero, it must be equal to or greater than the value of ResultsPurgeDays.
AccountingStatus=status	Alter job accounting status. This parameter specifies that the status of the DB2 Query Patroller job accounting feature should be altered. The status must be either active or inactive. If Active, DB2 Query Patroller inserts a row into the job accounting table as each job completes, aborts, or is canceled.