Chapter 1 Jaguar Configuration

Managing connection caches

A connection cache maintains a pool of available connections that Jaguar components use to interact with third-tier data servers. You must configure connection caches for the specific user and database combinations used by your components. A connection cache entry improves performance by eliminating the overhead associated with setting up a connection when one is required. Create as many connection caches as you need.

See Chapter 28, "Using Connection Management" in the Jaguar CTS Programmer's Guide for additional information.

A cache must be installed in a server before it is available to components running on that server. You must refresh the cache, refresh the server, or restart the server before any changes to the list of installed caches or to cache properties take effect, and you should test the connection with ping before trying to access it from components.

You cannot define two distinct caches that use identical values for server, user, password, and connectivity library. If two caches are defined with matching values for these settings, and your application requests one, Jaguar returns the first match that is found.

To create a new connection cache:

Highlight the Connection Caches folder.
Select either File | New Connection Cache or File | New XA Connection Cache.
Configure the connection cache properties as described in "Connection cache properties".

Configured connection cache entries appear on the right side of the window of Jaguar Manager when you highlight the Connection Cache folder on the left side of the window.

To add a connection cache to a server:

Double-click the Servers icon.
Select the server (listed on the left side of the window) where you want to install a connection cache.
Highlight the Installed Connection Caches folder.
Select File | Install Connection Cache. Then select one of the following options from the Connection Cache wizard:
- Install an Existing Connection Cache - a list of uninstalled connection caches appears in the dialog box. Highlight the connection cache to be installed and click OK.
- Create and Install a New Connection Cache - enter the name of the new connection cache to be installed. Select the connection cache property tab and complete the property sheet as described in "Connection cache properties".

To view or modify a connection cache entry:

Expand the Connection Caches folder, or, if the cache is installed in a server, expand the Installed Connection Caches folder of that server.
Highlight the connection cache you want to modify.
From the File menu, select one of the following options:
- Connection Cache Properties - view or modify this connection cache's properties. See "Connection cache properties".
- Remove Connection Cache - if you have selected a connection cache that is installed on a server, this option removes the connection cache from the server.
- Delete Connection Cache - if you have selected a connection cache that is not installed on a server, this option deletes the connection cache from the system.

Connection cache properties

Table 1-7 lists the general and driver connection cache properties that you can configure in Jaguar Manager. After you have configured a connection cache, click OK to save your changes, or click Cancel to disregard them. You must use the cache properties file to manually configure the additional properties described in "Other cache settings".

Table 1-7: Connection cache properties
Property	Description	Comments/example
Connection Cache Name	The name for this cache configuration.	Connection cache names are limited to one word, which can contain letters, numbers, and underscores. Names are case-sensitive. You cannot modify the name of an existing connection cache.
Description	The description of the connection cache section.	The description is a string of a maximum of 255 characters.
Enable Cache-by-Name Access	Select this option to allow retrieval of a database connection using the connection cache name instead of requiring a user name and password.	By default, a cache cannot be retrieved by its name. You must be logged in as jagadmin to update the cache's properties to allow the cache to be retrieved by name. Cache-by-name is less secure than requiring a user name and password.
Enable connection sanity check	Whether connections should be verified before releasing them into the cache.	Components may release a connection that is not ready for use by another component. For example, there may be unretrieved results on the connection. Enabling this option causes Jaguar to test whether the connection is usable before replacing it in the cache. Disabling the option increases performance, but may complicate debugging.
Number of Connections in Cache	The number of connections in the pool.	After a connection is released, it is returned to the pool. The default value is 10. You can increase this number if performance suffers due to an insufficient number of available connections.
Service Name	When you are defining a Java connection cache that uses the Sybase jConnect driver and that connects to a Sybase DirectConnect™ gateway, set the Service Name field to the back end data server name that the DirectConnect gateway connects to.	Service name is ignored for caches that use JDBC drivers other than jConnect™ for JDBC™.
Server Name	ODBC - the ODBC data source name. CTLIB - the server name as it would be specified in a ct_connect call. On UNIX platforms, the server must be listed in the Jaguar interfaces file. For Windows NT, it must be listed in the ini\sql.ini file. JDBC - the URL appropriate for use in JDBC calls. OCI 7.X - the Oracle SQLNet connect string or database alias. OCI 8.X - the Oracle SQLNet connect string or database alias.	For ODBC or JDBC connections, see your driver documentation for more information. For OCI connections, see your Oracle documentation.
User Name	The user name for this cache.	The name used (along with a password) to connect to the database identified by the server entry.
Password	The password for this cache.	The password used in connection with a user name to connect to the database identified by the server entry. Passwords are encrypted in the Jaguar configuration file. Jaguar Manager does not display passwords for existing caches. If you need to change a password, enter the new password and click OK.
DLL or Class Name	Set the DLL or Class Name and properties using the Driver tab on the Connection Cache Properties window. Enter the file name of the connection library, and select the connection library type used for this cache. Your choices for library type are: Client Library 11.x - for Sybase Open Client Client-Library connections. ODBC - for connections using an open database connectivity driver. JDBC - for connections using a Java Database Connectivity driver. OCI 7.X - for connections using OCI 7.x OCI 8.X - for connections using OCI 8.x	The DLL names for each of the cache types are: NT: Client Library 11.x - libjct.dll. You must use the version in the Jaguar dll subdirectory. This version has been optimized for Jaguar threading. ODBC - odbc32.dll OCI 7.X - ociw32.dll OCI 8.X - oci.dll JDBC - the Java class name for the driver class. For example, the Sybase jConnect 5.2 driver requires com.sybase.jdbc2.jdbc.SybConnectionPoolDataSource. The file must be in your PATH environment variable for ODBC, Client-Library, or OCI caches, and in CLASSPATH for JDBC caches.
DLL or Class Name		For UNIX platforms: Client Library 11.x - libjct_r.so for Solaris, AIX, Digital UNIX, and LINUX; libjct_r.sl for HP-UX. You must use the version in the Jaguar lib subdirectory. This version has been optimized for Jaguar threading. ODBC - libodbc.so (installed in $JAGUAR/intersolv/odbc/dlls) for Solaris and AIX; libodbc.so (installed in /var/opt/DAU100/connect/lib) for Digital UNIX; libodbc.sl (installed in $JAGUAR/intersolv/odbc/dlls) for HP-UX. OCI 7.X or OCI 8.X - libclntsh.so for Solaris, AIX, Digital UNIX, and LINUX; libclntsh.sl for HP-UX. Client Library 11.x - libjct.dll. You must use the version in the Jaguar dll subdirectory. This version has been optimized for Jaguar threading. ODBC - odbc32.dll OCI 7.X - ociw32.dll OCI 8.X - oci.dll JDBC - the Java class name for the driver class. For example, the JDBC-ODBC driver requires sun.jdbc.odbc.JdbcOdbcDriver. On Solaris, Digital UNIX, and LINUX, the file must be in your LD_LIBRARY_PATH environment variable for ODBC, Client-Library, or OCI caches, and in CLASSPATH for JDBC caches. On AIX, the file must be in your LIBPATH environment variable for ODBC, Client-Library, or OCI caches, and in CLASSPATH for JDBC caches. On HP-UX, the file must be in your SHLIB_PATH environment variable for ODBC, Client-Library, or OCI caches, and in CLASSPATH for JDBC caches.

Other cache settings

You cannot use Jaguar Manager to set the cache settings described in this section. You must edit the underlying configuration file to change them. Use a text editor to edit the cache's property file in Repository/ConnCache. The file is CacheName.props, where CacheName represents the cache name as it displays in Jaguar Manager.

JDBC connection properties

Different JDBC drivers recognize different sets of properties. For a JDBC connection cache, these additional connection properties allow you to specify settings beyond those shown in the Connection Cache Properties dialog.

Cache properties are defined in the form:

propname=value specification

Any property whose name does not begin with com.sybase.jaguar is passed to the JDBC driver as a connection property. For example:

PACKETSIZE=2048

If a property setting conflicts with a setting in the Connection Cache Properties dialog, the dialog setting takes precedence.

See your driver documentation for more information.

Enabling set-proxy support

Current versions of Adaptive Server Enterprise and Adaptive Server Anywhere allow a user to assume the identity and privileges of another user. Except for Oracle connections that use OCI, you can use this feature with any database that recognizes this command:

set session authorization "login-name"

When proxy support is enabled, connections retrieved from the cache are set to act as a proxy for the user name associated with the Jaguar client. To set proxy to another user name, use the Java JCMCache.getProxyConnection() method or the C JagCmGetProxyConnection() routine in your component.

You must enable set-proxy support in the cache properties file before components can take advantage of it. To enable set-proxy support, add the following line to the cache properties file:

com.sybase.jaguar.conncache.ssa=true

To disable support, delete this line or change true to false .

Client-Library connection settings

You can set the following properties for Client-Library connections in the $JAGUAR/Repository/ConnCache/<cachename>.props file. See the Client-Library documentation for the ct_con_props routine for more information:

CS_HOSTNAME
CS_APPNAME
CS_TDS_VERSION
CS_PACKETSIZE

This is an example of a properties file that sets all of these properties:

# this is a comment line
CS_HOSTNAME=myhostname
CS_TDS_VERSION=CS_TDS_46
CS_PACKETSIZE=512
CS_APPNAME=myapp

Any property name not recognized by Jaguar is ignored.

The CS_TDS_VERSION property takes one of these values; CS_TDS_50, CS_TDS_495, CS_TDS_46, CS_TDS_42, or CS_TDS_40.

The CS_PACKETSIZE property takes a numeric value within the range of legal packet sizes for the server. If the server does not support the packet size then the cache will not be able to connect to the server.

Make sure there is no extraneous white space between the property name, the equals sign, and the property value, or after the property value.

Connection cache refresh

If you have just installed the cache in a server or modified an installed cache, refresh the server or the connection cache before you attempt to test the cache. You can refresh as follows:

To refresh the server, highlight the server icon where the cache is installed, then choose File | Refresh. All caches installed in the server will be refreshed.
To refresh the cache:
1. Highlight the Installed Connection Caches folder under the server icon where the cache is installed.
2. Highlight the cache's icon and choose File | Connection Cache Properties.
3. In the Connection Cache Properties dialog, click Refresh.

Refreshing a cache may affect running components that are using the cache, specifically:

If you change the connectivity library setting, cache references held by components become invalid. Attempts to retrieve connections or query cache properties will cause errors. In this case, the component must retrieve a new cache handle.
If you change other properties, such as user name, password, server name, or the number of connections in a cache, cache references remain valid, but components may be affected by the changed settings. For example, if you change the server name, connections retrieved after the cache has been refreshed will go to the server indicated by the new name.

Connection cache ping

This feature allows you to test the cache configuration to verify that connections can be made using the supplied parameters. To ping, the connection must be installed in the server that Jaguar Manager is connected to. If you have just installed the cache or changed any settings, refresh the cache before testing it.

To test the cache with ping:

Highlight the Installed Connection Caches folder under the server icon where the cache is installed.
Highlight the cache's icon and choose File | Connection Cache Properties.
In the Connection Cache Properties dialog, enter the password. (Though the password is recorded in the repository, the window does not display it.)
Click Ping.
Jaguar Manager reports whether the connection attempt succeeded.

If ping fails, check the message text for a description of the problem. The server log file may contain additional information about the cause of the error.

If you change the cache properties to correct the problem, you must refresh the cache before testing again.