KnowledgeBase 00067: Using QM Triggers

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

After reading a record.
Before writing a record
Before deleting a record
Before clearing a file
After writing a record
After deleting a record
After clearing a file

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.