Installing jConnect for JDBC

Installing jConnect for JDBC

To install jConnect for JDBC, complete the following tasks:

Install JDK or JRE

Before installing jConnect, you must download and install the Java Development Kit (JDK) if developing programs that use jConnect, or the Java Runtime Environment (JRE) based on your needs.

Installing JDK/JRE

Download the current JDK/JRE from Sun's Java Software Web site at the following URL:

http://java.sun.com/products/index.html

Download and install the JDK or JRE using the installation instructions provided.

After installing the JRE/JRE, define the JRE_HOME/JAVA_HOME environment variable to point to the JRE/JDK installation directory. See your operating system documentation for instructions.

Install jConnect products

This section explains how to download jConnect products from the Web or from a CD.

If you cannot download jConnect from the Sybase Web site, contact Sybase Technical Support to request a CD. When you receive the CD, see "lnstalling jConnect from a CD" for installation instructions.The following instructions apply to standalone jConnect product downloaded from the Web site or obtained on a CD. If the jConnect you want to install is part of the Sybase Software Developer's Kit (SDK) or any other Sybase product, please refer to the Installation Guide for that product for installation instructions.

Installing jConnect from the Web

Go to the jConnect download Web page at the following URL:

http://www.sybase.com/products/middleware/jconnectforjdbc

Click Downloads in the Information box on the left side of the window.

When you see the registration page, read the jConnect License Agreement, and then complete and submit the provided registration form. You may see a message that your registration has been successful.

Download the jConnect 6.05 driver and related documentation utilities, as needed:.

Extract the zip files into a directory on your machine.

To extract zip files, you need a zip-file extraction utility. Most UNIX and Linux platforms provide an unzip utility as part of their standard tools. Windows users can use WinZip.

After installing jConnect:
- Set the JDBC_HOME and CLASSPATH environment variables.
  See "Set environment variables".
- Review your installation contents. See "Review the installation contents".

lnstalling jConnect from a CD

Use these instructions only if you requested a jConnect CD because you cannot download jConnect from the Web. Do not use these instructions to install the version of jConnect included with Adaptive Server Enterprise or other Sybase products. Instead, use the installation guide provided.

Log in to the machine on which you want to install jConnect. Use a login with Administrator privileges or the ID you use for all installations.

Place the Sybase jConnect CD in the CD-ROM drive.

Access the CD from your system:
- For UNIX or Linux:
  
  Mount the CD by typing the command for your platform.
- For Windows:
  
  Use MyComputer or Windows Explorer to access the CD-ROM drive.

Select the zip files for components you wish to install. The CD contains jConnect 6.05 driver, documentation, and utilities.

Extract the zip files into a directory on your machine.

To extract zip files, you need a zip-file extraction utility. Most UNIX and Linux platforms provide an unzip utility as part of their standard tools. Windows users can use WinZip.

After installing jConnect:
- Set the JDBC_HOME and CLASSPATH environment variables.
  See "Set environment variables".
- Review your installation contents. See "Review the installation contents".

Set environment variables

To use the jConnect classes you installed, you must set the JDBC_HOME and CLASSPATH environment variables.

Setting JDBC_HOME

JDBC_HOME represents the directory in which you install jConnect. For example:

The zip file is not aware of your directory structure and installs everything below a directory with the specific jConnect driver's name.

On Windows:

If you unzipped the jConnect 6.05 driver in C:\Sybase on Windows, you must set JDBC_HOME to:
```
C:\Sybase\jConnect-6_0
```
On UNIX and Linux:

If you installed the zip file into /usr/local/Sybase, you would set JDBC_HOME to:
```
/usr/local/Sybase/jConnect-6_0
```

Setting the CLASSPATH

CLASSPATH is the location of the jConnect runtime classes and/or jar files for JDK 1.4.x or later. This section describes what you need in your CLASSPATH depending on which versions of JDK and jConnect you are using.

Using jConnect 6.05 with JDK 1.4.x and later

To use jConnect 6.05 with JDK versions 1.4.x and later, add the following path to the CLASSPATH environment variable:

On UNIX or Linux:

$JDBC_HOME/classes/jconn3.jar
On Windows:

%JDBC_HOME%\classes\jconn3.jar

Running samples or TDS-tunnelling servlet

To run the samples or the TDS-tunnelling servlet, add the following to the CLASSPATH environment variable:

On UNIX or Linux:

$JDBC_HOME/classes/jconn3.jar:$JDBC_HOME/classes
On Windows:

%JDBC_HOME%\classes\jconn3.jar;%JDBC_HOME%\classes

Sybase requires that you run JDK 1.4.2 or later with jConnect 6.05.

In addition, the CLASSPATH should include the location of any application classes you have defined.

CLASSPATH restriction using Netscape

If you use Netscape, some restrictions may apply to the way you set your CLASSPATH environment variable.

The Java VM security manager will not allow a version of jConnect installed in your local file system to create a connection to a server, even if the server is your local system. This can create a problem if you use Netscape to run an applet that uses jConnect.

When Netscape needs to load jConnect to create a connection to a server, it looks for a CLASSPATH defined in its environment to find the jConnect classes. If it finds a CLASSPATH that you have defined to point to your local jConnect installation, it loads jConnect directly from the local file system--rather than from the server--and tries to create a connection. This generates a security error and the connection fails.

In summary, if you are using Netscape to run jConnect applets, do not set the CLASSPATH to the local jConnect directory.

Install stored procedures

For jConnect to function properly, you must install stored procedures and tables on the Adaptive Server Enterprise or Adaptive Server Anywhere database to which your application will be connecting. jConnect provides the following scripts to install the required stored procedures and tables:

sql_server12.5.sql, which installs stored procedures on Adaptive Server Enterprise versions 12.5.x. or later.
sql_server15.0.sql, which installs stored procedures for Adaptive Server Enterprise 15.x or later.
sql_asa.sql, which installs stored procedures on SQL Anywhere and Adaptive Server Anywhere databases.

If you use ASE 12.5.3 or later, or ASA 9.0.2 or later, the scripts come pre-installed on the server. You will need to install these scripts only if you have a later version of the driver than the one that shipped with ASE. In addition, for backward compatibility, sql_server.sql and sql_server12.sql are included on ASE 11.9.2 and 12.0 respectively, although these versions are no longer supported.

Running stored-procedure installation scripts

Verify that your JAVA_HOME, JDBC_HOME, and CLASSPATH environment variables are set.

Use the IsqlApp sample application according to the instructions in the following sections, based on the target database and your platform.

On an Adaptive Server Enterprise database

The following describes how to install stored procedures for metadata in an Adaptive Server Enterprise database using Windows, UNIX, and Linux.

Installing stored procedures on Windows

Go to a DOS prompt

Enter the following command on one line from the %JDBC_HOME%\classes directory:

For Adaptive Server Enterprise version 15.x:

java IsqlApp -U sa -P password -S jdbc:sybase: Tds:[hostname]:[port] -I %JDBC_HOME%\sp\sql_server15.0.sql -c go

For Adaptive Server Enterprise version 12.5.x:

java IsqlApp -U sa -P password -S jdbc:sybase: Tds:[hostname]:[port] -I %JDBC_HOME%\sp\sql_server12.5.sql -c go

Installing stored procedures on UNIX and Linux

Enter the following command from your $JDBC_HOME/classes directory:

For Adaptive Server version 15.x:

java IsqlApp -U sa -P password -S jdbc:sybase: Tds:[hostname]:[port] -I $JDBC_HOME/sp/sql_server15.0.sql -c go

For Adaptive Server version 12.5.x:

java IsqlApp -U sa -P password -S jdbc:sybase: Tds:[hostname]:[port] -I $JDBC_HOME/sp/sql_server12.5.sql -c go

On a SQL Anywhere or Adaptive Server Anywhere database

The following describes how to install stored procedures for metadata in a SQL Anywhere or Adaptive Server Anywhere database using Windows, UNIX, and Linux.

Installing stored procedures on Windows

Go to a DOS prompt

Enter the following command on one line from the %JDBC_HOME%\classes directory:

java IsqlApp -U dba -P password -S  jdbc:sybase:
     Tds:[hostname]:[port] -I %JDBC_HOME%\sp\sql_asa.sql  -c go

Installing stored procedures on UNIX and Linux

Enter the following command from your $JDBC_HOME/classes directory:
java IsqlApp -U dba -P password -S jdbc:sybase: Tds:[hostname]:[port] -I $JDBC_HOME/sp/sql_asa.sql -c go

Review the installation contents

After completing the jConnect installation, review the contents listed in this section.

Packages

For jConnect version 6.05, the following packages are found inside jar files
( jconn3.jar for the release build and jconn3d.jar for the debug build):

com.sybase.jdbc3.jdbc
com.sybase.jdbc3.tds
com.sybase.jdbc3.timedio
com.sybase.jdbc3.utils
com.sybase.jdbcx

The jConnect driver, com.sybase.jdbc3.jdbc.SybDriver, is located in the com.sybase.jdbc3.jdbc package.

Directories and files

Table 1-3 lists the directories and files in jconnect605.zip.

Table 1-3: Directories and files for jconnect605.zip installation
Name	Type	Description
jconnect-6_0	Directory	Contains all of the jConnect version 6.05 files and subdirectories.
classes	Subdirectory	Contains the following jConnect 6.05 components: jconn3.jar file that contains jConnect 6.05 classes sample2 subdirectory with jConnect 6.05 class files for sample applets and applications gateway2 subdirectory for compiled TDS-tunnelling servlet
devclasses	Subdirectory	Contains the jconn3d.jar file that contains the same jConnect 6.05 components as jconn3.jar, but debug mode is turned on.
docs	Subdirectory	Contains the: en subdirectory, which contains the English javadoc documentation en/progref subdirectory, which contains the jConnect for JDBC Programmer's Reference in HTML and PDF format en/installdocs subdirectory, which contains the jConnect for JDBC Installation Guide in HTML and PDF format
gateway2	Subdirectory	Contains source code for the TDS-tunnelling servlet.
sample2	Subdirectory	Contains source code for sample Java applications.
sp	Subdirectory	Contains isql scripts that install stored procedures for function escapes and DatabaseMetaData methods on a database server. The scripts are: sql_asa.sql (Adaptive Server Anywhere) sql_server15.0.sql (Adaptive Server Enterprise version 15.x) sql_server12.5.sql (Adaptive Server Enterprise version 12.5.x)
tools	Subdirectory	Contains a perl script (decode-tli) that UNIX or Linux users can apply to parse an interfaces file into a readable format.
netimpct.gif	Graphic file	Contains a jConnect graphic.
index.html	HTML file	Contains links to jConnect documentation and jConnect samples.

JDBC 2.0 samples

You can find JDBC 2.0 code samples in the sample2 subdirectory under the jConnect installation directory. For more information, see "jConnect Sample Programs," in Appendix B of the jConnect for JDBC Programmer's Reference.

JDBC 3.0 conformance

The JDBC 3.0 specification provides much new functionality unavailable in the JDBC 2.0 specification. jConnect 6.05 contains the methods offered in the JDBC 3.0 specification; however some are not implemented. Applications that invoke any un-implemented JDBC 3.0 methods receive a SQL exception indicating that the method has not been implemented.

Future versions of jConnect will support the missing JDBC 3.0 features.

Test the jConnect installation

After jConnect is installed, test the installation by running the Version program.

The Version program connects to a demonstration database that Sybase has made available on the Internet. You must have Internet access to run the Version program successfully, or explicitly run it with [-U username]
[-P password] [-S servername] commands to point it to your database.

Testing the installation

From the DOS prompt for Windows, or at a UNIX or Linux prompt, change to the JDBC_HOME directory.

Verify that your CLASSPATH variable is set for running the sample programs (see "Setting the CLASSPATH" for details) and enter the following text:
```
java sample2.SybSample Version
```
A SybSample window appears. At the top of the window, the Running Sybase Sample text box displays the source code for Version as the program runs. The middle text box (Sample Output) should display version information. For example:
```
Using JDBC  driver version 6.05
jConnect (TM) for JDBC(TM)/6.05...
```

Depending on the output, do one of the following:
- If the previous message appears in the Sample Output text box, you have successfully installed jConnect.
- If you get the previous message but the source code for Version does not appear in the Running Sybase Sample text box, and the Status text box at the bottom of the window shows a message like the following, you successfully installed jConnect but probably did not enter the command to run the Version program from the sample2 directory under JDBC_HOME:
```
java.io.FileNotFoundException: Version.java
```
- If the SybSample window does not appear and you get the following error message, check your CLASSPATH to verify that it is set correctly:
```
Can't find class sample2.SybSample 
```
- Using Windows, if the SybSample window does not come up, and you get one of the following error messages, make sure that your path includes the bin subdirectory of your JDK home directory:
```
"Name  specified is not recognized as an internal or external command" (Windows  NT)
```
```
"Bad command or file  name" (Windows 95)
```

When you have verified that your installation was successful, click Close to exit the SybSample window.

Verifying the jConnect version

The following describes how to check the exact build version of your jConnect installation.

Verifying the build version of the installation

Execute the following command; from your $JDBC_HOME/classes directory on UNIX or Linux, or from your %JDBC_HOME%\classes directory on Windows:
```
java -jar jconn3.jar
```

This command prints a version string like the following:

jConnect (TM) for JDBC(TM)/6.05(Build 25773/P/EBF12723/JDK14/Fri  Aug 5  0:05:43 2005

Here, the version number is 6.05. The 5-digit number following the letters "EBF" indicates the exact version of jConnect. This number increases as subsequent EBFs are released.

Sybase recommends that you check the Sybase download Web site periodically for updated versions of jConnect and download the latest version.