In addition to carrying out default behavior for events such as filling or updating a ProDataSet, ABL defines named events to which you can attach internal procedures. Then you can define callbacks within your application to register a mapping of an event name with an internal procedure in a running procedure handle. For each defined event on each ProDataSet or ProDataSet temp-table where there is a callback, the AVM runs the internal procedure defined in the callback and passes in the ProDataSet as a parameter. This allows you to define business logic to validate or manipulate the data, or to extend or replace the default behavior of the ProDataSet.
The SET-CALLBACK-PROCEDURE method lets you associate a named event with an internal procedure to run when the event occurs, and a persistent procedure handle to run it in.
If there is a registered callback procedure for an event/ProDataSet combination, the AVM runs the internal procedure and passes the ProDataSet parameter to it. If there is no registered callback, then the AVM does nothing. This eliminates the possible overhead of searching up the procedure stack on every event to see if there is anything defined to run for it. Rather than searching through a stack of procedures that have all been attached to an object, the AVM can immediately go to the correct handle (if any) for each event.
Because the procedure handle for the event handler is part of the callback definition, the event handler can be in a logic procedure completely separate from where the ProDataSet is defined or used. In addition, many different procedures that all use the same ProDataSet can reference the same business logic that need only be running once within a session. Business logic for different parts of a ProDataSet can be handled by different procedures, so you can organize that logic to be as flexible as is needed. For example, it is entirely possible for you to use a single "pass-through" event procedure as the registered handle for all events, and then build a super procedure stack of procedures where the actual processing logic resides. Other organizational techniques are also possible; the mechanism provides efficiency and flexibility.
The SET-CALLBACK-PROCEDURE method uses this syntax:
object-handle is the handle of a ProDataSet, a query, a ProDataSet temp-table buffer, depending on the event.
event-name-expr is a character expression representing the name of the event as defined by the AVM for this object. The specific event names the AVM supports are described below.
internal-proc-expr is a character expression representing the name of the internal procedure to run in response to this event.
proc-handle is the procedure handle of a running persistent procedure where the internal-proc-expr is located. In order to provide a valid handle, the procedure must be running within the session before the callback is registered. The default is THIS-PROCEDURE.
The ProDataSet is always passed in as an INPUT parameter. The event procedure can receive this either into a static definition, using the parameter form DATASET PARAMETER FORdataset-name, or into a handle using the parameter form DATASET-HANDLEhandle-var. Within the callback event procedure, the SELF handle function evaluates to the ProDataSet handle or buffer handle associated with the event.
Note that you can only have a single active callback procedure for an event/object combination at any time. If you execute the SET-CALLBACK-PROCEDURE for an event name and object handle that already has a callback for that event, the latest one defined replaces the earlier one.
There are two methods you can use to retrieve callback procedure names:
GET-CALLBACK-PROC-CONTEXT( ) method — Returns the handle of the procedure that contains the internal procedure associated with the AVM callback for the specified event. For example:
GET-CALLBACK-PROC-CONTEXT ( event-name )
If the object does not have a callback procedure for the specified event, this method returns the Unknown value (?).
GET-CALLBACK-PROC-NAME( ) method — Returns the name of the internal procedure associated with the the AVM callback for the specified event. For example:
GET-CALLBACK-PROC-NAME ( event-name )
If the object does not have a callback procedure for the specified event, this method returns the Unknown value (?).
There is an APPLY-CALLBACK method, described later, to force callback procedures to run at a time other than when the built-in events for them occur.
object-handle is the handle of a ProDataSet, a query, a ProDataSet temp-table buffer, depending on the event.