ADMIN_TASK_ADD 过程 - 调度新任务

ADMIN_TASK_ADD 过程调度管理任务，这是可以封装在过程中的任何工作。

语法

Read syntax diagramSkip visual syntax diagramADMIN_TASK_ADD(name,begin_timestamp,end_timestamp,max_invocations,schedule,procedure_schema,procedure_name,procedure_input,options,remarks)

模式为 SYSPROC。

过程参数

name
类型为 VARCHAR (128) 的输入参数，用于指定任务的名称。 此参数不能为 NULL。
开始时间戳记
类型为 TIMESTAMP 的输入参数，用于指定任务可以开始执行的最早时间。 此自变量的值不能是过去的值，并且不能晚于 end_timestamp。
何时开始执行任务取决于如何定义此自变量和 schedule 自变量:
  • 如果 begin_timestamp 自变量不是 NULL:
    • 如果 schedule 自变量为 NULL，那么任务执行将从 begin_timestamp开始。
    • 如果 schedule 自变量不是 NULL，那么任务执行将在下次调度时间 begin_timestamp或之后开始。
  • 如果 begin_timestamp 自变量为 NULL:
    • 如果 schedule 自变量为 NULL，那么将立即开始执行任务。
    • 如果 schedule 自变量不是 NULL，那么任务执行将在下一个调度时间开始。
end_timestamp
类型为 TIMESTAMP 的输入参数，用于指定任务上次可以开始执行的时间。 此参数的值不能是过去的值，并且不能早于 begin_timestamp。 如果参数为 NULL，那么该任务可以继续无限期地按调度执行。

执行中的任务不会在其 end_timestamp处中断。

最大调用数
类型为 INTEGER 的输入参数，用于指定任务允许的最大执行次数。 如果参数为 NULL，那么对任务可以执行的次数没有限制。 如果参数为 0，那么将不会执行该任务。

如果 schedule 不是 NULL，那么此值将应用于调度。

如果同时指定了 end_timestamp 和 max_invocations ，那么 end_timestamp 优先。 即，如果达到 end_timestamp 时间戳记，即使到目前为止的任务执行次数尚未达到 max_invocations的值，也不会再次执行该任务。

日程安排
类型为 VARCHAR (1024) 的输入参数，用于指定固定时间点的任务执行调度。 如果参数为 NULL，那么不会在固定时间点调度任务。

必须使用 UNIX cron 格式指定 schedule 字符串。

不支持多个调度。

PROCEDURE_SCHEMA
类型为 VARCHAR (128) 的输入参数，用于指定此任务将执行的过程的模式。 此参数不能为 NULL。
procedure_name
类型为 VARCHAR (128) 的输入参数，用于指定此任务将执行的过程的名称。 此参数不能为 NULL。
过程输入
类型为 CLOB (2M) 的输入参数，用于指定此任务将执行的过程的输入参数。 此自变量必须包含返回一行数据的 SQL 语句。 返回的值将作为自变量传递至过程。 如果此参数为 NULL，那么不会将任何参数传递到过程。

SQL 语句返回的列数必须与过程的自变量总数 (和类型) 相匹配，并且必须包含单行。 对于输出参数，将忽略值本身，但该值应该与过程所需的 SQL 数据类型相同。

每次执行任务时都将执行此 SQL 语句。 如果 SQL 语句失败，那么任务的状态将设置为NOTRUN并且将记录特定的 SQLCODE 信息。 如果该语句不返回结果集，不返回行，返回多行或结果集，那么将不会执行该任务。 任务的状态将设置为NOTRUN并且将设置 SQLCODE SQL1465N 以指示此自变量无效。

如果语句结果包含序列化 XML 参数，那么组合的所有 XML 参数的总大小将限制为 256 千字节。 如果结果超过此阈值，那么任务的状态将设置为NOTRUN. 将设置 SQLCODE -302 和 SQLSTATE 22001 以指示已发生数据截断。

要查看任务的状态，请使用 SYSTOOL.ADMIN_TASK_STATUS 视图

选项
类型为 VARCHAR (512) 的输入自变量。 此自变量必须为 NULL。
备注
类型为 VARCHAR (254) 的输入参数，用于指定任务的描述。 此参数是可选的，可以是 NULL。

权限

需要下列其中一项权限才能执行此例程：
  • 对例程的 EXECUTE 特权
  • DATAACCESS 权限
  • DBADM 权限
  • SQLADM 权限

缺省 PUBLIC 特权

在非限制数据库中，自动创建过程时会将 EXECUTE 特权授予 PUBLIC。

使用说明

在调用 ADMIN_TASK_ADD 过程之前， SYSTOOLSPACE 表空间必须存在。 如果它不存在，那么该过程将返回 SQL0204N 错误消息。

调度任务时，将记录当前会话用户的授权标识。 调度程序在执行任务时切换到此会话授权标识。

管理任务调度程序不支持执行在没有指定用户标识和密码的情况下执行数据库连接的过程。 例如， ADMIN_CMD 过程可用于从数据库执行 LOAD。 使用为当前连接的数据库提供的用户标识和密码建立与源数据库的连接。 此类型的 LOAD 操作无法由任务调度程序执行。

如果将无效参数传递到过程中，那么将返回 SQL0171N 。 消息的标记将指示哪个参数无效以及过程的名称。

在落实工作单元并且调度程序已访存任务定义之前，无法调度任务执行。

调度程序每 5 分钟检查一次新的或更新的任务。 为确保任务按预期执行，最早开始时间 (由 begin_timestamp， end_timestamp 和 schedule 参数定义) 应至少在工作单元落实后 5 分钟。

数据库必须在所有数据库分区上处于活动状态，以确保调度程序可以执行该任务。

在分区数据库环境中，可以从任何数据库分区调用 ADMIN_TASK_ADD 过程。 但是，调度程序将从目录数据库分区执行所有任务。

begin_timestamp， end_timestamp和 schedule 基于服务器的时区。 在夏令时 (DST) 的过渡期间调度任务时需要特别注意。 如果该任务安排在凌晨 2:01 运行，并且是时间向前的一年时间，那么该任务将不会运行，因为时钟将从凌晨 2:00 跳到凌晨 3:00。 如果在激活数据库时发生 DST 更改，并且在 DST 更改时间期间未调度任何任务，那么 DST 更改后的第一个已调度任务将不会运行。 任务将从第二个任务开始正常运行。 例如，如果在凌晨 2:00 到凌晨 3:00 之间未调度任何任务，但在凌晨 3:10 有一个任务也是 DST 更改后的第一个任务，那么此任务将不会运行。 这与调度任务的 DST 更改后的时间无关。 例如，无论调度 DST 后的第一个任务是在 DST 更改一天还是一个月后，只要该任务是 DST 更改后的第一个任务并且数据库一直保持活动状态，该任务就不会运行。 另一方面，当时间倒退一个小时时，最初安排在凌晨 2:00 到凌晨 3:00 之间的任务将执行两次。 用户负责对夏令时进行调整，以确保其所需行为。

在调用由 procedure_schema 和 procedure_name指定的过程之后，调度程序将始终落实。 如果需要事务回滚，那么必须在过程中执行回滚。

如果任务名称不唯一，那么该过程将失败，并返回 SQL0601N。

示例

示例 1: 创建一个任务，该任务在每天凌晨 12:00 执行联机 TSM 备份，立即生效:
CALL SYSPROC.ADMIN_TASK_ADD
  ( 'DAILY TSM BACKUP',
    CURRENT_TIMESTAMP,
    NULL,
    NULL,
    '0 0 * * *',
    'SYSPROC',
    'ADMIN_CMD',
    'VALUES(''BACKUP DATABASE SALES ONLINE USE TSM WITHOUT PROMPTING'')',
    NULL,
    NULL )
示例 2: 调度任务以每小时清空一次事件监视器:
  1. 在 PROD 模式中创建一个 SQL 过程，用于清空名为 "em" 的事件监视器:
    CREATE PROCEDURE FLUSH_EVENT_MONITOR()
	SPECIFIC FLUSH_EVENT_MONITOR
  	LANGUAGE SQL
  	BEGIN
  	DECLARE stmt VARCHAR(100) ;
  	SET stmt = 'FLUSH EVENT MONITOR em' ;
  	EXECUTE IMMEDIATE stmt ;
  	END
    注: 不能在过程中直接调用 FLUSH EVENT MONITOR SQL 语句。 但是，可以使用 EXECUTE IMMEDIATE。
  2. 调用 ADMIN_TASK_ADD 以调度任务:
    CALL SYSPROC.ADMIN_TASK_ADD 
	('FLUSH EVENT MONITOR EVERY HOUR',
  	NULL,
   	NULL,
  	NULL,
  	'0 0-23 * * *',
  	'PROD',
  	'FLUSH_EVENT_MONITOR',
  	NULL,
  	NULL,
  	NULL )