Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
Installing and Setting up WebLogic Server 5.1: Previous topic | Next topic | Contents | Index

Installing WebLogic jDriver for Oracle

Overview

Other JDBC drivers

Installation steps

Editing an entry to the XML license file

Setting your path and client libraries

JDBC 2.0

Platform considerations

Directory to put in your system PATH

Windows NT

Solaris

IBM AIX

HP-UX

SGI Irix

Siemens MIPS

Compaq Tru64 UNIX

Note for Microsoft SDK for Java (Jview) users

Checking connections to the Oracle database

Using IDEs or debuggers with WebLogic jDrivers

Next step

Overview

WebLogic jDriver for Oracle is a new name for the product formerly known as jdbcKona/Oracle.

WebLogic jDriver for Oracle, a Type-2 JDBC driver for the Oracle DBMS is included with WebLogic Server. For this driver to function, you must have a complete Oracle client installed on the machine that will be the client to the Oracle DBMS. This Oracle client installation contains vendor-supplied client libraries and associated files that WebLogic jDriver for Oracle requires to operate.

The WebLogic Server distribution includes a choice of several BEA-supplied native libraries for WebLogic jDriver for Oracle. The library that you choose depends on which Oracle client version you have installed on your client machine and which version of the Oracle API you will use to access your Oracle server. Installing this driver requires that both the BEA-supplied native library and the Oracle-supplied client libraries be available by including them in your the client's PATH (Windows NT) or shared library path (UNIX), as described below.

For information on using WebLogic jDriver for Oracle see Using WebLogic jDriver for Oracle.

Important issues for release 5.1

Please read the Release notes for details on the issues highlighted below.

Oracle Release Notes are also available on line at http://www.weblogic.com/docs51/classdocs/release_notes_joci.html.

Platform Support:

Check the Release Notes or the WebLogic Platform Support page in the online documentation for details about which platforms, operating systems, DBMS versions, and Java versions are supported for WebLogic jDriver for Oracle.

Important issues include:

- WebLogic jDriver for Oracle is not supported when using the Oracle 8 API and connecting to an version 7 Oracle DBMS.

- Using CallableStatement.getResultSet()

- Mixing different versions of the Oracle Client and Oracle Server

- Codeset conversion with CLOBs when using a different operating system on the client and server.

Other JDBC drivers

BEA also has Type-4 JDBC drivers available for the Informix and Microsoft SQL Server DBMSs. These are pure-Java drivers and do not require vendor-supplied client libraries.

For more information on these drivers, please see: WebLogic JDBC Options.

Installation steps

1. Select the appropriate native library for your environment.

   WebLogic jDriver for Oracle is shipped with dll, sl, or so files for various combinations of Oracle client versions, APIs, and platforms. You must place the appropriate file in your system's path or shared library path for this driver to function. Unlike previous releases of WebLogic jDriver for Oracle, which had only one such file that was always present in the default path, you now must specify this path setting explicitly. For details and instructions on setting these options, see Setting your path and client libraries .

2. Add the client libraries from your Oracle installation to your system PATH (Windows NT) or load library path (UNIX-the name of this variable differs among UNIX systems). Check your Oracle documentation for the location of these libraries. On Windows NT the client libraries are usually located in c:\ORANT\bin.

3. Unpack the distribution.

   If you have purchased WebLogic Server, WebLogic jDriver for Oracle is included with your distribution. No further steps are required to unpack the distribution. The remainder of these installation steps are required only for users of the stand-alone version of WebLogic jDriver for Oracle.

   If you haven't already, unpack the archive you downloaded in the root directory of your computer. You must use a program such as WinZip that preserves the directory structure of the archive. The files unpack into the weblogic directory.

   The instructions in this document assume that you are installing WebLogic jDriver for Oracle on a Windows computer and that you unpacked the archive in the root directory of your C drive. If you're installing on a different operating system or in a different location, check your system documentation for help in adjusting the commands shown in these instructions for your own environment.

4. Add the WebLogic jDriver for Oracle classes directory to your CLASSPATH variable.

   Note: If you are using the WebLogic jDriver for Oracle that is bundled with WebLogic Server, the classpath setting are the same as those required for WebLogic Server. The standard start up scripts supplied with the WebLogic Server distribution will do this for you.

   To change your CLASSPATH temporarily at a Windows Command Prompt, use this command:

       $ set CLASSPATH=%CLASSPATH%;c:\weblogic\oci\classes

   To change your CLASSPATH permanently:

   1. Double-click the System icon in the Control Panel.

   2. Click the Environment tab.

   3. In the lower panel, select the CLASSPATH variable. If no CLASSPATH variable is defined, add it.

   4. Add c:\weblogic\oci\classes to the value of the CLASSPATH variable. Use a semicolon (;) to separate the new path from the previous value of the variable, if any.

      Any program you launch after you update the CLASSPATH variable in the System control panel will have access to the new value.

      For more help setting your CLASSPATH, read Setting classpath. If you're using WebLogic jDriver for Oracle from within an IDE like Symantec Cafe or JBuilder, the procedure for adding classes to the CLASSPATH may be different.

5. Install WebLogic jDriver for Oracle for use with browser applets.

   If you're planning to use WebLogic jDriver for Oracle to access databases via applets in a web browser, you must install the distribution on the computer executing the web server. Furthermore, the web server and the Oracle database server must be running on the same computer. This is a security restriction enforced by most web browsers, including Netscape Navigator and Internet Explorer. For information about browser security and applets, read Troubleshooting Applet Security problems.

   The web server must also be able to find the WebLogic jDriver for Oracle class files. To ensure that the web server can find the files, install the WebLogic jDriver for Oracle distribution on your web server computer and then set the CLASSPATH on that computer as described in step 4. Be sure to restart the web server after you change the CLASSPATH so that the web server has access to the revised CLASSPATH value.

6. Install a license file.

   With the release of version 5.1 of WebLogic jDriver for Oracle, a new type of license is shipped with the distribution. This license uses an XML file to store the license keys.

   There are several issues to consider regarding your license for WebLogic jDriver for Oracle:

   - If you downloaded an evaluation version of the driver, your distribution includes an evaluation license. Your driver is ready for evaluation use.

   - If you have previously purchased a license for WebLogic jDriver for Oracle, you must obtain an updated license file from your BEA contact person and place that license in your WebLogic jDriver for Oracle installation.

     Copy your license key into your WebLogicLicense.xml, file. This file is located at weblogic/oci/license/WebLogicLicense.xml (where weblogic is the directory containing your WebLogic jDriver for Oracle installation). For instructions on editing a WebLogic XML license file, see Editing an entry to the XML license file.

     To purchase a permanent license for WebLogic jDriver for Oracle, contact sales@weblogic.com.

Editing an entry to the XML license file

1. Open the message containing the key(s) you received by email when you purchased a license from BEA Systems, Inc.

2. Open the WebLogicLicense.xml file in a text editor. This file is located in one of the following directories:

   - standalone driver: weblogic/oci/license

   - using the driver with WebLogic Server: weblogic/license

     (Where weblogic is the directory containing your WebLogic jDriver for Oracle or WebLogic Server installation.)

     Do not edit this file in Microsoft Word or any other word-processing program that will save the file as a binary.

3. Copy the keys from the email and paste them at the top of the XML file.

   For example, if you have received a key, it'll look something like this:

         <LICENSE PRODUCT="jdbcKona/Oracle"
               IP="000.000.900.900"
               UNITS="5"
               EXPIRATION="31-Mar-1999"
               KEY="w20f8s08480v0adpup43245paprtnp8ac"
         />

4. Save the WebLogicLicense.xml file into the same directory.

5. Save your license key information and a copy of your WebLogicLicense.xml file in a safe place outside the WebLogic distribution, preferably someplace you will remember. Although no one else will be able to use your license keys, you should probably save this information in a place protected from either malicious or innocent tampering by others. Please note that when you upgrade your WebLogic classes, you will want to keep your original WebLogicLicense.xml and add new keys to it for any new services you purchase.

Setting your path and client libraries

A native dll, so, or sl file containing your driver must be made available to your WebLogic jDriver for Oracle client by including its directory in your system PATH (Windows NT), LD_LIBRARY_PATH (most Unix systems), or SHLIB_PATH (HP-UX). The directory containing the correct file varies depending on several factors discussed below.

The vendor-supplied libraries from Oracle must also be included in your PATH, load library path, or shared library path. The location of the directory containing your Oracle client libraries will vary depending on your installation. On Windows NT, these libraries are normally placed into your machine's path by the Oracle installer.

Version 5.1 of WebLogic jDriver for Oracle now uses the dll, so, or sl files built with the Oracle 8 API as the native interface for accessing an Oracle DBMS. This API allows for improved connectivity to a version 7 or version 8 Oracle Server and also provides access to new features available only in Oracle 8 (some of these features require JDBC 2.0, which requires a Java 2 JVM).

An older version of these dll, so, or sl files that uses the Oracle 7 API, is also included with this release to assure backwards compatibility.

The tables below, under Directory to put in your system PATH, list the Oracle client version, the Oracle API version and the directory you must put in your system PATH to access that version of the driver.

JDBC 2.0

JDBC 2.0 features are only available when using a driver that uses the Oracle 8 API. You must also run your WebLogic jDriver for Oracle client under a Java 2 compatible JDK. Using JDBC 2.0 also requires using a different driver class and URL in your Java code. For more information, see JDBC 2.0 for Oracle in the document Using WebLogic jDriver for Oracle http://www.weblogic.com/docs51/classdocs/API_joci.html#jdbc20.

Platform considerations

For information on supported platforms and JVM versions for WebLogic jDriver for Oracle, see the WebLogic platform support page.

The minimum supported client library is Oracle version 7.3.4.

Directory to put in your system PATH

Windows NT

Add weblogic\bin and the appropriate directory from the table below to your PATH, for example:

    $ set PATH=%PATH%;c:\weblogic\bin\oci805_8

Where c:\weblogic is the home directory of your WebLogic Server or WebLogic jDriver for Oracle installation.

Directory to put in your PATH

####

Oracle Client version | Oracle API version | Directory | Notes
7.3.4 | 7 | oci734_7 | Provided for backwards compatibility. No Oracle 8 or JDBC 2.0 features.
8.0.5 | 7 | oci805_7 | Provided for backwards compatibility. No Oracle 8 or JDBC 2.0 features.
8.0.5 | 8 | oci805_8 | Allows access to Oracle 8 and JDBC 2.0 features.
8.1.5 | 8 | oci815_8 | Allows access to Oracle 8 and JDBC 2.0 features.
8.1.6 | 8 | oci816_8 | Allows access to Oracle 8 and JDBC 2.0 features.

Solaris

Add weblogic/lib/solaris and the appropriate directory from the table below to your ld library path. (Where weblogic is the home directory of your WebLogic Server or WebLogic jDriver for Oracle installation)

Directory to put in your ld_library_path

####

Oracle Client version | Oracle API version | Directory | Notes
7.3.4 | 7 | oci734_7 | Provided for backwards compatibility. No Oracle 8 or JDBC 2.0 features.
8.0.5 | 7 | oci805_7 | Provided for backwards compatibility. No Oracle 8 or JDBC 2.0 features.
8.0.5 | 8 | oci805_8 | Allows access to Oracle 8 and JDBC 2.0 features.
8.0.6 | 8 | oci806_8 | Allows access to Oracle 8 and JDBC 2.0 features.
8.1.5 | 8 | oci815_8 | Allows access to Oracle 8 and JDBC 2.0 features.
8.1.6 | 8 | oci816_8 | Allows access to Oracle 8 and JDBC 2.0 features.

You must also include the path to your vendor-supplied client libraries from Oracle in your ld_library_path. The location of these libraries will depend on your Oracle client installation.

IBM AIX

WebLogic jDriver for Oracle for IBM AIX is available only for the Oracle 7 API. For a list of supported client versions, see Platform support for JDBC drivers.

Add the directory weblogic/lib/aix to your LIBPATH.

Where weblogic is the home directory of your WebLogic Server or WebLogic jDriver for Oracle installation.

HP-UX 11

Add weblogic/lib/hpux11 and the appropriate directory from the table below to your SHLIB_PATH. (Where weblogic is the home directory of your WebLogic Server or WebLogic jDriver for Oracle installation)

####

Oracle Client version | Oracle API version | Directory | Notes
8.0.4 | 7 | oci804_7 | Provided for backwards compatibility. No Oracle 8 or JDBC 2.0 features.
8.0.5 | 8 | oci805_8 | Allows access to Oracle 8 and JDBC 2.0 features.
8.1.5 | 8 | OCI815_8 | Allows access to Oracle 8 and JDBC 2.0 features.
8.1.6 | 8 | oci816_8 | Allows access to Oracle 8 and JDBC 2.0 features.

SGI IRIX

WebLogic jDriver for Oracle for SGI IRIX is available only for the Oracle 7 API. For a list of supported client versions, see Platform support for JDBC drivers.

- Irix users must run Java in N32 mode.

- You must have the Oracle 8.0.5 N32 client installed on your computer.

Add the directory weblogic/lib/irixsh to your LD_LIBRARYN32_PATH.

Where weblogic is the home directory of your WebLogic Server or WebLogic jDriver for Oracle installation.

Siemens MIPS

WebLogic jDriver for Oracle for Siemens MIPS is available only for the Oracle 7 API. For a list of supported client versions, see Platform support for JDBC drivers.

Add the directory weblogic/lib/reliantunix to your LD_LIBRARY_PATH.

Where weblogic is the home directory of your WebLogic Server or WebLogic jDriver for Oracle installation.

Compaq Tru64 UNIX

WebLogic jDriver for Oracle for Compaq Tru64 UNIX is available only for the Oracle 7 API. For a list of supported client versions, see Platform support for JDBC drivers.

Add the directory weblogic/lib/tru64unix to your LD_LIBRARY_PATH.

Where weblogic is the home directory of your WebLogic Server or WebLogic jDriver for Oracle installation.

Note for Microsoft SDK for Java (Jview) users

- Version 5.00, build 3186 or later of Jview is required for WebLogic jDriver for Oracle.

- Jview does not support JDBC 2.0 features.

Checking connections to the Oracle database

Once you have installed WebLogic jDriver for Oracle you should check that you can use it to connect to your database. A utility called dbping is included with WebLogic Server that you can use to test this connection.

To use this helper application, type the following at the command line (on one line):

    $ java -classpath
      c:\java\lib\classes.zip;c:\weblogic\classes;
      c:\weblogic\license;utils.dbping ORACLE user password server

Where c:\weblogic is the directory containing your WebLogic Server or WebLogic jDriver for Oracle installation and c:\java is the path to your JDK.

Note: If you are using Java 2 (JDK 1.2), omit "c:\java\lib\classes.zip" from the above command.

For more detailed instructions on how to verify your connection to a DBMS, see Testing connections.

If you have problems, check Troubleshooting problems with shared libraries on UNIX.

Setting up a connection pool

If you are using WebLogic jDriver for Oracle with either WebLogic Server or WebLogic Express, you can set up a pool of connections to your Oracle DBMS that will be established when WebLogic Server is started. Since the connections are shared among users, these connection pools eliminate the overhead of opening a new database connection for each user.

Your application then uses a multitier (Type-3) JDBC driver, such as the WebLogic Pool, JTS or RMI driver to connect to WebLogic Server. WebLogic Server then uses WebLogic jDriver for Oracle and one of the existing connections from the pool to connect to the Oracle database on behalf of your application.

Configuring a connection pool with WebLogic Server

1. Include the vendor-supplied native libraries and the WebLogic native libraries for WebLogic jDriver for Oracle in the PATH (Windows) or load library path (UNIX) of the shell where you will start WebLogic Server (for details, see Setting your path and client libraries). For more information on starting WebLogic Server, see Setting up and Starting WebLogic Server.

2. Add an entry to the weblogic.properties file specifying the connection pool properties (driver name, url, server, password, ACLs, etc.). For example:

       weblogic.jdbc.connectionPool.OraclePool=\
             url=jdbc:weblogic:oracle:myServer:myPort,\
             driver=weblogic.jdbc.oci.Driver,\
             loginDelaySecs=1,\
             initialCapacity=4,\
             maxCapacity=10,\
             capacityIncrement=2,\
             allowShrinking=true,\
             shrinkPeriodMins=15,\
             refreshMinutes=10,\
             testTable=dual,\
             props=user=myUserName;password=secret;server=myServer;\

       weblogic.allow.reserve.weblogic.jdbc.connectionPool.SQLPool=\
              guest,joe,jill
       weblogic.allow.reset.weblogic.jdbc.connectionPool.SQLPool=\
              joe,jill
       weblogic.allow.shrink.weblogic.jdbc.connectionPool.SQLPool=\
              joe,jill

   For more information on setting properties for connection pools, see JDBC Connection Pools in the WebLogic Administrators guide Setting WebLogic Properties.

3. Start WebLogic Server.

Using the connection pool in your application

Client-side applications

To use a connection pool in a client-side application, establish the database connection using the WebLogic JDBC/RMI driver. For more information, see

- Using WebLogic JDBC/RMI and WebLogic Clustered JDBC.

Server-side applications

To use a connection pool in a server-side application (such as a servlet), establish your database connection using the WebLogic pool or jts drivers. For more information, see:

- Using connection pools with server-side Java (in Using WebLogic HTTP Servlets)

- Creating a startup connection pool

Using IDEs or debuggers with WebLogic jDrivers

If you are using Symantec Cafe, other IDEs, or debuggers, copy the WebLogic-supplied native library to a new file with a name that ends in _g (before the dot).

For example on a Unix machine, copy libweblogicoci36.so to libweblogicoci36_g.so. For Windows NT, copy weblogicoci36.dll to weblogicoci36_g.dll

Next step

See Setting your development environment for information on setting up a development environment for running JDBC clients.

Using WebLogic jDriver for Oracle (at http://www.weblogic.com/docs51/classdocs/API_joci.html). Developers Guide for WebLogic jDriver for Oracle.

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.