Types of Trigger Programs

You need to understand the types of trigger progams.

Note the following about Program objects attached to Event Triggers:


  • Any changes made to the Program object are immediately picked up when fired by a trigger. This implies that a check or override program can modify the code of an action program that follows.
  • Check and Override programs must return an exit code in order for the event processing to know how to proceed. Code can be included in the Program that performs other functions prior to setting the exit code's integer value.
  • Programs that use trigger-specific macros cannot be used as methods, since the macro values rely on the triggering event.
  • When a Program object attached to a trigger is renamed, the newly-named Program object remains attached to the trigger.
  • Deleting a Program object that is attached to a trigger automatically detaches the Program object from the trigger.

The following topics are discussed:

Trigger Macros

Macros are a simple name/value string substitution mechanism, where the macro value is substituted for the macro name when used in a Program as follows:

${MACRONAME}

This single one-pass string substitution process occurs just prior to program execution. Refer to Appendix: Macros for more details

Check Programs

Do not defer trigger check program execution. Make sure the exit code is an integer value that is always tested by the trigger logic to determine whether or not to block the event. Any system errors encountered while executing the check program will abort the event transaction. When the check program returns a non-zero exit code, the event is not performed. This is one way to block events from occurring.

Unlike replacing events (see below), blocking events with a check program causes the event transaction to abort, and raises an exception (and therefore displays an error). If a check program blocks, then neither the override program nor the action program get executed.

Events can also be blocked using an override program. To block an event without having an error message presented, use an override trigger. If the exit code from the override program is a non-zero integer, the event is completely replaced, but the transaction is committed, and no error message is displayed.

In this scenario the normal event processing is skipped, and therefore the override program becomes the event. If the override program causes the event to be replaced without providing code for an alternative event, the original event is, in a sense, blocked. This is called a soft block. It is different from blocking with the check program in that the event transaction is committed anyway. Since the transaction is not aborted, any processing that may have occurred in the check program is not rolled back and the action trigger will fire. If there is an action trigger program, you may need to use the RPE to communicate to the action program that the event was blocked, and not to do its normal activity.

Override Programs

Do not defer override program execution. The exit code should be an integer value, and is always tested by the trigger logic to determine whether or not to replace the event.

If the override program returns a zero exit code, the event is not replaced, and the flow of control proceeds in its normal fashion. That is, the normal system code is executed, the history of the event is recorded, the transaction is committed, and then the action trigger is fired, if it exists. You can use this technique to add pre-event processing to an ENOVIA Live Collaboration event.

Replacing Events

When the override program returns a non-zero exit code, the normal system event code and history mechanism is skipped, and then the event transaction is committed and the action program is executed.

When the override program returns a non-zero exit code, the normal system event code and history mechanism is skipped, and then the event transaction is committed and the action program is executed. This method lets you replace existing event handling with new, custom event handling. A non-zero exit code in an override program can also be used to block the event. Refer toOverride Programs.

When replacing normal event processing, the associated history entry is not recorded. This brings up the issue of which events should occur in the override program. Certainly if the overriding behavior causes other normal ENOVIA Live Collaboration events to occur, those events are logged by their associated history mechanism. If this is not the case, the overriding behavior is unrecorded by the history mechanism. You can use other means of recording the event such as the check or action code. The following MQL command can be used to add custom history entries to a business object:

modify bus TYPE NAME REV add history VALUE [comment VALUE];

For details, see "Extending an Application" in the MQL Guide.

Changing the behavior of the ENOVIA products without any explicit indication, as is the case when using the replace event feature, can lead to problems that are extremely difficult to troubleshoot. Therefore, when triggers that are designed to replace expected ENOVIA behavior are implemented, it is recommended that you create a trigger log by setting the environment variable MX_TRIGGER_LOG to TRUE.

Any system errors encountered while executing the override program will abort the event transaction.

Override on Disconnect

A delete relationship (disconnect) override program poses a special case, since this event occurs not only when 2 objects are simply disconnected, but also when an object on 1 end of a relationship is deleted. Before ENOVIA Live Collaboration deletes an object from the database, any connections it has are first removed, which results in an invocation of the delete relationship triggers.

If the override program returns an exit code of 1 (implying that the trigger took care of the deletion), ENOVIA Live Collaboration will double check to insure that the relationship was really removed. If it was not, it aborts the current transaction (that attempted to delete the business object) and issues the following error messages: 

Error: #1900068: del business object failed  
System Error: #1500573: Override trigger for deleting 
connections failed to delete relationship RELID when business 
object at one end was being deleted.

This error indicates that the override trigger program is incorrectly coded, and should be reexamined to provide the required functionality (perhaps rewriting as an action program.)

Action Programs

Without transactions and potential rollbacks to worry about, it is best to execute the action program immediately after the event takes place. This is the case with non-deferred action programs.

Refer to Types of Triggers for more information.

Trigger action program execution is deferred if the Execute Deferred setting is on. Deferred action programs are queued for execution which takes place when the outer-most transaction is committed. See the "Extending an Application" chapter of the MQL Guide for additional information.

Trigger action program exit codes are never tested by the trigger logic. (This is not the case, however for lifecycle actions. In a state promotion action, if the program returns 1 or aborts, the promote transaction is aborted.)

Any system errors encountered while executing a non-deferred action program will only abort the event transaction if it is nested within an outer transaction.