Chapter 4 Jaguar and Application Issues

Connections and Connection Caching

This section discusses how Application Integrator components use connections to target servers, including the following topics:

• Component Properties: Connections and Security
• Acquiring and Disposing of Connections
• Defining Connection Caches in Jaguar Manager
• AI Component Properties in Jaguar Components

Component Properties: Connections and Security

When the Component Builder deploys a component into Jaguar, it sets the following properties for the component. The following are properties that relate to connection handling and security:

com.sybase.ai.connection_name

This property is referred to as connection_name. It specifies the name of the connection associated with the component.

com.sybase.ai.use_client_security

This property is referred to as use_client_security. It affects the user ID and password that are used to obtain connections. Valid values are:

• false
  A value of false tells the Application Integrator component to use the user ID and password that were supplied in the connection object from the Component Builder. The default value is false.
  
• true
  A value of true tells the component to use the user ID and password from the client that invoked the component method. When the value is true, the caller's user ID and password are obtained from Jaguar and are subsequently used to override the user ID and password from the connection definition.
  

com.sybase.ai.use_connection_cache

This property is referred to as use_connection_cache. It specifies how the Application Integrator component acquires and disposes of connections. Valid values are:

• false
  A value of false (the default) tells the Application Integrator component to open and close connections to a server directly.
  
• true
  A value of true tells the component to get and release connections from a Jaguar connection cache.
  

com.sybase.ai.connection_cache_unavail_action

This property is referred to as connection_cache_unavail_action. It controls the action that Jaguar takes if there are no connections available in the cache. Valid values correspond to the possible values for the flag parameter on the JCMCache.getConnection() method. (See the connection cache section of the Jaguar CTS Programmer's Guide for a more detailed discussion). Valid values are:

• nowait
  Indicates that if no connections are available, the request results in an exception (error condition) that is then propagated back to the caller. The default is nowait.
  
• force
  Indicates that Jaguar should attempt to open a new connection (that will not be placed back in the cache after use).
  
• wait
  Indicates that the component waits indefinitely until a connection becomes available. We do not recommend that you use this option because this indefinite wait can cause component instances to tie up resources and can cause the client application to wait indefinitely.
  

Acquiring and Disposing of Connections

Connections created in the Component Builder give an Application Integrator component the information it needs to connect to a CICS server at execution time. The CICS server is an Application Integrator-supplied CICS program that Application Integrator components communicate with to execute a CICS application program.

The process of acquiring and disposing of connections differs depending on whether the Application Integrator component is configured to use connection caching.

When connection caching is not being used:

• Acquiring connections refers to the process of opening a new connection directly to the CICS server. The Application Integrator component uses the values supplied in the connection definition with the name that matches the connection_name property. These values include such information as the TCP/IP host name, a port number, an Open ServerConnect RPC name, and a Code Page.
• Disposing of connections refers to closing connections.

When connection caching is being used:

• Acquiring connections refers to the process of retrieving a connection from the Jaguar connection cache mechanism. When the Application Integrator component needs to get a connection to the target server, it uses the connection_name property to locate a Jaguar connection cache by name.
• Disposing of connections refers to releasing a connection back to the Jaguar connection cache for other components to use.

Defining Connection Caches in Jaguar Manager

Defining connection caches for Application Integrator components is similar to defining them for other components that use JDBC connection caches.

You must set up connection cache definitions in Jaguar Manager using the following procedure. In general, use the same information that was used to create the connection in the Component Builder. To define a connection cache:

1. On the Driver tab of the Connection Cache Properties dialog box, select the JDBC 1.1 radio button.
2. Enter the JDBC driver class name in the DLL or Class Name as follows:
   com.sybase.ai.common.adapter.AIJagDriver
   
3. On the General tab:
   1. Set the Server Name property in the following format:
      jdbc:sybase_ai:ai:<connection_name>
      
      where <connection_name> is the connection name associated with any AI for CICS components that should use this connection.
      
   2. Enter a valid user name and password.
4. Click the Enable cache-by-name access check box to turn this property on (it is off by default). This allows the Application Integrator component to look up connection caches by name.

      Setting the Jaguar Enable cache-by-name access property requires Jaguar Administrator authority.
   

5. Restart the Jaguar server to make the changes to connection cache definitions take effect.

      Make sure the connection cache is installed in a running Jaguar server before you use it in a component to connect to a target.
   

AI Component Properties in Jaguar Components

In addition to the properties that all Java-style Jaguar components have, Application Integrator adds some properties to the component in the Jaguar component repository. Application Integrator-specific properties begin with the com.sybase.ai prefix. You must refresh the component in Jaguar Manager for property changes to take effect.

To edit these properties in Jaguar Manager, use the All Properties tab on the Component Properties dialog box. Click on the column heading once to sort the properties alphabetically by name in ascending order; click on the column heading again to sort the properties alphabetically in descending order.

Do not modify any of the following component properties unless instructed to do so by Sybase Technical Support:

• com.sybase.jaguar.component.files
• com.sybase.jaguar.component.ids
• com.sybase.jaguar.component.java.classes
• com.sybase.jaguar.component.interfaces
• com.sybase.jaguar.component.java.class
• com.sybase.jaguar.component.type
• com.sybase.jaguar.component.name
• com.sybase.jaguar.component.bind.object
• com.sybase.jaguar.component.bind.thread

Component Execution Debugging

The com.sybase.ai.debug component property can be used to cause the component to write detailed trace information to the Jaguar server log. The property can have a value of true to indicate that the component should write trace information to the Jaguar server log. A value of false indicates that the component should not write information to the log. The default value is false.

In general, the information produced by this logging is intended for Sybase Technical Support to aid in problem determination.

To turn on component debugging:

1. In Jaguar Manager:
   1. Set the com.sybase.ai.debug property to a value of true.
   2. Refresh the component.
2. Run the component using your Jaguar client application.
3. Check the Jaguar server log to view the debug output produced by component execution.

Copyright © 1999 Sybase, Inc. All rights reserved.