The Trigger_RegisterDatabase() function registers a database trigger for use with the runtime engine. Database triggers are activated by successful table operations in an application, such as saving a record, deleting a record or reading a record.
Trigger_RegisterDatabase(anonymous(table table_name), form form_name , table_operations, script processing_procedure {, tag})
• table table_name – A table resource in the application dictionary. This is the table for which the trigger will be registered. Use the anonymous() function with this parameter to avoid implicitly opening the table.
• form form_name – The restriction for the database trigger. The form_name is a form resource in the application. This restricts the trigger to database operations that originate from the form_name. Use a zero (0) if no form restriction applies.
• table_operations – An integer identifying which table operation activates the trigger. The following constants represent these operations; add values together to activate a trigger for more than one table operation. For nstance, the integer “3” activates a database trigger for all types of database read operations (trigger_on_db_read + trigger_on_db_read_lock).
![[spacer]](1p.gif){kind=small}
|
Constant |
Value |
Description |
|---|---|---|
|
TRIGGER_ON_DB_READ |
1 |
Occurs when the application reads an existing record in table_name without locking it, such as done by the get statement. |
|
TRIGGER_ON_DB_READ_LOCK |
2 |
Occurs when the application reads an existing record in table_name and passively or actively locks it, such as done by the change or edit table statements. |
|
TRIGGER_ON_DB_ADD |
4 |
Occurs when the application adds a new record to table_name. |
|
TRIGGER_ON_DB_UPDATE |
8 |
Occurs when the application updates an existing record in table_name. |
|
TRIGGER_ON_DB_DELETE |
16 |
Occurs when the application deletes a record in table_name. |
• script processing_procedure – The procedure you write that’s run (called the trigger processing procedure) when the database trigger is activated. Upon a successful table operation, the database trigger passes the current record buffer to this procedure as an inout parameter.
• tag – An optional returned integer that uniquely identifies the trigger. This value is used when you want to unregister, enable or disable the trigger individually.
An integer corresponding to the following constants:
|
Constant |
Value |
Description |
|---|---|---|
|
SY_NOERR |
0 |
No error occurred. |
|
SY_UNKNOWN |
1 |
An unknown error occurred and the trigger was not registered. |
|
SY_INVALID_SCRIPT |
2 |
The trigger processing script was either not found or had the wrong number of parameters. The trigger was not registered. |
Upon a successful table operation, a database trigger is activated and passes the table buffer on which the table operation occurred to the trigger processing procedure as an inout parameter. This buffer is always available to the processing procedure, regardless of the table operation successfully completed. Successful table operations that occur for a range of records will activate a database trigger for each record in the range. Each record’s buffer is then passed to the processing procedure.
You can include a second optional integer in parameter in the trigger processing procedure. If this parameter is included, a value is automatically passed in indicating the table operation that activated the trigger. The value corresponds to the constants listed in the table_operations parameter.
A database trigger with a form restriction is activated only if that form’s record buffer is used for the table operation. For instance, if another form performs an operation on the same table, the database trigger won’t be activated, because the other form has its own table buffer for the table.