The Trigger_RegisterDatabaseByName() function registers a database trigger for a table in the specified dictionary. Database triggers are activated by successful table operations in an application, such as saving a record, deleting a record or reading a record.
Trigger_RegisterDatabaseByName(product_ID, table_name, form_name, table_operations, script processing_procedure {, tag})
• product_ID – An integer specifying the ID of the product that contains the table for which the trigger is being registered.
• table_name – A string specifying the table for which the trigger is being registered.
• form_name – A string specifying any form restriction for the database trigger. This restricts the trigger to database operations that originate from the form specified. Use an empty string ("") 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 instance, 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. |
|
SY_INVALID_OBJECT |
4 |
The object for which the trigger is being registered cannot be found. |
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 anonymous inout parameter. This buffer is always available to the processing procedure, regardless of whether the table operation successfully completed. Use the column() function to retrieve specific fields from the table buffer.
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.