Subject Re: [IB-Architect] Event datasets RFD
Author Bill Karwin
> What Bill outlines is very useful from an application development
> standpoint, and deserves to be inside of InterBase -- but I think
> that munging the existing event design is the wrong approach.

I'd be happy about that. The current event API calls are pretty awkward and
difficult to use dynamically. For instance, one can't register interest in
a list of events when you don't know the length of the list at compile-time
(because the API uses varargs). And since the event counts are returned in
the status-vector, you can't listen for more than 20 events.

How about a new message API based on parameter buffers, like the services
API? This has the advantage of being easy to manipulate in multiple

(ISC_STATUS *) status,
(isc_db_handle *) &dbhandle,
(unsigned short) mpb_length,
(char *) mpb_buffer,
isc_callback callback_fn);

This is to register interest in one or more message by name.
The names of interesting messages are stored in a series in the
mpb_buffer. Names are of the form "". If one listens for "foo"
one receives notification when messages are posted under the name "foo",
"", or "". If one listens for "", one receives
notification when messages are posted under the name "" or
"", but not "foo" or "foo.bean".
If callback_fn is NULL, this API function suspends execution until ths
client receives notification of any of the messages. If callback_fn is not
NULL, the API function returns immediately, but invokes the callback
function when the message is received.

(ISC_STATUS *) status,
(isc_db_handle *) &dbhandle,
(unsigned short) mpb_receive_length,
(char *) mpb_receive_buffer);

This is to receive information about which message occurred. The
mpb_receive_buffer contains a series of names of messages, followed by the
count of how many times the message was posted.
One would call isc_message_receive() in both synchronous and
asynchronous cases: in the synchronous case, call it right after
isc_message_listen() returns; in the asynchronous case, call it in the
callback function.
isc_message_receive() returns a warning status code if the
mpb_receive_length is too short to contain the full information.

(ISC_STATUS *) status,
(char *) message_name);

This maps a message name to a virtual statement handle, which one can then
use to fetch datasets, as I described in my previous email.

Bill Karwin