17 Database Triggers

Database triggers use the FreeM asynchronous event handling subsystem to allow a FreeM process to execute arbitrary M code when a particular action occurs on a particular global.

To set up a database trigger, you must set up an event handler for event class TRIGGER. The event identifier must be in the format of "<action>:<gvn>", where <gvn> is a global variable name, and <action> is one of the following:

DATA

Trigger will fire when the $DATA intrinsic function is called on <gvn>.

GET

Trigger will fire when <gvn> is read from.

INCREMENT

Trigger will fire when intrinsic function $INCREMENT is called on <gvn>.

KILL

Trigger will fire when <gvn> is KILLed.

NEXT

Trigger will fire when intrinsic function $NEXT is called on <gvn>.

ORDER

Trigger will fire when intrinsic function $ORDER is called on <gvn>.

QUERY

Trigger will fire when intrinsic function $QUERY is called on <gvn>.

SET

Trigger will fire when SET <gvn>=value occurs.

ZDATA

Trigger will fire when intrinsic function ZDATA is called on <gvn>.

When a TRIGGER event occurs, the "GLOBAL" node of the ^$EVENT structured system variable will be populated with the global reference that invoked the trigger event.

If a SET or KILL trigger was the source of the TRIGGER event, the OLD_VALUE node of ^$EVENT will be populated with original value of ^$EVENT("GLOBAL") prior to the change, and NEW_VALUE will be populated with the new value. This allows triggers to contain logic to undo database changes. This functionality can also be used to provide auditing of specific global changes.

The following example shows a trigger implemented for SET operations on the ^DD global.

TRIGGER ;
    ;
    ; Set up a SET trigger on ^DD
    ;
    SET ^$JOB($JOB,"EVENT","TRIGGER","SET:^DD")="ONSET^TRIGGER"
    ;
    ; Enable the TRIGGER event class
    ;
    ASTART "TRIGGER"
    ;
    ; Try setting a node in ^DD
    ;
    SET ^DD(1)="Test"
    ;
    ; Quit
    ;
    QUIT
    ;
    ;
ONSET ;
    WRITE "The "_^$EVENT("GLOBAL")_" global node was SET.",!
    QUIT

You can also set up a trigger that applies to all FreeM processes by setting descendant subscripts of ^$SYSTEM("EVENT","TRIGGER",...) instead of using ^$JOB($JOB,"EVENT","TRIGGER",...).

This document was generated on September 20, 2023 using texi2html 5.0.