DataSource Connection Parameters
This section describes the information used to connect to a CA IDMS database using a JDBC DataSource, including the CA IDMS Server implementation classes and their properties.
The IdmsDataSource class implements the JDBC DataSource interface. It is used with an application server provided Java Naming and Directory Interface (JNDI) naming service to establish a connection to a CA IDMS database.
IdmsDataSource properties conform to the Java Beans naming conventions and are implicitly defined by public "setter" and "getter" methods. For example, the "description" property, which is required for all DataSource implementations, is set using the setDescription(String) method. The application server may use the java.lang.reflection methods to discover DataSource properties and provide an interface to set them, or may simply require that they are defined in some configuration file.
IdmsDataSource properties are used to specify the connection parameters. These properties are the equivalent of the DriverPropertyInfo attributes described in the previous section and can be used to completely define the parameters needed to connect to a database. Like a URL, an IdmsDataSource object can also reference an "ODBC" style data source name, where the connection parameters are defined in the registry on Windows, the configuration file on z/OS or Linux, or in the Java properties file.
- accountInfoSpecifies optional accounting information. See the DriverPropertyInfo attribute descriptions.
- connectSuspendSpecifies that when set to true, the JDBC driver suspends the SQL session and pseudo converses immediately after connecting to the database. The default for a non-pooled connection is false.
- databaseNameIdentifies the database on the CA IDMS CV. When nodeName is specified, the driver interprets this property as the DICTNAME of the catalog in which the tables are defined and assumes that the IdmsDataSource contains all information needed to connect to the CV. When nodeName is not specified, the driver interprets this property as the name of an ODBC style data source containing connection information. The networkProtocol property can be used to override this behavior.
- dataSourceNameSpecifies a logical data source name. Container provided DataSource implementations use this to name the ConnectionPoolDataSource object. The IdmsDataSource implementation does not use this internally.
- defaultSchemaSpecifies the name of the default SQL Schema. This is an optional 1-to-18 character field. When specified, this field is used as the schema qualifier for all SQL table references that do not contain an explicit schema qualifier. The default is blank (unspecified).
- descriptionSpecifies a data source description. This property is required of all DataSource implementations.
- externalWaitOverrides the external wait interval for the server task invoked by the Type 4 driver. This effectively becomes the socket timeout.
- identityAuditedEnables end-to-end auditing of the external user identity provided by an identity manager such as CA SiteMinder.
- networkProtocolSpecifies how the JDBC driver communicates with the CV:
- CCI can be specified on Windows or z/OS when the native client interface is installed. It causes the driver to function as a Type 2 driver, using CAICCI/PC on Windows or CAICCI/ENF on z/OS to communicate with the CV.
- TCP can be specified on any platform. It causes the driver to function as a Type 3 driver when connected to the JDBC Server or as a Type 4 driver when connected directly to CA IDMS.
- IDMS can be specified on any platform. It provides a hint to the driver that it connects directly to CA IDMS as a Type 4 driver. When IDMS is specified, the driver ignores the nodeName and viaName properties and always interprets the databaseName as the DICTNAME.
- nodeNameSpecifies the NODE name that identifies the CV containing the database. This property should be used to define a Type 2 connection without defining an ODBC style data source. Use of this property implies that the databaseName is a DICTNAME.
- passwordSpecifies the password for the default user ID. The application can override this when the connection is established. For security, the getPassword method does not return the value.
- portNumberSpecifies the TCP/IP port number of the CCITCP address space, JDBC Server, or CA IDMS CV, depending on the value of networkProtocol.
- programNameSets an external application name to be used as the CA IDMS program name for all connections created by this data source. The first eight characters of this name are written to the journal.
- resourceIntervalOverrides the resource interval for the server task invoked by the Type 4 driver.
- roleNameSupported for compatibility with other DataSource implementations. The IdmsDataSource implementation does not use this internally.
- serverLengthOverrides the default data buffer size specified in the listener PTERM PARM string for the Type 4 driver server interface, IDMSJSRV.
- serverNameSpecifies the DNS name or TCP/IP address of the server. The driver uses the value of networkProtocol to interpret this property:
- When networkProtocol is CCI, this property refers to the mainframe where the CCITCP address space is running when the driver is running on Windows and is ignored when the JDBC driver is running on z/OS.
- When network protocol is TCP, this property refers to the machine where the JDBC server is running, which can be on any platform.
- When network protocol is IDMS, this property refers to the machine where the CA IDMS CV is running.
- serverTraceSets the IDMSJSRV trace flags as defined in CSACFLG1 and CSACFLG2 as directed by CA IDMS Technical Support. Used only with the Type 4 driver.
- sslSpecifies that when set to true, the JDBC driver requests a secure socket for all communication to a CA IDMS CV or a JDBC proxy server.
- taskCodeOverrides the TASK code. See the DriverPropertyInfo attribute descriptions.
- userSpecifies a default user ID to sign on to CA IDMS. The application can override this when the connection is established.
- viaNodeNameSpecifies the NODE name of an intermediate CV used to route the connection to the destination CV for a Type 2 driver connection. Valid only if nodeName is specified. See the DriverPropertyInfo attribute descriptions.
The IdmsConnectionPoolDataSource class implements the JDBC ConnectionPoolDataSource interface. It is used with an application server that provides container managed connection pooling to establish a pooled connection to a CA IDMS database.
An application server typically provides visible DataSource implementation that references a ConnectionPoolDataSource and is exposed to the application as a standard DataSource. Connection pooling is completely transparent to the application.
IdmsConnectionPoolProperties are used by the application server connection pool manager to administer the pool of connections for a particular data source.
- connectSuspendSpecifies the default for a pooled connection is true.
- initialPoolSizeSpecifies the number of connections that the pool manager should initially allocate.
- maxIdleTimeSpecifies the interval in seconds that a pooled connection can be idle before it is closed. When set, it increases the resourceInterval value for a Type 4 connection to the value specified plus the value of propertyCycle property. This aligns the task resource interval with the application server idle time so that the CA IDMS system does not terminate an idle pooled connection due to inactivity.
- maxPoolSizeSpecifies the maximum number of connections that the pool manager should allocate.
- maxStatementsSpecifies the maximum statement pool size. Note that CA IDMS/DB provides an internal statement caching feature in releases 16.0 and later.
- minPoolSizeSpecifies the minimum number of available connections that pool manager should maintain.This property (or the corresponding property within an application server's connection pool definition) should always be set to 0. This avoids potential timeout-related problems between the JDBC connections and their associated tasks and sessions on the CA IDMS/DC system.
- propertyCycleIndicates the interval in seconds the pool manager should wait before enforcing these policies.
For more information on deploying and using DataSource and ConnectionPoolDataSource objects to connect to a database, see JDBC 4.0 Specification, available at www.java.sun.com. Detailed information for these interfaces is included in the JDK "javadoc," available in the same place, and detailed information on the CA IDMS Server implementations methods is included in the installed "javadoc" (and also on the CD in /doc/javadoc.zip).
JDBC Connection Options Summary
As described in the previous sections, there are numerous ways to define CA IDMS Server connection information. Commonly used options are:
- When using the JDBC driver with a Servlet, EJB, or other application running in an application server, all information can be defined in an IdmsDataSource, or more likely, an IdmsConnectionPoolDataSource or IdmsXADatasource object, and accessed using the container's JNDI implementation. It is not necessary to define an ODBC style data source.
- When using the Type 2 JDBC driver in a standalone Java application on Windows or z/OS, a JNDI implementation is generally not available, and it is usually most convenient to reference an ODBC style data source in a CA IDMS URL, accessed using the DriverManager. The ODBC style data source is defined in the registry on Windows and the configuration file on the mainframe.
- When using the Type 3 JDBC driver in an applet or standalone application that connects through the JDBC server, it is usually most convenient to reference an ODBC style data source defined on the machine where the JDBC server invokes the native client interface.
WebSphere Application Server DataStoreHelper
Clients using CA IDMS Server as a JDBC provider within WebSphere Application Server version 7.0 and later can use the supplied
com.ca.idms.was.IdmsJdbcDataStoreHelper class instead of the IBM-supplied com.ibm.websphere.rsadapter.GenericDataStoreHelper. This class is contained within the idmsjdbc.jar file and provides CA IDMS specific data source settings.
Setting the External Identity
Standalone JDBC applications can sectionly set an external user identity to be recorded in the journal similar to the audit trail provided for applications managed by CA SiteMinder.
This method is a CA IDMS extension to JDBC that can be invoked to set the external identity at any time after the connection is established. This specified identity is recorded in the journal at the start of the next transaction and remains in effect until changed or set to null. This method cannot be used with pooled connections.