Thursday, June 10, 2010

ADS 10 Tip #9 – Notifications with Data

Advantage added Notifications(Events) in version 9, you can read an overview here. Notifications have been enhanced in version 10 by adding the ability to pass back a string with a notification. This can save a round trip to the server since all the information the client needs can be provided in the notification.

As a quick review using notifications with Advantage is a three step process. First the client must register for the event(s) it wants. Second the client listens for the event and finally the server must signal the event. This is all done with the use of system procedures as outlined below.

/* Client-side setup */
// Create an event with data
EXECUTE PROCEDURE sp_CreateEvent( 'AdminMsg', 2 );

// Wait for the event this is a blocking call
EXECUTE PROCEDURE sp_WaitForEvent( 'AdminMsg', -1, 0, 2 ); 

/* Server-side setup */
// Signal an event this must be done in a trigger or stored procedure
EXECUTE PROCEDURE sp_SignalEvent( 'AdminMsg', true, 2, 'test message' );

In the example the client "registers" for an event called AdminMsg using the ADS_WITH_DATA option. Next the client calls sp_WaitForEvent which sets up an efficient wait with the Advantage server. In this case it will wait until the query is cancelled or a notification is received. Since this is a blocking call we recommend using a second thread.

Signaling is the responsibility of the server and is usually done in response to an action performed on the server. For example a table being updated. The sp_SignalEvent system procedure can only be called within a trigger or stored procedure. A client cannot call this system procedure directly. The data returned when the event is signaled can be any string value. The return type is a memo field which allows for large amounts of data to be passed back with the notification.

There is a screencast available that demonstrates notifications with version 10.

1 comment:

Doug Woodrow said...

Hi Chris,
This is a great feature of the Advantage server, and your screencast is really clear and helpful, thanks!

I don't know if you're still in touch with the developers, but there is a memory leak problem with the TAdsEvent component and I can't work out how to report it on the new SAP portal (it was so much better in the devzone days :).

The memory leak can be fixed by adding "FEvents.Free;" to the Destroy() method of both TAdsEvent and TAdsEventReceiveThread.