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

Sets up the CLIv2 environment.

The application must provide the DBCAREA and then call DBCHINI to initialize it.

The alternate six-character name for DBCHINI is DBCHIN.

Interface

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

DBCHINI(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

  • The application must declare or allocate the DBCAREA and call DBCHINI to initialize the fields prior to using CLIv2 functions.
  • Total-length must be filled in by the application before calling DBCHINI. DBCHINI verifies this value prior to any initialization attempt. The length must be at least 384, the size of the smallest DBCAREA. If the length is at least 640, the Level 1 enlarged DBCAREA will be formatted. If the length is at least 1024, the Level 2 enlarged DBCAREA will be formatted. For lengths greater than 384 but less than 640, greater than 640 but less than 1024, or greater than 1024, the excess is assumed to be an application appendage to the DBCAREA: it will be zeroed by DBCHINI but is otherwise unused by CLIv2. When not appending fields to the DBCAREA, mnemonics should be used to set the Total-length field to the largest DBCAREA. When appending fields to the DBCAREA, depending on the application development environment it may be better to use hard-coded values rather than mnemonics. For example, if the total size of the DBCAREA plus application fields must be less than some size, it might be unwise to allow the DBCAREA size to increase.
  • DBCHINI obtains default values from the HSHSPB currently available to the application.
  • The return code will either be 0 (if the initialization is completed successfully) or 126 if the Total-length value is insufficient for the smallest DBCAREA (384 bytes). After the call, the return code variable contains a return code.
  • After the call, CLIv2 changes ContextArea for its own purposes.
  • DBCHINI initializes the DBCAREA allocated by the application with the length specified in DBCSIZE. DBCHINI does not initialize any DBCAREA extensions addressed by the DBCAXP DBCAREA field.