# DBトリガー

## オペレーション名

DBトリガー

## 機能概要

DBトリガーは、指定したデータベースのテーブルを監視し、ステータスカラムの値の状態によってスクリプトを実行するトリガー機能です。
DBトリガーは実行時に監視テーブルのデータをXML型の引数として実行スクリプトに渡します。実行スクリプト側ではXML型のスクリプト入力変数を経由してDBトリガーから受け渡されるXMLデータを取得し、そのデータを用いてデータベースとの同期処理などを実現することが可能となります。
DBトリガーの実行には、事前に監視対象のテーブルにステータス値を指定するカラムを用意する必要があります。
事前設定については、こちらを参照してください。

## 発火イメージ

- トリガー発火前
- トリガー発火時

## 監視イベントの種類

### 挿入時

監視対象のテーブルのステータスカラムの値が[挿入時トリガー待ち状態]であった場合に発火します。
スクリプトの実行終了後、[挿入時トリガー待ち状態]の値を[未変更状態]の値に変更します。

### 更新時

監視対象のテーブルのステータスカラムの値が[更新時トリガー待ち状態]であった場合に発火します。
スクリプトの実行終了後、[更新時トリガー待ち状態]の値を[未変更状態]の値に変更します。

### 削除時

監視対象のテーブルのステータスカラムの値が[削除時トリガー待ち状態]であった場合に発火します。
スクリプトの実行終了後、[削除時トリガー待ち状態]の値を[削除状態]の値に変更します。

## プロパティ

##### DBトリガーの設定

項目名 | 内容 | 備考
--- | --- | ---
トリガー名 | トリガーの名前を入力します。 |
接続 | グローバルリソースを選択します。 | 使用可能なグローバルリソースについては、こちらを参照してください。
監視テーブル | 監視対象となるテーブルを選択または入力します。 | グローバルリソースの一覧設定で指定した制限数のテーブルが表示されます。 環境変数などの変数を使用することはできません。
ステータスカラム | 監視対象となるステータスカラムを選択または入力します。 | 環境変数などの変数を使用することはできません。
監視イベント | トリガーで監視するイベントを選択します。 挿入時:(デフォルト) ステータスカラム内に[挿入時トリガー待ち状態]の値が存在する時に発火します。 更新時: ステータスカラム内に[更新時時トリガー待ち状態]の値が存在する時に発火します。 削除時: ステータスカラム内に[削除時トリガー待ち状態]の値が存在する時に発火します。 | 複数項目の選択が可能です。
監視間隔(秒) | 監視を行う間隔を秒単位で入力します。 | デフォルト値は「10」です。
終了時オプション | スクリプト終了時のオプションを選択します。 成功時のみステータスを変更する:(デフォルト) スクリプトの実行が成功した場合のみステータスカラムの値をすべて[未変更状態]または[削除状態]の値に戻します。 成功/失敗にかかわらずステータスを変更する: スクリプトの実行の成否に関わらずステータスカラムの値をすべて[未変更状態]または[削除状態]の値に戻します。 |
スクリプトに渡すデータをメモリに保持する | トリガー発火時に取得するデータをメモリに保持するかどうかを選択します。 チェックあり:(デフォルト) トリガー発火時に取得するデータをメモリに保持します。 チェックなし: トリガー発火時取得するデータをファイルに保持します。 | 取得するデータが大容量の場合は、[チェックなし]を選択してください。
ステータス値 | 各ステータスの値を入力します。
値 | 状態
--- | ---
0(デフォルト) | 未変更状態
1(デフォルト) | 挿入時トリガー待ち状態
2(デフォルト) | 更新時トリガー待ち状態
3(デフォルト) | 削除時トリガー待ち状態
4(デフォルト) | 削除状態
| [値]は編集することができます。 [値]は「0」以上「1000」未満および「11000」以上の整数値を指定してください。(最大値はステータスカラムのデータ型に依存します。) 指定範囲は変更することもできます。 詳細については、「実行IDについて」を参照してください。 [値]は重複した値の指定はできません。 [状態]の編集はできません。

##### 実行内容の設定

項目名 | 内容 | 備考
--- | --- | ---
トリガー所有者 | 作成するトリガーの所有者を選択します。 | 管理者権限を持ったユーザのみ選択できます。 (一般ユーザは自分以外を選択することはできません。)
実行ユーザ名 | [スクリプト]で指定したスクリプトを実行するユーザを選択します。 |
パスワード | [実行ユーザ名]で指定したユーザに対応したパスワードを入力します。 |
サービス | トリガーで実行するスクリプトを含むサービスを選択します。 | サービスとして登録されたプロジェクトが表示されます。
スクリプト | トリガーで実行するスクリプトを選択します。 | [サービス]で指定したサービス内のスクリプトが表示されます。
スクリプト引数 | [スクリプト]で指定したスクリプトに設定されているスクリプト入力変数が表示されます。 | スクリプト出力変数は表示されません。 実行スクリプトにXML型のスクリプト入力変数が設定されている必要があります。また、XML型スクリプト入力変数の位置は最上位にしてください。 スクリプトにスクリプト入力変数を設定し、使用する方法については、「入出力変数について」を参照してください。
スクリプト引数/変数名 | スクリプト変数名が表示されます。 | 編集はできません。
スクリプト引数/型 | スクリプト変数の型が表示されます。 | 編集はできません。
スクリプト引数/値 | スクリプト変数の値を入力します。 |

##### 実行オプションの設定

実行オプションの設定については、「実行オプションの設定」を参照してください。

## 事前設定について

DBトリガー使用の際には、以下の2つの事前設定が必要となります。

1. ステータスカラムの追加
   監視対象となるテーブルにステータスカラムを追加します。
   例:「SAMPLE」テーブルに「STATUS_COLUMN」をステータスカラムとして追加
   ステータスカラムのデータ型は整数型(INTEGER)である必要があります。サイズは「5」以上にしてください。
2. XML型スクリプト入力変数の作成
   トリガーで実行するスクリプトにXML型のスクリプト入力変数を作成します。
   スクリプト変数の作成については、「スクリプト変数」を参照してください。
   例:スクリプト「Script」にXML型のスクリプト入力変数「in_xml」を作成
   トリガーから渡されるXMLデータは実行スクリプトの最上位のスクリプト入力変数に代入されるため、XML型スクリプト入力変数の位置は最上位にしてください。

## 使用可能なグローバルリソース

[接続]では、以下のアダプタのグローバルリソースを指定できます。

アダプタの種類
Accessアダプタ
DB2アダプタ
Oracleアダプタ
PostgreSQLアダプタ
SQL Serverアダプタ
JDBCアダプタ
ODBCアダプタ

## 入力XMLデータの扱いについて

トリガーから渡されるXMLデータを実行スクリプト内のMapperで扱う場合には、以下の手順でスキーマの読み込みを行ってください。

1. 監視対象のデータベースのテーブル読み取り処理をスクリプトキャンバスに配置します。
2. テーブル読み取り処理のプロパティ設定ダイアログで、DBトリガーで指定するものと同じグローバルリソースとテーブルを選択します。
3. Mapperをスクリプトキャンバスに配置し、Startアイコン(XML型スクリプト入力変数)からデータフローを引きます。
4. Mapperエディタを開き、入力データのルートの右クリックメニュー[スキーマの読み込み]を選択します。
5. [コンポーネントから選択]で1.で配置したコンポーネントを選択します。

監視対象のテーブルの構造が変更された場合には、上記手順を繰り返してMapperのスキーマを更新してください。

## 実行IDについて

トリガー発火後、「1000」から「10999」までの整数値が「実行ID」として内部で使用されます。実行IDはトリガー1個につき3個割り当てられます。
たとえばDBトリガーが100個発火した場合、割り当てられる実行IDの数は300個になります。同時に割り当てられる実行IDの最大数は10000個(トリガー3333個分)になります。
実行終了後、割り当てられた実行IDは破棄され、そのあとに発火したトリガーが再利用します。同時に割り当てられる実行IDが10000個を超えた場合はトリガーは発火しません。
実行IDに関する設定は以下のプロパティファイルで変更可能です。

キー | 配置場所 | 説明 | 備考
--- | --- | --- | ---
min.execution.id | $DATAANYWARE_HOME/server/plugin/trigger/modules/database_trigger/META-INF/ database_trigger.properties | 実行IDの開始番号を指定します。 | [ステータス値]で指定した値以外の整数値を指定してください。 省略した場合「1000」が設定されます。(デフォルト) [min.execution.id]以上、[min.execution.id]+[max.execution.number]未満の整数値は[ステータス値]で指定することはできません。
max.execution.number | 実行IDの割り当て最大数を指定します。 | 整数値を指定してください。 省略した場合「10000」が設定されます。(デフォルト) 推奨はデフォルト値です。 [min.execution.id]+[max.execution.number]が実行IDの最大値になります。

## 仕様制限

- 削除時の監視イベントで発火したトリガーは、ステータスカラムの更新のみ行い、レコードは削除しません。
  必要であれば、後続の処理で[削除状態]の値が設定されたレコードの削除を行ってください。
- トリガー発火時に実行スクリプトに渡されるXMLデータは、監視イベントのステータス値を持ったレコードのデータになります。データモデルは「テーブルモデル型」です。
  例:「カラム1」「カラム2」「ステータスカラム」という3つのカラムで定義されたテーブルの場合、実行スクリプトに渡されるデータは以下の通りです。

      <table>
        <row>
          <column>カラム1の値</column>
          <column>カラム2の値</column>
          <column>ステータスカラム値</column>
        </row>
          :
      </table>

- [監視間隔]で指定した時間よりも実行スクリプトの処理の時間が長い場合、その処理が終了した直後にステータスカラムの監視を再開します。
  (その場合、スクリプトの実行間隔が監視間隔となります。)
  つまり、トリガー実行中の場合は対象テーブルに監視イベントが発生しても、そのイベントは検知されません。

## 主な例外

ありません。

## 注意事項

- トリガーの登録後、トリガーに設定されているサービスやスクリプトの状態が変更された場合(サービス名・スクリプト名の変更や、スクリプト変数の追加・削除など)、登録済みのトリガーにその変更は反映されません。
  対象のトリガーのプロパティ設定ダイアログを開き、サービスやスクリプトの再選択を行ったあと[完了]ボタンを押下して再登録してください。
- スクリプト終了時のステータスの変更に失敗する場合があります。
  - 例:データベースへの接続ができない
    →サーバコンソールおよびserver.logにエラーが出力されます。
  - 例:変更対象のレコードがロックされている
    →更新を行わず、トリガーの処理が終了します。
- 名前にマルチバイト文字や機種依存文字を含むカラムを[ステータスカラム]に使用する場合は、カラム名を引用符で囲んでください。
  引用符はデータベースによって異なります。引用符の定義については、各データベースベンダーに問い合わせてください。
- [接続]に使用できるグローバルリソースの種別は「デフォルト」のみとなります。