Creating EPBs with isc_event_block( )

From InterBase
Jump to: navigation, search

Go Up to Working with Events


Before an application can register interest in an event, it must establish and populate two event parameter buffers (EPBs), one for holding the initial occurrence count values for each event of interest, and another for holding the changed occurrence count values. These buffers are passed as parameters to several API event functions.

In C, each EPB is declared as a char pointer, as follows:

char *event_buffer, *result_buffer;

Once the buffers are declared, isc_event_block() is called to allocate space for them, and to populate them with starting values.

isc_event_block() also requires at least two additional parameters: the number of events in which an application is registering interest, and, for each event, a string naming the event. A single call to isc_event_block() can pass up to 15 event name strings. Event names must match the names of events posted by stored procedures or triggers.

isc_event_block() allocates the same amount of space for each EPB, enough to handle each named event. It returns a single value, indicating the size, in bytes, of each buffer.

The syntax for isc_event_block() is:

ISC_LONG isc_event_block(char **event_buffer, char **result_buffer,
unsigned short id_count,
. . );

For example, the following code sets up EPBs for three events:

#include <ibase.h>;
. . .
char *event_buffer, *result_buffer;
long blength;
. . .
blength = isc_event_block(&event_buffer, &result_buffer, 3, "BORL",
"INTEL", "SUN");
. . .

This code assumes that there are triggers or stored procedures defined for the database that post events named “BORL”, “INTEL”, and “SUN”.

Tip: Applications that need to respond to more than 15 events can make multiple calls to isc_event_block(), specifying different EPBs and event lists for each call.

For the complete syntax of isc_event_block(), see isc_event_block().

Advance To: