JagCmGetCachebyUser  JagCmGetCtx

Chapter 5: C Routines Reference

JagCmGetConnection

Description

Retrieve a connection from a specified cache or from any cache that matches a specified set of values for server, user name, password, and connectivity library.

Syntax

JagStatus JagCmGetConnection (
        JagCmCache    *cache,
        SQLCHAR       *username,
        SQLCHAR       *password,
        SQLCHAR       *server,
        SQLCHAR       *con_lib,
        SQLPOINTER    *connection,
        JagCmOpt      opt
        );

Parameters

cache

The address of a JagCmCache cache handle variable. The input value determines how the parameter is used:

username

When *cache is NULL, the user name for connections in the desired cache. Ignored when *cache is not NULL.

password

When *cache is NULL, the password used by connections in the desired cache. Ignored when *cache is not NULL.

server

When *cache is NULL, the name of the server to which cached connections are made. Ignored when *cache is not NULL.

con_lib

When *cache is NULL, indicates a string value indicating the connectivity library used by connections in the cache. Ignored when *cache is not NULL.

When *cache is NULL, allowable values for con_lib are:

con_lib value

To indicate

“CTLIB_110”

Sybase Open Client Client-Library

“ODBC”

An ODBC implementation library

“OCI_7”

Oracle Call Interface 7.x

“OCI_8”

Oracle Call Interface 8.x

connection

The address of a variable that receives the connection handle. Declare a variable of the appropriate type, as follows:

On successful return, the connection will be open and in a state that allows commands to be sent to the remote server.

opt

A symbolic value that indicates the desired behavior if all connections in a cache are in use. Allowable values are:

Value of opt

JagCmGetConnection behavior when all connections are in use

JAG_CM_NOWAIT

Fails with an error if no connection can be returned.

JAG_CM_WAIT

Does not return until a connection becomes available.

JAG_CM_FORCE

Allocates and opens a new connection. The new connection is not cached and will be destroyed when JagCmReleaseConnection is called.

Returns

Return value

To indicate

ODBC status code

The result of a SQLAllocConnect or SQLConnect call, or SQL_SUCCESS in the case where a previously opened connection is returned.

Client-Library status code

The result of a ct_con_alloc or ct_connect call, or CS_SUCCEED in the case where a previously opened connection is returned.

OCI_SUCCESS (An OCI 7.x and 8.x status code)

Successful retrieval of an OCI 7.x or 8.x connection.

OCI_FAIL (An OCI 7.x and 8.x status code)

Failure to retrieve an OCI 7.x or 8.x connection. Check the server log for errors, and verify that the connection can be pinged in EAServer Manager.

JAG_FAIL

Failure. JagCmGetConnection returns JAG_FAIL when the call specifies an invalid con_lib value.

Usage

JagCmGetConnection returns a connection that was allocated and opened with the specified connectivity library and that has matching values for server, user name, and password.

JagCmGetConnection behaves differently depending on whether the *cache parameter is NULL.


Calls that pass a NULL cache handle

If *cache is NULL, CmGetConnection looks for a cache with settings that match the values of the username, password, server, and con_lib parameters. If a cache is found and a connection is available, a connection is returned from that cache and *cache is set to reflect the cache from which the connection came. If no cache is found, then a connection structure is allocated, a connection is opened using the specified connectivity library and the new connection structure is returned. If a cache was found, con_lib is ignored. The following table summarizes the JagCmGetConnection call when *cache is NULL.

Table 5-3: JagCmGetConnection behavior when *cache is NULL

Cache found?

Connection available in cache?

Result

Yes

Yes

The call returns a connection handle in *connection and sets *cache to reflect the cache from which the connection came.

Yes

No

Depending on the value of the opt parameter, the call fails, waits for an available connection, or allocates and opens a new, uncached connection. *cache is returned as NULL.

No

N/A

The call attempts to allocate and open a new, uncached connection. *cache is returned as NULL.


Cached and uncached connections

A connection obtained with JagCmGetConnection is either cached or uncached.

A cached connection is one that was taken from a configured connection cache. When JagCmGetConnection returns a cached connection, it sets *cache to indicate the cache to which the connection belongs. Cached connections must be released to the cache from which they were taken: pass the cache reference obtained in the JagCmGetConnection call when calling JagCmReleaseConnection.

An uncached connection is one that was not taken from a cache. JagCmGetConnection returns an uncached connection in either of the following cases:


Calls that pass a non-NULL cache handle

When a cache handle is passed in *cache, JagCmGetConnection looks for an available connection in that cache. If none is available, then the value of the opt parameter determines whether the call waits for a connection to be released, fails, or opens a new, uncached connection.

See also

JagCmReleaseConnection





Copyright © 2005. Sybase Inc. All rights reserved. JagCmGetCtx