17.10 - DBCHWL - 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)

Wait for completion of any active requests from the application or events associated with the ContextArea.

A completed request will return the request token and the session id. A completed event will return a value in ReturnCode indicating completion of the event.

Only those sessions defined in the supplied sessions list are considered eligible.

Parameters

Int32 DBCHWL (ReturnCode, ContextArea,sessions, sessid, reqtoken)
Int32 *ReturnCode;
char **ContextArea;
SESSIONS_PTR sessions
Int32 *sessid;
Int32 *reqtoken;

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 DBCHWL, 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.

If the sessions array is NULL, a NOSESSION error is returned. If the ContextArea is not initialized correctly, a BADUECNTA error is returned. If the user supplied event times out, an EM_TIMEEXCEEDED error is returned.

ContextArea Indirect pointer to a character pointer. DBCHUE initializes the ContextArea and associates an event with this ContextArea.

If this parameter is non-null, DBCHWL will wait for completion of the defined event or a completed request contained within the session list, whichever completes first.

sessions Array of SESSIONS_PTR, containing session ids in which the application is interested on completion of requests. This user supplied array must contain a NULL session array element terminating this array.
sessid (session) Pointer to a four-byte signed integer. After control returns successfully from DBCHWL, sessid will contain the value of the session id of the completed request.
reqtoken Pointer to a four-byte signed integer. After control returns successfully from DBCHWL, reqtoken will contain the optionally supplied user token, that is associated with the first active request to complete, from the user supplied sessions list.

Usage Notes

DBCHWL must contain a NULL session in the terminating element of the SESSIONS_PTR array.

DBCHWL waits for a request on a specified list of sessions or an event associated with a ContextArea defined in DBCHUE.

Only CLI_WIN_TIMEOUT events are supported as event types in DBCHWL. The associated return code from this event is EM_TIMEEXCEEDED.

This function supports multi-threaded CLI.

Example

Wait for requests from a single session for only 5 seconds.

/* supplied from a previous call to DBCHUE - char *cnta, which
	 	 	 contains a 5 second timeout event */
SESSIONS_PTR Sessions;
Int32 Active;
Int32 retcode = 0;
Int32 result = 0;
struct DBCAREA dbc;

/* allocate 2 session arrays and initialize arrays to 0's */
	 	 	 Sessions = (SESSIONS_PTR)calloc(2, sizeof(SESSIONS));
/* the dbcarea has been updated from the dbc.o_sess_id from
	 	 	 DBFCON CLI function */
/* first session is set, second session is NULL */
Sessions[0].session = dbc.i_sess_id;

retcode = DBCHWL(&result, (char **) &cnta, Sessions,
	 	 	 	 	 	 &Active,&dbc.token);
/* done with the event - delete the event and free memory */
retcode = DBCHUE(&result, (char **) &cnta, &time_event,
	 	 	 	 	 	 DELETE_EVENT);