isc_wait_for_event()

From InterBase

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 called gds_$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 replacing gds_$ with isc_.

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

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.

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().

result_buffer

char *

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 isc_event_block().

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, use ­isc_que_events() instead of isc_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.

See Also

Advance To: