Triggers

Top  Previous  Next

 

A trigger is an optional user written function associated with a hashed file and configured to be executed when certain file operations are performed. Executed before a write or delete, the trigger can be used to apply data validation. Executed after a record is written or deleted, the function can trigger other events such as related file updates. Trigger functions can also be executed after a read and before or after a clear file operation.

 

The trigger function is simply a catalogued QMBasic subroutine which is automatically executed as part of the file operation. The subroutine is passed a mode flag to indicate the action being performed, the record id, the record data (read or write operations) and a flag indicating whether the QMBasic ON ERROR clause is present. The subroutine may do whatever processing the application designer wishes. If the write or delete is to be disallowed, the pre-write or pre-delete trigger function should set the @TRIGGER.RETURN.CODE variable to a non-zero value such as an error number or an error message text to cause the write or delete to take its ON ERROR clause if present or to abort if omitted. The STATUS() function will return ER$TRIGGER when executed in the program that initiated the file operation. Programs should test STATUS() rather than testing for @TRIGGER.RETURN.CODE being non-zero to determine whether the trigger function has disallowed the write or delete as @TRIGGER.RETURN.CODE is only updated when the error status is set.

 

The trigger function is set up using the SET.TRIGGER command. After it has been set up, the trigger function is loaded into memory when the file is opened and is called for all write or delete operations. Modifying and recataloguing the trigger function will have no effect on processes that have the file open until they close and reopen it.

 

If the trigger function is not in the catalogue or has the incorrect number of arguments, no error occurs until the first write or delete is attempted. Note that the trigger function must be visible to all accounts that may reference the file. Where a file is used by multiple accounts, this can be achieved by using global cataloguing, sharing a private catalogue, or ensuring that the VOC entry for a locally catalogued trigger function is present in each account. Although it would be possible for a shared file to use a different trigger function depending on the account from which it is referenced, this is not recommended. Files that are to be accessed via QMNet require that associated trigger functions are globally catalogued.

 

The interface into a trigger function is:

 

SUBROUTINE name(mode, id, data, on.error, fvar)

 

where

nameis the trigger subroutine name.
modeindicates the point at which the trigger function is being called:

1

FL$TRG.PRE.WRITE

before writing a record

2

FL$TRG.PRE.DELETE

before deleting a record

4

FL$TRG.POST.WRITE

after writing a record

8

FL$TRG.POST.DELETE

after deleting a record

16

FL$TRG.READ

after reading a record

32

FL$TRG.PRE.CLEAR

before clearing the file

64

FL$TRG.POST.CLEAR

after clearing the file

Other values may be used in the future. Trigger functions should be written to ignore unrecognised values.

idis the id of the record to be written or deleted.
datais the data. This is a null string for a delete or clearfile action.
on.errorindicates whether the program performing the file operation has used the ON ERROR clause to catch aborts.
fvaris the file variable that can be used to access the file. Beware that reading, writing or deleting records via this file variable may cause a recursive call to the trigger function. This argument can be omitted for compatibility with earlier releases.

 

When writing trigger functions, the original data of the record to be written or deleted can be examined by reading it in the usual way. Trigger functions should not attempt to write the record for which they are called. Neither should they release the update lock on this record as this could cause concurrent update of the record.

 

If the value of data is changed by a pre-write trigger function, the modified data is written to the file. Similarly, a read trigger can modify the data that will be returned to the application that requested the read. Changes to the value of id will not affect the database update in any way.

 

Trigger functions may perform all of the actions available to other QMBasic subroutines including performing updates that may themselves cause trigger functions to be executed.