trigger accept

Handles processing when an Accept request is received, usually with the intention of closing the component and keeping all changes made on it. This trigger is exposed as an operation in the component signature.

Description

An Accept request is usually invoked to close the component and save all modifications. (In contrast, the Quit request is invoked to close the component without saving modifications).

By default, the accept trigger does not contain a store statement, so any data that has not been saved will be lost. It is therefore common to add ProcScript that stores data, such as a store statement, or a reference to a Global ProcScript, which stores modified data.

However, the accept trigger can also be fired because of an Accept request on an attached parent component, for example, if it is in a form container or tab. In this case, the accept trigger should only contain ProcScript that determines whether the component agrees on the Accept request or not. ProcScript to store the data should be in a separate operation that is activated from the accept trigger of the parent component. This way, no data is stored until all involved components agree on the Accept request.

Code for validating data should not appear in this trigger. It is better to use field-level triggers or entity-level triggers for data validation.

Trigger Activation and Execution

The accept trigger is activated after the Accept operation of a component instance is started with an activate statement, or by the ^ACCEPT structure editor function in a form. However, it is fired only after implicit field syntax checking and data validation completes successfully. If all involved components agree to the Accept request, the component is closed.

The accept trigger is executed in the following circumstances:

• For all supported components—when an Accept request is invoked on the current component.
• For components that have one or more attached child components—when an Accept request is invoked on the current component and all attached child components agree on the Accept request by successfully executing their accept triggers . If the execution of the accept trigger of one of the child component fails, the Accept request is terminated. As a consequence, this trigger is not executed and no components are closed.
• For components that are attached as a child to a parent component—when an Accept request is invoked on the parent component. If the execution of the accept trigger of any other attached child components fails, the Accept request is terminated. As a consequence, this trigger is not executed and no components are closed.

Controlling Behavior Upon Completion

The value in $status when exiting the accept trigger determines whether the component agrees on the Accept request or not.

If $status is 0, the component agrees on the Accept request and will close after agreement of other involved components. The Accept request can still be terminated by other components, like attached child or parent components. If all involved components agree on termination, they are closed without firing any additional triggers.

If $status is non-zero, the component does not agree on the Accept request. accept triggers of other involved components will not be fired; none of the involved components will be closed.

Note:  Be aware of the values returned in $status, because it is quite easy to write components that you cannot exit.