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

DBCHWAT waits for one or more requests to complete on the database and the response to arrive at the workstation, that is, it returns to the caller the session id and the associated request Token (which was supplied by the application when the request was initiated) of the first active request to complete.

DBCHWAT is intended primarily for the use of multi- session applications so that the application can have several active requests on the database simultaneously.

Each session can only have one active request at a time on the database.

DBCHWAT should not be used by multi-threaded applications. Nor should it be used by single-threaded applications that employ more than one CLIv2-dependent component within a given process. Because DBCHWAT causes the current unit of work to block until any session within the process returns ready, it is possible for unpredictable results to occur should a request initiated by one component signal completion while another component is in control. To avoid this problem, such applications should instead use DBCHWL exclusively.

What Event Means

DBCHWAT waits for an event to occur. Event refers to the arrival of some response from the database. If DBCHUEC has been invoked, event also refers to the occurrence of some application-program-defined event.

Parameters

Int32 DBCHWAT (ReturnCode, ContextArea, sessid, token)
Int32 *ReturnCode;
char *ContextArea;
Int32 *sessid;
Int32 *token;

where the following is true:

The parameter... Is the...
ReturnCode four-byte address of an area allocated by the application program for storage of a four-byte signed integer.
After control returns from DBCHWAT, the integer contains a code whose value represents success or failure.
  • A return code of zero indicates success.
  • A non-zero return code indicates failure, and the value specifies the reason for the failure.
ContextArea four-byte field which may contain any value, because it is not used by CLI or the application program.

It is provided to maintain compatibility with calls on mainframe clients.

sessid (session) four-byte address of an area allocated by the application for storage of a four-byte signed integer.

After control returns from DBCHWAT, the integer contains the logical session id of the first active request to complete.

token four-byte address of an area allocated by the application for storage of a four-byte signed integer.

After control returns from DBCHWAT, the integer contains the user-supplied token, if there is one, that is associated with the first active request to complete.

Usage Notes

If two requests post arrival of responses, the second notice does not overwrite the first. Each call to DBCHWAT will obtain a notice of the arrival of a response until the list of postings is empty.

Also, after the application is notified about the arrival of a response, DBCHWAT no longer retains information about that posting. For example, if two requests complete and the application calls DBCHWAT three times, on the third time DBCHWAT returns "nothing pending".

With the introduction of multi-threaded Windows CLI, DBCHWAT becomes limited in its applicability on Windows platforms for multi-threaded applications. A more applicable wait function - DBCHWL will wait on a list of sessions for each thread, while DBCHWAT waits on the next available request from ANY session.

Returns 0 if succeeds, else returns error.