Triggers Technical Bulletin

Contact Information

Table of Contents

Overview

• Enforce schema-level consistency: Since database schema created in a normal M application are implicit, M applications implement logic to maintain and enforce conformance with an application schema. Using triggers to enforce schema-level consistency ensures all processes invoke the code uniformly, and increases code modularity and maintainability.
• Allow an application to maintain one or more non-primary key indexes. For example, a trigger on updates to global nodes containing a customer id can maintain an index on the last name.
• Implement business logic: For example, an update to an account could automatically trigger updates to related accounts.
• Reducing replication traffic: Since the GT.M replication stream carries only the triggering updates, not the triggered updates, triggers reduce network traffic.
• Automate application defined logging or journaling of updates or maintaining historical records.  Triggers can be used to control these.
• Implement referential integrity: For example, a trigger can prevent the posting of a bank transaction for an inactive account and display a rule violation message.
• Debugging: Debugging an application with multiple concurrent accesses is hard.  You can use triggers to establish "watch points" on global variable updates to trap incorrect accesses.  For example, if an application is failing because certain global variable nodes either have incorrect values or when previously set values disappear. A trigger can be used to trap all such accesses.
• Implement a dataflow based programming paradigm. Although not a primary goal of the implementation of triggers, you can use them to implement applications that use a dataflow programming paradigm.

Trigger Definition File

• Trigger signature: A trigger signature consists of:
• Global Variable: The name of a specific global to which this trigger applies.
• Subscripts: Subscripts for global variable nodes of the named global, specified using the same patterns as the ZWRITE command.
• 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 handles $INCREMENT() of a global matching a SET trigger definition as a triggering update.
• 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. The specified code can invoke additional routines and subroutines.
  
  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 ensures the triggering database update, and any updates generated by trigger logic executed with transaction semantics.  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. In such a case, the application and schema design provides Isolation by ensuring only one process ever updates nodes in a particular global at any given time, say by using $JOB as a subscript. 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. This property anticipates a time when a trigger specification permits an application to inform the runtime system the application and schema design ensures appropriate Consistency for a trigger and its logic, thus relieving the GT.M runtime system from that task.
• Trigger Name: You can optionally specify a trigger name that uniquely identifies each trigger. GT.M uses a trigger name for error reporting and configuration management of triggers - for example, a ZSHOW "S" reports the name of each trigger on the stack. 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. It must start with an alphabetic character or a percent sign (%). For a trigger name, GT.M uses the same naming convention as an M name (or a routine name). In other contexts, GT.M truncates M names at 31 characters. However, GT.M treats a trigger name of over 28 characters as an error. This is because a trigger name uniquely identifies a trigger and truncation may cause duplication.

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. 

The syntax of an entry in a trigger definition file is: 
{-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:   You can use patterns and ranges for subscripts. You can specify a semicolon (;) separated list for subscripts. You can specify a selection list that includes a mix of points, ranges and patterns, but a pattern cannot serve as either end of a range. For example, :,"a":"d";?1U is a valid specification but :,"a":?1A is not.  You can specify a local variable name for each subscript. 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. The trigger code can then use these variables just like any other M local variable. 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 a?? 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. You cannot use patterns and ranges for the global variable name. Therefore, you cannot set a trigger for ^Acct*. In order to account for any non-standard collation, GT.M evaluates string subscript ranges using the global specific collation when an application update first invokes a trigger - as a consequence, it detects and reports range issues at run-time rather than from MUPIP TRIGGER or $ZTRIGGER(), so test appropriately. For example, GT.M reports a run-time error for an inverted subscript range such as (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:   A KILL of a node that does not exist. 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. The trigger uses the "piece" syntax (described below) and no triggering piece changes in the update. 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. The trigger gets executed only when any piece from the specified piece list changes. 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. This trigger is not executed if you change the first element. For example:   S $P(^trigvn,"|",1)="Chandelier" does not invoke the trigger.   You can also specify a range for your piece sequence. For example, 3:5;7;9:11 specifies a trigger on pieces 3 through 5,7 and 9 through 11. GT.M merges any overlapping values or ranges - for example, 3:6;7 is the same as 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. It is an alphanumeric string of up to 28 characters. It must start with an alphabetic character or a percent sign (%). Note: -name is 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.

 

Trigger ISVs

A Simple Example

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. Execute a command like the following:
   $ mupip trigger -triggerfile=triggers.trg
   This command adds a trigger for ^CIF(:,1).
   On successful trigger load, this command displays an output like the following:
   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. Using your editor, create an M routine called XNAMEinCIF.m with the following code: 
   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 
       ; Create a new cross reference if the command is a 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.
  
  

Trigger Definition Storage

Trigger Invocation and Execution Semantics

GT.M stores Triggers for each global variable in the database file for that global variable.  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.

Whenever a command updates a global variable, the GT.M runtime system first determines whether there are any triggers for that global variable.  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. This means that the node to be KILLed and descendants (if any) remain visible to the trigger code. Note that a KILL trigger ignores $ZTVALUE.

Set

• a log or journal entry may need to be stored in a different piece of the same node as the update, or
• the node being updated may need its data to be stored in a canonical form (such as all-caps, or with standardized punctuation, regardless of how it was actually entered), or have its value limited to a range.

GT.M treats a MERGE command as a series of SET commands performed in collation order of the data source.  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 treats the $INCREMENT() function as a SET command.  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.

Trigger Execution Environment

As noted above, if there are multiple matching triggers, the GT.M process makes a list of matching triggers and executes them in an arbitrary order with no guarantee of predictability.

For each matching trigger:

1. The GT.M process implicitly stacks the naked reference, $REFERENCE, $TEST, $ZTOLDVAL, $ZTDATA, $ZTRIGGEROP, $ZTUPDATE and NEWs all local variables. 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 executes the trigger code. 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. Triggers may nest up to 127 levels, after which an additional attempt to nest produces a MAXTRGRNEST error.
   
3. When the code completes, GT.M clears local variables, restores what was stacked, except $ZTVALUE (refer to the ISV definitions for comments on modifying $ZTVALUE) to the values they had at the start of the trigger, and if there is any remaining trigger matching the original update, adjusts $ZTUPDATE and executes that next action. $ZTVALUE always holds the current target value for the node for which the application update initially invoked the trigger(s). Note that because multiple triggers for the same node execute in an arbitrary order, having more than one trigger change $ZTVALUE requires careful design and implementation.

After executing all triggers, GT.M commits the operation initiating the trigger as well as the trigger updates and continues execution with the next command (or, in the case of multiple nodes being updated by the same command, with the next node).  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.

To ensure trigger actions are Atomic with respect to the update that invokes them, GT.M always executes trigger logic and the triggering update within a transaction.  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. Therefore, the trigger code and/or its error trap always operate inside a Transaction and can use the TRESTART command even if the main application code never uses TSTART. $ETRAP code for use in triggers may include TROLLBACK logic.

The deprecated ZTSTART/ZTCOMMIT transactions are not compatible with triggers.  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. Likewise GT.M treats any attempt to issue a ZTSTART within a trigger context as an error.

Error Handling during Trigger Execution

GT.M uses the $ETRAP mechanism to handle errors during trigger execution. If an error occurs during a trigger, GT.M executes the M code in $ETRAP. If $ETRAP does not clear $ECODE, GT.M does not commit the database updates within the trigger and passes control to the environment of the trigger update. If the $ETRAP action or the logic it invokes clears $ECODE, GT.M can continue processing the trigger logic.

Consider the following trivial example:

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.

• The run-time $ETRAP code modified the trigger logic to achieve the desired result

• The replicating configuration is different from the initiating configuration

• The filters between the initiating and replicating instance introduce an error

• Intended and the $ETRAP mechanism is an integral part of managing the difference
• Unintended and the $ETRAP mechanism should help notify the operational team to correct the difference and restart replication 

The trigger facility introduces an environment variable called gtm_trigger_etrap. It provides the initial value for $ETRAP in trigger context and can be used to set error traps for trigger operations in both mumps and MUPIP processes.  The code can, of course, also SET $ETRAP within the trigger context. During a run-time trigger operation if you do not specify the value of gtm_trigger_etrap and a trigger fails, GT.M uses the current trap handler. In a mumps process, if the trap handler was $ZTRAP at the time of the triggering update and gtm_trigger_etrap isn't defined, the error trap is implicitly replaced by $ETRAP="" which exits out of both the trigger logic and the triggering action before the $ZTRAP unstacks and takes effect. In a MUPIP process, if you do not specify the value of gtm_trigger_etrap and a trigger fails, GT.M implicitly performs a SET $ETRAP="If $ZJOBEXAM()" and terminates the MUPIP process. $ZOBEXAM() records diagnostic information (equivalent to ZSHOW "*") to a file that provides a basis for analysis of the failure.

Important: $ZJOBEXAM() dumps the context of a process at the time the function executes and the output may well contain sensitive information such as identification numbers, credit card numbers, and so on.  You should secure the location of files produced by the MUPIP error handler or set up appropriate security characteristics for operating MUPIP. Alternatively, if you do not want MUPIP to create a $ZJOBEXAM() file, explicitly set the gtm_trigger_etrap environment variable to a handler such as "Write !,$ZSTATUS,!,$ZPOSITION,! Halt".

• Any attempt to use the $ZTRAP error handling mechanism for triggers results in a NOZTRAPINTRIGR error.

• If the trigger initiating update occurs outside any transaction ($TLEVEL=0), GT.M implicitly starts a transaction to wrap the initiating update and the triggered updates. Consequently if a TROLLBACK or TCOMMIT within the trigger context causes the code to come back to complete the initiating update with a different $TLEVEL than when the trigger started (including any implicit TSTART), GT.M issues a TRIGTLVLZERO error and does not commit the original update.

• Any TCOMMIT that takes $TLEVEL below what it was when at trigger initiation, causes a TRIGTLVLCHNG error. This behavior applies to any trigger, whether chained, nested or singular.

• It may appear that GT.M executes trigger code as an argument for an XECUTE. However, for performance reasons, GT.M internally converts trigger code into a pseudo routine and executes it as if it is a routine. Although this invisible for the most part, the trigger name can appear in places like error messages and $STACK() return values.

• Triggers are associated with a region and a process can use one or more global directories to access multiple regions, therefore, there is a possibility for triggers to have name conflicts. 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. If this attempt to make the name unique fails, GT.M issues a TRIGNAMEUNIQ error.

• 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 (a??), exclamation-point (!) and back-slash (\) characters. For a comprehensive (but hopefully not very realistic) example:

  $ 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

To maintain the transactional integrity of triggers and to avoid branching control to an inappropriate destination, ZGOTO behaves as follows:

1. GT.M does not support ZGOTO 1:<entryref> arguments in MUPIP because they form an attempt to replace the MUPIP context. 
   
2. When a ZGOTO argument specifies an entryref at or below the level of the update that initiated the trigger, GT.M redirects the flow of control to the entryref without performing the triggering update. Alternatively if GT.M finds a non-null $ECODE, indicating an unhandled error when it goes to complete the trigger, it throws control to the current error handler rather than committing the original triggering update.
   
3. ZGOTO 0 terminates the process and ZGOTO 1 returns to the base stack frame, which has to be outside any trigger invocation.
   
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.

Other Utilities

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.

Triggers in Journaling and Database Replication  

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.

Journaling

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().    

Multisite Database Replication

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.

Replicating to an instance with a different trigger configuration

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. 

Replicating to an instance that does not support triggers

Update & Helper Processes

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 TRIGGER

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 a??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 a??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 a??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.

Examples for MUPIP TRIGGER

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. Execute a command like the following:
   $ 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. 

Examples for $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 a??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 allows you to specify a string that you want to make available in chained or nested triggers invoked for an outermost transaction (when a TSTART takes $TLEVEL from 0 to 1). 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  

Trigger Error Messages 

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.