16.20 - DBCHCL - 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

Calls the functions to be used by the application.

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

Process

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

Interface

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

DBCHCL(ReturnCode,ContextArea,DBCAREA)

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.
DBCAREA The DBCAREA structure.

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 will change 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 Teradata Database, the application will receive 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 will be set.