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

DBCHCL calls the functions requested by the application program.

For an overview of the functions relative to DBCHCL (see the table under Use of CLIv2 Routines: Tabular Summary). Each function is described in detail later in the sections that follow.

How It Works

Before each call to DBCHCL, the application program 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 and then passes back to the caller the DBCAREA, which contains, among other things, a return code.

The application program checks the return code in the DBCAREA, which is where CLI and MTDP indicate any problem they find. If the call resulted in a delivery of parcels to the response buffer, the program checks the first parcel, which is the Error and Failure parcel.

Parameters

The DBCHCL parameters are as follows:

Int32 DBCHCL (ReturnCode, ContextArea, DBCAREA)
Int32 *ReturnCode;
char *ContextArea;
struct dbcarea_struct *dbcarea;

where the following is true:

The parameter . .buffer-full 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 DBCHCL, the integer contains a code whose value represents success or failure of the function as seen by CLI and MTDP.

A return code of zero indicates success. A non-zero return code indicates failure, and the value specifies the reason.

The return code covers only the work done on the client, it does not cover any work that may have been done on the database.
ContextArea Four-byte field that 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-attached systems.

DBCAREA Four-byte address of the area allocated by the application program for use as DBCAREA.

The application program and CLI share the DBCAREA and use it for input of values to CLI and output of values from CLI.

Usage Notes

Before DBCHCL is called:
  • The application program must call DBCHINI to initialize the DBCAREA to be used by DBCHCL.
  • The application program must provide input in the DBCAREA whose address is provided to DBCHCL. The function code must always be provided. The other input that must be provided is determined by the function code chosen.
After DBCHCL returns control to the application program, the application program must check the return code. The return code may be checked in either the parameter list, the DBCAREA or in the DBCHCL function. All have the same value.
  • If the application program is running with Wait For Response set to 'Y', a return code of busy (EM_NODATA 211) will not be encountered.
  • If the application program is running with Wait For Response set to 'N', a return code of busy may be encountered.

What Busy Means

Busy means that the requested function could not be initiated or completed, because the session was in pending state (that is, CLI was waiting for the database to send it some information it requested on that session). There are two ways to code for busy:
  1. If the return code from DBCHCL is busy, call DBCHCL for the same function, repeat.
  2. If the return code from DBCHCL is busy, call DBCHWAT, check for a DBCHWAT return code of zero, call DBCHCL for the same function, repeat.

The second method is strongly preferred because it does not tie up the system during the wait period.

Do not code a fixed number of loops, because the number may change depending on the circumstances.