Chapter 5: C Routines Reference

JagCmReleaseConnection

Description

Place a connection back in the cache for reuse.

Syntax

JagStatus JagCmReleaseConnection (

        JagCmCache    *cache,

        SQLCHAR       *username,

        SQLCHAR       *password,

        SQLCHAR       *server,

        SQLCHAR       *con_lib,

        SQLPOINTER    connection,

        SQLINTEGER    opt

);

Parameters

cache

The address of a JagCmCache cache handle variable. *cache can be NULL or a valid cache handle.

If *cache is not NULL, must be the cache handle that was used to obtain the connection by calling JagCmGetConnection.

If *cache is NULL, JagCmReleaseConnection attempts to place the connection in a cache that has available space and that uses the same values for username, password, server, and con_lib. If no such cache has available space, the connection is closed and deallocated.

username: The user name of the connection. Ignored unless cache is NULL.

password: The password used by the connection. Ignored unless cache is NULL.

server: The name of the server to which the connection is made. Ignored unless cache is NULL.

con_lib

A string value indicating the connectivity library used by the connection. Ignored unless cache is NULL. Allowable values for con_lib are:

con_lib value	To indicate
“CTLIB_110”	Sybase Open Client Client-Library
“ODBC”	An ODBC driver library
“OCI_7”	Oracle Call Interface 7.x
“OCI_8”	Oracle Call Interface 8.x

connection: The connection handle to be released. The connection must be in a state that allows commands to be sent to the remote server. If commands were sent using the connection, the results of the commands must have been completely processed.

opt

One of the following symbolic constants:

opt value	To indicate
JAG_CM_DROP	The connection should be forced closed and deallocated. If the connection came from a cache, a new connection will be created in its place.
JAG_CM_UNUSED	Normal behavior: a connection taken from a cache is placed back in the cache; a connection created outside of a cache is closed and destroyed.

Use JAG_CM_DROP to destroy a connection when errors have made it unusable.

Returns

Returns	To indicate
ODBC or Client-Library return status	The result of connectivity library calls to close and deallocate a connection that was not released to a cache.
CS_SUCCEED	A Client-Library connection was returned to a cache.
SQL_SUCCESS	An ODBC connection was returned to a cache.
JAG_FAIL	Failure. JagCmReleaseConnection fails when cache is NULL and con_lib specifies an invalid value.

Usage

JagCmReleaseConnection releases control of a connection that was obtained from JagCmGetConnection.

WARNING! Do not release a connection more than once.