Connecting using the IMS Universal Database resource adapter in a managed environment

In a managed (or three-tier) environment, your Java™ EE application interacts with a Java EE application server, such as WebSphere® Application Server, and the IMS Universal Database resource adapter to communicate with an IMS database.

To configure and use a CCI Connection object in WebSphere Application Server to access an IMS database:

Procedure

  1. Deploy the IMS Universal Database resource adapter in WebSphere Application Server using the administrative console.
  2. Create a connection factory for use with the IMS Universal Database resource adapter in WebSphere Application Server through the administrative console.
    1. Specify a name for the connection factory and a Java Naming and Directory Interface (JNDI) name.
    2. Set the following custom connection properties for the IMS Universal Database resource adapter:
      DatastoreName

      The name of the IMS data store to access.

      When using type-4 connectivity, the DatastoreName property must match either the name of the data store defined to ODBM or be blank. The data store name is defined in the ODBM CSLDCxxx PROCLIB member using either the DATASTORE(NAME=name) or DATASTORE(NAME=name, ALIAS(NAME=aliasname)) parameter. If an alias is specified, you must specify the aliasname as the value of the datastoreName property. If the DatastoreName value is left blank (or not supplied), IMS Connect connects to any available instance of ODBM as it is assumed that data sharing is enabled between all datastores defined to ODBM.

      When using type-2 connectivity, set the DatastoreName property to the IMS subsystem alias. This is not required to be set for the Java Dependent Region run time.

      DatabaseName

      The location of the database metadata representing the target IMS database.

      The DatabaseName property can be specified in one of two ways, depending on whether the metadata is stored in the IMS catalog or as a static metadata class generated by the IMS Enterprise Suite Explorer for Development.

      If your IMS system uses the IMS catalog, the DatabaseName property is the name of the PSB that your application uses to access the target IMS database.

      If you are using the IMS Explorer for Development, the databaseName property is the fully qualified name of the Java metadata class generated by the IMS Explorer for Development. The URL must be prefixed with class:// (for example, class://com.foo.BMP255DatabaseView).

      In a J2C Connection Factory environment, the DatabaseName property can be overridden for an individual connection without affecting the default value specified for the resource adapter.

      MetadataURL

      The location of the database metadata representing the target IMS database.

      This property is deprecated. Use DatabaseName instead.

      The MetadataURL property is the fully qualified name of the Java metadata class generated by the IMS Enterprise Suite Explorer for Development. The URL must be prefixed with class:// (for example, class://com.foo.BMP255DatabaseView).

      In a J2C Connection Factory environment, the MetadataURL property can be overridden for an individual connection without affecting the default value specified for the resource adapter.

      PortNumber

      The TCP/IP server port number to be used to communicate with IMS Connect. The port number is defined using the DRDAPORT parameter on the ODACCESS statement in the IMS Connect configuration PROCLIB member. The default port number is 8888. Do not set this property when using type-2 connectivity.

      DatastoreServer

      The name or IP address of the data store server (IMS Connect). You can provide either the host name (for example, dev123.svl.ibm.com) or the IP address (for example, 192.166.0.2). Do not set this property when using type-2 connectivity.

      DriverType

      The type of driver connectivity to use. The DriverType value must be 4 for type-4 connectivity or 2 for type-2 connectivity. If the driver is running on WebSphere Application Server for z/OS®, you can also set the DriverType value to 2_CTX for RRSLocalOption connectivity.

      user

      The user name for the connection to IMS Connect provided by your RACF® administrator. Do not set this property when using type-2 connectivity.

      password

      The password for the connection to IMS Connect provided by your RACF administrator. Do not set this property when using type-2 connectivity.

      allMetadata

      Optional. When this property is set to true, the DatabaseMetadata interface returns information for all resources in the IMS catalog. When the property is set to false, the DatabaseMetadata interface returns information for the allocated PSB. The default value for this property is false.

      signedCompare

      Optional. When this property is set to true, special SSAs are generated to support ranged queries over signed data types. If the property is set to false, standard binary comparisons are performed based on the binary representation of the data type value. Setting the value to false can increase performance but might result in incorrect results. The default value for this property is true.

      flattenTables

      Optional. Indicates whether to produce a flattened view of the database tables. A value of true exposes the sub-elements of a STRUCT or an ARRAY as additional columns of the table. The default value is false.

      IMS Explorer flattens the copybook structures when you import the copybook. Although the copybook itself remains unchanged in the IMS catalog, the information about the structure of each table is altered for that particular connection.

      The the flattenTables property allows you to query the fields in complex structures directly. For more information about support for flattening complex structures, see Support for flattening complex structures.

      Restriction: The flattenTables connection property supports static arrays and structures only. Dynamic arrays are not altered.
      initStatusGroup

      Optional. When a connection is made and the PSB is allocated, this property will indicate that the driver should automatically issue an INIT STATUS GROUPA or INIT STATUS GROUPB if a value of 'A' or 'B' is provided. The default will not issue an INIT STATUS GROUP call.

      sslKeyStoreType

      Optional. Specifies the format of the file that contains cryptographic objects needed to establish a secure socket connection. The valid values are JKS and PKCS12. This value is only used when sslConnection is set to true and sslKeyStoreType is not specified. The sslKeyStoreType parameter defaults to JKS.

      sslSecureSocketProtocol

      Optional. Specifies the cryptographic communication protocol for the new connection. Specify a protocol that is supported by the server and provides the highest level of security. The valid values are SSL, SSLv3, TLSv1.1, and TLSv1.2. This value is only used when sslConnection is set to true. If sslConnection is set to true and sslSecureSocketProtocol is not specified, a default protocol will be determined at runtime by the JRE and the server.

      t2OutputBufferSize

      Optional. The size of the output buffer in bytes for the results from a SELECT operation for a type-2 connection.

      The minimum value for t2OutputBufferSize is 500000. If any value less than 500000 is set, this property value will be adjusted to 500000. There is no maximum bound. The default value is 1280000.

      treatInvalidDecimalAsNull

      Optional. Indicates whether to interpret certain Decimal values that appear invalid in Java applications (such as PACKEDDECIMAL and ZONEDDECIMAL with invalid sign bits) as null. By default, this property is false, and a conversion exception is thrown when the Java applications are processing invalid values.

      removeInvalidCaseFields

      Optional. If you use SELECT * to access a map case, the JDBC Universal Driver returns the set of all map case segment fields. When this property is set to true, the results contain only map case fields that satisfy a WHERE clause with a DEPENDINGON field condition. To learn more, see Using the removeInvalidCaseFields property.

      currentSchema

      Optional. Specifies the default schema name that is used to qualify unqualified database objects in dynamically prepared SQL statements.

      dbViewLocation

      Optional. Specifies the fully qualified path to a databaseView metadata class. You can use this property to include a metadata class that is not located in your project path.

      dpsbOnCommit

      Optional. Set this property to true to deallocate the PSB when a commit occurs.

      Recommendation: Do not set this property to true except in a managed environment with integrated connection pooling.
      fetchSize

      Optional. Gives the client a hint about the number of rows to get from the database when more rows are needed. The number specified for this property only affects data retrieved with the current connection. If the value specified is 0, all of the applicable rows are returned.

      The default value for this property is 0 for both managed and unmanaged connections.

      llField

      Optional. The default value for this property is true. You can modify the LL field value to change the length of a variable length segment instance. Set this property to false to hide the LL field data from the column list in the result set.

      maxRows

      Optional. Specifies the maximum number of rows to return in a query result set. The default value is 0, which returns all of the applicable rows in the result set.

      expandArrayResultSet

      Optional. This property enables IMS Universal JDBC driver to create an ArrayResultSet with the array elements as the actual fields in the ResultSet instead of a Struct object containing those elements as the only entry into that ResultSet. To learn more, see Using the expandArrayResultSet property.

      ssaOptimization

      Optional. When set to true, the SSA is optimized to a fully qualified key if subfields of that key are provided. To learn more, see Optimizing SQL statements to promote partial key subfields in the WHERE Clause.

      traceFile

      Optional. Specifies the name of the trace file for the connection.

      traceFileAppend

      Optional. If the specified trace file exists, setting this property to true specifies that the trace data for the new connection must be appended to the existing trace file instead of overwriting it.

      This property is ignored if no value is specified for traceFile.

      traceDirectory

      Optional. Specifies the file system directory where the trace file is located. By default, this path is the directory where the application is executed.

      This property is ignored if no value is specified for traceFile.

      traceLevel

      Optional. Specifies which traces are enabled for the connection. The valid values for this property are defined in the Java API documentation for the IMSDataSource class.

      By default, all traces are disabled.

      This property is ignored if no value is specified for traceFile.

      Trace level traceLevel package value traceLevel constant field in IMSDataSource traceLevel demical value
      All com.ibm.ims.db.opendb.* TRACE_ALL -1
      DL/I com.ibm.ims.db.opendb.dli.* TRACE_DLI 28
      DRDA com.ibm.ims.db.opendb.drda.* TRACE_DRDA 1
      JDBC com.ibm.ims.db.opendb.jdbc.* TRACE_JDBC 32
      Java EE com.ibm.ims.opendb.spi.*
      com.ibm.ims.db.opendb.cci.*      		 TRACE_JEE 192
  3. To use the connection factory that is created in WebSphere Application Server in the previous step, use one of the following approaches:
    • For Java EE 6 or later applications, you can use resource injection to get a handle to the connection factory object. Below is an example:
      // When using imsudbLocal.rar or imsudbXA.rar the connection 
// information is returned as a javax.resource.cci.ConnectionFactory object
@Resource(name=”imsdblocal”)
private javax.resource.cci.ConnectionFactory cf;

// When using imsudbJLocal.rar or imsudbJXA.rar the connection 
// information is returned as a javax.sql.DataSource object
@Resource(name=”imsdblocal”)
private javax.sql.DataSource ds;
    • For earlier Java EE applications or other applications, you can use a lookup facility to look up the connection factory object programmatically. Below is an example:
      // When using imsudbLocal.rar or imsudbXA.rar the connection 
// information is returned as a javax.resource.cci.ConnectionFactory object
Context initctx = new InitialContext();
javax.resource.cci.ConnectionFactory cf = 
 (javax.resource.cci.ConnectionFactory)initctx.lookup
 ("java:comp/env/imsdblocal");

// When using imsudbJLocal.rar or imsudbJXA.rar the connection 
// information is returned as a javax.sql.DataSource object
Context initctx = new InitialContext();
javax.resource.cci.ConnectionFactory cf = 
 (javax.sql.DataSource)initctx.lookup
 ("java:comp/env/imsdblocal");
  4. Invoke the getConnection() method to get the connection to an IMS database from the connection factory (cf) or data source (ds) object.
    Follow one of the following methods:
    • If the application does not need to override any connection properties that are set in the connection factory deployment, call the getConnection() method:
      // When using imsudbLocal.rar or imsudbXA.rar 
javax.resource.cci.Connection conn = cf.getConnection();

// When using imsudbJLocal.rar or imsudbJXA.rar
javax.sql.Connection conn = ds.getConnection();
    • If the application needs to override certain connection properties such as user, password, databaseName, or metadataURL, provide an additional IMSConnetionSpec object with the override values. Take the new IMSConnectionSpec object as the argument when you call the getConnection() method. Here is an example of overriding user and the password:
      // specify connection properties to override user and password
IMSConnectionSpec connSpec = new IMSConnectionSpec();
connSpec.setUser(yourUser);
connSpec.setPassword(yourPassword);

// When using imsudbLocal.rar or imsudbXA.rar 
javax.resource.cci.Connection conn = ((com.ibm.ims.db.cci. ConnectionFactoryImpl)cf).getConnection(connSpec);


// When using imsudbJLocal.rar or imsudbJXA.rar
javax.sql.Connection conn = ((com.ibm.ims.db.hybrid.IMSHybridDataSource)ds).getConnection(connSpec);
      Note: Overriding the connection property values in this way does not alter the default values or require any modifications to the J2C connection factory parameters.
  5. Use the connection that you established in the previous steps to access the IMS database.
  6. After your Java EE application is finished with the connection, close the connection with the close() method on the Connection interface: 
    conn.close();

Example code for connecting to an IMS database using the IMS Universal Database resource adapter in a managed environment

The following code sample shows the flow for connecting to an IMS database using the IMS Universal Database resource adapter from an Java EE application:

In this example, the JNDI facility is used to look up the ConnectionFactory object and overrode connection properties user and password:

//obtain the initial JNDI Naming context
Context initctx = new InitialContext();

//perform JNDI lookup to obtain the connection factory
javax.resource.cci.ConnectionFactory cf = 
   (javax.resource.cci.ConnectionFactory)initctx.lookup("java:comp/env/imsdblocal");	

//specify connection properties
IMSConnectionSpec connSpec = new IMSConnectionSpec();
connSpec.setUser("user");
connSpec.setPassword("password");

//create CCI connection
javax.resource.cci.Connection conn = ((com.ibm.ims.db.cci. ConnectionFactoryImpl)cf).getConnection(connSpec);