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 EAServer Manager before you can use this feature. See Chapter 4, "Database Access," in the EAServer 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 EAServer 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 Value

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 EAServer Manager. If support is enabled, connections retrieved from the cache with JagCmGetConnection set-proxy to the 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.