ADMIN_TASK_ADD プロシージャー - 新規タスクのスケジュール

ADMIN_TASK_ADD プロシージャーは、管理タスク、つまりプロシージャーの内部にカプセル化できる処理をスケジュールに入れます。

構文

構文図を読む構文図をスキップするADMIN_TASK_ADD(name,begin_timestamp,end_timestamp,max_invocations,schedule,procedure_schema,procedure_name,procedure_input,options,remarks)

スキーマは SYSPROC です。

プロシージャー・パラメーター

name
タスクの名前を指定する、タイプ VARCHAR (128) の入力引数。 この引数は NULL にできません。
begin_timestamp
タスクの実行を開始できる最も早い時刻を指定する、タイプ 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 で中断されることはありません。

max_invocations
タスクで許容される最大実行数を指定する、タイプ INTEGER の入力引数。 引数が NULL の場合、タスクを実行できる回数に制限はありません。 引数が 0 の場合、タスクは実行されません。

schedule が NULL 以外の場合、この値がスケジュールに適用されます。

end_timestamp と max_invocations の両方が指定されている場合、end_timestamp が優先されます。つまり、end_timestamp タイム・スタンプに達すると、タスクの回数がその時点で max_invocations の値に達していなくても、そのタスクが再び実行されることはありません。

schedule
特定の時間にタスクが実行されるようにスケジュールを指定する、タイプ VARCHAR(1024) の入力引数。 引数が NULL の場合、タスクは、特定の時間にスケジュールされません。

schedule ストリングは、UNIX cron 形式を使用して指定する必要があります。

複数のスケジュールはサポートされていません。

procedure_schema
このタスクが実行するプロシージャーのスキーマを指定する、タイプ VARCHAR(128) の入力引数。 この引数は NULL にできません。
procedure_name
このタスクが実行するプロシージャーの名前を指定する、タイプ VARCHAR(128) の入力引数。 この引数は NULL にできません。
procedure_input
このタスクが実行するプロシージャーの入力引数を指定する、タイプ CLOB(2M) の入力引数。 この引数には、1 行のデータを戻す SQL ステートメントが含まれている必要があります。 戻り値は、引数としてプロシージャーに渡されます。 この引数が NULL の場合、引数はプロシージャーに渡されません。

SQL ステートメントによって戻される列数は、プロシージャーの引数の総数 (およびタイプ) と一致していなければならず、単一行を含んでいる必要があります。 出力引数の場合、値自体は無視されますが、プロシージャーが要求するのと同じ SQL データ・タイプでなければなりません。

この SQL ステートメントは、タスクが実行されるたびに実行されます。 SQL ステートメントが失敗すると、タスクの状況は NOTRUN に設定され、特定の SQLCODE 情報が記録されます。ステートメントが結果セットや行を戻さず、複数の行または結果セットを戻す場合、タスクは実行されません。 タスクの状況は NOTRUN に設定され、この引数が無効であることを示す SQLCODE SQL1465N が設定されます。

ステートメントの結果に直列化 XML パラメーターが含まれる場合、結合されるすべての XML パラメーターの合計サイズは 256 キロバイトに制限されます。結果がこのしきい値を超えた場合、タスクの状況は NOTRUN に設定されます。データ切り捨てが発生したことを示す、SQLCODE -302 および SQLSTATE 22001 が設定されます。

タスクの状況を表示するには、SYSTOOL.ADMIN_TASK_STATUS ビューを使用します。

options
タイプ VARCHAR(512) の入力引数。 この引数は NULL でなければなりません。
remarks
タスクの説明を指定する、タイプ VARCHAR(254) の入力引数。 この引数はオプションであり、NULL にすることができます。

許可

このルーチンを実行するには、以下のいずれかの権限が必要です。
  • ルーチンに対する EXECUTE 特権
  • DATAACCESS 権限
  • DBADM 権限
  • SQLADM 権限

デフォルトの PUBLIC 特権

制限のないデータベースでは、このプロシージャーが自動的に作成されると、EXECUTE 特権が PUBLIC に付与されます。

使用上の注意

ADMIN_TASK_ADD プロシージャーを呼び出す前に、SYSTOOLSPACE 表スペースが存在している必要があります。 存在しない場合、プロシージャーは SQL0204N エラー・メッセージを戻します。

タスクがスケジュールされている場合は、現行セッション・ユーザーの許可 ID が記録されます。 スケジューラーは、タスクを実行するときにこのセッション許可 ID に切り替えます。

管理タスク・スケジューラーは、指定したユーザー ID およびパスワードを使用せずにデータベース接続を実行するプロシージャーの実行をサポートしていません。 例えば、ADMIN_CMD プロシージャーを使用して、データベースから LOAD を実行できます。ソース・データベースへの接続は、現在接続中のデータベースに提供されているユーザー ID およびパスワードを使用して確立されます。 このタイプの LOAD 操作は、タスク・スケジューラーでは実行できません。

無効な引数がプロシージャーに渡されると、SQL0171N が戻されます。メッセージのトークンは、無効な引数およびプロシージャーの名前を示します。

タスクは、作業単位がコミットされて、スケジューラーがタスク定義をフェッチするまでは、実行をスケジュールすることはできません。

スケジューラーは、新規および更新されたタスクがないかどうか 5 分おきに調べます。 予期されるとおりにタスクが実行されるようにするには、begin_timestamp、end_timestamp、および schedule 引数で定義される最も早い開始時刻は、作業単位がコミットされてから少なくとも 5 分後でなければなりません。

タスクがスケジューラーによって実行できるようにするには、データベースはすべてのデータベース・パーティションでアクティブである必要があります。

パーティション・データベース環境では、ADMIN_TASK_ADD プロシージャーは任意のデータベース・パーティションから呼び出すことができます。ただし、スケジューラーはカタログ・データベース・パーティションからすべてのタスクを実行します。

begin_timestamp、end_timestamp、および schedule はサーバーの時間帯に基づいています。 夏時間調整 (DST) の移行期間にタスクをスケジュールする場合には、特に注意が必要です。 タスクが午前 2 時 1 分に実行されるようスケジュールされている場合に、それが時間を早めるときに当たると、時間は午前 2 時から午前 3 時までスキップされるため、そのタスクは実行されません。 DST の変更がデータベースがアクティブな状態で行われ、DST の変更時間中にスケジュールされたタスクがない場合、DST の変更後にスケジュールされている最初のタスクは実行されません。2 番目以降のタスクは正常に実行されます。例えば、午前 2 時から午前 3 時の間にスケジュールされているタスクはなく、 午前 3 時 10 分にスケジュールされているタスクがあり、それが DST の変更後の最初のタスクである場合、このタスクは実行されません。これは、DST 変更のどれくらい後にタスクがスケジュールされているかとは関係がありません。例えば、DST より後の最初のタスクが DST の変更から 1 日後や 1 カ月後にスケジュールされていたとしても、そのタスクが DST 変更後の最初のタスクであり、データベースがその間ずっとアクティブな状態であった限り、そのタスクは実行されません。一方、時間が 1 時間戻されるときには、午前 2 時から 3 時の間にスケジュールされているタスクは 2 回実行されることになります。 必要な動作が実行されるように、夏時間調整時間の調整はユーザーの責任で行う必要があります。

スケジューラーは常に、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 時間ごとにイベント・モニターをフラッシュするタスクをスケジュールする:
  1. "em" というイベント・モニターをフラッシュする SQL プロシージャーを PROD スキーマに作成します。 
    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 )