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

DBCHCLN cleans up CLI's memory.

How It Works

The application invokes the DBCHCLN routine when all processing that involves interfacing with the database is complete.

DBCHCLN logs off any idle sessions, awaits completion of any active sessions (internally DBCHCLN invokes DBFDSC on any session that is still logged on), and then logs them off. It frees all internal memory and context information allocated by CLI.

DBCHCLN de-allocates internal data structures that were allocated by DBCHINI.

DBCHCLN returns control to the application after all sessions have been logged off and all internal context has been cleaned up.

The call to DBCHCLN does not de-allocate the DBCAREA. The application program may itself de-allocate the DBCAREA if the programming language provides that ability.

DBCHCLN performs cleanup on a process-wide basis and should only be issued once. If the application program consists of multiple threads using CLIv2, issuing DBCHCLN while one or more threads is still using CLIv2 can result in failures. To avoid this situation, verify the application program issues DBCHCLN only from a control or supervisory thread after all other threads have concluded their use of CLIv2. Alternatively, the application program can use the atexit() function of the C/C++ run-time library to invoke DBCHCLN at process termination as follows:

if (atexit(clean_up))
{
   perror("atexit failed");
   exit(8);
}
...

void clean_up(void)
{
DBCHCLN(&result, cnta);
}

The process termination exit registered by atexit() is only called for normal termination. It will not receive control if the program is terminated by abort(), an unhandled signal. Consult system documentation or man pages for further information.

Returns 0 if succeeds, else returns error.

Parameters

Int32 DBCHCLN (ReturnCode, ContextArea)
Int32 *ReturnCode;
char *ContextArea;

where the following is true:

The parameter... 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 DBCHCLN, the integer contains a code whose value represents success or failure to clean up. A return code of zero indicates success; a non-zero return code indicates failure, and the value specifies the reason for the failure.

ContextArea Four-byte field which 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 clients.