Determining Which Events Occurred with isc_event_counts()

From InterBase
Jump to: navigation, search

Go Up to Working with Events


When an application registers interest in multiple events and receives notification that an event occurred, the application must use isc_event_counts() to determine which event or events occurred. isc_event_counts() subtracts values in the event_buffer array from the values in the result_buffer array to determine the number of times each event has occurred since an application registered interest in a set of events. event_buffer and result_buffer are variables declared within an application, and allocated and initialized by isc_event_block().

The difference of each element is returned in the error status array that is passed to isc_event_counts(). To determine which events occurred, an application must examine each element of the array for nonzero values. A nonzero count indicates the number of times an event is posted between the time isc_event_block() is called and the first time an event is posted after isc_wait_for_event() or isc_que_events() are called. Where multiple applications are accessing the same database, therefore, a particular event count may be 1 or more, and more than one event count element may be nonzero.

Note: When first setting up an AST to trap events with isc_que_events(), InterBase initializes all count values in the status vector to 1, rather than 0. To clear the values, call isc_event_counts() to reset the values.

In addition to determining which event occurred, isc_event_counts() reinitializes the event_buffer array in anticipation of another call to isc_wait_for_event() or isc_que_events(). Values in event_buffer are set to the same values as corresponding values in result_buffer.

The complete syntax for isc_event_counts() is:

void isc_event_counts(ISC_STATUS status_vector, short buffer_length,
char *event_buffer, char *result_buffer);

For example, the following code declares interest in three events, waits on them, then uses isc_event_counts() to determine which events occurred:

#include <ibase.h>;
. . .
char *event_buffer, *result_buffer;
long blength;
ISC_STATUS status_vector[20];
isc_db_handle db1;
long count_array[3];
int i;
. . .
/* Assume database db1 is attached here and a transaction started. */
blength = isc_event_block(&event_buffer, &result_buffer, 3,
"BORL", "INTEL", "SUN");
isc_wait_for_event(status_vector, &db1, (short)blength,
event_buffer, result_buffer);
/* Application processing is suspended here until an event occurs. */
isc_event_counts(status_vector, (short)blength, event_buffer, result_buffer);
for (i = 0; i < 3; i++) {
if (status_vector[i]) {
/* Process the event here. */
}
}

For more information about isc_event_counts(), see isc_event_counts() of API Function Reference.

Advance To: