A Message Handler is only ever called by the Database on a Database Event. These Event Messages allow a Developer to intercept operations taking place on a per-record level and implement Event based business logic.
Message Handler Procedures are called after the processing of Field Attributes, but before the Event Messages are sent to any Custom COM DLLs.
Field Formatting and simple business logic should be implemented using Attributes wherever possible; with a Message Handler only responsible for more complex business logic. The Message Handler Procedure itself should be kept as small as possible. If there is any substantial amount of source code the Message Handler should only testing if conditions require attention, and then where necessary, call one or more Public Methods to perform the work.
When a Message Handler Procedure for an individual record event is initiated, the record in question will be in a Query Object named Input and it will be set as the Top Query. An empty Query Object named Output will be set as the Work Query. Any changes made to the Input Query will be committed to the Database for New and Update Events. Any changes made to the Output Query will be discarded.
When a Message Handler Procedure for a relationship event is initiated, the parent record alias and child record alias will be in a Query Object named Input and it will be set as the Top Query.
In order to be called, a Message Handler must be named after a valid Database Event name, such as DB-Update-Pre (see complete list below.) The Group Types security system used by other Procedures does not apply to Message Handlers, however, any Public Methods they call will have their Group Types security checked.
All Database Event Messages start with DB-
The Parent receives the Event Message first, then the Child. If an error is thrown during the processing of the Parent's Event Message, the Child's Message will not be sent. To be clear, Attach-Parent is the Event sent to the Parent Object of the Relationship.
For example, if Table A is the parent and Table B is the child and we want to trigger an event if Table B is detached from Table A, we would create a DB-Detach-Child Message Handler on Table B or a DB-Detach-Parent Message Handler on Table A. You would not create a DB-Detach-Parent Message Handler on Table B for this example, since it is the child in the relation.