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, Server socket object handle, RUN statement

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".
  • For a Server Socket object handle, this can only be "CONNECT".
  • For SOAP header callback events, this can only be "REQUEST-HEADER" for a SOAP request event or "RESPONSE-HEADER" for a SOAP response event. The corresponding procedure or method associated with the request or response event is invoked. For a SOAP request or response message, the associated procedure or method handler provides access to the SOAP request or response header during the execution of the Web service operation.

You can also use the APPLY-CALLBACK( ) method to apply a callback procedure for a Buffer, ProDataset, or Query object. You cannot use the APPLY-CALLBACK() method for a Procedure, Socket or Server-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.
  • For a server socket object:
    • The callback handler signature takes a single input parameter of type HANDLE. The handle value is the socket handle for the client connection.
    • The callback 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, CONNECT event