Configuring BPM for the OCI Driver

If you are using Oracle for the monitoring and recovery database, you can use Oracle’s Type 2 driver, the Oracle Call Interface (OCI) driver. This requires some additional steps. BPM typically uses a DataDirect® driver to establish a database connection and interact with the database server. This section provides the requirements and instructions for enabling and configuring BPM for the OCI driver.

The OCI driver works in conjunction with the monitoring and recovery database only. The Worklist Manager uses the DataDirect driver only.

System Requirements for the Oracle OCI driver

The Oracle OCI driver is also called the thick driver because of the extensive native code it uses to communicate with the database. OCI is written in C; all of its Java calls use JNI to direct the calls to the C layer. The C layer communicates with the database and returns the results to the Java layer.

The library to map the Java calls to C calls is installed with the Oracle client’s installation. To enable monitoring and recovery persistence with OCI, you must install the Oracle client software.

Before You Begin

Before configuring the OCI driver, make sure the following are in place.

• The Oracle database is running and you can access the database using a SQL Plus client. Also ensure that the BPM Engine connects to an Oracle database server. Test the connection by configuring the engine for persistence using the DataDirect driver and verify that the monitoring and recovery database tables have been successfully populated.

• The Oracle client is installed and tnsnames.ora has an entry connecting to the Oracle database. Installing the Oracle client installs all the necessary libraries for database interactions and connection with the OCI driver.

• If you are connecting to an Oracle database server older than version 9.2, obtain a patch from your DBA to update the Oracle client for backward compatibility. Without the appropriate backward compatibility patch, the Oracle client cannot communicate properly with the older database server, and unpredictable behavior might result.

• In order to create connections to an Oracle database using the OCI driver, the OCI client version and the JDBC driver version must match. If the versions are not the same, testing or opening the connection fails. Depending on the version of the OCI client, one of the following errors could occur:

  Character Set Not Supported !!: DBConversion
  
  oracle.jdbc.oci8.OCIEnv.envCharSetId
  
  java.lang.NoSuchFieldError: oracle.jdbc.oci8.OCIEnv.envCharSetId

Implementing the OCI Driver

Implementing the OCI driver involves the following tasks:

• Copying the OCI Driver Library Files

• Setting up the Environment

• Configuring the BPM Engine to use the Oracle OCI Driver

Copying the OCI Driver Library Files

In order for BPM to use the OCI driver, the library file must reside in the application server's library directory.

To Copy the OCI Driver Library Files

1. Install the Oracle client on the system where application server resides.
2. Define the monitoring and recovery database in tnsnames.ora.
3. Copy the OCI driver file (for example, ojdbc14.jar) from the /jdbc/lib subdirectory in the Oracle client installation to the /lib subdirectory in the application server directory. For example,

   copy from oracle_home\jdbc\lib

   to JavaCAPS_Home\appserver\lib

   ---

   Note - The location of the files in the Oracle installation varies depending on the version of Oracle being used and whether it is a client or server installation.

   ---

4. Restart the application server to load the driver classes.

Setting up the Environment

To enable the OCI driver with the BPM Engine, set the following environment variables.

For Windows operating systems:

• Set the oracle_home environment variable.

• Add oracle_home\lib to the system PATH.

• Add oracle_home\bin to the system PATH.

For Linux and UNIX operating systems (except HPUX and AIX):

• Set the oracle_homeenvironment variable.

• Add oracle_home/lib to the LD_LIBRARY_PATH environment variable.

• Add oracle_home/bin to the PATH environment variable.

For HP-UX:

• Set the oracle_home environment variable.

• Add oracle_home/lib to the SHLIB_PATH environment variable.

• Add oracle_home/bin to the PATH environment variable.

For AIX:

• Set the oracle_home environment variable.

• Add oracle_home/lib to the LIBPATH environment variable.

• Add oracle_home/bin to the PATH environment variable.

Configuring the BPM Engine to use the Oracle OCI Driver

You must configure the BPM Engine to use the OCI driver instead of the default thin driver. This is configured in the NetBeans Services window in the application server properties sheet.

To Configure the Engine to Use the Oracle OCI Driver

1. In the NetBeans Services window, right-click the application server, and then click Properties.
2. Click BPM Engine Configuration.
3. On the Properties dialog box, enter the service name in the Oracle Net Service Name field.

   The value to enter is the TNS name configured in the tnsnames.ora file (located at <oracle_home>/network/admin). The following example shows a typical TNS name configuration where ORCL.STC.COM is the Oracle Net Service Name.

   ORCL.STC.COM =
     (DESCRIPTION =
       (ADDRESS_LIST =
         (ADDRESS = (PROTOCOL = TCP)(HOST = MyHost)(PORT = 1521))
       )
       (CONNECT_DATA =
         (SERVICE_NAME = orcl)
       )

4. Fill in the properties.
5. Click OK.

   The following table describes the fields you must configure in the BPM Engine Configuration properties.

   
   

   Field Description Persistence Mode An indicator of whether persistence is enabled. Select one of the Persist to Database options to enable persistence in BPM. Database The database platform in use. Select the correct version of Oracle to enable the OCI feature. Database Host The name of the computer on which the Oracle database resides. Database Port The port on which the Oracle database is listening. The default is 1521. Oracle Net Service Name The TNS name of the database (from the tnsnames.ora file). The BPM Engine uses the OCI driver if this property is populated. Otherwise, the BPM Engine uses the default DataDirect driver. Database Instance/Schema The name of the database. Database User The user name to access the monitoring and recovery tables. Password The Password to access the monitoring and recovery tables.

Implementing Transparent Application Failover

Oracle RAC is an Oracle database that has two or more instances accessing a shared database using cluster technology. A cluster is a group of machines (or nodes) that work together to perform the same task. To support this architecture, two or more machines that host the database instances are linked by a high-speed interconnect to form the cluster. The interconnect is a physical network used as a means of communication between each node of the cluster.

After Oracle RAC is installed, the Transparent Application Failover (TAF) feature can be configured to ensure the highest levels of availability. TAF compliments all levels of the availability hierarchy. Applications and users are automatically and transparently reconnected to another system, applications and queries continue uninterrupted, and the login context is maintained. Oracle Net Services is configured to allow the listener on each database instance of RAC to failover in case of failure.

The OCI driver works in conjunction with the BPM Engine only. The Worklist Manager uses the DataDirect driver only.

To Implement Transparent Application Failover

1. Set up the Oracle RAC server with the multiple hosts or instances sharing the same data storage.

   For information about configuring tnsnames.ora to enable the TAF feature when using the OCI driver, see Before You Begin.

2. If you have not already done so, install Oracle client locally where the application server is running.

   Oracle client must be installed for OCI to work. Since the OCI driver establishes connectivity to the database based on a native C call, the same version of the Oracle client must be installed as packaged with BPM. Version conflicts for OCI would result in problems configuring the OCI driver with BPM.

3. Configure the tnsnames.ora file for TAF.

   Below is an example of a tnsnames.ora file configured for a transparent application failover (TAF).

   Option 1: Connect time FAIL OVER and TAF

   MY_CLUSTER =
     (DESCRIPTION =
       (FAILOVER = ON)
       (LOAD_BALANCE = OFF)
       (ADDRESS_LIST =    
         (ADDRESS = (PROTOCOL = TCP)(HOST = Node1)(PORT = 1521))
         (ADDRESS = (PROTOCOL = TCP)(HOST = Node2)(PORT = 1521))
       )
       (CONNECT_DATA =
         (SERVICE_NAME = my_cluster.my_company.com)
         (FAILOVER_MODE =
           (TYPE = SELECT)
           (METHOD = PRECONNECT)
           (BACKUP=Node2)
         )
       )
     )

   Option 2: TAF configuration

   MY_CLUSTER =
     (DESCRIPTION =
       (ADDRESS = (PROTOCOL = TCP)(HOST = Node1)(PORT = 1521))
       (CONNECT_DATA =
         (SERVICE_NAME = my_cluster.my_company.com)
         (FAILOVER_MODE =
           (TYPE = SELECT)
           (METHOD = PRECONNECT)
            (BACKUP = Node2)
          )
       )
     )

   In the above configuration, MY_CLUSTER has the knowledge of the two nodes that are configured to act as a cluster. The cluster should be configured to share the same disk by RAC/OPS.

   In option 1, FAILOVER is set to ON and LOADBALANCE is set to OFF. This is the configuration for a connect time failover. In connect time failover, when the OCI driver tries to connect to Node1 and determines that the node is down, it connects to the other host in the Address list (Node2). Option 2 is shown only to illustrate configuring just the TAF feature in the OCI client. For BPM, both the connect time failover and the TAF configuration is required.

   Configuring the TAF option involves adding Oracle Net parameters to the tnsnames.ora file and the use of parameter values to ascertain the next step in the failover process when one of the participating nodes encounters failure. The parameter that drives the TAF option is the FAILOVER_MODE under the CONNECT_DATA section of a connect descriptor. By using one or more of the following parameters, the full functionality of TAF can be achieved.

   
   

   Parameter Description BACKUP Specifies a different net service name to be used to establish the backup connection. A backup should be specified when using PRECONNECT to pre-establish connections. Specifying a BACKUP is strongly recommended for BASIC methods; otherwise, reconnection might first attempt the instance that has just failed, adding additional delay until the client reconnects. TYPE Specifies the type of failover. Three types of Oracle Net failover functionality are available to the Oracle Call Interface by default. SESSION– Fails over the session. With this option only a connection is established and no work in progress is transferred from the failed instance to the available instance. SELECT– Enables a user with open cursors to continue fetching on them after failure. Oracle Net keeps track of any SELECT statements issued in the current transaction, as well as how many rows have been fetched back to the client for each cursor associated with a SELECT statement. If the connection to the instance is lost, Oracle Net establishes a connection to a backup instance, re-executes the SELECT statements, and positions the cursors so the client can continue fetching rows as if nothing had happened. However, no DML operations are transferred. NONE– No failover functionality is implemented (this is the default). METHOD Determines the speed of the failover from the primary to the secondary or backup node. BASIC– Establishes connections at failover time. PRECONNECT– Pre-establishes connections. If this parameter is used, connection to the backup instance is made at the same time as the connection to the primary instance. RETRIES Specifies the number of times to attempt to connect to the BACKUP node after a failure before giving up. DELAY Specifies the amount of time in seconds to wait between attempts to connect to the BACKUP node after a failure before giving up.

Troubleshooting

To aid in troubleshooting, common error messages and resolutions are described below.

Table 3 Troubleshooting Windows Systems

Table 4 Troubleshooting Linux/UNIX Systems