トリガ技術情報

連絡先情報

目次

概要

• ［参考］ <s0>スキーマレベルの整合性を強制する： </s0>、通常Mのアプリケーションで作成された データベーススキーマが暗に示されるまで、Mのアプリケーションは、アプリケーションのスキーマを維持し強制的に適用するために、ロジックを実装します。スキーマレベルの整合性の適用を強制するためにトリガを使用は、すべてのプロセスを、均一性のあるコード、増加するコードのモジュール、保守を呼び出すことを確実にします。
• ［参考］ <s0>1以上の非主キー(non-primary key)のインデックスの確保を、アプリケーションに許可します。</s0>たとえば、顧客IDを格納するグローバルノードへ更新する時のトリガは、名前のインデックスを確保できます。
• ［参考］ <s0>ビジネスロジックの実装： </s0>たとえば、アカウントの更新が、自動的に関連するアカウントへの更新をトリガすることができます。
• ［参考］ <s0>レプリケーションのトラフィックを削減： </s0>トリガ更新ではなく、 GT.Mレプリケーションストリームにのみトリガするアップデートを運ぶので、ネットワークトラフィックが削減されます。
• ［参考］ <s0>自動化アプリケーションは、ログや、ジャーナリングの更新や、歴史的な記録の維持を定義しました。 </s0>トリガは、これらを制御するために使用することができます。トリガは、これらを制御するために使用することができます。
• ［参考］ <s0>参照の整合性を実装： </s0>たとえば、トリガは、非アクティブアカウントによるの銀行取引におけるポスティングを防ぎ、ルール違反のメッセージを表示することができます。
• ［参考］ <s0>デバッグ： </s0>複数の同時アクセスがあるアプリケーションのデバッギングは難しい。［参考］ 不正なアクセスをトラップするために、グローバル変数の更新時に"watch points" を設定するために、トリガを使用することができます。［参考］ 例えば、アプリケーションで失敗があれば、あるグローバル変数のノードには不正確な値があるか、または、以前に設定される値は見えなくなります。トリガは、トラップするようなすべてのアクセスに使用することができます。
• データフローの実装に基づくプログラミングパラダイム 。トリガの実装自体が主な目的ではないが、データフローのプログラミングパラダイムを使用するアプリケーションの実装のために、それらを使用することができます。

トリガ定義ファイル

• トリガ署名 ：トリガ署名の構成：
• グローバル変数 ：このトリガが適用される特定グローバルの名前。
• 添字 ：のグローバル変数ノードの添字グローバルZWRITEコマンドと同じパターンを使用して指定の名前。
• Value: For commands that SET or update the value at a node, GT.M honors an optional pattern to screen for changes to delimited parts of the value.  A value pattern includes a piece separator and a list of pieces of interest.
• Command: There are three commands: SET, KILL and ZKILL (ZWITHDRAW is identical to ZKILL; the shorter name for the command is used when specifying triggers.  MERGE is logically treated as equivalent to a series of SET operations performed in a loop. GT.Mは、トリガ更新のようなグローバルマッチングSETするトリガ定義の$INCREMENT() を処理します。
• Trigger code:  A string containing M code that GT.M executes when application code updates,  including deletions by KILL and like commands, a global node with a matching trigger. 指定されたコードは、追加のルーチンやサブルーチンを呼び出すことができます。
  
  Note: Although the trigger code is a part of a trigger signature, GT.M uses a combination of global variable, subscripts, value, and command to find the matching trigger to invoke for a database update.
  
  
• ACID property modifiers for triggered database updates: Currently, GT.M merely performs a syntax check on this part of a trigger definition. GT.Mは、トリガしているデータベースの更新と、トランザクション セマンティクスを使用して実行されるトリガロジックによって生成されるすべての更新を保証します。 With the VIEW "NOISOLATION" command, GT.M transaction processing has long provided a mechanism for an application to inform the GT.M runtime system that it need not enforce Isolation. このような場合には、アプリケーションとスキーマのデザインは、いつの時点でも特別なグローバルでの更新ノードを1つのプロセスでのみを確保することによりアイソレーションを提供し、添字として$JOBを使用することをよく言います。This property anticipates a time when a trigger specification can provide NOISOLATION for particular nodes, in contrast to entire globals, and for every update to that node, in contrast to by process use of a VIEW command.  Currently, the GT.M runtime system enforces Consistency for application logic inside a transaction and for triggered updates. このプロパティは、トリガの仕様がランタイムシステムのアプリケーションに通知するアプリケーションを許可する時の時間を見込んでいて、スキーマデザインは、トリガとそのロジックに適した一貫性を保証します。したがって、そのタスクからのGT.Mランタイムシステムを切り離しています。
• Trigger Name: You can optionally specify a trigger name that uniquely identifies each trigger. GT.Mは、トリガのエラー報告と設定管理のためにトリガ名を使用します： 例えば、ZSHOW "S" は、スタック上の各トリガの名前を報告します。If you do not specify a trigger name, GT.M automatically generates one using the global name as a base.
  
  A user-specified trigger name is an alphanumeric string of up to 28 characters. アルファベット文字またはパーセント記号(%)で始まる必要があります。トリガ名は、GT.Mは、Mの名前（またはルーチン名）と同じ命名規則を使用しています。他のコンテキストでは、GT.Mは31文字でMの名前を切り捨てます。しかし、GT.Mは、エラーとして28文字以上のトリガ名を扱います。これは、トリガ名をトリガがユニークに識別し、切り捨てにより重複が起こる可能性があるからです。

Suppose you want to set up a trigger called TrigAcct on every s ^Acct("ID") to invoke the routine ^OpenAccount. Your trigger definition file may have an entry like +^Acct("ID") -command=S -xecute="do ^OpenAccount" -name=TrigAcct. The following diagram identifies the different parts of this trigger definition:

To apply this trigger definition file to GT.M, all you do is to load it using MUPIP TRIGGER -TRIGGERFILE or $ZTRIGGER(). GT.M would invoke trigger name TrigAcct on every Set operation on ^Acct("ID").  Internally, GT.M stores trigger TrigAcct in the same database file where ^Acct is stored. 

トリガ定義ファイル内のエントリの構文は次のとおりです： 
{-triggername|-triggername-prefix*|-*|{+|-}trigvn -commands=cmd[,...] -xecute=strlit1 [-[z]delim=expr][-pieces=[lvn=]int1[:int2][;...]] [-options={[no]i[solation]|[no]c[onsistencycheck]}...] [-name=strlit2]}

 

-triggername|-trigger-name-prefix*|-*	-triggername deletes a user-specified trigger name called triggername from the database.   -triggername* deletes all those user-defined triggers whose starting name match triggername.   -* deletes all triggers; if the MUPIP TRIGGER command does not specify -NOPROMPT , GT.M displays a warning and asks for user confirmation before deleting all triggers. If MUPIP TRIGGER command specifies -NOPROMPT and the definition file includes a -* line, GT.M deletes all the triggers without user confirmation. $ZTRIGGER() performs deletions -NOPROMPT.   +triggername issues an error; to add a new user-specified trigger name, use -name=strlit2.
{+|-}trigvn	trigvn is a global node on which you set up a trigger.    -trigvn deletes any triggers in the database that match the specified trigger.    +trigvn adds or replaces the specified trigger.  If the specified trigger exists (with a matching specification), MUPIP TRIGGER or $ZTRIGGER() treats the matching definition as a no-op, resulting in no database update.  If you want to specify more than one global node for the same trigger code, the following rules apply:   添字のためのパターンと範囲を使用できます。 添字のために、セミコロン(;) で区切られたリストを指定できます。 ポイント、範囲、パターンの組み合わせを含む選択リストを指定できますが、パターンは、範囲の両端で機能はできません。For example, :,"a":"d";?1U is a valid specification but :,"a":?1A is not.  各添字のローカル変数名を指定できます。For example instead of ^X(1,:,:), you can specify ^X(1,lastname=:,firstname=:). This causes GT.M to define local variables lastname and firstname to the actual second and third level subscripts respectively from the global node invoking this trigger. トリガコードは、ちょうど他のMローカル変数のように、これらの変数を使用できます。As described in the Trigger Execution Environment section, trigger code executes in a clean environment - as if all code is preceded by an implicit NEW – the implicit assignments apply only within the scope of the trigger code and don't conflict or affect any run-time code or other triggers. You cannot use the @ operator, unspecified subscripts (for example, ^A() or ^A(:,)) or local or global variable names as subscripts. グローバル変数名のパターンと範囲は使用できません。Therefore, you cannot set a trigger for ^Acct*. いくつかの非標準の照合順序を考慮するには、アプリケーション更新が最初にトリガを起動する時に、GT.Mは、グローバル固有の照合順序を使用して、文字列の添字の範囲を評価します。結果として、それは、MUPIP TRIGGERまたは$ZTRIGGER() からではなく実行時に範囲の問題を検出し報告するので、適切にテストします。たとえば、GT.Mは、（ASCII）C:A のような反転する添字の範囲にランタイムエラーを報告します。
-command=cmd	cmd is the trigger invocation command. Currently, you can specify one or more of S[et], K[ill] or ZK[ill]. A subsequent GT.M release may support ZTK[ill] for triggering on descendent nodes of a KILLed ancestor, but, while current versions accept ZTK, they convert it into K.   If cmd specifies multiple command values, GT.M treats each M command as a separate trigger. Note that even if you specify both SET and KILL, only one M command matches at any given time. Trigger code is not executed in the following conditions:   存在しないノードのKILLの場合 A KILL of a node that has a cmd=ZK trigger, but no cmd=K trigger. A ZKILL or ZWITHDRAW of a node that has descendents but no data and a trigger with cmd=ZK. トリガは、 "piece" 構文（後述）を使用し、更新中にトリガ部分を変更しません。 The duplicate SET optimization is enabled (that is, the environment variable gtm_gvdupsetnoop is set to 1|True|Yes) and a SET command causes no change in the value of a preexisting node.
-xecute="strlit1"	strlit1 specifies the trigger code executed when an update matches the trigvn. Note that strlit1 is a quoted string literal and quotes inside strlit1 are doubled as in normal M syntax.  To validate strlit1, MUPIP TRIGGER or $ZTRIGGER() compiles it before applying the trigger definition to the database and issues a TRGCOMPFAIL error if it contains any invalid code. Note: Trigger compilation detects compilation errors, but not run-time errors. Therefore, you should always test your trigger code before applying trigger definitions to the database Warning: As stated in the Trigger Definition File section, the text of trigger code is a part of the trigger signature. If you use two trigger signatures that have the same semantics (global variable, subscript, value, and command) but different text (for example: set foo=$ztoldval, s foo=$ztoldval, and set foo=$ztol), their signatures become different and GT.M treats them as different triggers. FIS recommends you to use comprehensive and strong coding conventions for trigger code or rely on user-specified names in managing the deletion and replacement of triggers.
[-pieces=int1[:int2][;...]]	If cmd is S[et], you can specify an optional piece list sequence where int2>int1 and int1:int2 denotes a integer range from int1 to int2. 指定された部分リストの変更から任意の部分の場合のみ、トリガが実行されます。Suppose your trigvn has a list "Window|Chair|Table|Door" and you want to execute the trigger only when the value of the 3rd or 4th piece changes so you might specify the following trigger definition:   +^trigvn -commands=S -pieces=3;4 -delim="|" -options=NOI,NOC -xecute="W ""3rd or 4th element updated."""   GTM>W ^trigvn Window|Chair|Table|Door| GTM>s $P(^trigvn,"|",3)="Dining Table" 3rd or 4th element updated. もし最初の要素を変更した場合、このトリガは実行されません。次に例を示します。   S $P(^trigvn,"|",1)="Chandelier" トリガを呼び出しません。   また、部分シーケンスの範囲を指定することもできます。たとえば、3:5;7;9:11 は3から5、7、9、11 でトリガを指定します。GT.Mは、任意の重複値または範囲をマージします - 例えば、 3:6;7 は 3:7と同じです。
[-[z]delim=expr]	If cmd is S[et], you can specify an optional piece delimiter using -[z]delim=expr where expr is a string literal or an expression (with very limited syntax) evaluating to a string separating the pieces (e.g., "|") in the values of nodes, and is interpreted as an ASCII or UTF-8 string based on the $gtm_chset environment variable.  To allow for unprintable delimiters in the delimiter expression, MUPIP TRIGGER only accepts  $Char() and $ZChar()  and string concatenation (_) as embellishments to the string literals.  If zdelim specifies a delimiter, GT.M uses the equivalent of $ZPiece() to match pieces and to identify changes in $ZTUPDATE() (refer to the ISV description for additional information); otherwise, if delim specifies a delimiter, GT.M uses the equivalent of $Piece() for the current mode (M or UTF-8). Specifying a delimiter for cmd other than S[et] or specifying both delim and zdelim for the same trigger each produce an error.
[-options={no]i[solation]|[[no]c[onsistencycheck]}...	You can specify [NO] ISOLATION or [NO]CONSISTENCYCHECK as a property of the triggered database updates. NOISOLATION is a facility for your application to instruct GT.M where the application logic and database schema take responsibility for ensuring the ACID property of ISOLATION, and that any apparent collisions are purely coincidental from multiple global nodes resident in the same physical block which serves as the GT.M level of granularity in conflict checking. In the current release this trigger designation is notational only - you must still implement NOISOLATION at the process level with the VIEW command, but you can use the trigger designation in planning to move to schema-based control of this facility. NOCONSISTENCYCHECK is a facility for your application to instruct GT.M that application logic and schema take responsibility for ensuring the ACID property of CONSISTENCY. The [NO]CONSISTENCYCHECK feature is not yet implemented and will be made available in a future GT.M release. For now, you can plan to move CONSISTENCY responsibility from your application to a trigger and implement it later when this feature becomes available. Note: -options are not part of the trigger signature and so can be modified without deleting an existing trigger.
[-name=strlit2]	strlit2 is a user-specified trigger name. 28文字までの英数字文字列です。［参考］ ［参考］ アルファベット文字またはパーセント記号（％）で始まる必要があります。 ［参考］ Note: -options are not part of the trigger signature and so can be modified without deleting an existing trigger. Note also that the name can be used to delete a trigger - this alternative avoids potential issues with text variations in the code associated with the -xecute qualifier which is part of the trigger signature when the variations don't have semantic significance.

 

トリガのISVs

簡単な例

1. Using your editor, create a trigger definition file called triggers.trg¹with the following entry:
   +^CIF(acn=:,1) -delim="|" -pieces=2 -commands=SET,KILL -xecute="Do ^XNAMEinCIF"
   In this definition:
   ^CIF - specifies the global variable to which the trigger applies.
   acn=: - in ZWRITE syntax, ":" specifies any value for the first subscript, and the acn= prefix requests GT.M assign the value of the first subscript (ACN) to the local variable acn before invoking the trigger logic.
   1 - specifies that the trigger matches only if the second subscript is 1 (one).
   -delim="|" - specifies that GT.M use "|"  as the piece separator when checking the value of the node to see whether to invoke the trigger.  Use of the keyword delim tells GT.M to use $PIECE() semantics for the value at the node; zdelim, instead, would instruct GT.M to use $ZPIECE() semantics.
   -pieces=2 - specifies that GT.M should only invoke the trigger when the update changes the second piece (XNAME) not for a change to the first piece (NAM), or any other piece without a change to XNAME.
   -commands=SET,KILL - specifies that GT.M invoke the trigger for SET and KILL updates (but not a ZKILL/ZWITHDRAW command).
   -xecute="Do ^XNAMEinCIF" - provides code for GT.M to invoke to perform the trigger logic.
   
   
2. 次のようなコマンドを実行します：
   $ mupip trigger -triggerfile=triggers.trg
   このコマンドは ^CIF(:,1) にトリガを追加します。
   トリガのロードが成功して、このコマンドは、次のような出力が表示されます：
   File triggers.trg, Line 1: ^CIF trigger added with index 1
   =========================================
   1 triggers added
   0 triggers deleted
   0 trigger file entries not changed
   0 triggers modified
   =========================================
   Now, every S[et] and K[ill] operation on the global node ^CIF(:,1) executes the routine XNAMEinCIF.
   
   
3. エディタを使用して、次のコードで XNAMEinCIF.m をコールするMルーチンを作成します。 
   XNAMEinCIF ; Triggered Update for XNAME change in ^CIF(:,1)
       Set oldxname=$Piece($ZTOLDval,"|",2) Set:'$Length(oldxname) oldxname=$ZChar(254)    ; old XNAME 
       Kill ^XALPHA("A",oldxname,acn)                                                      ; remove any old xref 
       ; コマンドがSetされているなら、新しいクロスリファレンスを作成
       Do:$ZTRIggerop="S" 
       . Set xname=$Piece($ZTVALue,"|",2) Set:'$Length(xname) xname=$ZChar(254)            ; new XNAME
       . Set^XALPHA("A",xname,acn)=""                                                      ; create new xref
   ;
   When the XNAME piece of a ^CIF(:,1) node is SET to a new value or KILLed, we delete the existing cross references.  The deletion can be unconditional, because if the node did not previously exist, then the KILL is a no-op.  If the command is a SET, we create new cross references.  From the definition of the schema, the code uses the following values:

• acn - GT.M sets variable acn to the value of the first subscript of the ^CIF() node matching the trigger specification.
• the code sets the variable oldxname to the prior value of the node, from the ISV $ZTOLDVAL and if that is null (has zero length), substitutes the byte $ZCHAR(254).
• the code SETs the variable xname to the new value of the node, from the ISV $ZTVALUE or to $ZCHAR(254) if that is null.
  
  

トリガ定義の保存

トリガ呼出と実行のセマンティクス

GT.Mは、そのグローバル変数のためのデータベースファイル内の各グローバル変数のためにトリガを保存します。 When a global directory maps a global variable to its database file, it also maps triggers for that global variable to the same database file.  When an extended reference uses a different global directory to map a global variable to a database file, that global directory also maps triggers for that global variable to that same database file.

Although triggers for Set and Kill / ZKill commands can be specified together, the command invoking a trigger is always unique. The ISV $ZTRIggerop provides the trigger code which matched the triggering command.

コマンドがグローバル変数を更新するたびに、GT.Mランタイムシステムは、最初にそのグローバル変数にトリガがあるかどうかを決定します。 If there are any triggers, it scans the signatures for subscripts and node values to identify matching triggers.  If multiple triggers match, GT.M invokes them in an arbitrary order.  Since a future version of GT.M, potentially multi-threaded, may well choose to execute multiple triggers in parallel, you should ensure that when a node has multiple triggers, they are coded so that correct application behavior does not rely on the order in which they execute.

When a process executes a Kill, Zkill or Set command, the target is the global variable node specified by the command argument for modification.  With Set and ZKill, the target is a single node.  In the case of Kill, the target may represent an entire sub-tree of nodes.  GT.M only matches the trigger against the target node, and only invokes the trigger once for each Kill command.  GT.M does not check nodes in sub-trees to see whether they have matching triggers.

Kill / ZKill

If Kill or ZKill updates a global node matching a trigger definition, GT.M executes the trigger code when a database state change has been computed but before it has been applied in the process space or the database. KILLされるべきノードと（もしあれば）下位ノードがトリガコードに表示されたままになることを意味します。KILLトリガーが$ZTVALUEを無視することに注意してください。

Set

• ログまたはジャーナルエントリが、更新と同じノードの別の部分に格納する必要があるかもしれません、または
• 更新されているノードは、、標準的な形式（例えば、それが実際に入力された方法にかかわらず、すべて大文字や標準化された句読点のような）で格納されたそのデータを必要とするか、または、その値が範囲に制限があるかもしれません。

GT.Mは、データソースの照合順序で実行されるSETコマンドのシリーズとしてMERGEコマンドを扱います。 GT.M checks each global node updated by the MERGE for matching triggers.  If GT.M finds one or more matches, it invokes all the matching trigger(s) before the next command or the next set argument to the same SET command.

GT.Mは、SETコマンドとして$INCREMENT() 関数を扱います。 Since the result of a $INCREMENT() operation must be numeric, if the trigger code modifies $ZTVALUE, at the end of the trigger, GT.M applies the value of +$ZTVALUE (that is, $ZTVALUE coerced to a number) to the target node.

トリガの実行環境

上述したように、もし複数のマッチングのトリガがある場合は、GT.Mプロセスは、マッチングのトリガのリストを作り、そして、予測可能性の保証なしで任意の順序でそれらを実行します。

各マッチングトリガ：

1. GT.Mプロセスは、ネイキッド リファレンス、$REFERENCE、$TEST、ZTOLDVAL、$ZTDATA、ZTRIGGEROP、$ZTUPDATEと、すべてのローカル変数のNEWなどを、暗黙的にスタックします。At the beginning of trigger code execution, $REFERENCE, $TEST and the naked indicator initially retain the values they had just prior to being stacked (in the case of KILL/ZKILL, to the reference of the KILL/ZKILL command, even though the trigger executes prior to the removal of any nodes).  If an update directly initiates multiple (chained) triggers, all start with identical values of the naked reference, $REFERENCE, $TEST, $ZTDATA, $ZTLevel, $ZTOLDVAL and $ZTRIGGEROP.  This facilitates triggers that are independent of the order in which they run.  Application logic inside triggers can use $REFERENCE, the read-only intrinsic special variables $ZTDATA, $ZTLEVEL, $ZTOLDVAL, $ZTRIGGEROP & $ZTUPDATE, and the read-write intrinsic special variables $ZTVALUE, and $ZTWORMHOLE.
   
2. GT.Mは、トリガのコードを実行します。Note that in the course of executing this GT.M trigger, if the same trigger matches again for the same or a different target, GT.M reinvokes the trigger recursively.  In other words, the same trigger can be invoked more than once for the same command.  Note that such a recursive invocation is probably a pathological condition that will eventually cause a STACKCRIT error. トリガはの最大127レベルまでネストし、その後は、ネストへ追加する試みは、MAXTRGRNESTエラーを生成します。
   
3. コードが完了すると、GT.Mは、ローカル変数をクリアし、$ZTVALUEを除いて （$ZTVALUEの変更でのコメントについてはISVの定義を参照）、それらがトリガの開始時にあった値にスタックしたものをレストアし、そして、オリジナルの更新にマッチングする残りのトリガのいずれかが存在する場合、$ZTUPDATEを調整し、その次のアクションを実行します。$ZTVALUEは、アプリケーションのアップデートが最初にトリガを起動しているノードの現在のターゲット値を、常に保持します。同じノードの複数のトリガは任意の順序で実行するので、$ZTVALUEを変更する1つ以上のトリガを持つには、設計と実装には注意を必要とすることに注意してください。

すべてのトリガを実行した後、GT.Mは、トリガアップデートだけでなくトリガ開始の操作をコミットし、そして、次のコマンドで実行を継続します（または、次のノードで、同じコマンドによって更新されている複数のノードの場合）。 Note that if the operation initiating the trigger is itself within a transaction, other processes will not see the database state changes till the TCOMMIT of the outermost transaction.

トリガアクションがそれらを呼び出す更新に関してアトミックであることを確認するために、GT.Mは、トリガロジックとのトランザクション内でトリガアップデートを常に実行します。 If the triggering update is not within an application transaction, GT.M implicitly starts a restartable "Batch" transaction to wrap the original update and any triggers generated by the update.  In other words, when 0=$TLEVEL GT.M behaves as if implicit TStart *:Transactionid="BATCH" and TCommit commands bracket the upddate and its triggers. したがって、トリガコードおよび/またはそのエラートラップは、トランザクション内で常に動作し、もしメインアプリケーションコードがTSTARTを使用していない場合でも、TRESTARTコマンドを使用することができます。トリガで使用するための$ETRAPコードは、TROLLBACKロジックを含めることができます。

推奨されていないZTSTART / ZTCOMMITトランザクションは、トリガと互換性がありません。 If a ZTSTART transaction is already active when an update to a global that has any trigger defined occurs, GT.M issues a runtime error. 同様に、GT.Mは、エラーとしてトリガ コンテキスト内でZTSTARTを発行しようとする試みを扱います。

トリガ実行中のエラー処理

GT.Mは、トリガの実行中にエラーを処理する$ETRAPメカニズムを使用します。もしトリガ中にエラーが発生した場合、GT.Mは、$ETRAPのMコードを実行します。もし$ETRAPが$ECODEをクリアしない場合は、GT.Mは、トリガ内のデータベース更新をコミットせず、トリガアップデートの環境に制御を渡しません。もし$ETRAPアクションまたはそれが呼び出すロジックが$ECODEをクリアすると、GT.Mはトリガ ロジックの処理を続行することができます。

以下のささいな例を考えてみましょう：

During trigger execution if disc (the second subscript of the triggering update) evaluates to zero, resulting in a DIVZERO (Attempt to divide by zero) error, GT.M displays the message "Trigger Failed".  Since the $ETRAP does not clear $ECODE, after printing the message, GT.M leaves the trigger context and invokes the error handler outside the trigger, if any.  In a DIVZERO case, the process neither assigns a new value to ^Acct(id,disc) nor commits the incremented value of ^count to the database.

• 望ましい結果を達成するためにトリガロジックを変更するランタイム$ETRAPコード

• レプリケーションの設定は、初期設定と異なっている

• 初期化とレプリケーションインスタンス間のフィルタがエラーを導きます。

• 意図されていて、そして、$ETRAPのメカニズムは、異なった管理の不可欠な部分です。
• 意図されていない、そして、$ETRAPメカニズムは、異なった修正をするために、オペレーションチームに通知する助け、そして、レプリケーションを再起動する必要があります。 

トリガ機能はgtm_trigger_etrapと呼ばれる環境変数を導入しています。トリガのコンテキストで$ETRAPの初期値を提供し、mumpsとMUPIPプロセスの両方でトリガ操作用のエラートラップをセットするために使用できます。コードは、もちろん、トリガのコンテキスト内でSET $ETRAPもできます。もし gtm_trigger_etrap とトリガの失敗の値を指定しない場合、ランタイム トリガの動作時には、GT.Mは、現在のトラップハンドラを使用します。mumpsプロセスでは、もしトラップハンドラがトリガアップデートの時点で$ZTRAPがあった場合とgtm_trigger_etrap が定義されていない場合に、$ZTRAPがアンスタックでかつ有効になる前に、エラートラップは、トリガ ロジックとトリガアクションの両方の外側で終了する$ETRAP="" に暗黙的に置換されます。MUPIPプロセスでは、もしgtm_trigger_etrapとリガの失敗の値を指定しない場合、GT.Mは SET $ETRAP="If $ZJOBEXAM()" を、暗黙的に実行し、MUPIPプロセスを終了します。$ZOBEXAM()は、失敗の解析のための基礎を提供するファイルに診断情報（ZSHOW "*" に相当）を記録します。

重要：$ZJOBEXAM() は、関数の実行時にプロセスのコンテキストをダンプし、そして、出力は識別番号、クレジットカード番号などのような機密情報も含むことができます。MUPIPエラーハンドラによって生成されたファイルの場所をセキュアにすべきか、または、MUPIP操作のために適切なセキュリティ特性を設定する必要があります。代わりに、もし、$ZJOBEXAM() ファイルを作成するMUPIPを必要としない場合は、"Write !,$ZSTATUS,!,$ZPOSITION,! Halt" のようなハンドラを gtm_trigger_etrap 環境変数に明示的にセットします。Halt".

• トリガ用の$ZTRAPエラー処理メカニズムを使用しようとすることは、NOZTRAPINTRIGRエラーを生じさせます。

• もしアップデートを開始するトリガが、トランザクション($TLEVEL=0)の外側に発生した場合は、GT.Mは、アップデートの初期化とトリガ更新をラップするトランザクションを暗黙的に開始します。したがって、もしトリガのコンテキスト内でTROLLBACK または TCOMMIT が、トリガが起動（暗黙のTSTARTを含む）した時とは異なる$TLEVELを開始するアップデートを完了するために戻すコードを引き起こす場合に、GT.Mは、TRIGTLVLZEROエラーを発生し、オリジナルの更新をコミットしません。

• トリガ開始時にそれが何だったかの根底にある$TLEVELを取るTCOMMITは、TRIGTLVLCHNGエラーが発生します。この動作は、チェインかネストか特異かどうかは、トリガに適用されます。

• それは、GT.MがXECUTEの引数としてトリガコードを実行するように見えるかもしれません。しかしながら、パフォーマンス上の理由から、GT.Mは、擬似ルーチンにトリガコードを内部的に変換し、そして、ルーチンであるかのようにそれを実行します。 ほとんどの部分について、これは見えないが、トリガ名は、エラーメッセージと$STACK()の戻り値のような場所に表示することができます。

• トリガは、領域に関連付けられており、プロセスは、複数の領域にアクセスする1つ以上のグローバルディレクトリを使用できます、したがって、それは、名前の衝突を持っているトリガの可能性があります。To avoid a potential name conflict with other resources, GT.M attempts to add a two character suffix, delimited by a "#" character to the user-supplied or automatically generated trigger name. もし名前がユニークとなるための試みが失敗した場合は、GT.Mは、TRIGNAMEUNIQエラーを発行します。

• Defining gtm_trigger_etrap to hold M code of any complexity exposes mismatches between the quoting conventions for M code and shell scripts. FIS suggests an approach of enclosing the entire value in single-quotes and only escaping the single-quote (‘), exclamation-point (!) and back-slash (\) characters. 包括的な（しかし、うまくいけば非常に現実的ではありませんが）例えば：

  $ export gtm_trigger_etrap='write:1\'=2 $zstatus,\!,"5\\2=",5\\2,\!halt'
  $ echo $gtm_trigger_etrap
  write:1'=2 $zstatus,!,"5\2=",5\2,! halt
   
  GTM>set $etrap=$ztrnlnm("gtm_trigger_etrap")
  GTM>xecute "write 1/0"
  150373210,+1^GTM$DMOD,%GTM-E-DIVZERO, Attempt to divide by zero
  5\2=2

ZGOTO

トリガのトランザクション整合性を維持するために、そして、不適切な最終点に制御を分岐を避けるために、ZGOTOは次のように動作します：

1. それらはMUPIPコンテキストを置換する試みを形成するので、GT.Mは、MUPIPの ZGOTO 1:<entryref> 引数をサポートしません。 
   
2. ZGOTO引数が、トリガを開始したアップデートのレベル以下の entryref を指定した場合、GT.Mは、トリガ更新を実行せずに entryref に制御フローをリダイレクトします。GT.Mはnull 以外の$ECODEを見つける代わりに、それがトリガを完了することになる時に未処理のエラーを示し、オリジナルのトリガ更新をコミットするのではなく、現在のエラーハンドラへ制御を投げますします。
   
3. ZGOTO 0 はプロセスを終了して、トリガの呼び出しの外側である必要がありますベースのスタックフレームへのZGOTO 1を返します。 更新が発生したレベルがないentryrefを引数に指定してZGOTOは、更新自体に返すため、ランタイム·トリガのコンテキスト内からZGOTOは、直接（ように、トリガを起動したコマンドを含む行に、後続のMコマンドに到達することはできません$ ECODEがNULLの場合は、GT.Mは、任意の追加のトリガと行を再開する前にトリガ更新を処理を続行し、QUIT）となります。
   
4. ZGOTO from within a run-time trigger context cannot directly reach a subsequent M command on the line containing the command that invoked the trigger, because a ZGOTO with an argument specifying the level where the update originated but no entryref returns to the update itself (as would a QUIT) and, if $ECODE is null, GT.M continues processing with any additional triggers and the triggering update before resuming the line.

GT.CM

GT.CM servers do not invoke triggers. This means that the client processes must restrict themselves to updates which don't require triggers, or explicitly call for the actions that triggers would otherwise perform. Because GT.CM bypasses triggers, it may provide a mechanism to bypass triggers for debugging or complex corrections to repair data placed in an inconsistent state by a bug in trigger logic.

その他のユーティリティ

During MUPIP INTEG, REORG and BACKUP (including -BYTESTREAM), GT.M treats trigger definitions just as it treats any normal global node. 

Because they are designed as state capture and [re]establishment facilities, MUPIP EXTRACT does not extract trigger definitions and MUPIP LOAD doesn't restore trigger definitions or invoke any triggers. While you can construct input for MUPIP LOAD which bypasses triggers, there is no way for M code itself to bypass an existing trigger, except by using a GT.CM configuration. The $ZTRIGGER() function permits M code to adjust the triggers, including removing triggers, but those actions affect all processes updating the node associated with any trigger. Like MUPIP EXTRACT and LOAD, the ^%GI and ^%GO M utility programs do not extract and load GT.M trigger definitions. Unlike MUPIP LOAD, ^%GI invokes triggers just like any other M code, which may yield results other than those expected or intended.

ジャーナリングとデータベースのレプリケーションのトリガー  

GT.M handles "trigger definitions" and "triggered updates" differently.

• Trigger definition changes appear in both journal files and replication streams so the definitions propagate to recovered and replicated databases.
• Triggered updates appear in the journal file, since MUPIP JOURNAL RECOVER/ROLLBACK to not invoke triggers.  However, they do not appear in the replication stream since the Update Process on a replicating instance apply triggers and process their logic.

ジャーナリング

Legend (additions and changes):

A trigger associated with a global in a region that is journaled can perform updates in a region that is not journaled. However, if triggers in multiple regions update the same node in an unjournaled region concurrently, the replay order for recovery or rollback might differ from that of the original update and therefore produce a different result; therefore this practice requires careful analysis and implementation. Except when using triggers for debugging, FIS recommends journaling any region that uses triggers.

The following sample journal extract shows how GT.M journals records updates to trigger definitions and information on $ZWORmhole:

This journal extract output shows $ZTWORMHOLE information for each triggered update to ^trigvn. Notice how GT.M stored trigger definitions as a node of a global-like structure ^#t and how GT.M journals the trigger definition for ^trigvn and the triggered update for ^trgvn.

Note: GT.M implicitly wraps a trigger as an M transaction. Therefore, a journal extract file for a database that uses triggers has Type 8 and 9 (TSTART/TCOMMIT) records even if the triggers perform no updates (that is, are effectively No-ops).

MUPIP JOURNAL -RECOVER / -ROLLBACK

The lost and broken transaction files generated by MUPIP JOURNAL -RECOVER / -ROLLBACK contain trigger definition information. You can identify these entries + or - and appropriately deal with them using MUPIP TRIGGER and $ZTRIGGER().    

マルチサイトのデータベース レプリケーション

During replication, GT.M replicates trigger definitions to ensure that when MUPIP TRIGGER updates triggers on an initiating instance, all replicating instances remain logically identical.

The replication stream has no records for updates generated by implicit GT.M trigger logic. If your trigger action invokes a routine, specify the value of the gtmroutines environment variable before invoking replication with MUPIP so the update process can locate any routines invoked as part of trigger actions. 

To support upward compatibility, V5.4-000 allows your originating primary to replicate to:

• An instance with a different a trigger configuration.

• An instance running a prior GT.M version (having no trigger capability), in which case it replicates any triggered updates.

When a replicating instance needs to serve as a possible future originating instance, you must carefully design your replication filters to handle missing triggers or trigger mismatch situations to maintain logical consistency with the originating primary.

インスタンスに別のトリガ設定でレプリケート

During an event such as rolling upgrade, the replicating instance may have a new database schema (due to application upgrades) and in turn a new set of triggers.  Therefore, GT.M replication allows you to have different-trigger configuration for originating (primary) and replicating (secondary) instances.  When replication starts between the two instances, any update to triggers on the originating instance automatically flow (through the filters) to the replicating instance. For the duration of the rolling upgrade, your application must use replication filters to ensure trigger updates on the originating instance produce an appropriate action on the replicating instance.  However, whenever you follow the practice of creating replicating instances from backups of other appropriate originating instances, you do not have to use additional replication filters, because the backups include GT.M trigger definitions, under normal conditions instances automatically have the same triggers.

Because the replication stream carries the native key format, having different collation for a replicated global on the replicating node from that on the initiating node is effectively a schema change and requires an appropriate filter to appropriately transform the subscripts from initiating form to replicating form. This is true even without triggers. However, with triggers a mismatch also potentially impacts appropriate trigger invocation.

Because GT.M stores triggers in the database files as pseudo global variables, an application upgrade requiring a change to triggers is, in the worst case, no different than an application upgrade that changes the database schema, and can be handled under current rolling upgrade methods. Some changes to GT.M triggers may well be much simpler than a database schema change, and may not need a rolling upgrade. 

サポートしていないインスタンスにレプリケートトリガー

アップデートとヘルパープロセス

For any replication stream record indicating triggers were invoked, the Update Process scans for matching GT.M triggers and unconditionally executes the implicit GT.M trigger logic.

MUPIP TRIGGER and $ZTRIGGER()

MUPIP TRIGGER provides a facility to examine and update triggers. The $ZTRIGGER() function performs trigger maintenance actions analogous to those performed by MUPIP TRIGGER. $ZTRIGGER() returns the truth value expression depending on the success of the specified action. You choice of MUPIP TRIGGER or $ZTRIGGER() for trigger maintenance should depend on your current application development model and configuration management practices.   Both MUPIP TRIGGER and $ZTRIGGER() use the same trigger definition syntax. You should familiarize yourself with the syntax of an entry in a trigger definition file before exploring MUPIP TRIGGER and $ZTRIGGER().  

MUPIP トリガ

Examines or loads trigger definitions. The format of the MUPIP TRIGGER command is:

• Set the value of the environment variable gtmgbldir: to specify the value of a current global directory.
• Ensure that the key size, record size, block size of your database is sufficient for storing trigger definition. You may have to set the key and record sizes larger than the database content would otherwise require.

The qualifiers of the MUPIP TRIGGER command are as follows:

TRIGgerfile

Loads a trigger definition file to the database. The format of the TRIGGERFILE qualifier is:

• For information on the syntax and usage of a trigger definition file, see "Trigger Definition File".
• A MUPIP TRIGGER –TRIGGERFILE operation occurs within a transaction boundary, therefore, if even one trigger from the trigger definition file fails to parse correctly, MUPIP TRIGGER rolls back the entire trigger definition file load.
• MUPIP TRIGGER –TRIGGERFILE ignores blank lines and extra whitespace within lines. It treats lines with a semi-colon in the first position as comments and ignores their content.
• MUPIP TRIGGER compiles the XECUTE action string and rejects the load if the compilation has errors.
• Always specify the same value for the environment variable gtm_chset during loading and executing triggers. If you specify different values of gtm_chset during loading and executing triggers, MUPIP TRIGGER generates a run-time error (TRIGINVCHSET). GT.M does not prevent a process from updating different nodes with triggers using a different character set, however, GT.M prevents a process from updating the same triggering node with different character sets. Your coding practice, for all database updates, should be to ensure that you provide the same value for gtm_chset during load compilation and run-time compilation.
• Incompatible with: -SELECT 
  

SELEct

Provides a facility to examine the current trigger definition. SELECT produces a list of the current triggers for a comma-separate list of global variables or trigger names. The format of the SELECT qualifier is:

• Name-list can include global names, delimited with a leading up-arrow, (^) and/or trigger names with no leading up-arrow. You can specify a trailing asterisk(*) with either.
• With no arguments specified, GT.M treats -SELECT as –SELECT="*" and extracts a list of all current triggers.
• Optionally, you can specify a file name to redirect the output of the command. If you do not specify a file name, MUPIP TRIGGER prompts for a file name. If you respond with an empty string (RETURN), MUPIP TRIGGER directs the output to STDOUT.

MUPIPトリガーの例

1. Begin by executing the following command:
   $mupip trigger -select="^Acct*"
   Output file: 
2. Specify trigger_mod.trg as the output file. This file contains entries like the following:
   ;trigger name: ValidateAccount#  cycle: 1
   +^Acct("ID") -name=ValidateAccount -commands=S -xecute="Write ""Hello Earth!"""
3. Using your editor, open trigger_mod.trg and change + (plus) to - (minus) for the trigger definition entry for ValidateAccount and add a new trigger definition for ^Acct("ID"). To avoid inconsistent application behavior, it is important to replace an old trigger with a new one in the same transaction (Atomic). The trigger_mod.trg file should have entries like:
   ;trigger name:  ValidateAccount#    cycle: 1
   -^Acct("ID") -name=ValidateAccount -commands=Set -xecute="Write ""Hello Earth!"""
   ;trigger name: ValidateAccount#
   +^Acct("ID") -name=ValidateAccount -commands=Set -xecute="Write ""Hello Mars!""" 
4. 次のようなコマンドを実行します：
   $ mupip trigger -triggerfile=trigger_mod.trg

1. Begin by executing the following command: 
   $mupip trigger -select="^Acct*"
   Output file:
   
   
2. Specify trigger_delete.trg as the output file. This file contains entries like the following:
   ;trigger name: ValidateAccount#  cycle: 3
   +^Acct("ID") -name=ValidateAccount -commands=S -xecute="Write ""Hello Mars!"""
   
   
3. Using your editor, change + (plus) to - (minus) for the trigger definition entry for ValidateAccount. Alternatively, you can create a file with an entry like -ValidateAccount.  
   
   
4. Now, execute a command like the following:
   $ mupip trigger -triggerfile=trigger_delete.trg
   
   This command displays an output like the following: 

You have successfully deleted trigger "ValidateAccount".

1. Using your editor, create a new file called trigger_rename.trg and add a trigger definition entry for ValidateAcct with the same trigger signature as ValidateAccount. Your trigger definition would look something like: 
   +^Acct("ID") -name=ValidateAcct -commands=S -xecute="Write ""Hello Mars!"""
   
2. Verify that the ValidateAccount trigger exists by executing the following command:
   $mupip trigger -select="^Acct*"
   Output file:
   
3. Respond with an empty string (Press Enter). Confirm that the trigger summary report contains an entry like the following:
   ;trigger name: ValidateAccount#  cycle: 3
   +^Acct("ID") -name=ValidateAccount -commands=S -xecute="Write ""Hello Mars!"""
4. Now, execute a command like the following:
   $ mupip trigger -triggerfile=trigger_rename.trg
   
   This command displays an output like the following:
   =========================================
   0 triggers added
   0 triggers deleted
   0 trigger file entries not changed
   1 triggers modified
   =========================================
   You have successfully changed the trigger name ValidateAccount to ValidateAcct.
   
   

$ZTRIGGER

• $ZTRIGGER() returns the truth value expression depending on the success of the specified action.
• $ZTRIGGER() performs trigger maintenance actions similar those performed by MUPIP TRIGGER.  
• If expr1 evaluates to case-insensitive "FILE", $ZTRIGGER() evaluates expr2 as the location of the trigger definition file. Then, it applies the trigger definitions in the file specified by expr2 with no user confirmation in the case of a -*.
• If expr1 evaluates to case-insensitive "ITEM", $ZTRIGGER() evaluates expr2 as a single line trigger definition entry.
• If expr1 evaluates to case-insensitive "SELECT", $ZTRIGGER() evaluates the optional expr2 as a trigger name or name wildcard, and direct its output to $IO. A FALSE result indicates there are no matching triggers. 
• A $ZTRIGGER() within a TP transaction (0<$TLEVEL) produces a ZTRIGNOTP error. 

$ZTRIGGERの例は

ISVs and Environment Variables 

GT.M provides seven ISVs (Intrinsic Special Variables) to facilitate trigger operations. With the exception of $ZWORMHOLE, all trigger-related ISVs return zero (0) if they have numeric values or an empty string when referenced by code outside of a trigger context.

$ZTCOde

Within trigger context, $ZTCOde evaluates to a string containing the trigger code (that is, the string value for the –xecute in the trigger definition). Outside trigger context, $ZTCOde has the value of an empty string.

$ZTCode evaluates to Write "Hello Mars!" in the context of trigger in the following definition:

Note that even though the quotes inside the -xecute literal are doubled as in normal M, $ZTCode evaluates them as one quote, again as in normal M.

$ZTDAta

Within trigger context, $ZTDATA returns $Data(@$REFERENCE)#2 for a SET or $Data(@$REFERENCE) for a KILL, ZKILL or ZWITHDRAW prior to the explicit update. This provides a fast path alternative, avoiding the need for indirection in trigger code, to help trigger code determine the characteristics of the triggering node prior to the triggering update. For a SET, it shows whether the node did or did not hold data - whether a SET is modifying the contents of an existing node or creating data at a new node. For a KILL it shows whether the node had descendants and whether it had data.

$ZTLevel

Within trigger context, $ZTLevel returns the current level of trigger nesting (invocation by a trigger of an additional trigger by an update in trigger context).

Outside trigger context (no trigger active), $ZTLevel returns 0.

These trigger definitions show different values of $ZTLevel when two triggers are called recursively (and pathologically).

$ZTOLdval

Outside trigger context, $ZTOLDVAL has the value of an empty string.

$ZTRIggerop

$ZTSlate

$ZTSLATEは、最も外側のトランザクションに呼び出されたチェーンまたはネストのトリガで利用したい文字列を指定できます（TSTARTが0から1の$TLEVELを取る時）。You might use $ZTSLATE to accumulate transaction-related information, for example $ZTOLDVAL and $ZTVALUE,  available within trigger context for use in a subsequent trigger later in the same transaction. For example,  you can use $ZTSLATE to build up an application history or journal record to be written when a transaction is about to commit.

You can SET $ZTSLATE only while a database trigger is active. GT.M clears $ZTSLATE for the outermost transaction or on a TRESTART. However, GT.M retains $ZTSLATE for all sub-transactions (where $TLEVEL>1).

$ZTUPdate

+^trigvn -commands=Set -pieces=1;3:6 -delim="|" -xecute="Write !,$ZTUPDATE"

$ZTVAlue

For SET, $ZTVALUE has the value assigned to the node by the explicit SET operation. Modifying $ZTVALUE within a trigger modifies the eventual value GT.M assigns to the node. Note that changing $ZTVALUE has some performance impact as it causes an additional update operation on the node once all trigger code completes. If a node has multiple associated triggers each trigger receives the current value of $ZTVALUE, however, because the triggers run in arbitrary order, FIS strongly recommends no more than one trigger change any given element of application data, for example, a particular piece. For KILL and its variants, $ZTVALUE returns the empty string "". While GT.M accepts updates to $ZTVALUE within the trigger code invoked for a KILL or any of its variants, it ultimately discards any such value. Outside trigger context, $ZTVALUE has the value of an empty string and attempting to SET it produces a SETINTRIGONLY error.

$ZTWOrmhole

• For each sale transaction, set $ZTWORmhole to contain the country-specific discount percentage and investment switching information.
• Design the trigger code to read the $ZTWORmhole information and complete the sale process.
• GT.M ensures that the process-specific context, available in $ZTWORmhole, goes into the journal files and replication stream so that it can be recalled in a future database administration or audit operation.

Examples for Trigger ISVs  

トリガエラーメッセージ 

GVDATAGETFAIL

GVDATAGETFAIL, Global variable DATAGET sub-operation (in KILL function) failed. Failure code: cccc.

Run Time Trigger Error: The target node for a KILL operation could not present its state to the trigger logic due to a database problem. cccc contains the failure codes for the failed attempts. The database may have integrity errors or the process-private data structures may be corrupted.

Action: Report this database error to the group responsible for database integrity at your operation.  

NOZTRAPINTRIG  

SETINTRIGONLY

TRIG2NOTRIG

TRIGCOMPFAIL

• A database upgrade was performed but the trigger code was not updated to eliminate obsolete syntax
• The portion of the database holding the trigger definitions may be corrupted
  

TRIGINVCHSET

TRIGJNLSTATE

TRIGNAMEUNIQ

TRIGTCOMMIT

TRIGTLVLCHNG

ZGOTOINVLVL

ZTRIGINVACT

ZTRIGNOTP

ZTWORMHOLE2BIG

For more information, see the GT.M web site.