16.20 - DBCHWAT - Teradata Tools and Utilities

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

prodname
Teradata Tools and Utilities
vrm_release
16.20
created_date
September 2019
category
Programming Reference
featnum
B035-2417-108K

Purpose

Waits for an event, such as the arrival of a response from the Teradata Database or some other occurrence defined by the application.

The alternate six-character name for DBCHWAT is DBCHWT.

Interface

This routine is called with the following parameters, stylistically presented (the actual syntax varies according to the programming language being used):

DBCHWAT(ReturnCode,ContextArea,ConnectionNumber,Request-token)

In high-level languages, the details of the parameter list are handled by the compiler. For Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit address of a parameter. The last address has the first bit set to one to indicate the end of the list.

The parameters for this routine are:

Argument Content
ReturnCode A 4 byte unsigned integer field into which the return code will be placed by CLIv2.
ContextArea A 4 byte unsigned integer field for internal use by CLIv2.
ConnectionNumber An area to receive a four-byte unsigned integer representing the CLIv2 connection number of the first active request to complete.
Request-token An area to receive a four-byte unsigned integer user-supplied token associated with the first active request to complete.

Usage Notes

  • Each call to DBCHWAT reflects completion of one event. If multiple events have completed, none are lost. Rather, their completions are reflected on subsequent calls to DBCHWAT. Each completed event is reflected only once.

    For example, if two events complete, the first call to DBCHWAT reflects one event, the second call reflects the second event, and the third call waits for completion of another event, if any responses are pending. When multiple responses have arrived, they are reflected to the application in the order in which their requests were initiated, not the order in which they arrived. This ensures that repeated use of a request that completes quickly does not prevent reflection of longer-running responses.

  • If DBCHUE has been used to provide a User-event, its completion is reflected before the arrival of any response.
  • DBCHWAT is normally used when an application has multiple sessions, allowing the application to be notified immediately of the first completion.
  • If there are no responses whose arrival is pending, a return code 123 results. If DBCHUE has been used to provide a User-event, it is ignored. That is, when there are no pending responses, the User-event is neither checked for completion nor does suspension occur for the event's completion. A User-event is honored only when a request has been issued but not yet completed.
  • When the DBCHME service has been used to include Teradata requests in another event, DBCHWAT never waits. If no events have completed, a return code 162 is reflected, allowing the application to wait for the master event using an operating system service.
  • After the call, the return code variable contains a return code.
  • After the call, CLIv2 changes ContextArea for its own purposes.
  • Requests for sessions that specify the Wait-exclusion option are ignored by DBCHWAT.