Enabling a DB2 JDBC Type 2 driver on z/OS

The Liberty server can be enabled to interact with DB2® by using the JDBC Type 2 driver implementation on z/OS®.

Before you begin

The angel process must be started before you enable this support. For more information, see Administering Liberty on z/OS. You can configure a Liberty server to run as a z/OS started task.

About this task

When you use an RRS capable resource such as DB2, you have the following optional configurations:

You can enable the server to automatically delete resource manager names from the Resource and Recovery Services (RRS) RM.DATA logstream when the server is stopped. This configuration is optional, but if enabled it prevents resource manager names from accumulating in the logstream. To enable automatic RM name deletion, configure Resource Access Control Facility (RACF®) to allow the server to call the ATRSRV macro. To enable automatic RM name deletion, the user ID that the Liberty server runs under must have ALTER access in the FACILITY class to either:
- MVSADMIN.RRS.COMMANDS.gname.sysname resource to access to a specific logging group name (gname) and system (sysname)
- MVSADMIN.RRS.COMMANDS.* resource to allow access to all systems and logging group names
You can define the RM.METADATA logstream to log data that assists debugging. The user ID that the Liberty server runs under must have ALTER access in the FACILITY class as described.

Note: For more information about the ATRSRV macro, setting the appropriate RACF permission, and how to define the RM.METADATA logstream, refer to the MVS Programming: Resource Recovery publication relevant to your system's z/OS level.

You can control the time to wait for transactions actively by using native contexts to complete when the server is stopped or the zosTransaction-1.0 feature is no longer needed. This can be done by using nativeTransactionManager configuration element and the shutdownTimeout attribute.
You can restrict user authority for performing any transactional work that involves RRS capable resources, for example DB2 T2, on a particular server. This can be done by using nativeTransactionManager configuration element, and the resourceManagerNamePrefix attribute.
Note: The resourceManagerNamePrefix attribute specifies a 1-8 alphanumeric (A-Z, a-z, 0-9) and national (@,#,$) only character prefix to be used as part of the server generated resource manager name that is registered with RRS. The prefix "DEFAULT" is a reserved prefix that identifies a default server configuration and must not be used for securing server access. If the configured prefix does not follow the name, length, and character requirements, the DEFAULT prefix name is used. The prefix is intended for system administrators to enable only authorized users to perform transactional work (normal and recovery) involving RRS capable resources. For example, DB2 T2 on the server where the prefix was configured. System administrators must define a BBG.RMNAME.<PREFIX>.RRS resource under the SERVER class, and give the required users READ authority.

These examples describe the optional configuration:
Server.xml element and attribute definition:
```
<nativeTransactionManager shutdownTimeout="20s" resourceManagerNamePrefix="PROD1"/>
```
RACF resource definition and user authorization:
```
RDEF SERVER BBG.RMNAME.PROD1.RRS UACC(NONE)
PERMIT BBG.RMNAME.PROD1.RRS CLASS(SERVER) ACCESS(READ) ID(PROD1USR)
SETR RACLIST(SERVER) GENERIC(SERVER) REFR
```
For more information about the nativeTransactionManager element, see z/OS Transaction Management.

Procedure

Update the Liberty server's server.xml configuration file. Add the zosTransaction-1.0 feature subelement to the featureManager element:
```
<featureManager>
  <feature>zosTransaction-1.0</feature>
</featureManager>
```
Specifying this feature enables the application server to synchronize and appropriately manage transactional activity between the Resource Recovery Services (RRS), the transaction manager of the application server, and the resource manager. So, work without configuring the zosTransaction-1.0 feature is not allowed.

Add the resource's (DB2) native libraries to the resource's <library> configuration element:

The <library> element in the example shows:

<library id ="DB2T2LibRef">
  	<fileset dir="<YOUR DB2 T2 LIBRARY PATHS>" />
	  <fileset dir="<YOUR DB2 T2 NATIVE LIBRARY PATHS>" />
</library>

Configure the jdbcDriver and datasource elements.

When you define the datasource element, you can skip configuring the type attribute because the value javax.sql.ConnectionPoolDataSource is used by default. If you choose to explicitly configure the type attribute, you must use the value: javax.sql.ConnectionPoolDataSource.

The datasource element can include a child element named properties.db2.jcc. Attributes that are supplied in the properties.db2.jcc element are passed directly to the DB2 JCC Driver. The driverType attribute is required and must be set to 2. The databaseName attribute is also required. The ssid attribute is not required, but can be used to control which DB2 for z/OS subsystem this data source connects to if there are multiple DB2 subsystems on the LPAR.

Example

This example describes how to configure your application, jdbc driver, library, fileset, and data source elements, in the server.xml configuration file.

<application type="war" id="db2T2TxWar" name="db2T2TxWar"
             location="/u/user1/wlp/usr/servers/defaultServer/dropins/db2T2Tx.war" />
<jdbcDriver id="DB2T2" libraryRef="DB2T2LibRef"/>

<library id="DB2T2LibRef">
  <fileset dir="/db2v10/jcc/classes" />
  <fileset dir="/db2v10/jcc/lib" />
</library>

<dataSource id="jdbc/DB2T2" jndiName="jdbc/DB2T2" jdbcDriverRef="DB2T2" type="javax.sql.ConnectionPoolDataSource">
  <properties.db2.jcc driverType="2" databaseName="LOC1" />
</dataSource>