logo
Powered by QM on a Rpi server

KnowledgeBase 00067: Using QM Triggers

Last updated: 22 Jul 2016
Applies to: All versions
Search  
Top level index       Full Index Search Tips
Previous article     Next article

This article was originally published as a Tip of the Week.

QM supports seven different trigger modes that cause execution of user written code when the related file operation is attempted. Triggers can be used to provide data integrity checks or, as their name implies, to trigger other actions within the application.


Trigger Events

The seven trigger points are

The read trigger event occurs after a record has been read. It could be used, for example, to implement data security rules that require special coding.

The pre-event triggers are typically used to perform data integrity checks. If an error is detected, the associated file operation can be refused.

The post-event triggers are typically used to trigger other actions within the application. For example, a sales system might use a trigger on a stock file to detect the need to reorder supplies.

Apart from one execption described below, a trigger will always trap the associated action, regardless of how it occurs. Triggers therefore provide a reliable way to catch file operations.


Writing a Trigger Subroutine

The trigger subroutine has a declaration of

   SUBROUTINE name(mode, id, data, on.error, file.var) 
where mode identifies the event for which the trigger was called.

A read or pre-write trigger can modify the data (but not the id). The associated file operation can be rejected by setting the @TRIGGER.RETURN.CODE variable to a non-zero value. For more details, see the QM Reference Manual.


The SET.TRIGGER Command

A trigger subroutine is associated with a file using a command of the form

   SET.TRIGGER filename subrname {modes} 
The modes element identifies which events are to be trapped. If omitted, this defaults to PRE.WRITE and PRE.DELETE.


Detecting Rejected Operations

If the file operation that caused the trigger subroutine to return a non-zero value in @TRIGGER.RETURN.CODE has an ON ERROR clause, this clause is executed and the STATUS() function returns ER$TRIGGER. If there is no ON ERROR clause, the program will abort. The trigger subroutine can determine whether the ON ERROR clause is present by use of the on.error argument.


Directory File Triggers

QM supports use of triggers on directory files though the trigger will only be executed as a result of QMBasic operations on the file, not changes made from outside QM.


Related Articles

None.



Please tell us if this article was helpful
Very     Slightly     Not at all
Comments
Email (optional)