DBCHUE
Restriction
Only supported on Microsoft Windows platforms.
Description
Associates platform-defined events with user defined contexts. Currently only supports one event type - a timeout defined internally as CLI_WIN_TIMEOUT.
Parameters
The following structure, cli_win_event is used as the parameter EventIDAddress in this function:
struct cli_win_event {
Int32 kind; /*event kind */
void *data; /*event data */
}
where kind must be a CLI_WIN_TIMEOUT and data must point to a timeval structure.
struct timeval {
Int32 tv_sec; /* seconds */
Int32 tv_usec; /* microseconds */
}
The DBCHUE parameters are:
|
DBCHUE (ReturnCode, ContextArea, EventIDAddress, Function) |
|
|
Int32 *ReturnCode |
|
|
char **ContextArea |
|
|
struct cli_win_event *EventIDAddress |
|
|
Int32 Function |
where:
|
The parameter... |
Is the... |
|
ReturnCode |
Address of a four byte signed integer allocated by the application program. |
|
|
After control returns from DBCHUE, the integer contains a code whose value represents success or failure. A zero return value indicates success, while a non-zero return code indicates the reason for failure. |
|
|
Possible return codes include: EM_OK - no errors |
|
|
BADUECNTA - context area is invalid |
|
|
BADUEKIND - bad kind value |
|
|
BADUEDATA - data values NULL |
|
|
ALLOCFAIL - memory failure |
|
|
BADUEFUNC - invalid function specified |
|
ContextArea |
Indirect pointer to a character pointer. During INSERT_EVENT functions, this pointer is allocated memory and initialized by DBCHUE. During DELETE_EVENT functions, this memory is freed by DBCHUE. |
|
|
This ContextArea is used for waiting on user defined events in DBCHWL. |
|
EventIDAddress |
User defined event. Currently only event kinds of CLI_WIN_TIMEOUT are supported. |
|
Function |
4 byte signed integer defining 2 supported event types - INSERT_EVENT and DELETE_EVENT. INSERT_EVENT inserts the event and associates the event with the ContextArea. DELETE_EVENT deletes the event and disassociates the event with the ContextArea. |
Usage Notes
DBCHUE presently only supports two event types - INSERT_EVENT and DELETE_EVENT.
Only CLI_WIN_TIMEOUT events are supported.
Only one event may be associated with a ContextArea.
DBCHUE supports multi-threaded CLI.
Example
This example defines a 5 second timeout event for use with DBCHWL.
cli_win_event time_event;
static struct timeval time_val;
Int32 result = 0;
Int32 retcode = 0;
char *cnta;
time_val.tv_sec = 5;
time_val.tv_usec = 0;
time_event.kind = CLI_WIN_TIMEOUT;
time_event.data = (void *)&time_val;
retcode = DBCHUE(&result, (char **) &cnta, &time_event,
INSERT_EVENT);