ADMIN_TASK_ADD ストアード・プロシージャー

SYSPROC.ADMIN_TASK_ADD ストアード・プロシージャーは、タスクを管理用タスク・スケジューラーのタスク・リストに追加します。

汎用プログラミングインターフェース情報の開始。

環境

ADMIN_TASK_ADDは、WLMが確立したストアドプロシージャアドレス空間で実行され、リソース回復サービスアタッチメント機能を使用して Db2 に接続します。

許可

この Db2 ストアドプロシージャを実行できる人は、タスクの追加を許可されます。

このストアード・プロシージャーを呼び出すユーザーには、MONITOR1 特権が必要です。

構文

以下の構文図は、このストアード・プロシージャーを呼び出す SQL CALL ステートメントを示します。

構文図を読むビジュアルシンタックスダイアグラムをスキップする CALL SYSPROC.ADMIN_TASK_ADD ( ユーザーＩＤ,パスワードNULL,NULL , 開始タイムスタンプNULL , 終了時刻スタンプNULL , 最大呼び出し回数NULL , インターバル,NULL,NULL,NULL,NULL,NULL,ポイント・イン・タイム,NULL,NULL,NULL,NULL,NULL,トリガタスク名,トリガタスク条件,トリガタスクコード,NULL,NULL, db2-ssidNULL , 手続きスキーマNULL,procedure-name,手続き入力NULL,NULL,NULL,NULL,NULL,NULL,NULL,JCLライブラリ,JCLメンバーNULL,ジョブウェイト, タスク名NULL , 説明NULL , 戻りコード , メッセージ )

オプションの説明

user-ID
タスクを実行するユーザー ID を指定します。

このパラメーターを NULL に設定すると、管理タスク・スケジューラーに関連付けられているデフォルトの許可 ID でタスクが実行されます。

これは、タイプ VARCHAR(128) の入力パラメーターです。

パスワード
入力パラメーター user-ID に関連したパスワードを指定します。

password の値は、ペイロードの一部としてストアード・プロシージャーに渡され、暗号化されません。 パラメーター・マーカーが使用されている場合は、動的キャッシュに格納されません。

推奨： このストアドプロシージャを呼び出すアプリケーションに、パスチケットと呼ばれる暗号化された使い捨てパスワードを渡させる。

これは、タイプ VARCHAR(24) の入力パラメーターです。 このパラメーターは、user-ID に NULL が設定された場合にのみ NULL です。user-ID が NULL の場合は NULL でなければなりません。

開始タイムスタンプ
タスクが最初に実行を開始できる時期を指定します。 タスク実行の開始は、以下のような、このパラメーターまたは他のパラメーターの設定によって異なります。
begin-timestamp が非 NULL 値の場合
begin-timestamp
point-in-time および trigger-task-name が NULL の場合、タスクの実行は begin-timestamp のときに始まります。
begin-timestamp 時点以降に定義された次のポイント・イン・タイム
タスクの実行は、point-in-time が NULL 以外の場合、begin-timestamp 時点以降に定義された次のポイント・イン・タイムに開始されます。
trigger-task-name が、begin-timestamp 時点以降に完了したとき
タスクの実行は、trigger-task-name が begin-timestamp のとき、またはそれ以後に完了する次のときに始まります。
begin-timestamp がNULL 値の場合
即時
タスクの実行は、point-in-time および trigger-task-name が NULL の場合は即時に開始されます。
定義された次のポイント・イン・タイム
タスクの実行は、point-in-time が NULL 以外の場合、定義された次のポイント・イン・タイムに開始されます。
trigger-task-name が完了したとき
タスクの実行は、trigger-task-name が次に完了したときに開始されます。

このパラメーターの値は、過去の時刻であってはならず、また end-timestamp より後であってはなりません。

これは、タイプ TIMESTAMP の入力パラメーターです。

終了時刻スタンプ
タスクが最後に実行を開始できるタイミングを指定します。 このパラメーターに NULL を設定すると、タスクはスケジュールに従って無限に実行し続けることができます。

このパラメーターの値は、過去の時刻であってはならず、また begin-timestamp より前であってはなりません。

これは、タイプ TIMESTAMP の入力パラメーターです。

最大呼び出し回数
タスクに許容される実行の最大数を指定します。 この値はすべてのスケジュールに適用されます。イベントによってトリガーされ、時間間隔で繰り返し実行され、ポイント・イン・タイムごとに繰り返し実行されます。 このパラメーターに NULL を設定すると、このタスクが実行できる回数には制限がありません。

1 回のみ実行されるタスクの場合は、max-invocations を 1 に設定し、interval、point-in-time、および trigger-task-name を NULL に設定する必要があります。

end-timestamp と max-invocations の両方を指定する場合、最初に到達した限界が優先されます。 つまり、タスクの実行回数がまだ max-invocations に達していなくても、end-timestamp に達すると、タスクは再実行されません。 実行回数が max-invocations に達した場合、end-timestamp にまだ達していない場合でも、それ以降タスクは再実行されません。

これは、タイプ INTEGER の入力パラメーターです。

間隔
定期的反復タスクを 2 回実行する間の期間を分単位で定義します。 最初の実行は、begin-timestampのときに行われます。 このパラメーターを NULL に設定すると、タスクは定期的には実行されません。 このパラメーターに非 NULL 値が含まれる場合、パラメーター point-in-time および trigger-task-name は NULL に設定する必要があります。

これは、タイプ INTEGER の入力パラメーターです。

ポイント・イン・タイム
タスクが実行される 1 つ以上のポイント・イン・タイムを定義します。 このパラメーターに NULL を設定すると、タスクは決まったポイント・イン・タイムにスケジュールされません。 このパラメーターに NULL 以外の値を指定する場合は、interval と trigger-task-name パラメーターに NULL を設定する必要があります。

ポイントインタイム文字列は、UNIX cron 形式を使用します。 このフォーマットでは、情報の各部分 (指定する分、時間、日付、月、および曜日) をブランクで区切って指定します。 各部分には、1 つ以上の値、範囲などを指定できます。

これは、タイプ VARCHAR(400) の入力パラメーターです。

トリガタスク名
ここに指定する名前のタスクの実行が完了すると、このタスクの実行がトリガーされます。

DB2START と DB2STOP のタスク名は、それぞれ Db2 の停止と開始イベント用に予約されています。 これらのイベントは、起動または停止する Db2 サブシステムに関連付けられたスケジューラによって処理されます。

このパラメーターに NULL を設定すると、このタスクの実行は別のタスクからはトリガーされません。 このパラメーターに NULL 以外の値を指定する場合は、interval と point-in-time パラメーターに NULL を設定する必要があります。

これは、タイプ VARCHAR(128) の入力パラメーターです。

トリガタスク条件
trigger-task-name タスクの実行後に、戻りコードに対して行う比較のタイプを指定します。 可能な値は以下のとおりです。
GT
より大きい
GE
より大か等しい
EQ
等しい
LT
より小さい
LE
より小か等しい
NE
等しくない

このパラメーターを NULL に設定すると、trigger-task-name タスクの戻りコードを反映せずにタスクの実行がトリガーされます。 trigger-task-name が NULL に設定されているか、DB2START または DB2STOP のいずれかである場合、このパラメーターは NULL に設定する必要があります。

これは、タイプ CHAR(2) の入力パラメーターです。

トリガタスクコード
実行している trigger-task-name からの戻りコードを指定します。

このタスクの実行がストアード・プロシージャーによってトリガーされる場合、このタスクを実行するには、trigger-task-code に、トリガーするストアード・プロシージャーから返される SQLCODE が含まれている必要があります。

このタスクの実行が JCL ジョブによってトリガーされる場合、このタスクを実行するには、trigger-task-code に、トリガーするジョブから返される MAXRC が含まれている必要があります。

実行後のタスクの MAXRC または SQLCODE を見つけるには、ユーザー定義関数 DSNADM を呼び出します。 ADMIN_TASK_STATUS は、この情報を MAXRC 列と SQLCODE 列に戻します。

次の制約事項が、trigger-task-code の値に適用されます。

  • trigger-task-cond が NULL の場合は、trigger-task-code も NULL にする必要があります。
  • trigger-task-cond が NULL 以外の値の場合は、trigger-task-code も NULL 以外の値でなければならない。

trigger-task-cond および trigger-task-code が非 NULL の場合、これらを使用して、trigger-task-name の実行による戻りコードを検査し、このタスクを実行すべきかどうかを識別します。

例えば、trigger-task-cond に「GE」が設定され、trigger-task-code に「8」が設定されている場合、このタスクは、trigger-task-name の直前の実行から 8 以上の MAXRC (JCL ジョブの場合) または SQLCODE (ストアード・プロシージャーの場合) が戻された場合にのみ実行されます。

これは、タイプ INTEGER の入力パラメーターです。

db2-ssid
Db2 サブシステムIDを指定し、関連付けられたスケジューラがタスクを実行するようにします。

このパラメータは、例えば、 Db2 のメンバーがそれぞれ異なる構成を有しており、タスクの実行が特定の環境に依存するようなデータ共有環境で使用されます。 ただし、db2-ssid に値を指定すると、他のメンバーの管理スケジューラーがこのタスクを実行することが防止されるので、db2-ssid の管理スケジューラーが実行されている間に限りタスクを実行できます。

トリガー・タスク名の Db2 開始イベントまたは Db2 停止イベントによってトリガーされるタスクの場合、 db2-ssid に値を指定すると、指定されたサブシステムが開始および停止しているときにのみ、タスクが実行されます。 値が指定されていない場合、始動または停止する各メンバーは、実行がシリアライズされている場合には、タスクのローカル実行をトリガーします。

このパラメーターを NULL に設定すると、すべてのスケジューラーがタスクを実行できます。

これは、タイプ VARCHAR(4) の入力パラメーターです。

手続きスキーマ
このタスクが実行する Db2 ストアドプロシージャのスキーマを指定します。 このパラメータがNULLに設定されている場合、 Db2 はデフォルトのスキーマを使用します。 procedure-name が NULL に設定されている場合は、このパラメーターに NULL を設定する必要があります。

これは、タイプ VARCHAR(128) の入力パラメーターです。

procedure-name
このタスクが実行する Db2 ストアドプロシージャの名前を指定します。 このパラメーターを NULL に設定する場合、ストアード・プロシージャーは呼び出されません。 この場合には、JCL ジョブが指定されている必要があります。

これは、タイプ VARCHAR(128) の入力パラメーターです。

手続き入力
このタスクが実行する Db2 ストアドプロシージャの入力パラメータを指定します。 このパラメータには、1行のデータを返す Db2 SELECT文を含める必要があります。 戻り値は、パラメーターとしてストアード・プロシージャーに渡されます。

このパラメーターを NULL に設定する場合、パラメーターはストアード・プロシージャーに渡されません。 procedure-name が NULL に設定されている場合、このパラメーターは NULL に設定する必要があります。

これは、タイプ VARCHAR(4096) の入力パラメーターです。

JCLライブラリ
実行する JCL ジョブが保管されているデータ・セットの名前を指定します。

このパラメーターに NULL を設定すると、JCL ジョブは実行されません。 この場合には、ストアード・プロシージャーが指定されている必要があります。

これは、タイプ VARCHAR(44) の入力パラメーターです。

JCLメンバー
実行する JCL ジョブが保管されているライブラリー・メンバーの名前を指定します。

このパラメーターに NULL を設定する場合は、JCL-library に指定されたデータ・セットは順次で、実行する JCL ジョブが含まれている必要があります。 JCL-library が NULL に設定されている場合は、このパラメーターに NULL を設定する必要があります。

これは、タイプ VARCHAR(8) の入力パラメーターです。

ジョブウェイト
ジョブを同期して実行できるかどうかを指定します。 JCL-library が NULL に設定されている場合、このパラメーターに指定できるのは、NULL のみです。 そうでない場合は、次のいずれかの値を指定する必要があります。
いいえ
非同期実行を指定します。 サブスレッドは、ジョブの実行が完了するまで待たず、ジョブの送信後すぐに返します。 タスク実行状況は提出状況に設定され、ジョブ実行自体の結果は利用できません。
はい
同期実行を指定します。 サブスレッドは、JCLジョブの同期実行をシミュレートします。 ジョブの実行が完了するまで待ち、JESリーダーからジョブのステータスを取得し、タスクの最後の実行ステータスを記入します。
PURGE
のジョブステータスが消去されることを指定します。 z/OS® 消去されることを指定します。 サブスレッドは、実行後にJESリーダーからジョブ出力をパージします。 実行は、 job-wait がYESの場合と同じです。

これは、タイプ VARCHAR(8) の入力パラメーターです。

タスク名
タスクに割り当てられている固有の名前を指定します。

task-name に NULL 値を指定してタスクを作成すると、固有のタスク名が戻されます。 この名前は TASK_ID_xxxx のフォーマットで構成されます。指定された最初のタスクの場合、xxxx は 0001 になり、2 番目のタスクの場合は、0002 などのようになります。

以下のタスク名は予約されているため、task-name の値として指定できません。

  • タスク ID (TASK_ID_) で始まる名前
  • DB2START
  • DB2STOP

これは、タイプ VARCHAR(128) の入出力パラメーターです。

説明
タスクに割り当てられた説明を指定します。

これは、タイプ VARCHAR(128) の入力パラメーターです。

戻りコード
ストアード・プロシージャーからの戻りコードを指定します。 可能な値は以下のとおりです。
0
呼び出しは正常に完了しました。
12
呼び出しは正常に完了しませんでした。 message 出力パラメーターにエラーについて説明するメッセージが含まれています。

これは、タイプ INTEGER の出力パラメーターです。

メッセージ
ストアード・プロシージャーにより検出されたエラーについて説明するメッセージが含まれます。 この領域の最初のメッセージは (ある場合)、ストアード・プロシージャーによって生成されます。 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));
}

出力

このストアドプロシージャの出力は、タスク名、 タスク名、および以下の出力パラメータです。これらはオプションの説明で説明されています

  • 戻りコード
  • メッセージ

汎用プログラミングインターフェース情報の終了。