To detect data using events, you set up an event handler for READ-RESPONSE events posted on a connected socket object. There are two options for implementing the event handler, depending on whether the event handler code is in a method or a procedure. The first option is preferable and can be used for both methods and procedures. The second option is strictly for procedures.

Option 1: Use SET-CALLBACK( )

  1. Define a PUBLIC method or a non-PRIVATE internal procedure that takes no arguments to contain your event handler code. If you are using a method for a callback, the method must satisfy the following requirements:
    • The method 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.
    You can define this method or procedure in any context that is active during the connection. When this method or procedure executes in response to a READ-RESPONSE event, the SELF system handle returns the handle of the connected socket.
  2. Specify the method or procedure you defined in Step 1 as a READ-RESPONSE event callback by invoking the SET-CALLBACK( ) method on the socket.
  3. Include input-blocking statements (such as WAIT-FOR) or PROCESS EVENTS statements in your code to initiate the handling of events. When any READ-RESPONSE event is received in the context of one of these statements, the event method or procedure specified in Step 2 executes.

Option 2: Use SET-READ-RESPONSE-PROCEDURE( )

  1. Define an internal procedure that takes no arguments to serve as an event procedure. You can define this procedure in any procedure context that is active during the connection. When this procedure executes in response to a READ-RESPONSE event, the SELF system handle returns the handle of the connected socket.
  2. Specify the procedure you defined in Step 1 as a READ-RESPONSE event procedure by invoking the SET-READ-RESPONSE-PROCEDURE( ) method on the socket.
  3. Include input-blocking statements (such as WAIT-FOR) or PROCESS EVENTS statements in your code to initiate the handling of events. When any READ-RESPONSE event is received in the context of one of these statements, the event procedure specified in Step 2 executes.

In the event-driven model, ABL can post a READ-RESPONSE event on a connected socket object for two reasons:

  • Data has arrived on the socket — You can then read this data during execution of the event procedure (or any time while the socket remains connected) using the READ( ) method. You do not have to read all the bytes available on the socket. If any data remains after reading on the socket, ABL immediately posts another READ-RESPONSE event on the socket object for the available data.
    Note: After ABL posts the first READ-RESPONSE event for a new socket, ABL does not post another READ-RESPONSE event for the socket until you call the READ( ) method on the socket object. Thus, if you do not read data on the socket in the event procedure, you must make sure to do so elsewhere in your application if you want the application to respond to any additional events for the socket.
  • The socket is disconnected — During execution of an event procedure called for a socket disconnection:
    • Calling the READ( ) method on the socket object returns an error
    • The value returned by a GET-BYTES-AVAILABLE( ) method invoked on the socket object is zero (0)
    • The value returned by a CONNECTED( ) method invoked on the socket object is FALSE