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
15.10
Language
English (United States)
Last Update
2018-10-07
dita:id
B035-2418
lifecycle
previous
Product Category
Teradata Tools and Utilities

DBCHWAT

DBCHWAT waits for one or more requests to complete on the Teradata 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 Teradata Database simultaneously.

Note: Each session can only have one active request at a time on the Teradata Database.

DBCHWAT should not generally 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 Teradata Database. If DBCHUEC has been invoked, event also refers to the occurrence of some application-program-defined event.

Parameters

 

where:

 

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 it's 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.