17.10 - DBCHINI - Call-Level Interface Version 2

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

Call-Level Interface Version 2
Release Number
Release Date
October 2021
Content Type
Programming Reference
Publication ID
English (United States)

DBCHINI sets up the CLI environment. Applications must allocate the DBCAREA and then call DBCHINI to initialize it.

How It Works

Applications must first allocate storage for a DBCAREA and then call DBCHINI for the following processing:
  • Initializing the DBCAREA
  • Resetting the DBCAREA length field
  • Setting all options to either their default (in CLI2SPB) or application specified values (in clispb.dat)
  • Initializing MTDP for the application
DBCHINI does not initialize the DBCAREAX.


The DBCHINI parameters are as follows:

Int32 DBCHINI (ReturnCode, ContextArea, DBCAREA)
Int32 *ReturnCode;
char *ContextArea;
struct DBCAREA

where the following is true:

For the Return Code Address
Length: 4 bytes
Input: address of a four-byte integer return code variable
Output: unchanged

After control returns from DBCHINI, the integer contains a code whose value represents success or failure to initialize. Return code zero indicates the DBCAREA is initialized. A non-zero return code indicates failure, and the value specifies the reason for the failure.

For the Context Area Address
Length: 4 bytes
Input: 0
Output: address of the internal CLI context area

Context Area is provided to maintain compatibility with calls on mainframe-attached systems.

For the DBCAREA Address
Length: 4 bytes
Input: address of the DBCAREA structure
Output: unchanged

Applications and CLI share the DBCAREA and use it for input of values to CLI and output of values from CLI.

Usage Notes

Application must declare or allocate the DBCAREA and call DBCHINI to initialize the fields prior to using CLI functions. Total Length must be filled in by the application before calling DBCHINI.

DBCHINI obtains default values from the SPB currently available to the application.

Applications are able to use the same DBCAREA for all requests. If this is the case, one call to DBCHINI is sufficient regardless of the number of sessions, requests, and so on, used by the application program. If the DBCAREA is used this way, Input Session Id, Input Request Id, and Token, if used, must be checked before each call, to ensure that they are appropriate for that call.

But the application can allocate and then initialize a new DBCAREA for each session and even for each request within each session. This is done by another call to DBCHINI with the new location. Using multiple DBCAREAs requires additional space for the extra DBCAREAs and additional time to allocate and initialize the extra DBCAREAs. However, this may result in saving some CPU time after the application program is in progress.

In addition to initializing the DBCAREA, DBCHINI also allocates and initializes some internal data structures.