Using a DB2 Universal JDBC Driver to access DB2 for z/OS

The z/OS operating system requires that you configure the DB2 Universal JDBC Driver and your database to ensure interoperability. Within WebSphere Application Server, configure a JDBC provider object and a data source object to implement the driver capabilities for your applications.

Before you begin

Use only the following versions of the DB2 Universal JDBC Driver to connect with DB2 on z/OS; consult DB2 service updates for available enhancements on the version that you choose.

Why and when to perform this task

To use a DB2 Universal JDBC Driver to connect to DB2 for z/OS, complete three primary tasks:

Steps for this task

  1. Install the driver class files and any necessary native files in an available HFS directory.
    (Native files are class files that some versions of the DB2 Universal JDBC Driver require for running on the z/OS operating system.)
  2. Configure the driver and database for interoperability.
    1. Bind the required DB2 packages

      As with any application that executes SQL statements in DB2 for z/OS, the Universal JDBC driver must first bind with DB2 the packages that represent the SQL statements to be executed. The Universal JDBC Driver does not use the same packages used by the legacy JDBC driver, and uses a different process for binding its packages.

      The specific details of the bind utility and bind process are described by the README provided with the installed DB2 Universal JDBC Driver. Refer to this README for details on how to setup and perform the required binding.

      Also note that the utility requires the server name (or IP address), the port number, and the database name (the database location on z/OS) for the target DB2. To get this information, issue a DB2 -DISPLAY DDF command on the target DB2 system. This displays the IPADDR (IP address), the SQL DOMAIN (server name), the TCPPORT number, and the LOCATION (database name/location) for you to use as input to the utility.

      You must perform the bind process for each target DB2 that will be accessed using the DB2 Universal JDBC Driver.

    2. Set up to handle in-doubt transactions

      You must perform this setup once for each target DB2 for z/OS Version 7 location that is accessed using the DB2 Universal JDBC Driver Type 4 XA support.

      Because DB2 for z/OS Version 7 does not implement J2EE XA support, the Type 4 driver XA processing uses DB2 V7 two-phase commit protocol and a table in each location (database) to store a list of global transactions that are in doubt (finished but not committed).

      This table must be set up at each DB2 V7 location that is accessed. To do this, use the In-Doubt Utility, which is included as part of the installed DB2 Universal JDBC Driver. Use this utility to create the SYSIBM.INDOUBT Table that stores information about In-Doubt Global Transactions. This utility also binds the package T4XAIndbtPkg, which contains the SQL statements to insert and delete from the SYSIBM.INDOUBT Table. The T4XAIndbtPkg package is written with SQLJ.

      This installation process requires that the target DB2 subsystem be configured with DDF enabled for incoming TCP/IP connections.

      1. To enable DDF on the target DB2, issue the DB2 -START DDF command on that system.
      2. This utility requires the server name (or IP address) and the port number for the target DB2 V7. To obtain this information, issue a DB2 -DISPLAY DDF command on the target DB2 V7 system. This displays the IPADDR (IP address), the SQL DOMAIN (server name), and the TCPPORT number that can be used as input to the utility.

      To find more detailed information about the In-Doubt utility, refer to the DB2 Universal Database for z/OS Version 7 Application Programming Guide and Reference for JavaTM publication. (You can download it from the Library section of the DB2 Universal Database for z/OS Version 7 product information Web pages.) Within this publication, search for discussion about the utility under DB2T4XAIndoubtUtil, which is the official name of the In-Doubt utility.

      Note: The previously described setup for in-doubt transactions is not a requirement for DB2 FOR z/OS Version 8 servers because DB2 FOR z/OS Version 8 natively supports XA commands over DRDA and manages the In-Doubt Global Transactions internally.

    3. Define a db2.jcc.propertiesFile

      A db2.jcc.propertiesFile for use by DB2 Universal JDBC Driver Type 2 processing under WebSphere Application Server for z/OS can be created and specified as input to the driver. This runtime properties file is for use in specifying various runtime options that the DB2 Universal JDBC Driver uses for Type 2 connectivity. These options are specified as properties in the form of parameter=value. Refer to the README file packaged with the installed DB2 Universal JDBC Driver for a detailed description of each of the properties.

      This file is not required; however, if it is not provided, universal driver default processing is performed.

      Of specific interest is the db2.jcc.ssid property. This property specifies the DB2 subsystem identifier (not location name), to be used by the DB2 Universal JDBC Driver Type 2 processing as the local subsystem name to which it should connect. If this property is not provided, the driver uses the subsystem identifier that it finds in the DSNHDECP load module. If the installation wants to use the DSNHDECP load module to specify the subsystem identifier, this load module must be included in a steplib dataset in the servant region PROCs associated with each server that will use the DB2 identified by the subsystem ID. Refer to the README file packaged with the universal driver for more information on using this load module. If that DSNHDECP load module does not accurately reflect the desired subsystem, or if multiple subsystems might be using a generic DSNHDECP, the db2.jcc.ssid property must be specified.

      Although the db2.jcc.propertiesFile is not required, if you choose to define the file, you must specify the fully qualified-hfs-filename. To do this, specify the file as a JVM System property as follows:

      • db2.jcc.propertiesFile = <fully-qualified-hfs-filename>

      Because the driver-general properties are typically specific to a driver load (for example, server) versus to all servers using the JDBC provider, it is best that this JVM property be set at the server level. To define the db2.jcc.propertiesFile= property to the server level using the WebSphere Application Server for z/OS Administrative Console:

      1. Under the WebSphere Application Server for z/OS Administrative Console, go to Servers > Application Servers, then click the server to which you want to add the JVM property.
      2. From the selected server page, go to Process Definition > Servant.
      3. On the Servant page, scroll down to the Additional Properties at the bottom of the page, then click Java Virtual Machine.
      4. On the Java Virtual Machine page, scroll down to Additional Properties at the bottom of the page, then click Custom Properties.
      5. On the Custom Properties page, scroll down to New to configure a new JVM property for the selected server. The name of the property is db2.jcc.propertiesFile. The value of the property is the fully-qualified-hfs-filename that you created and initialized with the DB2 Universal JDBC Driver properties. These are the properties that you want the Type 2 driver to use for the selected server
      6. Click OK.
      7. Click Save to save the new JVM property.

  3. Define a JDBC provider for the DB2 Universal JDBC Driver.
    The JDBC provider object encapsulates the driver classes for implementation in WebSphere Application Server.

    Note: Driver class file incompatibilities require that you configure DB2 Universal JDBC Driver providers and DB2 Local JDBC providers (RRS) at scopes that do not overlap with each other. Using the server scope for both providers reduces the chance of conflict. (Refer to Provider coexistence considerations.)

    1. Define WebSphere variables

      Before you create a JDBC provider for the DB2 Universal JDBC Driver for z/OS, WebSphere Application Server for z/OS must know the location of the installed DB2 Universal JDBC Driver and license file, and the location of any native files that might be required by your version of the DB2 Universal JDBC Driver. To do this, from the WebSphere Application Server for z/OS Administrative Console, go to Environment > Manage WebSphere Variables, and update the values of the following environment variables:

      1. DB2UNIVERSAL_JDBC_DRIVER_PATH

        Specify the fully-qualified path of the directory that contains the DB2 Universal JDBC Driver. This must be the directory that contains the db2jcc.jar and the db2jcc_license_cisuz.jar.

        Example: If the fully-qualified path of the db2jcc.jar is /usr/lpp/db2810/jcc/classes/db2jcc.jar, specify /usr/lpp/db2810/jcc/classes as the value of the variable.

      2. DB2UNIVERSAL_JDBC_DRIVER_NATIVEPATH

        Specify the fully-qualified directory path of the directory that contains the DB2 Universal JDBC Driver native files, if necessary. This is the directory that contains the driver files that have a .so file type. If the driver version you are using does not require native files, leave this value at null.

        Example: If the fully-qualified path of the directory containing the native files is /usr/lpp/db2810/jcc/lib, specify /usr/lpp/db2810/jcc/lib as the value of the variable.

    2. Save your work.
    3. From the WebSphere Application Server for z/OS Administrative Console, click Resources > JDBC Providers.
    4. On the JDBC Provider page, set the JDBC Provider scope to the server upon which you want to install the new provider.
    5. Click Apply.
    6. Click New.
    7. In the list of JDBC providers that displays, choose the type of DB2 Universal JDBC Driver Provider as follows:
      • DB2 Universal JDBC Driver Provider

        This provider supports driver Types 2 and 4. It does not support J2EE XA transaction processing, often called two-phase commit processing.

        Note: Do not select this provider if your installation has the z/OS Application Connectivity to DB2 for z/OS feature defined to WebSphere Application Server for z/OS. This feature provides Universal Driver type 4 XA connectivity, which is not supported by the non-XA DB2 Universal JDBC Driver Provider.

      • DB2 Universal JDBC Driver Provider (XA)

        This provider uses J2EE XA to manage global transactions across multiple resource managers and to perform two-phase commit processing. It supports only driverType 4 connectivity.

        (If you require both global transaction support and driverType 2 connectivity, use the Legacy DB2 for OS/390 and z/OS JDBC Driver and configure a DB2 for z/OS Local JDBC provider (RRS) for the driver. This provider activates z/OS Resource Recovery Services (RRS) with the driver implementation. RRS coordinates transaction processing, and can manage global transactions using two-phase commit.)

    8. Click OK.
      The console then displays a configuration view of the selected provider, showing the default name of the provider, the class path, the native library path, and the data source implementation class name used by the provider. Generally, you do not need to change this information. If you type a different value in the Name field, your provider configuration does not change; this name is for administrative purposes only.
    9. When the Provider definition is complete, click Apply.
    10. Finally, click Save to save the new JDBC provider.
  4. Define a data source.
    WebSphere Application Server uses the data source object to obtain database connections and manage those connections.
    1. From the WebSphere Application Server for z/OS Administrative Console, click Resources > JDBC Providers. On the JDBC Providers page, select the DB2 Universal JDBC Driver provider for which you will define a data source.
    2. On the provider properties page that the console displays, in the Additional Properties section at the bottom of the page, make a choice as follows:
      • Choose DataSources if you want to define a datasource for a DB2 Universal JDBC Driver Provider (XA). In this case, DataSources (Version 4) is not supported.
      • Choose DataSources or DataSources (Version 4) if you want to define a datasource for a DB2 Universal JDBC Driver Provider. This choice depends on the type of datasource you want to define.
    3. On the Data Sources page, click New.
    4. On the New page, complete the following fields as required for your data source:
      1. Name
      2. JNDI name
      3. Component-managed Authentication Alias (optional)
      4. Container-managed Authentication Alias (optional)
      5. Mapping-Configuration alias (optional)
      6. Indicate if you want this DataSource to be used for container managed persistence.

      Note: If you set the driverType property for the datasource to 4, an appropriate managed Authentication Alias must be specified. If you set the driverType property for the datasource to 2 and no managed Authentication Alias is specified, the user identity currently associated with the thread at the time of a getConnection request is used as the identity associated with the connection.

    5. Click Apply.
    6. The console displays a page with the name of the specified data source. In the Additional Properties section at the end of this page, click Custom Properties.
    7. In the Custom Properties page, specify the property settings you desire. At a minimum, specify the following data source properties:
      databaseName
      The location name of the target database used when establishing connections with this datasource
      driverType
      The JDBC connectivity type used by the datasource. If you want to use a driverType 4, set the value to 4. If you want to use a driverType 2 , set the value to 2. If the datasource is for the DB2 Universal JDBC Driver Provider (XA), specify only driverType 4. Specification of driverType 2 in the case of the DB2 Universal JDBC Driver Provider (XA) is not supported.
      ServerName
      The TCP/IP address or host name for the Distributed Relational Database Architecture (DRDA) server. This property is required only if driverType is set to 4. This property is not used if driverType is set to 2.
      PortNumber
      This is the TCP/IP port number where the DRDA server resides. Provide a value for this property only if driverType is set to 4. This property is not used if driverType is set to 2.

      You can learn about additional, optional data source properties in the Application Programming Guide and Reference for Java for your version of DB2 for z/OS.

    8. After you finish specifying the desired properties, click Save to save the new data source.

Related concepts
DB2 Universal JDBC Driver Support
Related reference
Vendor-specific data sources minimum required settings
Provider coexistence considerations



Searchable topic ID:   jdbcdb2cfg
Last updated: Jun 21, 2007 9:56:50 PM CDT    WebSphere Application Server for z/OS, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/tdat_jdbcdb2cfg.html

Library | Support | Terms of Use | Feedback