トリガの使用法

トリガの定義

特定のテーブルにトリガを定義するには、以下のような方法があります。

• SQL テーブルに投影される永続クラス定義にトリガ定義を含めます。例えば、MyApp.Person クラスのこの定義には LogEvent トリガの定義が含まれます。これは、MyApp.Person テーブルへのデータの INSERT が成功するたびに呼び出されます。

  Class/ObjectScript Class/Python

  Class MyApp.Person Extends %Persistent [DdlAllowed]
  {
      // ... Class Property Definitions
  
      Trigger LogEvent [ Event = INSERT, Time = AFTER ]
      {
          // Trigger code to log an event 
      }
  }

  

  Class MyApp.Person Extends %Persistent [DdlAllowed]
  {
      // ... Class Property Definitions
  
      Trigger LogEvent [ Event = INSERT, Time = AFTER, Language = python ]
      {
          // Trigger code to log an event 
      }
  }
  

  

  詳細は、"トリガ定義" を参照してください。

• SQL CREATE TRIGGER コマンドを使用して、トリガを作成します。これにより、対応する永続クラスでトリガ・オブジェクト定義が生成されます。SQL トリガ名は、識別子の名前付け規約に従います。InterSystems IRIS® データ・プラットフォームでは、SQL トリガ名を使用して対応するトリガ・クラス・エンティティ名を生成します。

トリガを作成するには、%CREATE_TRIGGER 管理者レベル特権が必要です。トリガを削除するには、%DROP_TRIGGER 管理者レベル特権が必要です。

1 つのクラスのユーザ定義トリガの最大数は 200 です。

トリガのタイプ

トリガは、以下によって定義します。

• トリガの実行の要因となるイベントのタイプ。トリガには、シングルイベント・トリガとマルチイベント・トリガがあります。シングルイベント・トリガは、指定したテーブルで INSERT、UPDATE、または DELETE のいずれかのイベントが発生したときに実行するように定義します。マルチイベント・トリガは、指定したテーブルで、指定した複数のイベントのいずれか 1 つが発生したときに実行するように定義します。クラス定義または CREATE TRIGGER コマンドを使用して、INSERT/UPDATE、UPDATE/DELETE、または INSERT/UPDATE/DELETE のマルチイベント・トリガを定義できます。イベントのタイプは、クラス定義で、必須の Event トリガ・キーワードによって指定します。

• トリガを実行するタイミング。イベント発生の前 (Before) または後 (After) です。これは、クラス定義で、オプションの Time トリガ・キーワードによって指定します。既定値は Before です。

• 同一のイベントやタイミングに複数のトリガを関連付けることができます。この場合、複数のトリガが起動される順番を Order トリガ・キーワードを使用して制御できます。Order 値が低いトリガから順番に動作します。複数のトリガが同じ Order 値を持つ場合は、動作する順番は不定になります。

• オプションの Foreach トリガ・キーワードを使用すると、よりきめ細かく制御できます。このキーワードは、トリガを行ごとに 1 回起動するか (Foreach = row)、行またはオブジェクトにアクセスするたびに 1 回起動するか (Foreach = row/object)、または文ごとに 1 回起動するか (Foreach = statement) を制御します。Foreach トリガ・キーワードが定義されていないトリガは、行ごとに 1 回起動します。Foreach = row/object を使用してトリガが定義されている場合、このドキュメントの後半で説明するように、トリガはオブジェクト・アクセスの特定の時点でも呼び出されます。INFORMATION.SCHEMA.TRIGGERSOpens in a new tab の ACTIONORIENTATION プロパティを使用して、各トリガの Foreach 値をリスト表示できます。

トリガ・キーワードの完全なリストは、"クラス定義リファレンス" を参照してください。

次の表に、使用できるトリガおよび対応するコールバック・メソッドを示します。

トリガとコールバック・メソッドは類似していますが、実行されるタイミングが異なる場合があります。

• トリガは、格納されているデータの変更の直前または直後に実行されます。

• コールバック・メソッドは、コールバックのタイプに応じて、%SaveData() または %DeleteData() メソッドの前か後に実行されます。したがって、オブジェクトの前の %OnBeforeSave() メソッドはロックするか、そうでなければ参照アクションによって変更されます。

詳細は、"InterSystems SQL リファレンス" の "CREATE TRIGGER" を参照してください。

ObjectScript トリガ・コード

各トリガには、トリガされたアクションを実行する 1 行以上のコードが含まれます。このコードは、トリガが定義されたイベントが発生した場合、常に SQL エンジンによって呼び出されます。トリガが CREATE TRIGGER を使用して定義されている場合、このアクション・コードを ObjectScript または SQL で記述できます (InterSystems IRIS は、SQL で記述されたコードをクラス定義の ObjectScript に変換します)。スタジオや VS Code などの IDE で定義したトリガの場合、このアクション・コードは ObjectScrip で記述する必要があります。

トリガのコードはプロシージャとして生成されないため、トリガ内のすべてのローカル変数はパブリック変数となります。システム変数 %ok、%msg、%oper (次のセクションで説明します) を除き、トリガに使用するすべての変数を NEW 文で明示的に宣言する必要があります。これにより、トリガを起動するコードで変数どうしが競合することを防止できます。

{fieldname} 構文

トリガ・コード内で、特別な {fieldname} 構文を使用して、(トリガが関連付けられているテーブルに属するフィールドの) フィールド値を参照できます。例えば、MyApp.Person クラスの LogEvent トリガの以下の定義には、ID フィールドへの参照が {ID} として含まれます。

Class MyApp.Person Extends %Persistent [DdlAllowed]
{
    // ... Definitions of other class members

    /// This trigger updates the LogTable after every insert
    Trigger LogEvent [ Event = INSERT, Time = AFTER ]
    {
        // get row id of inserted row
        NEW id,SQLCODE
        SET id = {ID}

        // INSERT value into Log table
        &sql(INSERT INTO LogTable 
            (TableName, IDValue) 
            VALUES ('MyApp.Person', :id))
        IF SQLCODE<0 {SET baderr="SQLCODE ERROR:"_SQLCODE_" "_%msg
                      SET %ok=0
                    RETURN baderr }

      }
   // ... Definitions of other class members

}

この {fieldname} 構文は、単一フィールドをサポートしています。%SerialObject コレクション・プロパティはサポートしていません。例えば、テーブルがプロパティ City を含む、埋め込みのシリアル・オブジェクト・クラス Address を参照する場合、トリガ構文 {Address_City} はフィールドへの有効な参照です。トリガ構文 {Address} はコレクション・プロパティへの参照であり、使用できません。

トリガ・コード内のマクロ

トリガ・コードには、フィールド名を参照するマクロ定義を含めることができます ({fieldname} 構文を使用)。ただし、{fieldname} 構文を使用してフィールド名を参照するマクロに対して #include プリプロセッサ指示文をトリガ・コードで使用している場合、そのフィールド名にはアクセスできません。これは、InterSystems IRIS がトリガ・コード内の {fieldname} 参照を、そのコードがマクロ・プリプロセッサに渡される前に変換するためです。#include ファイルの中で使用している {fieldname} 参照は、トリガ・コードで認識されないので変換されません。

この状況を回避するには、引数を指定してマクロを定義してから、トリガ内のマクロに {fieldname} を渡します。例えば、#include ファイルに、以下のような行を記述できます。

#define dtThrowTrigger(%val) SET x=$GET(%val,"?")

次に、{fieldname} 構文を引数として指定して、トリガ内でマクロを呼び出します。

  $$$dtThrowTrigger({%%ID})   

{name*O}、{name*N}、および {name*C} トリガ・コード構文

UPDATE トリガ・コードでは 3 種類の ObjectScript 構文ショートカットを使用できます。

以下の構文を使用して古い (更新前の) 値を参照できます。

{fieldname*O}

ここで、fieldname はフィールドの名前で、アスタリスクの後ろの文字はアルファベットの “O” です (Old を意味しています)。INSERT トリガの場合は、{fieldname*O} は必ず空文字列 ("") となります。

以下の構文を使用して新しい (更新後の) 値を参照できます。

{fieldname*N}

ここで、fieldname はフィールドの名前で、アスタリスクの後ろの文字はアルファベットの “N” です (New を意味しています)。この {fieldname*N} 構文は、格納される値を参照するためにのみ使用できます。値を変更するためには使用できません。トリガ・コードに {fieldname*N} を設定することはできません。INSERT または UPDATE でのフィールド値の計算は、SqlComputeOnChange などの他の方法で実行する必要があります。

以下の構文を使用して、フィールド値が変更 (更新) されたかどうかをテストできます。

{fieldname*C}

ここで、fieldname はフィールドの名前で、アスタリスクの後ろの文字はアルファベットの “C” です (Changed を意味しています)。{fieldname*C} は、フィールドが変更されているときは 1、変更されていないときは 0 となります。INSERT トリガの場合は、InterSystems IRIS によって {fieldname*C} が 1 に設定されます。

ストリーム・プロパティがあるクラスでは、SQL 文 (INSERT または UPDATE) がストリーム・プロパティ自体を挿入または更新しなかった場合は、ストリーム・プロパティ {Stream*N} および {Stream*O} への SQL トリガ参照では、ストリームの OID が返されます。ただし、SQL 文がストリーム・プロパティを挿入または更新した場合は、{Stream*O} は OID のままですが、{Stream*N} 値は以下のいずれかに設定されます。

• BEFORE トリガは、UPDATE または INSERT に渡された形式を問わず、ストリーム・フィールドの値を返します。これは、ストリーム・プロパティに入力されたリテラル・データ値か、一時ストリーム・オブジェクトの OREF または OID となります。

• AFTER トリガﾞは、ストリームの ID を {Stream*N} 値として返します。これは、InterSystems IRIS によって、そのストリーム・フィールドのためにグローバルな ^classnameD 内に格納される ID 値です。この値は、そのストリーム・プロパティの CLASSNAME 型パラメータに基づく適切な ID 形式となります。

ストリーム・プロパティが、InterSystems IRIS オブジェクトを使用して更新される場合は、{Stream*N} 値は必ず OID となります。

Note:

シリアル・オブジェクトの配列コレクションによって作成された子テーブルのトリガの場合、トリガ・ロジックはオブジェクト・アクセス/保存で機能しますが、SQL アクセス (INSERT または UPDATE) では機能しません。

Python トリガ・コード

組み込みの Python を含むトリガ・ブロック内で、そのトリガに関連する属性とメソッドを含む trigger オブジェクトにアクセスできます。これらの属性にはアクセス可能です。これらの詳細は、"トリガのタイプ" を参照してください。

• trigger.type — 有効な値は "row/object" と "row" です。

• trigger.operation — 有効な値は "BEFORE"、"UPDATE"、および "DELETE" です。

• trigger.time — 有効な値は "before" と "after" です。

トリガ・オブジェクトは、テーブル・フィールドにアクセスできる getfield() メソッドも適用します。以下のオプションを指定できます。

• trigger.getfield(fieldName) は、指定されたフィールド fieldName の値を返します。トリガ操作でフィールド値が変更されると、getfield() は新しい値を返します。

• trigger.getfield(fieldName, new) は、ブーリアン値 new を使用して新しいフィールド値と元のフィールド値のどちらを返すかを決定します。

  • new = 1 (既定) の場合、getfield() はトリガ操作で生じた新しい値を返します。このオプションは、INSERT 演算子と UPDATE 演算子に適用されます。

  • new = 0 の場合、getfield() は、トリガ操作の前の値を返します。このオプションは、UPDATE 演算子と DELETE 演算子に適用されます。

この例では、trigger オブジェクトを使用して、Name フィールドの名前変更というトリガ操作の結果をログ・ファイルに書き込みます。Python コードと対応する ObjectScript コードの両方を示します。

Python ObjectScript

Trigger LogRename [ Event = UPDATE, Foreach = row/object, Language = python, Time = AFTER ]
{
    with open('C:/temp/log.txt', 'a+') as file:
        file.write("Rename Event Occurred")
        file.write("\nID: " + str(trigger.getfield("ID")))
        file.write("\nOperation: " + trigger.operation)
        file.write("\nOld Name: " + trigger.getfield("Name", 0))
        file.write("\nNew Name: " + trigger.getfield("Name", 1) + "\n\n")
}

Trigger LogRename [ Event = UPDATE, Foreach = row/object, Time = AFTER ]
{
    set file = "C:/temp/log.txt"
    open file:("EWA") use file
    write "Rename Event Occurred"
    write !,"ID: "_{ID}
    write !,"Operation: "_{%%OPERATION}
    write !,"Old Name: "_{Name*O}
    write !,"New Name: "_{Name*N},!!
    close file
}

トリガのプル

そのテーブルに対応する DML コマンドが呼び出されると、定義されたトリガが "プル" (実行) されます。

DML コマンドが正常に挿入、更新、または削除した行ごとに、行レベルまたは行/オブジェクト・レベルのトリガがプルされます。

正常に実行される INSERT、UPDATE、または DELETE 文ごとに、文レベルのトリガが 1 回プルされます。文によってテーブル・データの行が実際に変更されるかどうかは関係ありません。

• INSERT 文は、対応する INSERT トリガをプルします。INSERT は、%NOTRIGGER キーワードを指定することにより、この対応するトリガのプルを阻止できます。%NOJOURN キーワードを指定する INSERT は、挿入または対応する INSERT トリガをジャーナリングしません。つまり、挿入イベントでもトリガ・イベントでもロールバックはできません。

• UPDATE 文は、対応する UPDATE トリガをプルします。UPDATE は、%NOTRIGGER キーワードを指定することにより、この対応するトリガのプルを阻止できます。%NOJOURN キーワードを指定する UPDATE は、更新または対応する UPDATE トリガをジャーナリングしません。つまり、更新イベントでもトリガ・イベントでもロールバックはできません。

• INSERT OR UPDATE 文は、実行する DDL 操作のタイプに応じて、対応する INSERT トリガまたは UPDATE トリガをプルします。どちらのタイプのトリガもプルしないようにするには、%NOTRIGGER キーワードを指定します。

• DELETE 文は、対応する DELETE トリガをプルします。DELETE は、%NOTRIGGER キーワードを指定することにより、この対応するトリガのプルを阻止できます。%NOJOURN キーワードを指定する DELETE は、削除または対応する DELETE トリガをジャーナリングしません。つまり、削除イベントでもトリガ・イベントでもロールバックはできません。

• TRUNCATE TABLE 文は、DELETE トリガをプルしません。

既定では、DDL 文および対応するトリガされたアクションはジャーナリングされます。%NOJOURN キーワードは、DDL コマンドとトリガされたアクションの両方のジャーナリングを阻止します。

トリガとオブジェクト・アクセス

Foreach = row/object を使用してトリガが定義されている場合、トリガ定義の Event および Time キーワードに応じて、トリガは以下のようにオブジェクト・アクセスの特定の時点でも呼び出されます。

この結果、SQL とオブジェクトの動作の同期を維持するためにコールバック・メソッドを実装する必要もなくなります。

Foreach トリガ・キーワードについては、"クラス定義リファレンス" を参照してください。

トリガとトランザクション

トリガは、トランザクションの範囲内でトリガ・コードを実行します。トリガは、トランザクション・レベルを設定してから、トリガ・コードを実行します。トリガ・コードが正常に完了すると、トリガによってトランザクションがコミットされます。

AFTER INSERT 文レベルの ObjectScript トリガの使用では、トリガを %ok=0 にした場合、行の挿入は SQLCODE -131 エラーにより失敗します。自動トランザクションの設定によっては、トランザクション・ロールバックも発生する場合があります。SQL では、SET TRANSACTION %COMMITMODE commitmode オプションによってこの設定が制御されます。ObjectScript では、SetOption()Opens in a new tab メソッドの "AutoCommit" オプションによってこの設定が制御されます。SET status=$SYSTEM.SQL.Util.SetOption("AutoCommit",intval,.oldval) という構文が使用されます。次の表は、自動トランザクション設定がロールバックに与える影響を示します。対応する commitmode オプション (SQL に設定) と "AutoCommit" 整数値 (ObjectScript に設定) も示します。

このトリガにより、トリガ内の %msg 変数にエラー・メッセージが設定されます。このメッセージは発信者宛てに返され、トリガの失敗理由についての情報が提供されます。

%ok および %msg のシステム変数は、このドキュメントの “埋め込み SQL の使用法” の章の システム変数 のセクションで説明しています。

トリガのリスト

指定したテーブルに定義されているトリガは、管理ポータルの SQL インタフェース [カタログの詳細] にリストされます。このリストでは、各トリガの基本情報が表示されます。より詳細な情報をリスト表示するには、INFORMATION.SCHEMA.TRIGGERSOpens in a new tab を使用します。

INFORMATION.SCHEMA.TRIGGERSOpens in a new tab クラスは、現在のネームスペースで定義されているトリガをリスト表示します。INFORMATION.SCHEMA.TRIGGERSOpens in a new tab は、トリガごとにさまざまなプロパティをリストします。これには、トリガの名前、関連付けられたスキーマおよびテーブル名、EVENTMANIPULATION プロパティ (INSERT、UPDATE、DELETE、INSERT/UPDATE、INSERT/UPDATE/DELETE)、ACTIONTIMING プロパティ (BEFORE、AFTER)、CREATED プロパティ (トリガ作成タイムスタンプ)、および生成された SQL トリガ・コードの ACTIONSTATEMENT プロパティが含まれます。

CREATED プロパティでは、クラス定義が最後に変更されたときのトリガ作成タイムスタンプが得られます。このため、以後このクラスを使用すると (例えば、他のトリガを定義するために)、CREATED プロパティ値が意図せずに更新されることがあります。

この INFORMATION.SCHEMA.TRIGGERSOpens in a new tab 情報には、以下の例に示すように SQL クエリからアクセスできます。

SELECT TABLE_NAME,TRIGGER_NAME,CREATED,EVENT_MANIPULATION,ACTION_TIMING,ACTION_ORIENTATION,ACTION_STATEMENT 
FROM INFORMATION_SCHEMA.TRIGGERS WHERE TABLE_SCHEMA='Sample'