The ReleaseConnect() function (Windows)

The ReleaseConnect() function is available only in Windows™ environments. It releases, or terminates, the explicit connection and clears all allocated memory.

Important: supports the ReleaseConnect() connection library function for compatibility with Version 5.01 for Windows applications. When you write new applications for Windows environments, use the SQL DISCONNECT statement to terminate an established explicit connection.

Syntax

void *ReleaseConnect ( void *CnctHndl )

CnctHndl: A connection handle returned by a previous GetConnect() call.

Usage

The ReleaseConnect() function maps to a simple SQL DISCONNECT statement (one without an ALL, CURRENT, or DEFAULT option). The ReleaseConnect() call by itself is equivalent to the following SQL statement:

EXEC SQL disconnect db_connection;

In this example, db_connection is the name of an existing connection that the GetConnect() function has established. You pass this db_connection name to ReleaseConnect() as an argument; it is a connection handle for the desired connection.

For example, the following code fragment uses ReleaseConnect() to close an explicit connection to the stores7 database on the default database server:

void *cnctHndl;
;

cnctHndl = GetConnect();
EXEC SQL database stores7;
;

EXEC SQL close database;
cnctHndl = ReleaseConnect( cnctHndl );

Call ReleaseConnect() once for each connection that GetConnect() has established. The ReleaseConnect() function closes any open database before it terminates the current connection. It fails if any transactions are open in the current connection.

It is good programming practice to close the database explicitly with the SQL CLOSE DATABASE statement before the call to ReleaseConnect()

Important: Because the ReleaseConnect() function maps to a DISCONNECT statement, it sets the SQLCODE and SQLSTATE status codes to indicate the success or failure of the connection termination request. This behavior differs from ReleaseConnect() in Version 5.01 for Windows, in which this function did not set the SQLCODE and SQLSTATE values.

The ReleaseConnect() function differs from the DISCONNECT statement in the way that it obtains the connection name. ReleaseConnect() uses an internally generated name that is stored in the connection handle; you must specify this handle as an argument to the ReleaseConnect() call. The DISCONNECT statement uses an internally generated connection name only for a connection that a CONNECT statement without an AS clause has established; if the connection has a user-defined connection name (which the AS clause of the CONNECT statement specifies), DISCONNECT uses this name.

Return codes

CnctHndl: The call to ReleaseConnect() was successful if the function has returned a connection handle that matches the one passed to it.