isc_que_events()

Go Up to API Function Reference

Requests asynchronous notification of one of a specified group of events. For more information about writing an asynchronous event trap (AST) function, see Working with Events.

Syntax

 ISC_STATUS isc_que_events(
 ISC_STATUS *status_vector, 
 isc_db_handle *db_handle, 
 ISC_LONG *event_id,
 short length,
 char *event_buffer,
 isc_callback event_function,
 void *event_function_arg);

Parameter	Type	Description
<status_vector>	`ISC_STATUS` `*`	Pointer to the error status vector
<db_handle>	`isc_db_handle *`	Pointer to a database handle set by a previous call to `isc_attach_database`()`;` the handle identifies the database against which the events are expected to be posted. `db_handle` returns an error in `status_vector` if it is `NULL`.
<event_id>	`ISC_LONG` `*`	Pointer to an event identifier to set
<length>	`short`	Length of the event parameter buffers, returned by the `isc_event_block()` call which allocated them.
<event_buffer>	`char *`	Pointer to the event parameter buffer that specifies the current counts of the events to be waited on; this buffer should have been initially allocated and filled in by a call to `isc_event_block()`.
<event_function>	`isc_callback`	Pointer to the address of the function to receive event notification.
<event_function_arg>	`void *`	First argument to be passed to `event_function`, usually a pointer to the event parameter buffer you want to be filled in with updated event counts.

Description

isc_que_events() is called to request asynchronous notification of any of the events listed in event_buffer. Upon completion of the call, but before events are posted, control is returned to the calling application, which can continue other processing. When a requested event is posted, InterBase calls the function specified in event_function to process event occurrence.

After event_function is called, you must call isc_que_events() again if you want to start another asynchronous wait on the specified events.

Note: isc_que_events() cannot be called from within event_function.

If you want to cancel your isc_que_events() request for asynchronous event notification, call isc_cancel_events().

Note: To request synchronous notification, call isc_wait_for_event().

Example

The following program fragment illustrates calling isc_que_events() to wait asynchronously for event occurrences. Within a loop, it performs other processing, and checks the event flag (presumably set by the specified event function) to determine when an event has been posted. If one has, the program resets the event flag, calls isc_event_counts() to determine which events have been posted since the last call to isc_que_events(), and calls isc_que_events() to initiate another asynchronous wait.

#include <ibase.h>
#define number_of_stocks 3;
#define MAX_LOOP 10

char *event_names[] = {"DEC", "HP", "SUN"};
char *event_buffer, *result_buffer;
ISC_STATUS count_array[number_of_stocks];
short length;
ISC_LONG event_id;
int i, counter;
int event_flag = 0;
length = (short)isc_event_block(&event_buffer, &result_buffer,
  number_of_stocks, "DEC", "HP", "SUN");
isc_que_events(status_vector,
 &database_handle, /* Set in previous isc_attach_database(). */
 &event_id,
 length, /* Returned from isc_event_block(). */
   event_buffer, (isc_callback)event_function,
 result_buffer);
if (status_vector[0] == 1 && status_vector[1]) {
isc_print_status(status_vector); /* Display error message. */
return(1);
};
counter = 0;
while (counter < MAX_LOOP) {
counter++;
if (!event_flag) {
/* Do whatever other processing you want. */
}
else {
event_flag = 0;
isc_event_counts( count_array, length, event_buffer, result_buffer);
if (status_vector[0] == 1 && status_vector[1]) {
isc_print_status(status_vector); /* Display error message. */
return(1);
}
for (i=0; i<number_of_stocks; i++)
if (count_array[i]) {
/* The event has been posted. Do whatever is appropriate,
 * for example, initiating a buy or sell order. Note: event_names[i]
 * tells the name of the event corresponding to count_array[i]. */
}
isc_que_events(status_vector, &database_handle, &event_id, length,
 event_buffer, (isc_callback)event_function,
 result_buffer);
if (status_vector[0] == 1 && status_vector[1]) {
isc_print_status(status_vector); /* Display error message. */
return(1);
}
} /* End of else. */
} /* End of while. */

/* Let InterBase know you no longer want to wait asynchronously. */
isc_cancel_events(status_vector, &database_handle, &event_id);
if (status_vector[0] == 1 && status_vector[1]) {
isc_print_status(status_vector); /* Display error message. */
return(1);
}

Return value

isc_que_events() returns the second element of the status vector. Zero indicates success. A nonzero value indicates an error. For InterBase errors, the first element of the status vector is set to 1, and the second element is set to an InterBase error code.

To check for an InterBase error, examine the first two elements of the status vector directly. For more information about examining the status vector, see Handling Error Conditions.

Advance To:

isc_rollback_retaining()