Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy

Installing WebLogic jDriver for Informix

Overview

Before you begin

Upgrade information

Evaluation licenses

Installation steps

Editing an entry to the XML license file

Setting up a connection pool

Configuring a connection pool with WebLogic Server

Using the connection pool in your application

Verifying your connection to the Informix database

Determining your database, hostname, and port

More resources

Documentation

Applet programming

Code examples

Overview

WebLogic jDriver for Informix is a new name for the product previously referred to as jdbcKona/Informix4.

This document tells you how to install WebLogic jDriver for Informix, BEA's pure-Java Type 4 JDBC driver for Informix. WebLogic jDriver for Informix is a 100% pure Java implementation of the Java Database Connectivity (JDBC) API, the industry standard for relational database access from Java clients. It provides Java clients, including applets, with direct access to the Informix database management system (DBMS). If you are using the driver with applets, then you must install the package on your web server host, which must also host your Informix database.

Before you begin

Upgrade information

Note: If you are using WebLogic jDriver for Informix with WebLogic Server 4.5 or later, you must also upgrade the driver for use with WebLogic Server. You can download the driver from the BEA website.

Evaluation licenses

The WebLogic jDriver for Informix distribution you downloaded from WebLogic's website includes an evaluation license that allows you to test the product with 2 users for 30 days. To purchase additional licenses, contact sales@weblogic.com.

Installation steps

1. Unpack the distribution.

   If you have not already done so, unpack the zip file containing the WebLogic jDriver for Informix into 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 Informix on a Windows computer and that you unpacked the archive in the root directory of your C drive. If you are 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.

2. Add the WebLogic jDriver for Informix classes directory to your CLASSPATH variable.

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

       $ set CLASSPATH=%CLASSPATH%;c:\weblogic\informix4\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\informix4\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 are using WebLogic jDriver for Informix from within an IDE like Symantec Cafe or JBuilder, the procedure for adding classes to the CLASSPATH may be different.

3. Install WebLogic jDriver for Informix for use with browser applets.

   If you are planning to use WebLogic jDriver for Informix 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 Informix 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 Informix class files. To ensure that the web server can find the files, install the WebLogic jDriver for Informix distribution on your web server computer and then set the CLASSPATH on that computer as described in Step 2. Be sure to restart the web server after you change the CLASSPATH so that the web server has access to the revised CLASSPATH value.

4. Install a license file.

   With the release of version 5.1 of WebLogic jDriver for Informix, 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 Informix:

   - 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 Informix, you must obtain an updated license file from your BEA contact person and place that license in your WebLogic jDriver for Informix installation. The procedure required to use the XML license differs depending on whether you are using WebLogic jDriver for Informix as a standalone driver (without WebLogic Server), or as a two-tier driver from within WebLogic Server (using the t3, Pool, JTS, or RMI multitier drivers).
   Standalone use
     Copy your license key into your WebLogicLicense.xml, file. This file is located at weblogic/informix4/license/WebLogicLicense.xml (where weblogic is the directory containing your WebLogic jDriver for Informix installation). For instructions on editing a WebLogic XML license file, see Editing an entry to the XML license file.
   Using with WebLogic Server
     If are using WebLogic jDriver for Informix as a middle tier JDBC driver within WebLogic Server (via the Pool, JTS, t3, or RMI multitier drivers), copy your license key into the license file used by WebLogic Server. This file is located at weblogic/license/WebLogicLicense.xml (where weblogic is the directory containing your WebLogic Server 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 Informix, 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/informix4/license

   - using the driver with WebLogic Server: weblogic/license

     (Where weblogic is the directory containing your WebLogic jDriver for Informix 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 for clustering, it'll look something like this:

         <LICENSE PRODUCT="jdbcKona/Informix4"
               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 up a connection pool

If you are using WebLogic jDriver for Informix with either WebLogic Server or WebLogic Express, you can set up a pool of connections to your Informix 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 Informix and one of the existing connections from the pool to connect to the Informix database on behalf of your application.

Configuring a connection pool with WebLogic Server

1. Include the WebLogic jDriver for Informix classes in the WebLogic classpath used to start WebLogic Server (specified with the weblogic.class.path property on the command line). 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.InfxPool=\
             url=jdbc:weblogic:informix4,\
             driver=weblogic.jdbc.informix4.Driver,\
             loginDelaySecs=1,\
             initialCapacity=4,\
             maxCapacity=10,\
             capacityIncrement=2,\
             allowShrinking=true,\
             shrinkPeriodMins=15,\
             refreshTestMinutes=10,\
             testTable=dual,\
             props=user=myUserName;password=secret;\
                server=myDatabase@myDBServer:myPortNo

       weblogic.allow.reserve.weblogic.jdbc.connectionPool.InfxPool=\
              guest,joe,jill
       weblogic.allow.reset.weblogic.jdbc.connectionPool.InfxPool=\
              joe,jill
       weblogic.allow.shrink.weblogic.jdbc.connectionPool.InfxPool=\
              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

Verifying your connection to the Informix database

Check your connection to the Informix database. You need to have a username and password of a valid user, and you also need to know the database name, hostname, and port of your database (see Determining your database, hostname, and port).

Once you've collected that information, you can test your connection. The WebLogic distribution includes a Java application to help you in setting up WebLogic jDriver for Informix. To use this helper app, make sure that the c:/weblogic/informix4/classes directory is in your CLASSPATH. At a command line, type:

    java utils.dbping INFORMIX4 user pass db@host:port

where:

user
  The Informix username of a valid user for this database

pass
  Password for the user

db@host:port
  These three arguments together describe how to reach your Informix database:

db is the name of the database
host is the name of the computer on which the Informix server is running
port is the TCP/IP port number on which the Informix server is listening for connection requests
Note the syntax of the command: the database name is followed by "@" (the at-sign), and the hostname and port are separated by a colon.

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

Determining your database, hostname, and port

You need to know several details about your Informix server installation in order to make a connection to it. These include:

- Name of the database you'll be accessing

- Hostname of the computer on which the Informix server is running

- The TCP/IP port number on which the Informix server is listening for connection requests

This may seem a little confusing because often people use the word "server" to mean both the machine on which your database is running and the database instance itself. We'll be clear in this document: the "hostname" is the name of the machine, and the "database name" is the name of the Informix instance.

To get information about the Informix server you want to connect to, look in $INFORMIXDIR/etc/sqlhosts and find the appropriate entry under the "SERVER" column. The entry in this file will tell you the hostname and servicename - located in the far right column - for the connection. You only need to know the servicename to find out the port number.

Then look in your /etc/services file (or, on Windows NT, in \Winnt\system32\drivers\etc\services) to find the port number associated with the servicename.

More resources

Documentation

- API reference

- Using WebLogic jDriver for Informix

Applet programming

If you are planning to use WebLogic jDriver for Informix in an applet, you need to install the driver on your web server host. In addition, the web server and the Informix database must be located on the same machine. Because an applet must communicate only with the host from which its classes were loaded, the Informix database and the web server must be on the same IP host.

If you have questions about applet security issues, read Troubleshooting Applet Security problems.

For more information on applets, read Using WebLogic for applet programming.

Code examples

We also ship a number of code examples in the distribution that will help you get started. Code examples are located in the weblogic/informix4/examples/ directory in the distribution.

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