Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs   |   Site Map   |   Search   |   Contact   |   Glossary   |   WebLogic Server Documentation

Installing WebLogic jDriver for Microsoft SQL Server

Overview

Which version should I use?

WebLogic jDriver for Microsoft SQL Server version 6.5 and 7.0

WebLogic jDriver for Microsoft SQL Server version 7.0

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 SQL Server installation

Setting a port for SQL Server connections

Verifying the JDBC driver with dbping

More resources

Documentation

Code examples

WebLogic jDriver for Microsoft SQL Server is a new name for the product previously referred to as jdbcKona/MSSQLServer4.

This document tells you how to install WebLogic jDriver for Microsoft SQL Server (formerly called FastForward for SQL Server), WebLogic's pure-Java Type 4 JDBC driver for Microsoft SQL Server. WebLogic jDriver for Microsoft SQL Server 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 Microsoft SQL Server. The driver ships in two versions, one for SQL Server version 6.5 and 7.0, and another for SQL Server 7.0 only. Both versions function identically, except as noted below.

WebLogic jDriver for Microsoft SQL Server, like all Type 4 JDBC drivers, is pure-Java and requires no vendor-supported client libraries. WebLogic jDriver for Microsoft SQL Server communicates directly with SQL Server through a TCP/IP network, using the SQL Server "Tabular Data Stream" protocol, so DB-Library does not have to be installed on a client computer.

• Supports SQL Server versions 4.2, 6.0, and 6.5.

• Supports SQL Server 7.0, with the following restrictions:

  • The SQL Server responds as if the connection were coming from a SQL Server version 6.5 client, and implements the semantics of SQL Server version 6.5. For instance, when executing a "CREATE TABLE" SQL statement, the DBMS, by default, creates columns that do not allow null values. (This is the normal behavior for SQL Server version 6.5.)

  • New SQL Server 7.0 data types are not supported.

WebLogic jDriver for Microsoft SQL Server version 7.0

• Supports only SQL Server 7.0. The SQL Server responds to requests made from this driver as requests from a SQL Server version 7.0 client and implements the semantics of a SQL Server 7.0. For instance (in contrast to the semantics of SQL Server version 6.5), the DBMS, by default, creates columns that allow null values.

• Supports new data types introduced with SQL Server version 7.0.

Before you begin

If you are using WebLogic jDriver for Microsoft SQL Server with WebLogic Server 4.5 or later, you must also upgrade the driver for use with WebLogic Server.

If you have previously purchased a license for WebLogic jDriver for Microsoft SQL Server, you must obtain an updated license file from your BEA contact person. Instructions for updating your license are included in the Installation steps, below.

The WebLogic jDriver for Microsoft SQL Server 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.

1. Unpack the distribution.

   If you have not already done so, unpack the zip file containing WebLogic jDriver for Microsoft SQL Server 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 Microsoft SQL Server 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.

2. Add the WebLogic jDriver for Microsoft SQL Server classes and license directory to your CLASSPATH variable.

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

   $ set CLASSPATH=%CLASSPATH%;c:\weblogic\mssqlserver4\classes;
     c:\weblogic\mssqlserver4\license

   (If you are using the WebLogic jDriver for Microsoft SQL Server version 7.0, substitute mssqlserver4v70 for mssqlserver4 in the above command line.)

   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\mssqlserver4\classes and c:\weblogic\mssqlserver4\license to the value of the CLASSPATH variable. Use a semicolon (;) to separate the new path from the previous value of the variable, if any.

      (If you are using the WebLogic jDriver for Microsoft SQL Server version 7.0, substitute mssqlserver4v70 for mssqlserver4 in the above classpath.)

      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 Microsoft SQL Server 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 Microsoft SQL Server for use with browser applets.

   If you're planning to use WebLogic jDriver for Microsoft SQL Server to access SQL Server databases via applets in a web browser, you must install the distribution on the computer executing the web server. Furthermore, the web server and SQL Server must be running on the same computer. This is a security restriction enforced by most web browsers, including Netscape Navigator and Internet Explorer.

   The web server must also be able to find the WebLogic jDriver for Microsoft SQL Server class files. To ensure that the web server can find the files, install the WebLogic jDriver for Microsoft SQL Server distribution on your web server computer and then set the CLASSPATH on that computer as described in step 2. above. 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 Microsoft SQL Server, 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 Microsoft SQL Server:

   • 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 Microsoft SQL Server, you must obtain an updated license file from your BEA contact person and place that license in your WebLogic jDriver for Microsoft SQL Server installation. The procedure required to use the XML license differs depending on whether you are using WebLogic jDriver for Microsoft SQL Server as a standalone driver (without WebLogic Server), or as a two-tier driver from within WebLogic Server (using the t3, pool, JTS, or RMI type-3 drivers):

   Standalone use

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

   
   (If you are using the WebLogic jDriver for Microsoft SQL Server version 7.0, substitute mssqlserver4v70 for mssqlserver4 in the above path.)

   Using with WebLogic Server

   If are using WebLogic jDriver for Microsoft SQL Server as a middle tier JDBC driver within WebLogic Server (via the pool, JTS, t3, or RMI type-3 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 Microsoft SQL Server, contact sales@weblogic.com.

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/mssqlserver4/license

   • standalone driver for SQL Server version 7.0: weblogic/mssqlserver4v70/license

   • using the driver with WebLogic Server: weblogic/license

     (Where weblogic is the directory containing your WebLogic jDriver for Microsoft SQL Server 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 looks something like this:

     <LICENSE PRODUCT="jdbcKona/MSSQLServer4"
           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.

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

Configuring a connection pool with WebLogic Server

1. Include the WebLogic jDriver for Microsoft SQL Server 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.SQLPool=\
         url=jdbc:weblogic:mssqlserver4:myServer:myPort,\
         driver=weblogic.jdbc.mssqlserver4.Driver,\
         loginDelaySecs=1,\
         initialCapacity=4,\
         maxCapacity=10,\
         capacityIncrement=2,\
         allowShrinking=true,\
         shrinkPeriodMins=15,\
         refreshTestMinutes=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.

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 SQL Server installation

Verify that you are using version 6.5 or 7.0 of Microsoft SQL Server. Older versions of SQL Server do not properly support JDBC metadata functions and have limited data type support.

To connect to SQL Server, you need the following information:

• Username and password of a valid SQL Server account

• Hostname or IP number of the machine where the SQL Server is running

• TCP/IP port at which the DBMS is listening for connection requests.

  For Microsoft SQL Server, the default port number is 1433. Servers, however, can be configured to listen on any port number. Verify the port number from your configuration files. If you need help setting the port number, see the following section Setting a port for SQL Server connections.

Setting a port for SQL Server connections

You set the hostname and port for SQL Server connections by making an entry into the SQL Server configuration files. In the configuration files, a logical "server name" is associated with a server machine name and port number. WebLogic jDriver for Microsoft SQL Server does not use the logical server name, only the host name and the port number.

You must have administrator privileges to change your SQL Server settings. To set the port:

1. Run MS SQL Server Setup.

2. Select Change Network Support.

3. Select TCP/IP.

4. Select the port you want to use, such as "1433".

Once you have set the port, you can verify with telnet that the server is listening on that port. Here is the syntax for the telnet command:

 $ telnet hostname_or_IP_address port

For example, to test the SQL Server listening on port 1433 of the computer named "myhost", type:

 $ telnet myhost 1433

If the server is not listening on the port, telnet will display an error message. If the server is listening on the port, telnet will display nothing; eventually, the host will drop the connection.

You can use isql to test your login information. Here's the isql syntax:

 $ isql -Uusername -Ppassword -Sserver

You can use the WebLogic dbping Java application to verify that WebLogic jDriver for Microsoft SQL Server can connect to your SQL Server. To use dbping, make sure that the classes for WebLogic jDriver for Microsoft SQL Server are in your CLASSPATH (as described under Installation steps), then type this command:

$ java utils.dbping MSSQLSERVER4 username password
   [database@]host[:port]

where:

For example, the following command pings the SQL Server "pubs" database on the computer named "myhost", using the default TCP/IP port, and the "sa" login with a null password:

$ java utils.dbping MSSQLSERVER4 sa "" pubs@myhost

The output from the command includes code that you can use to connect to the database in a Java program.

See Using WebLogic jDriver for SQL Server for more information about JDBC connections.

• API reference

• Using WebLogic jDriver for SQL Server

• WebLogic JDBC Options

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 examples directory in the distribution.