ADMIN_TASK_UPDATE stored procedure

The ADMIN_TASK_UPDATE stored procedure updates the schedule of a task that is in the task list for the administrative task scheduler. If the task that you want to update is running, the changes go into effect after the current execution finishes.

You must specify all of the parameters for the task that you want to modify the schedule for, even if those parameters have not changed since you created the task by using the ADMIN_TASK_ADD stored procedure.

Begin general-use programming interface information.

Environment

ADMIN_TASK_UPDATE runs in a WLM-established stored procedure address space and uses the Resource Recovery Services attachment facility to connect to DB2®.

Authorization

To call this stored procedure, you must have MONITOR1 privilege.

Anyone with SYSOPR, SYSCTRL, or SYSADM authority can update any task. Anyone who has EXECUTE authority on this stored procedure can update tasks that they added. If you try to update a task that was added by a different user, an error is returned in the output.

Syntax

The following syntax diagram shows the SQL CALL statement for invoking this stored procedure:


>>-CALL--ADMIN_TASK_UPDATE--(--task-name--,--description--,----->

>--begin_timestamp--,--end_timestamp--,--max_invocations--,----->

>--interval--,--point-in-time--,--trigger-task-name--,---------->

>--trigger-task-cond--,--trigger-task-code--,--db2-ssid--,------>

>--return-code--,--message--)----------------------------------><

Option descriptions

task-name

Specifies the unique name of the task that is to be updated in the task list of the administrative task scheduler. This is an input parameter of type VARCHAR(128).

description

Specifies a description that is assigned to the task. This is an input parameter of type VARCHAR(128).

begin-timestamp

An input argument of type TIMESTAMP that specifies the earliest time a task can begin execution. The value of this argument cannot be in the past, and it cannot be later than end_timestamp.

When the execution of a task begins depends on how this parameter and other parameters are defined:

Non-null value for begin-timestamp

At begin-timestamp: The task execution begins at begin-timestamp if point-in-time and trigger-task-name are NULL.
Interval in minutes after the last execution of this task: The task execution begins at begin-timestamp.
Next point in time defined at or after begin-timestamp: The task execution begins at the next point in time that is defined at or after begin-timestamp if point-in-time is non-null.
When trigger-task-name completes after begin-timestamp: The task execution begins the next time that trigger-task-name completes or after begin-timestamp.

Null value for begin-timestamp

Immediately: The task execution begins immediately if point-in-time and trigger-task-name are NULL.
Interval in minutes after the last execution of this task: The task execution begins at begin-timestamp.
Next point in time defined: The task execution begins at the next point in time that is defined if point-in-time is non-null.
When trigger-task-name completes: The task execution begins the next time that trigger-task-name completes.

end-timestamp

An input argument of type TIMESTAMP that specifies the latest time that a task can begin execution. The value of this argument cannot be in the past, and it cannot be earlier than begin_timestamp. If the argument is NULL, the task can continue to execute as scheduled indefinitely.

An executing task will not be interrupted at its end_timestamp value.

max-invocations

Specifies the maximum number of executions that are allowed for the modified task. This value applies to all scheduled executions, whether they be triggered by events, recurring by time interval, or recurring by points in time. This value includes the previous executions of the modified task.

If max-invocations is smaller than, or equal to the number of times that the task has already been executed, the task will not be executed again. To modify the task to run again, you must specify max-invocations as NULL, or as a value that is greater than the current number of times that the task has already been executed. In addition, if max-invocations, interval, point-in-time, and trigger-task-name are NULL, the task executes only one more time.

If this parameter is set to NULL, there is no limit to the number of times this task can execute. If both end-timestamp and max-invocations are specified, the first limit that is reached takes precedence. For example, if the value for end-timestamp is reached, the task will not be executed again, even if the number of task executions has not reached the value of max-invocations. Likewise, if the value for max-invocations is reached, the task will not be executed again, even if the value for end-timestamp is not reached.

This is an input parameter of type INTEGER.

interval

Defines a time duration between two executions of a repetitive regular task. The first execution occurs at begin-timestamp.

If this parameter is set to NULL, the task is not regularly executed. If this parameter contains a non-null value, you must set the point-in-time and trigger-task-name parameters to NULL.

This is an input parameter of type INTEGER.

point-in-time

Specifies one or more points in time when a task is executed. If this parameter is set to NULL, the task is not scheduled at fixed points in time. If this parameter contains a non-null value, the parameters interval and trigger-task-name must be set to NULL.

The point-in-time string uses the UNIX cron format. This format contains the following pieces of information separated by blank spaces:

Given minute or minutes
Given hour or hours
Given day or days of the month
Given month or months of the year
Given day or days of the week

For each part, you can specify one or several values and ranges.

This is an input parameter of type VARCHAR(400).

trigger-task-name

Specifies the name of the task that, upon completion, will trigger the execution of this task. The task names DB2START and DB2STOP are reserved for DB2 startup and shutdown events. Those events are handled by the scheduler that is associated with the DB2 subsystem that is starting or stopping.

If this parameter is set to NULL, the execution of this task will not be triggered by another task. If this parameter contains a non-null value, the parameters interval and point-in-time must be NULL.

This is an input parameter of type VARCHAR(128).

trigger-task-cond

Specifies the type of comparison to be made to the return code after the execution of task trigger-task-name. Possible values are:

GT: Greater than
GE: Greater than or equal to
EQ: Equal to
LT: Less than
LE: Less than or equal to
NE: Not equal to

If this parameter is set to NULL, the task execution is triggered without considering the return code of task trigger-task-name. This parameter must be set to NULL if trigger-task-name is set to NULL or is either DB2START or DB2STOP.

This is an input parameter of type CHAR(2).

trigger-task-code

Specifies the return code from executing the task trigger-task-name.

If the execution of this task is triggered by a stored procedure, trigger-task-code contains the SQLCODE that must be returned by the triggering stored procedure in order for this task to execute.

If the execution of this task is triggered by a JCL job, trigger-task-code contains the MAXRC that must be returned by the triggering job in order for this task to execute.

To find out what the MAXRC or SQLCODE of a task is after execution, invoking the user-defined function DSNADM. ADMIN_TASK_STATUS returns this information in the columns MAXRC and SQLCODE.

The following restrictions apply to the value of trigger-task-code:

If trigger-task-cond is NULL, then trigger-task-code must also be NULL.
If trigger-task-cond is non-null, then trigger-task-code must also be non-null.

If trigger-task-cond and trigger-task-code are not set to NULL, they are used to test the return code from executing trigger-task-name to determine whether to execute this task. For example, if trigger-task-cond is set to "GE", and trigger-task-code is set to "8", then this task will execute only if the previous execution of trigger-task-name returned a MAXRC (for a JCL job) or an SQLCODE (for a stored procedure) that is greater than or equal to 8.

This is an input parameter of type INTEGER.

db2-ssid

Specifies the DB2 subsystem ID whose associated scheduler should execute the task.

This parameter is used in a data sharing environment, where different DB2 members have different configurations and executing the task relies on a certain environment. However, specifying a value in db2-ssid will prevent the administrative task schedulers of other members from executing the task. Therefore, the task can be executed only if the administrative task scheduler of db2-ssid is running.

For a task that is being triggered by a DB2 start or DB2 stop event in trigger-task-name, specifying a value in db2-ssid causes the task to be executed only when the named DB2 subsystem is starting or stopping. If no value is given, each member that starts or stops will trigger a local execution of the task, if the executions are serialized.

If this parameter is set to NULL, any administrative task scheduler can execute the task.

This is an input parameter of type VARCHAR(4).

return-code

Provides the return code from the stored procedure. Possible values are:

0: The call completed successfully.
12: The call did not complete successfully. The message output parameter contains messages describing the error.

This is an output parameter of type INTEGER.

message

Contains messages describing the error encountered by the stored procedure. The first messages in this area, if any, are generated by the stored procedure. Messages that are generated by DB2 might follow the stored procedure messages.

This is an output parameter of type VARCHAR(1331).

Output

This stored procedure has the following output parameters, which are described in Option descriptions:

return-code
message

End general-use programming interface information.