isc_wait_for_event()
Go Up to API Function Reference
Waits synchronously until one of a specified group of events is posted.
- Note: The
isc_wait_for_event()
function was calledgds_$event_wait
() in InterBase 3.3. It is therefore the only function that can’t be translated from 3.3 nomenclature to all later versions by replacinggds_$
withisc_
.
Syntax
ISC_STATUS isc_wait_for_event(
ISC_STATUS *status_vector,
isc_db_handle *db_handle,
short length,
char *event_buffer,
char *result_buffer);
Parameter | Type | Description |
---|---|---|
|
|
Pointer to the error status vector |
|
|
|
|
|
Length of the event parameter buffers, returned by the |
|
|
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 |
|
|
Pointer to the event parameter buffer to be filled in with updated event counts as a result of this function call; this buffer should have been initially allocated by a call to |
Description
isc_wait_for_event()
is used to wait synchronously until one of a specified group of events is posted. Control is not returned to the calling application until one of the specified events occurs.
Events on which to wait are specified in event_buffer
, which should have been initially allocated and filled in by a previous call to isc_event_block()
.
When one of these events is posted, isc_wait_for_event()
fills in result_buffer
with data that exactly corresponds to the data in the initial buffer, except that the event counts will be the updated ones. Control then returns from isc_wait_for_event
() to the calling application. The application should then call isc_event_counts()
to determine which event was posted.
- Note: To request
asynchronous
notification of event postings, useisc_que_events
() instead ofisc_wait_for_event()
. You must use asynchronous notifications in Microsoft Windows applications, or wherever a process must not stop processing.
Example
The following program fragment illustrates a call to isc_wait_for_event()
to wait for a posting of any of the events named “DEC”, “HP”, or “SUN”.
#include <ibase.h> #define number_of_stocks 3; char *event_buffer, *result_buffer; short length; length = (short)isc_event_block( &event_buffer, &result_buffer, number_of_stocks, "DEC", "HP", "SUN"); isc_wait_for_event( status_vector, &database_handle, length, /* Returned from isc_event_block(). */ event_buffer, result_buffer); if (status_vector[0] == 1 && status_vector[1]) { isc_print_status(status_vector); /* Display error message. */ return(1); } /* Call isc_event_counts() to compare event counts in the buffers * and thus determine which event(s) were posted. */
Return value
isc_wait_for_event()
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.