To create an object trigger, you must register the trigger for use with the runtime engine. You also need to create a trigger processing procedure that runs when the trigger is activated. Use the following functions to register each of your application’s triggers for use with the runtime engine.
![[spacer]](1p.gif){kind=small}
|
Trigger type |
Function and parameters |
|---|---|
|
Form |
Trigger_RegisterForm(form form_name, menu_item_name, accelerator_key, script processing_procedure {, tag}) |
|
Focus |
Trigger_RegisterFocus(anonymous (qualified_resource), focus_type, attach_type, script processing_procedure {, tag}) |
|
Database |
Trigger_RegisterDatabase(anonymous(table table_name), form form_name, table_operations, script processing_procedure {, tag}) |
|
Procedure |
Trigger_RegisterProcedure(script procedure_name {of form form_name}, attach_type, script processing_procedure {, tag}) |
|
Function |
Trigger_RegisterFunction(function function_name {of form form_name}, attach_type, [function processing_function | script processing_procedure] {, tag}) |
The trigger registration specifies the conditions that will activate the trigger. For instance, the registration for a procedure trigger includes the name of the procedure that will activate the trigger when it is called.
When you register a trigger, a tag is assigned that uniquely identifies the trigger. The tag is returned by the optional tag parameter for each trigger registration function. You will use the tag when you want to enable, disable or unregister the trigger. There is no way to get a specific trigger’s tag after the trigger has been registered. If you need to work with an individual trigger, you must keep track of the tag assigned when you registered the trigger. Commonly, global variables are used to store the tag for each trigger.
When you register a trigger, the return value from the function indicates whether the trigger was registered. The following table lists the possible return values:
|
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_FOCUS |
3 |
The focus_type is not valid for the resource for which the trigger is being registered. |
|
SY_INVALID_OBJECT |
4 |
The object for which the trigger is being registered cannot be found. |
Although you can register triggers from anywhere in your application, the preferred method is through a startup procedure. This is a procedure that’s run prior to the Main Menu form pre script for for the main application dictionary. You can create two types of startup procedures:
For example, the following procedure named “Startup” registers a form trigger. It runs before the form pre script for the Main Menu form. The procedure named IG_Open_Contact_History runs in response to this trigger.
{Name: Startup}
local integer l_result;
l_result = Trigger_RegisterForm(form RM_Customer_Maintenance, "Contact History", "1", script IG_Open_Contact_History);
if l_result <> SYNOERR then
warning "Form trigger registration failed.";
end if;
If you make changes in how your triggers are registered, the registration code must be run again before any changes will take effect. If your triggers are registered in the Startup procedure, be sure you exit then restart the runtime engine (or test mode) to reregister your triggers.