ADMIN_TASK_REMOVE procedure - Remove scheduled tasks or task status records

The ADMIN_TASK_REMOVE procedure removes scheduled administrative tasks, which are pieces of work that can be encapsulated inside a procedure. It also removes task status records.

Syntax

Read syntax diagramSkip visual syntax diagramADMIN_TASK_REMOVE(name,end_timestamp)

The schema is SYSPROC.

Procedure parameters

name
An input argument of type VARCHAR(128) that specifies the name of the task.
end_timestamp
An output argument of type TIMESTAMP that specifies the status record end_timestamp timestamp.

Authorization

One of the following authorizations is required:
  • EXECUTE privilege on the ADMIN_TASK_REMOVE procedure
  • DATAACCESS authority
  • DBADM authority
  • SQLADM authority

Although the statement authorization ID might allow the procedure to be executed, successful removal of task and status records depends on the value of the current session authorization ID. The current session authorization ID must match the session authorization ID that was recorded when the task was created. Users with SYSADM, SYSCTRL, SYSMAINT, or DBADM authority can remove any task or status record. If an unauthorized user attempts to remove a task or status record, an SQL0551N is returned.

Default PUBLIC privilege

In a non-restrictive database, EXECUTE privilege is granted to PUBLIC when the procedure is automatically created.

Usage notes

The task is not removed until the unit of work is committed.

The behavior of the task removal depends on how the name and end_timestamp arguments are defined:
  • If the end_timestamp argument is NULL:
    • If the name argument is NULL, all tasks and status records are removed. If one or more tasks are currently running, then the task and associated status records are not removed. In this case, SQL1464W is returned.
    • If the name argument is not NULL, the task record that matches name is removed. If the specified task is currently running, the task is not removed and SQL20453N is returned. If the specified task is removed, all associated status records are removed.
  • If the end_timestamp argument is not NULL:
    • If the name argument is NULL, all status records with end_timestamp timestamps less than or equal to end_timestamp are removed. No task records are removed. The procedure will not remove any status records that have a status value of RUNNING.
    • If the name argument is not NULL, the status records for the task that matches name are removed if their end_timestamp timestamp is less than or equal to end_timestamp. No task records are removed. The procedure will not remove any status records that have a status value of RUNNING.

If a user attempts to remove a task that does not exist, an SQL0204N is returned.

Example

Remove a backup task called 'DAILY TSM BACKUP':
CALL SYSPROC.ADMIN_TASK_REMOVE('DAILY TSM BACKUP', NULL)