Associates a method within a class instance, or an internal procedure within a persistent procedure, with an ABL callback event.

Return type: LOGICAL

Applies to: Buffer object handle, Procedure object handle, ProDataSet object handle, Query object handle, Socket object handle

Syntax

SET-CALLBACK ( callback-name , routine-name [ , routine-context ] )
callback-name
A quoted string or character expression representing the name of a callback. The callback-name is not case-sensitive.
  • For a ProDataSet buffer object handle, this can be "BEFORE-FILL", "AFTER-FILL", "BEFORE-ROW-FILL", "AFTER-ROW-FILL", "ROW-CREATE", "ROW-DELETE", "ROW-UPDATE", "FIND-FAILED", or "SYNCHRONIZE".
  • For a Procedure object handle, when calling a Web service, this can be either "REQUEST-HEADER" or "RESPONSE-HEADER".
  • For a ProDataSet object handle, this can be "BEFORE-FILL" or "AFTER-FILL".
  • For a Query object handle, this can be "OFF-END".
  • For a Socket object handle, this can be "READ-RESPONSE".

You can also use the APPLY-CALLBACK( ) method to apply a callback procedure for a Buffer, Procedure, ProDataset, or Query object. You cannot use the APPLY-CALLBACK() method for a Socket object.

routine-name
A quoted string or character expression representing the name of a method or an internal procedure that resides within routine-context. If calling this on a procedure handle, routine-name can only be an internal procedure.
routine-context
An object reference for a class instance or a handle to a persistent procedure that contains the method or internal procedure specified by routine-name. If not specified, and the routine is executed within a procedure, THIS-PROCEDURE is used as the routine context. If not specified, and the routine is executed within a class instance, THIS-OBJECT is used as the routine context.

If callback-name is not a valid callback, or routine-context is not a valid object reference or handle, this method returns FALSE; otherwise, it returns TRUE. If the SET-CALLBACK( ) method is specified but cannot be invoked, or it fails, no method or procedure is executed as part of the callback event.

Notes

  • The callback method or procedure must be public.
  • If routine-name represents a class method that is associated with an ABL event as a callback, and the method is overridden in a derived class, the overridden method is run when the callback is invoked.
  • To clear a callback, pass the Unknown (?) value or an empty string as the routine-name parameter. The following code fragment shows clearing a callback by passing the empty string:
    BUFFER <buffer-name>:HANDLE:SET-CALLBACK ("After-Row-Fill", "").
  • When used with a class instance, the SET-CALLBACK( ) method creates an internal reference to the instance. As a result, the instance cannot be garbage collected while the callback is in effect. If you clear it, the object may be garbage collected if there are no more references to it.
  • For a Socket object:
    • The callback method or procedure signature must not have any parameters. Overloaded methods are allowed, but only the method with no parameters is invoked on the READ-RESPONSE event.
    • The method return type should be VOID. Any value returned from the method is ignored.

See also

APPLY-CALLBACK( ) method, GET-CALLBACK-PROC-CONTEXT( ) method, GET-CALLBACK-PROC-NAME( ) method, OFF-END event, ProDataSet events, READ-RESPONSE event