IBM DB2 Query Patroller Administration Guide

Submit Command (iwm_submit)

The submit command (iwm_submit) enables users to submit jobs to DB2 Query Patroller. You can use iwm_submit to submit SQL commands and system commands.

The following diagram provides the syntax for the iwm_submit command:

>>-iwm_submit----+---------------------------------+------------>
                 '--u--user_id--+---------------+--'
                                '--p--password--'
 
>-----+---------------+---+--F--sql_stmt_file-----+------------->
      '--c--max_cost--'   +--S--"sql_smt"---------+
                          '--E--"system_command"--'
 
>-----+------------+---+------------+--------------------------->
      '--m--+-Y-+--'   '--C--+-Y-+--'
            '-N-'            '-N-'
 
>-----+----------------------------+---+------------------+----->
      '--t--sched_after_date_time--'   '--d--data_source--'
 
>-----+-------------------------+---+-------------------------+->
      '--r--result_destination--'   '--e--elapsed_time_limit--'
 
>-----+----------------+---+-------------------+---------------->
      '--l--row_limit--'   '--L--+-Abort----+--'
                                 '-Truncate-'
 
>-----+-----------------+---+-----+----------------------------->
      '--i--+-Low----+--'   '--q--'
            +-Normal-+
            '-High---'
 
>-----+-------------------------+------------------------------><
      '--j--predecessor_job_id--'

Note: When executing a SELECT statement against a lowercase table or column name using iwm_submit, the SELECT statement must be defined in an SQL statement file (sql_stmt_file) and submitted using the -F parameter. See the following table for more information on the -F parameter and SQL statement files.

Table 1. iwm_submit Parameter Descriptions

Parameter Description
-u user_id
User identification. This parameter enables the submitting user to specify a different owner for the job. This gives the DB2 Query Patroller system administrator the ability to submit queries or jobs on behalf of end users. The user ID must be a valid system and database ID, and a registered DB2 Query Patroller user. The command iwm_submit executes under the submitting user's environment. The user ID must conform to the system user identification syntax.
The job owner defaults to the submitting user.
-p password User password. If you provide the -u parameter and the submitting user is neither root nor the DB2 Query Patroller system administrator, this password parameter must also be specified. The password must be the user's database password.
-c max_cost
Cost threshold. This option enables the user to lower the cost threshold from what is defined in the DB2 Query Patroller user profile. Only root and the DB2 Query Patroller system administrator can increase the cost threshold with this option. The cost threshold must be a numeric value.
By default, DB2 Query Patroller uses the cost threshold defined in the DB2 Query Patroller database.
-F sql_stmt_file Specifies the name and path of a file that contains a single SQL statement. The sql_stmt_file must be a valid file path name. The file contents are immediately placed in the DB2 Query Patroller database.
-S "sql_stmt" Specifies a single SQL command enclosed in quotes. The SQL statement is immediately placed in the DB2 Query Patroller database.
-E "system_command" Specifies an entire system command including any optional arguments. The command is executed from the user's home directory, and its source directory must be available in the search path.
-m {Y | N}
Mail Notification. This parameter specifies whether or not the user should be notified through e-mail when the job completes or receives a hold status.
By default, the user receives notification upon completion of the submitted job.

-C {Y | N}
Cost analysis override. If the user's DB2 Query Patroller profile allows queries to be submitted without cost analysis, this parameter determines whether the cost analysis should be performed. The option must be either Y or N. Y directs iwm_submit to perform cost analysis; N indicates no cost analysis.
By default, DB2 Query Patroller performs cost analysis on SQL queries. DB2 Query Patroller ignores this option for system commands.
-t sched_after_date_time Schedule after date/time. This parameter specifies the date and time after which the job will run. The parameter default is the present date and time.
-d data_source Data source. Specifies the data source to run the job on. The only supported data source is IWM. This is the default value.
-r result_destination Result Destination. This parameter specifies the name of an alternate destination where results are sent instead of being written to a table in the database.
-e elapsed_time_limit Elapsed time limit. This option enables the user to set a limit for the elapsed time the job will be permitted to run. If the time limit is exceeded, DB2 Query Patroller aborts the job. The time limit value is in seconds. By default, DB2 Query Patroller will not impose an elapsed time limit on the job.
-l row_limit Result row limit. This option enables the user to set a limit for the number of rows returned by an SQL SELECT statement. If the row limit is exceeded, the action taken by DB2 Query Patroller depends on the setting of the -L parameter. By default, DB2 Query Patroller will not impose a result row limit.
-L {Abort | Truncate} Result row limit action. This option enables the user to specify the action taken by DB2 Query Patroller should the job return more rows than the result row limit. If it is not specified or set to Abort, DB2 Query Patroller aborts the job. Otherwise, if it is set to Truncate, DB2 Query Patroller truncates the result table at the row limit.
-i {Low | Normal | High}
User Priority. This parameter enables the user to select the priority of the job. The priority value can be Low, Normal, or High. Only the first letter is significant. These values may also be specified as 0, 1, or 2. The user's DB2 Query Patroller profile defines the actual priority levels that correspond to these values.
By default, DB2 Query Patroller assigns the user's normal priority to the job.
-q Quiet mode. This parameter directs DB2 Query Patroller to print only the job number upon successful job submission. This may be useful if the iwm_submit command is used from within a shell script.
-j predecessor_job_id Predecessor job number. This parameter specifies a job number of a previously submitted DB2 Query Patroller job. The new job cannot be scheduled until the predecessor job completes.

Parameter	Description
-u `user_id`	User identification. This parameter enables the submitting user to specify a different owner for the job. This gives the DB2 Query Patroller system administrator the ability to submit queries or jobs on behalf of end users. The user ID must be a valid system and database ID, and a registered DB2 Query Patroller user. The command iwm_submit executes under the submitting user's environment. The user ID must conform to the system user identification syntax. The job owner defaults to the submitting user.
-p `password`	User password. If you provide the -u parameter and the submitting user is neither root nor the DB2 Query Patroller system administrator, this password parameter must also be specified. The password must be the user's database password.
-c `max_cost`	Cost threshold. This option enables the user to lower the cost threshold from what is defined in the DB2 Query Patroller user profile. Only root and the DB2 Query Patroller system administrator can increase the cost threshold with this option. The cost threshold must be a numeric value. By default, DB2 Query Patroller uses the cost threshold defined in the DB2 Query Patroller database.
-F `sql_stmt_file`	Specifies the name and path of a file that contains a single SQL statement. The sql_stmt_file must be a valid file path name. The file contents are immediately placed in the DB2 Query Patroller database.
-S "`sql_stmt`"	Specifies a single SQL command enclosed in quotes. The SQL statement is immediately placed in the DB2 Query Patroller database.
-E "`system_command`"	Specifies an entire system command including any optional arguments. The command is executed from the user's home directory, and its source directory must be available in the search path.
-m {Y \| N}	Mail Notification. This parameter specifies whether or not the user should be notified through e-mail when the job completes or receives a hold status. By default, the user receives notification upon completion of the submitted job.
-C {Y \| N}	Cost analysis override. If the user's DB2 Query Patroller profile allows queries to be submitted without cost analysis, this parameter determines whether the cost analysis should be performed. The option must be either `Y` or `N`. `Y` directs iwm_submit to perform cost analysis; `N` indicates no cost analysis. By default, DB2 Query Patroller performs cost analysis on SQL queries. DB2 Query Patroller ignores this option for system commands.
-t `sched_after_date_time`	Schedule after date/time. This parameter specifies the date and time after which the job will run. The parameter default is the present date and time.
-d `data_source`	Data source. Specifies the data source to run the job on. The only supported data source is IWM. This is the default value.
-r `result_destination`	Result Destination. This parameter specifies the name of an alternate destination where results are sent instead of being written to a table in the database.
-e `elapsed_time_limit`	Elapsed time limit. This option enables the user to set a limit for the elapsed time the job will be permitted to run. If the time limit is exceeded, DB2 Query Patroller aborts the job. The time limit value is in seconds. By default, DB2 Query Patroller will not impose an elapsed time limit on the job.
-l `row_limit`	Result row limit. This option enables the user to set a limit for the number of rows returned by an SQL `SELECT` statement. If the row limit is exceeded, the action taken by DB2 Query Patroller depends on the setting of the -L parameter. By default, DB2 Query Patroller will not impose a result row limit.
-L {Abort \| Truncate}	Result row limit action. This option enables the user to specify the action taken by DB2 Query Patroller should the job return more rows than the result row limit. If it is not specified or set to `Abort`, DB2 Query Patroller aborts the job. Otherwise, if it is set to `Truncate`, DB2 Query Patroller truncates the result table at the row limit.
-i {Low \| Normal \| High}	User Priority. This parameter enables the user to select the priority of the job. The priority value can be `Low`, `Normal`, or `High`. Only the first letter is significant. These values may also be specified as `0`, `1`, or `2`. The user's DB2 Query Patroller profile defines the actual priority levels that correspond to these values. By default, DB2 Query Patroller assigns the user's normal priority to the job.
-q	Quiet mode. This parameter directs DB2 Query Patroller to print only the job number upon successful job submission. This may be useful if the iwm_submit command is used from within a shell script.
-j `predecessor_job_id`	Predecessor job number. This parameter specifies a job number of a previously submitted DB2 Query Patroller job. The new job cannot be scheduled until the predecessor job completes.

[ Top of Page | Previous Page | Next Page ]