Chapter 5 C Routines Reference

JagCmGetProxyConnection

Description

Retrieve a cached connection, specifying an alternate login name to set-proxy to.

Not all connection caches support set-proxy JagCmGetProxyConnection cannot be used with OCI connections. You must be connected to a database server, such as Adaptive Server Enterprise 11.5, that supports the set session authorization command. Set-proxy support must be enabled for caches in Jaguar Manager before you can use this feature. See the Jaguar CTS System Administration Guide for more information.

Syntax

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

Parameters

cache

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

When *cache is NULL, the values of username, password, server, and con_lib are used to search for a matching cache. If found, *ctx is set to the address of the connectivity-library context handle, and *cache is set to the matching cache handle.
If *cache contains a valid cache handle, JagCmGetProxyConnection retrieves the connectivity-library context for the indicated cache. You can call JagCmGetCachebyUser or JagCmGetCachebyName to obtain a cache handle for any cache that is defined in Jaguar Manager.

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, a string value indicating the connectivity library used by connections in the cache. Ignored when cache is not NULL.

When cache is NULL, con_lib must be one of the following:

con_lib value	To indicate
"CTLIB_110"	Sybase Open Client Client-Library
"ODBC"	An ODBC implementation library

connection

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

For ODBC connections, pass the address of an SQLHDBC variable
For Client-Library connections, pass the address of a CS_CONNECTION * variable

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.

proxy

The user name to set-proxy to.

Return Values

Return value	To indicate
ODBC status code	The result of a SQLAllocConnect or SQLConnect call, or the set session authorization command.
Client-Library status code	The result of a ct_con_alloc or ct_connect call, or the set session authorization command.
JAG_FAIL	Failure. JagCmGetConnection returns JAG_FAIL when the call specifies an invalid con_lib value.

Usage

JagCmGetProxyConnection retrieves a cached connection, specifying an alternate login name to set-proxy to. Set-proxy support must be enabled for a cache in Jaguar Manager. If support is enabled, connections retrieved from the cache with JagCmGetConnection set-proxy to the Jaguar client user name. Call JagCmGetProxyConnection to specify a different user name to set-proxy to.

Other than the set-proxy behavior, JagCmGetProxyConnection is identical to JagCmGetConnection.