ADMIN_TASK_ADD 存储过程

SYSPROC.ADMIN_TASK_ADD 存储过程将任务添加到管理任务调度程序的任务列表中。

开始通用编程接口信息。

环境

ADMIN_TASK_ADD在WLM建立的存储过程地址空间中运行，并使用资源恢复服务附件功能连接到 Db2。

授权

任何能够执行此 Db2 存储过程的人都可以添加任务。

调用此存储过程的用户必须拥有 MONITOR1 权限。

语法

下面的语法图显示了调用此存储过程的SQL CALL语句：

阅读语法图跳过可视化语法图 CALL SYSPROC.ADMIN_TASK_ADD ( 用户ID,密码NULL,NULL , 开始时间戳NULL , 结束时间戳NULL , 最大调用量NULL , 时间间隔,NULL,NULL,NULL,NULL,NULL,时间点,NULL,NULL,NULL,NULL,NULL,触发任务名称,触发任务条件,触发任务代码,NULL,NULL, db2-ssidNULL , 程序结构NULL,程序名,程序输入NULL,NULL,NULL,NULL,NULL,NULL,NULL,JCL-库,JCL成员NULL,待业, 任务名称NULL , 描述NULL , 返回码 , 消息 )

选项说明

用户ID
指定执行任务的用户ID。

如果此参数设置为 NULL，则使用与管理任务调度程序关联的默认授权 ID 执行任务。

这是一个VARCHAR(128)类型的输入参数。

密码
指定与输入参数 user-ID 关联的密码。

密码值作为有效载荷的一部分传递给存储过程，且未加密。 当使用参数标记时，它不会存储在动态缓存中。

建议 ：让调用此存储过程的应用程序通过一个加密的一次性密码， 即通行码。

这是一个VARCHAR(24)类型的输入参数。 仅当用户ID 设置为NULL时，此参数才为NULL，而当用户ID 为NULL时，此参数必须为NULL。

开始时间戳
指定任务何时可以开始执行。 任务执行的开始时间取决于此参数和其他参数的设置：
开始时间戳的非空值
开始时间戳
如果时间点和触发任务名称为空，则任务执行从开始时间戳开始。
下一个时间点定义为开始时间戳或之后
如果时间点不为空 ，则任务执行将在开始时间戳或之后定义的下一个时间点开始。
当触发任务名称在开始时间戳或之后完成时
当触发任务名称 在开始时间戳或之后完成时，任务执行开始。
开始时间戳的值为空
立即
如果时间点和触发任务名称为空，则立即开始执行任务。
定义了下一个时间点
如果时间点不为空 ，则任务执行从下一个时间点开始。
当触发任务名称完成后
任务执行将在触发任务名称完成时开始。

此参数的值不能是过去的时间，也不能晚于结束时间戳。

这是一个TIMESTAMP类型的输入参数。

结束时间戳
指定任务何时可以开始执行。 如果此参数设置为 NULL，则任务可以无限期地按计划继续执行。

此参数的值不能为过去的时间，且不能早于开始时间戳。

这是一个TIMESTAMP类型的输入参数。

最大调用量
指定一个任务允许的最大执行次数。 此值适用于所有日程安排：由事件触发、按时间间隔重复以及按时间点重复。 如果此参数设置为 NULL，则此任务可以无限次执行。

对于仅执行一次的任务， 最大调用次数必须设置为1， 间隔 、时间点和触发任务名称必须为空。

如果同时指定了结束时间戳和最大调用次数 ，则以先达到的限值为准。 也就是说，即使到目前为止的任务执行次数尚未达到最大调用次数 ，但一旦达到结束时间戳 ，该任务将不再执行。 如果 max-invocations 已经发生，即使未达到 end-timestamp ，任务也不会再次执行。

这是一个整数类型的输入参数。

时间间隔
定义重复性常规任务两次执行之间的时间间隔（以分钟为单位）。 第一次执行发生在开始时间戳。 如果此参数设置为 NULL，则不会定期执行任务。 如果此参数包含非空值，则必须将参数时间点和 触发任务名称设置为空。

这是一个整数类型的输入参数。

时间点
定义执行任务的一个或多个时间点。 如果此参数设置为 NULL，则任务不会在固定时间点进行调度。 如果此参数包含非空值，则参数interval 和 trigger-task-name 必须设置为NULL。

时间点字符串使用UNIX cron格式。 格式包含以下信息，以空格分隔：指定分钟数、指定小时数、指定日期、指定月份、指定星期几。 对于每个部分，您可以指定一个或多个值、范围等。

这是一个VARCHAR(400)类型的输入参数。

触发任务名称
指定任务的名称，当该任务执行完成后，将触发此任务的执行。

DB2START 和 DB2STOP 的任务名称分别保留给 Db2 停止和启动事件。 这些事件由与正在启动或停止的 Db2 子系统关联的调度程序处理。

如果此参数设置为 NULL，则不会由其他任务触发此任务的执行。 如果此参数包含非空值，则参数interval 和 point-in-time 必须设置为NULL。

这是一个VARCHAR(128)类型的输入参数。

触发任务条件
指定在执行任务触发器-任务名称后，对返回代码进行比较的类型。 可能的值包括：
GT
大于
GE
大于等于
环境资格
等于
LT
小于
LE
小于或等于
NE
不等于

如果此参数设置为 NULL，则触发任务执行，而不考虑任务触发器名称的返回代码。 如果触发器任务名称设置为 NULL 或为 DB2START 或 DB2STOP ，则该参数必须设置为 NULL。

这是一个字符型（CHAR）的输入参数（2）。

触发任务代码
指定执行触发器任务名称的返回代码。

如果执行此任务是由存储过程触发的，则触发任务代码包含触发存储过程必须返回的 SQLCODE，以便执行此任务。

如果执行此任务是由 JCL 作业触发的，则触发任务代码包含触发作业必须返回的 MAXRC，以便执行此任务。

要了解任务执行后的MAXRC或SQLCODE，请调用用户定义的函数DSNADM。 ADMIN_TASK_STATUS在MAXRC和SQLCODE列中返回这些信息。

触发任务代码的值受以下限制：

  • 如果触发任务条件为空，则触发任务代码也必须为空。
  • 如果触发任务条件不为空，则触发任务代码也必须不为空。

如果触发任务条件和触发任务代码不为空，则它们用于测试执行触发任务名称的返回代码，以确定是否执行此任务。

例如，如果触发任务条件设置为“GE”， 触发任务代码设置为“8”，则只有当触发任务名称的上一次执行返回的MAXRC（对于JCL作业）或SQLCODE（对于存储过程）大于或等于8时，才会执行此任务。

这是一个整数类型的输入参数。

db2-ssid
指定 Db2 子系统的ID，其关联的调度程序应执行该任务。

此参数用于数据共享环境，例如，不同的 Db2 成员有不同的配置，任务的执行依赖于特定的环境。 将阻止其他成员的调度程序执行任务，因此只有当调度程序处于 db2-ssid 将阻止其他成员的调度程序执行任务，因此该任务只能在调度程序运行时执行 db2-ssid 正在运行时才能执行。

对于由触发任务名称中的 Db2 启动或 Db2 停止事件触发的任务，在 db2-ssid 中指定一个值，则仅在指定的子系统启动和停止时执行任务。 如果没有给出值，则每个成员开始或停止都会触发任务的局部执行，前提是执行是串行的。

如果此参数设置为 NULL，则任何调度程序都可以执行任务。

这是一个VARCHAR(4)类型的输入参数。

程序结构
指定此任务将执行的 Db2 存储过程的架构。 如果此参数设置为 NULL，则 Db2 使用默认模式。 如果过程名称设置为 NULL，则此参数必须设置为 NULL。

这是一个VARCHAR(128)类型的输入参数。

程序名
指定此任务将执行的 Db2 存储过程的名称。 如果此参数设置为 NULL，则不会调用任何存储过程。 在这种情况下，必须指定JCL作业。

这是一个VARCHAR(128)类型的输入参数。

程序输入
指定此任务将执行的 Db2 存储过程的输入参数。 该参数必须包含一个返回一行数据的 Db2 SELECT语句。 返回的值将作为参数传递给存储过程。

如果此参数设置为 NULL，则不会向存储过程传递任何参数。 当过程名称设置为空时，此参数必须设置为空。

这是一个VARCHAR(4096)类型的输入参数。

JCL-库
指定保存要执行的JCL作业的数据集名称。

如果此参数设置为 NULL，则不会执行任何 JCL 作业。 在这种情况下，必须指定一个存储过程。

这是一个VARCHAR(44)类型的输入参数。

JCL成员
指定保存要执行的JCL作业的库成员名称。

如果此参数设置为 NULL，则 JCL 库中指定的数据集必须是顺序的，且包含要执行的 JCL 作业。 如果 JCL库设置为空，则此参数必须设置为空。

这是一个VARCHAR(8)类型的输入参数。

待业
指定作业是否可以同步执行。 仅当 JCL库设置为空时，此参数才能设置为空。 否则，它必须是以下数值之一：
否
指定异步执行。 子线程不会等到作业执行完成，而是在作业提交后立即返回。 任务执行状态设置为提交状态，无法获得任务执行结果。
是
指定同步执行。 子线程模拟JCL作业的同步执行。 它等待任务执行完成，从 JES 阅读器获取任务状态，并填写任务的最后执行状态。
PURGE
指定清除 z/OS® 被清除。 子线程在执行后清除 JES 读取器中的工作输出。 执行与工作等待为“是”时相同。

这是一个VARCHAR(8)类型的输入参数。

任务名称
指定分配给任务的唯一名称。

当任务创建时任务名称为空时 ，将返回一个唯一的任务名称。 该名称的格式为 任务编号_xxxx ，其中 xxxx 为0001，代表第一个任务，0002代表第二个任务，以此类推。

以下任务名称已被保留，不能作为任务名称的值：

  • 名字以 TASK_ID_ 开头
  • DB2START
  • DB2STOP

这是一个VARCHAR(128)类型的输入输出参数。

描述
指定分配给任务的描述。

这是一个VARCHAR(128)类型的输入参数。

返回码
提供存储过程的返回代码。 可能的值包括：
0
通话已成功结束。
12
通话未成功完成。 消息输出参数包含描述错误的消息。

这是一个整数类型的输出参数。

消息
包含描述存储过程所遇到错误的信息。 该区域中的第一条消息（如果有的话）由存储过程生成。 Db2 生成的消息可能会出现在第一条消息之后。

这是一个VARCHAR(1331)类型的输出参数。

示例

以下Java™示例展示了如何调用ADMIN_TASK_ADD：

import java.sql.CallableStatement;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;
import java.sql.Timestamp;
import java.sql.Types;

Connection con = DriverManager.getConnection
   ("jdbc:db2://myserver:myport/mydatabase", "myuser", "mypassword");
CallableStatement callStmt = con.prepareCall
   ("CALL SYSPROC.ADMIN_TASK_ADD("
   + "?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
// provide the authid
callStmt.setString(1, "myexecuser");
// provide the password
callStmt.setString(2, "myexecpwd");
// set the start time to now
callStmt.setNull(3, Types.TIMESTAMP);
// no end time
callStmt.setNull(4, Types.TIMESTAMP);
// set the max invocation
callStmt.setInt(5, 1);
// This is a non recurrent task
callStmt.setNull(6, Types.INTEGER);
callStmt.setNull(7, Types.VARCHAR);
callStmt.setNull(8, Types.VARCHAR);
callStmt.setNull(9, Types.CHAR);
callStmt.setNull(10, Types.INTEGER);
callStmt.setNull(11, Types.VARCHAR);
// provide the stored procedure schema
callStmt.setString(12, "MYSCHEMA");
// provide the name of the stored procedure to be executed
callStmt.setString(13, "MYPROC");
// provide the stored procedure input parameter
callStmt.setString(14, "SELECT 1 FROM SYSIBM.SYSDUMMY1");
// This is not a JCL job
callStmt.setNull(15, Types.VARCHAR);
callStmt.setNull(16, Types.VARCHAR);
callStmt.setNull(17, Types.VARCHAR);
// add a new task with task name mytask
callStmt.setString(18, "mytask");
callStmt.registerOutParameter(18, Types.VARCHAR);
// provide the task description
callStmt.setString(19, "MY DESCRIPTION");
// register output parameters for error management
callStmt.registerOutParameter(20, Types.INTEGER);
callStmt.registerOutParameter(21, Types.VARCHAR);
// execute the statement
callStmt.execute();
// manage the return code
if ( callStmt.getInt(20) == 0 )
{
  System.out.print("\nSuccessfully added task " + callStmt.getString(18));
}
else
{
  System.out.print("\nError code and message are: "
     + callStmt.getInt(20) + "/" + callStmt.getString(21));
}

输出

该存储过程的输出是任务名称、任务名称和以下输出参数，这些参数在选项描述中进行了说明：

  • 返回码
  • 消息

通用编程接口信息结束。