Subject Messaging API
Author Jim Starkey
Following the theme proposed by Mr. Bill "Xml" Karwin, here
is a reference API for messaging that is implementable. I
am not proposing it as an extension, per se, but as a starting
point for a discussion of usability and performance.

The basic API is:

typedef long (*msg_ast)(void* ast_arg, int msg_length, const char *message);

long isc_create_message_channel (
isc_status *status_vector,
void* database_handle, // input
void* channel_handle, // output
const char* message_filter, // input
msg_ast ast_function, // async delivery fn
void* ast_arg); // arbitrary argument

long isc_set_message_filter (
isc_status *status_vector,
const char* message_filter,
void* channel_handle);

long isc_close_message_channel (
isc_status *status_vector,
void* channel_handle);

A secondary API properly layer on the basic API:

long isc_create_message_queue (
isc_status *status_vector,
void* database_handle, // input
void* queue_handle, // output
const char* message_filter);

long isc_get_message_length (
isc_status *status_vector,
void* queue_handle, // input
short *message_length,
int blocking_flag);

long isc_get_message(
isc_status *status_vector,
void* queue_handle, // input
short buffer_length,
char *buffer,
short *message_length);

long isc_close_message_queue (
isc_status *status_vector,
void* queue_handle);

Both messages and message filters are ascii strings with
the following grammer:


where '\' is the escape character. A message filter could
contain "*" and "%" to match arbitrary strings and single
characters, respectively, in attributes (maybe) and values

A message would be posted by either:

blr_post_message, <blr_value>


PostMessage (String message) /* builtin function */

The semantics are:

1. A posted message is held until the associated transaction

2. If the transaction rolls back or a the server with a
limbo transaction fails, the message is dropped on the

3. If the transaction commits, the engine passes the message
to the message manager.

4. When the message handler receives a message, it matches
the message against each successive registered channel
message filter. If the message matches, the channel
is immediately notified. The message is then dropped
on the floor.

5. The remote server, acting as agent of client, is resposible
for registering client channel, receiving asynchronous
notifications, and blasting them to client on auxiliary

6. Romote interface receives message notification from auxiliary
connection and invokes ast function.

This mechanism is independent of the existing event mechanism. The
event server preserves no context other than registered channels and
filters. Message queuing is the sole responsibility of the client.
A client can either poll or block on a channel with isc_get_message_length.
The client is responsible for parsing the message string.

Among the operational differences from the existing mechanism:

1. Arbitrary state can be passed from engine to client.
2. Server side message processing is substantially more
computationally expensive than events.
3. Additional client side memory is required.

There are many details that can be twiddled. Among them:

1. Passing some sort of time stamp separate from the message.
2. Coercing the message into xml format (make Bill even
3. Providing a peek function into the client queue management
4. Providing a message parsing function (well, duh).
5. Providing a flag to perform automatic English/Russian or
Russian/English translation of message during transmission
across national boundaries (requires telco support).

OK, guys, go at it. No biting, scratching, or hitting below the
belt. Every message is required to have an xml reference.

Jim Starkey