DBCHCL - Teradata Tools and Utilities

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

Teradata Tools and Utilities
Release Number
June 2021
English (United States)
Last Update
Product Category
Teradata Tools and Utilities


Calls the functions to be used by the application.

An overview of the functions relative to DBCHCL is given in the first table in Summary of CLIv2 Routine Parameters. Each function is described in detail later in this section.


Before each call to DBCHCL, the application modifies the DBCAREA to specify the action requested and to fill in the input fields relevant to that action. DBCHCL carries out the function specified by the function code in the DBCAREA, then passes back to the caller the DBCAREA, which contains, among other things, a return code. The application checks the return code in the DBCAREA, which is where CLIv2 and TDP indicate any problem they find.

If the call results in a delivery of parcels to the response buffer, the program checks the first parcel, which may be one of the following:
  • Success
  • Error
  • StatementError
  • Failure


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


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 Four-byte unsigned integer field into which the return code is placed by CLIv2.
ContextArea Four-byte unsigned integer field for internal use by CLIv2.

Usage Notes

  • Before DBCHCL is called, the application must have called DBCHINI to initialize the DBCAREA to be used by DBCHCL.
  • After the call, CLIv2 changes ContextArea for its own purposes.
  • The DBCAREA address must always be passed to DBCHCL.
    • In addition, the function code must be supplied.
    • Other fields in the DBCAREA must be set as appropriate to the function requested.
  • If Wait-for-response is set to N (set and used by the Connect, Initiate Request, Command, Initiate with Protocol, and RunStartUp functions; used by the Fetch, Abort, Rewind, End Request, and Disconnect functions) and CLIv2 is waiting for a response from the database, the application receives a return code of 150 (busy).
    • The application may handle the busy response by calling routine DBCHWAT and waiting for control to return to the application.
    • If the return code is 0, resubmit the DBCHCL function that initially returned the busy indication.
  • If Return Code is nonzero for any function, the Message-length and Message-text fields of the DBCAREA are set.