Manually configuring Db2 type 2 connectivity with the CICS JDBC feature

The cicsts:jdbc-1.0 feature is used to configure JDBC in CICS® Liberty JVM servers to access Db2® databases with type 2 connectivity from Java™ applications. Db2 can be accessed using DataSources or a DriverManager.

Before you begin

Ensure your CICS region has access to the IBM® Data Server Driver for JDBC and SQLJ for Db2 and a CICS Db2 connection (DB2CONN) is defined. For more information, see Configuring a JVM server to support DB2.

About this task

This task explains how to define the elements in server.xml and properties in the JVM profile to connect a local Db2 database with type 2 connectivity using the cicsts:jdbc-1.0. Your application can connect to Db2 using either DataSources with the javax.sql.DataSource class, or using a DriverManager, with the java.sql.DriverManager class.

Java 17Java 21 To enable Db2 type 2 connectivity when you are running Java 17 or Java 21, add LIBPATH_SUFFIX=/usr/lpp/db2v13/jdbc/lib to the JVM profile.

You can use the cicsts:jdbc-1.0 feature if you want to use DriverManager to connect to Db2.

Procedure

  1. Add the cicsts:jdbc-1.0 feature to the featureManager element.
    The feature enables use of the cicsts_jdbcDriver and cicsts_dataSource elements in the server.xml file.
    <featureManager>
    <feature>cicsts:jdbc-1.0</feature>
</featureManager>
  2. Optional: Set the Db2 schema. For more information, see Setting the Db2 schema in a JVM server
  3. Add a library element to the server.xml file to specify the location, on zFS, of the IBM Data Server Driver for JDBC and SQLJ for Db2. 
    <library id="db2Library">
    <fileset dir="/usr/lpp/db2v13/jdbc/classes" includes="db2jcc4.jar db2jcc_license_cisuz.jar"/>
    <fileset dir="/usr/lpp/db2v13/jdbc/lib" includes="libdb2jcct2zos4_64.so"/>
</library>
    This step can be omitted if -Dcom.ibm.cics.jvmserver.wlp.jdbc.driver.location is set in your JVM profile, in which case it is added automatically. For more information, see JVM system property com.ibm.cics.jvmserver.wlp.jdbc.driver.location.
  4. Add a cicsts_jdbcDriver element to enable JDBC type 2 connectivity with the java.sql.DriverManager or javax.sql.DataSource interface.

    The cicsts_jdbcDriver element must specify an id attribute set to defaultCICSJdbcDriver and refer to the library element containing the IBM Data Server Driver for JDBC and SQLJ for Db2 in the libraryRef attribute.

    For example,
    
<cicsts_jdbcDriver id="defaultCICSJdbcDriver" libraryRef="db2Library"/>

    Only one cicsts_jdbcDriver element can be configured in server.xml.

    This step can be omitted if -Dcom.ibm.cics.jvmserver.wlp.jdbc.driver.location is set in your JVM profile, in which case it is added automatically. For more information, see JVM system property com.ibm.cics.jvmserver.wlp.jdbc.driver.location.

If you only use DriverManager support, the preceding steps are sufficient.

  1. To access Db2 with DataSources, a cicsts_dataSource element must be specified with an id attribute set to defaultCICSDataSource. The jndiName attribute defines the JNDI name that is referenced by your application.
    Tip: The class com.ibm.db2.jcc.DB2SimpleDataSource is the javax.sql.DataSource implementation used by the IBM Data Server Driver for JDBC and SQLJ for Db2.
    For example,
    <cicsts_dataSource  id="defaultCICSDataSource "jndiName="jdbc/cicsDb2DataSource"/>
  2. Optional: Configure the DataSource by using a properties.db2.jcc element.

    Some of the attributes that can be specified on the properties.db2.jcc element are not valid for DataSources with type 2 connectivity. If an invalid attribute is specified, it is ignored and a warning message is issued.

    The following attributes are not valid:
    • driverType
    • serverName
    • portNumber
    • user
    • password
    • databaseName
    For example,
    <cicsts_dataSource id="defaultCICSDataSource" jndiName="jdbc/cicsDb2DataSource"/>
    <properties.db2.jcc currentSchema="DB2USER" fullyMaterializeLobData="true" />
</cicsts_dataSource>

    Only one cicsts_dataSource element can be configured in server.xml. Any changes to the properties values are retained as long as the cicsts_dataSource element remains valid.

Results

The Liberty JVM server can connect to Db2 databases with JDBC type 2 connectivity that uses the CICS DB2CONN resource.
Note: Dynamic updates of the cicsts_dataSource element and its components are not supported. Updating the configuration while the Liberty server is running can result in Db2 application failures. Stop the Liberty JVM server before making any changes to the cicsts_dataSource element, then restart the Liberty JVM server.

You can create an instance of a DriverManager by calling the java.sql.DriverManager.getConnection method in your applications.

You can look up an instance of javax.sql.DataSource through JNDI in applications. The JNDI name of this DataSource is defined by the jndiName attribute in the cicsts_dataSource element.

Example server.xml configuration for a Db2 DataSource with type 2 connectivity that uses the CICS JDBC feature

<server>
    <!-- Install the JDBC feature -->
    <featureManager>
        <feature>cicsts:jdbc-1.0</feature>
    </featureManager>

    <!-- Configure the IBM Data Server Driver for JDBC and SQLJ for Db2 driver library -->
    <library id="db2Library">
        <fileset dir="/usr/lpp/db2v13/jdbc/classes" includes="db2jcc4.jar db2jcc_license_cisuz.jar"/>
        <fileset dir="/usr/lpp/db2v13/jdbc/lib" includes="libdb2jcct2zos4_64.so"/>
    </library>

    <!-- Configure the JDBC driver -->
    <cicsts_jdbcDriver id="defaultCICSJdbcDriver" libraryRef="db2Library"/>

    <!-- Configure the DataSource -->
    <cicsts_dataSource  id="defaultCICSDataSource" jndiName="jdbc/cicsDb2DataSource"/>
</server>