17.10 - DBCHUE - Call-Level Interface Version 2

Teradata® Call-Level Interface Version 2 Reference for Workstation-Attached Systems

Product
Call-Level Interface Version 2
Release Number
17.10
Release Date
October 2021
Content Type
Programming Reference
Publication ID
B035-2418-061K
Language
English (United States)

Associates platform-defined events with user defined contexts. Currently only supports one event type - a timeout defined internally as CLI_WIN_TIMEOUT.

Restriction

Only supported on Microsoft Windows platforms.

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 as follows:

DBCHUE (ReturnCode, ContextArea, EventIDAddress, Function)
Int32 *ReturnCode
char **ContextArea
struct cli_win_event *EventIDAddress
Int32 Function

where the following is true:

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);