Acquiring a connection using the DataSource interface

The DataSource interface is supported by the JDBC 2.0 driver provided by DB2® Version 7 or later, and the DB2 Universal JDBC Driver. To use this method of acquiring a connection, CICS® must be connected to a DB2 Version 7, or later, subsystem, and must be set up to use the JDBC 2.0 driver or the DB2 Universal JDBC Driver, with the appropriate zip file or jar files on the trusted middleware class path in the JVM profiles used by your applications (see Requirements to support Java programs in the CICS DB2 environment). You also need a suitably configured naming server. If you need to configure a naming server, see Java™ Applications in CICS, in particular the topics Defining name servers, Enabling JNDI references, Setting up an LDAP server, and Setting up a COS Naming Directory Server.

Instead of specifying a default or explicit URL in the program itself, an application can use the Java Naming and Directory Interface (JNDI) to look up a reference to a previously deployed DataSource. You can create, deploy and manage a DataSource separately from the applications that use it, and it acts as a "connection factory". The DataSource provides all the necessary information to generate the JDBC connection, so the application programmer does not need to provide the correct URL (as required by the DriverManager interface).

CICS provides sample Java applications to enable you to:

Currently, only DataSources published using either the CICS-supplied sample CICSDataSourcePublish.java, or code similar to this sample, are supported.

The DataSource in the sample applications does not specify the database name, so it generates connections with default URL characteristics. A DataSource that specified the database name would generate connections with an explicit URL. It is recommended that you do not specify the database name in your DataSource, so that it generates JDBC connections with a default URL. Using a default URL ensures the correct behaviour at the close of a connection. See Committing a unit of work for further information.

JDBC connection pooling is a technology used by JDBC 2.0 to optimize the acquisition of JDBC connections. The CICS DB2 attachment facility already has its own mechanism to manage, protect and reuse threads, so the JDBC connection pooling mechanism is superseded in the CICS DB2 environment by CICS' own mechanism, which provides an equivalent functionality. For this reason, a DataSource that is created in CICS to access DB2 uses the com.ibm.db2.jcc.DB2SimpleDataSource class, which does not contain support for JDBC connection pooling, rather than the com.ibm.db2.jcc.DB2DataSource class, which does contain that support. The DB2-supplied JDBC driver ensures that the correct class is used. Note that the CICSjdbcDataSource.java sample application uses a standard JDBC DataSource object to look up the DataSource, and the DB2 JDBC driver converts this to a CICS-compatible DataSource object that uses the com.ibm.db2.jcc.DB2SimpleDataSource class.

Setting up the sample applications to publish, look up and retract a DataSource tells you how to set up the CICS-supplied sample applications. Publishing a DataSource using CICSDataSourcePublish.java, Looking up a DataSource using CICSjdbcDataSource.java, and Retracting a DataSource using CICSDataSourceRetract.java tell you how to use the sample applications. For further technical background on the DataSource, see the DB2 Universal Database™ for OS/390® and z/OS® Application Programming Guide and Reference for Java which is appropriate for your version of DB2.

Setting up the sample applications to publish, look up and retract a DataSource

CICS provides the file CICSDB2DataSource.jar in the directory /usr/lpp/cicsts/cicsts31/samples/jdbc. This file contains the object (.class) files for the sample applications CICSDataSourcePublish.java, CICSjdbcDataSource.java, and CICSDataSourceRetract.java. The source code (.java) for these files is also in the directory /usr/lpp/cicsts/cicsts31/samples/jdbc.

To set up the sample applications, follow these steps:

  1. The sample applications use the CICS-supplied sample JVM profile DFHJVMPR, which is a HFS file. When you install CICS, the CICS-supplied sample JVM profiles are placed in the HFS directory /usr/lpp/cicsts/cicsts31/JVMProfiles, where cicsts31 is the value that you chose for the CICS_DIRECTORY variable used by the DFHIJVMJ job during CICS installation. CICS actually looks for the JVM profiles in the HFS directory that is specified by the JVMPROFILEDIR system initialization parameter, which might or might not be the directory containing the CICS-supplied sample JVM profiles. If the location of the JVM profiles has been changed for your CICS region, you can use the EXEC CICS INQUIRE JVMPROFILE command to find the full path name of the HFS file that CICS is using, provided that DFHJVMPR has been used during the lifetime of the CICS region. (Note that there is no CEMT equivalent for this command.) Locate the JVM profile DFHJVMPR and add classes to the classpaths as follows: Java Applications in CICS has more information about locating and customizing JVM profiles.
  2. Use CEDA to install transactions DSDB, DSPU, and DSRE from group DFH$DB2.
  3. Use CEDA to install programs DFJ$DSDB, DFJ$DSPU, and DFJ$DSRE from group DFH$DB2.
  4. The default name is jdbc/CICSDB2DataSource. You can change the name of the DataSource, or the subContext to where the DataSource will be published. There are two ways to do this:
    1. You can change the sample programs CICSDataSourcePublish.java, CICSDataSourceRetract.java, and CICSjdbcDataSource.java as required. If you change the name or subContext for the DataSource, remember to make the same change in all three of the sample programs. Put the new classes for the sample programs on your CLASSPATH option in the JVM profile DFHJVMPR.
    2. Alternatively, you can add the system property com.ibm.cics.datasource.path to the JVM properties file that is referenced by the JVMPROPS statement in the JVM profile DFHJVMPR. When you install CICS, the CICS-supplied sample JVM properties files are placed in the directory /usr/lpp/cicsts/cicsts31/props/, where cicsts31 is the value that you chose for the CICS_DIRECTORY variable used by the DFHIJVMJ job during CICS installation. The CICS-supplied sample profile DFHJVMPR references the JVM properties file dfjjvmpr.props. Include the following statement in the JVM properties file:
      com.ibm.cics.datasource.path=subContext/DataSourcename
      Specify the subContext and name that you want to use for the DataSource.
    If the com.ibm.cics.datasource.path system property is present in the JVM properties file, the sample applications use the values specified by that property. Otherwise, they default to the DataSource name specified in the sample programs.
  5. Before you use the sample applications, ensure that your user ID is authorized to access DB2 resources. Authorizing users to access resources within DB2 tells you how to ensure that your user ID has the correct authorization.

Although the sample applications use the CICS-supplied sample JVM profile DFHJVMPR, which is a profile for a standalone JVM (that does not use the shared class cache), DataSource lookup classes based on the sample application CICSjdbcDataSource.java can also be used by worker JVMs (that do use the shared class cache). Bear in mind that for a worker JVM, the CLASSPATH option in the JVM profile and the com.ibm.cics.datasource.path system property in the JVM properties file are taken from the JVM profile and JVM properties file for the worker JVM itself. However, the trusted middleware class path (including the TMSUFFIX statement or the TMPREFIX statement, where you need to specify the db2j2classes.zip file) is taken from the JVM profile for the master JVM.

Publishing a DataSource using CICSDataSourcePublish.java

To publish a CICS-compatible DataSource to your JNDI server using the sample program CICSDataSourcePublish.java, enter transaction DSPU at a terminal. By default, the DataSource will be named CICSDB2DataSource, and it will be published to subContext jdbc in the JNDI initial context. The location of the initial context is determined by the parameters specified in your LDAP or JNDI server configuration, in the JVM properties file for the JVM. You can change the sample program, or use the com.ibm.cics.datasource.path system property, to specify a different DataSource name and subContext; see Setting up the sample applications to publish, look up and retract a DataSource for instructions.

The following messages are displayed on the screen:

DSPU - CICSDataSourcePublish: Transaction starting

DSPU - CICSDataSourcePublish: Datasource jdbc/CICSDB2DataSource published

If the DataSource has already been published, the following message is displayed on the screen:

DSPU - CICSDataSourcePublish: Datasource jdbc/CICSDB2DataSource already published    

The following output appears in stdout:

Figure 30. Stdout output from transaction DSPU to publish a DataSource with default name and subContext
*********************************************************************************
**** CICSDataSourcePublish: started                                             
**** CICSDataSourcePublish: Looking up DataSource jdbc/CICSDB2DataSource        
**** CICSDataSourcePublish: DataSource jdbc/CICSDB2DataSource not found         
**** CICSDataSourcePublish: Binding DataSource jdbc/CICSDB2DataSource           
**** CICSDataSourcePublish: DataSource bound to JNDI                            
**** CICSDataSourcePublish: ended                                               
*********************************************************************************

The sample program publishes a DataSource that provides the information needed to generate default URL connections. Now, instead of specifying a URL in a DriverManager.getConnection request (the JDBC DriverManager interface), your application programs can use the Java Naming and Directory Interface (JNDI) to look up a reference to the DataSource, as described in Looking up a DataSource using CICSjdbcDataSource.java. Remember that CICS must be using the JDBC 2.0 driver (provided by DB2 Version 7 or later) or the DB2 Universal JDBC Driver to use the DataSource interface.

It is not recommended that you use CICSDataSourcePublish.java as a PLTPI program. Though this is possible, it severely impacts the time taken for control to be given to CICS. If you want to use the program in PLTPI processing, then you should have a PLTPI program start transaction DSPU.

Looking up a DataSource using CICSjdbcDataSource.java

To look up a DataSource to test that it has been published correctly, enter transaction DSDB at a terminal. The following messages are displayed on the screen:

DSDB - DataSource JDBC transaction starting.

DSDB - DataSource JDBC transaction finished. See stdout

The following output appears in stdout:

Figure 31. Stdout output from transaction DSDB to look up a DataSource with default name and subContext
*********************************************************************************
**** CICSjdbcDataSource: started
**** CICSjdbcDataSource: Looking up CICS datasource jdbc/CICSDB2DataSource
**** CICSjdbcDataSource: DataSource Connection created.
**** CICSjdbcDataSource: AutoCommit is false
**** CICSjdbcDataSource: First Select Statement created
**** CICSjdbcDataSource: First Result Set created
**** CICSjdbcDataSource: Table name = SYSCOPY
**** CICSjdbcDataSource: Table name = SYSCOLAUTH
**** CICSjdbcDataSource: Table name = SYSCOLUMNS
.
.	a list of table names defined to DB2
.
**** CICSjdbcDataSource: Table name = SYSSEQUENCESDEP
**** CICSjdbcDataSource: Result Set output completed
**** CICSjdbcDataSource: ended
*********************************************************************************

To acquire a connection for a Java application program using your published DataSource, use the sample code provided in the CICSjdbcDataSource.java sample. The sample code shows you how your application can look up the DataSource and make an SQL query.

The CICSjdbcDataSource.java sample gets a DB2SimpleDataSource instance from JNDI, but treats it as a DataSource, making it vendor and platform independent. It is possible to bypass this lookup by instantiating a DB2SimpleDataSource directly. You can do this by coding:

.
.
DataSource ds = new DB2SimpleDataSource():

Connection con1 = ds.getConnection();
.
.

You should be aware that if you do this, the code will no longer be portable in the true sense, as it is now platform and vendor specific.

Retracting a DataSource using CICSDataSourceRetract.java

To retract (unBind) a DataSource that you have published, enter transaction DSRE at a terminal.

The following messages are displayed on the screen:

DSRE - CICSDataSourceRetract: Transaction starting

DSRE - CICSDataSourceRetract: Datasource jdbc/CICSDB2DataSource retracted

If the DataSource has not been published or has already been retracted, the following message is displayed on the screen:

DSRE - CICSDataSourceRetract: Datasource jdbc/CICSDB2DataSource not found

The following output appears in stdout:

Figure 32. Stdout output from transaction DSRE to retract a DataSource with default name and subContext
*********************************************************************************
**** CICSDataSourceRetract: started
**** CICSDataSourceRetract: unbinding jdbc/CICSDB2DataSource
**** CICSDataSourceRetract: jdbc/CICSDB2DataSource unbound
**** CICSDataSourceRetract: ended
*********************************************************************************

Related tasks
Programming with JDBC and SQLJ in the CICS DB2 environment
Acquiring a connection to a database
Acquiring a connection using the JDBC DriverManager interface
Committing a unit of work
CICS abends during JDBC or SQLJ requests
Using JDBC and SQLJ in enterprise beans: special considerations
[[ Contents Previous Page | Next Page Index ]]