SOLID JDBC Driver 2.3 Readme

This document contains the installation instructions for the SOLID JDBC Driver product package.

Package Contents

The SOLID JDBC Driver product package is provided in three variants:

sj23win.zip
sj23unix.tar.gz
sj23unix.tar.Z

They all contain the following files:

System requirements

• SOLID Server release 02.30.0026
• Any Java runtime or development environment supporting JDBC API specification release 1.2, like JavaSoft's JDK 1.1 (final version) or compatible

Java code is platform independent by design, but because the technology is still new and developing dynamically, there may be compatibility problems between different development and execution environments. For a list of environments where SOLID JDBC Driver has been tested, please view the release notes.

Installation instructions

Before getting started with SOLID JDBC Driver, we recommend obtaining some basic knowledge about the following:

• The Java language
• Java environment issues, how to build Java applications
• Relational databases in general, SOLID Server in particular

SOLID JDBC Driver is installed as Java package solid.jdbc to your Java environment in the following way:

1. Make sure you have a working Java Virtual Machine environment.
   If not, you may locate one through the JavaSoft JDK 1.1 download pages.
   Install and test the environment according to its specific instructions.
2. Make sure that you have a working SOLID Server installation. If not, please download SOLID Server or SOLID Web Engine evaluation pack and install it according to the instructions in the package.
3. Uncompress the product package in a directory where you want to store the SOLID JDBC Driver. Uncompression command depends on the platform and the package variant :

   Platform, compression	Package uncompression instructions
   Windows	Unzip sj23win.zip using a tool that supports long filenames and select the option to restore subdirectory structures.
   UNIX, Gnu zip	gunzip sj23unix.tar.gz tar xf sj23unix.tar
   UNIX, compress	uncompress sj23unix.tar.Z tar xf sj23unix.tar

4. Check from your Java environment documentation whether it can use compressed bytecode. The SolidDriver.zip contains the SOLID JDBC Driver classes in compressed bytecode format usable by most Java Virtual Machines. However, some environments, like Microsoft J++, require uncompressed bytecode.
   
   4b) If your environment belongs to this group, please unzip the SolidDriver.zip using a tool that supports long filenames and select the option to restore subdirectory structures.. The result should be subdirectory solid\jdbc containg the classes of the JDBC driver. E.g. if you uncompress the SolidDriver.zip in directory c:\test, the class files should appear as c:\test\solid\jdbc\*.class.
5. Include SOLID JDBC Driver classes into the CLASSPATH definition used by your development/execution environment. CLASSPATH is the cornerstone of all Java environments, telling Java VM where to search for java classes.
   How to set the CLASSPATH definition varies in different Java products. Please check your Java environment documentation for details.
   
   5a) If compressed bytecode can be used, the full pathname including SolidDriver.zip is appended to CLASSPATH. E.g. When SolidDriver.zip is copied to directory c:\test, modify CLASSPATH with command:
   "set CLASSPATH=%CLASSPATH%; c:\test\SolidDriver.zip"
   
   5b) If compressed bytecode cannot be used, append to CLASSPATH the directory where subdirectory solid\jdbc is located. E.g. When SolidDriver.zip has been uncompressed in directory c:\test, modify CLASSPATH with command:
   "set CLASSPATH=%CLASSPATH%; c:\test"
   and Java package solid.jdbc class files will be searched by Java VM from directory c:\test\solid\jdbc .
6. Test your installation by running sample application sample1.java according to the instructions below.

Testing the installation with sample application

Description of the sample application

The sample application for validating the installation, sample1.java, performs the following actions:

1. Registers the SOLID JDBC Driver using JDBC Driver Manager services
2. Asks for the connect string for a running SOLID Server
3. Connects to SOLID Server using SOLID JDBC Driver
4. Creates a statement for one query,
   SELECT TABLE_CATALOG, TABLE_SCHEMA, TABLE_NAME, TABLE_TYPE FROM TABLES
   for reading data from one of SOLID Server's system tables.
5. Executes the query
6. Fetches all the rows of a result set. An empty SOLID Server database dictionary contains 24 rows.

Running the sample application

1. If you don't already have a SOLID Server running, start it now and create an empty database.
2. Start the sample application in subdirectory samples with command
   java sample1
3. The application prompts for a valid connect string. The connect string structure is:
   jdbc:solid://<host>:<port>/<user name>/<password>.
   For example, "jdbc:solid://mymachine:1313/dba/dba" attempts to connect to a SOLID Server in host mymachine listening to tcp/ip protocol at port 1313.
4. After entering the connect string, sample1 outputs the query results. You can check the output by comparing it to the expected output file.

Troubleshooting with the sample application

Possible problems in running sample1.java and solutions for them are listed in the following.

1. The driver can not be succesfully registered

• Java environment does not support java.sql classes.
• SolidDriver.zip not in the CLASSPATH definition.

2. Unable to connect to SOLID Server

• SOLID Server version should be 2.30.0026. Older SOLID Server versions may refuse connections from JDBC Driver.
• The connect string may be wrong or SOLID Server is not listening to tcp/ip. Check that SOLID Server is running and verify the listening information.Use SOLID Server administration utilities, like SOLID Remote Control, to ensure that that connection can be established through the network. Note that the connect string format elsewhere than in JDBC is "tcp <host> port".
• Make sure that the license used by SOLID Server enables JDBC connections. The file solid.lic file in the directory where SOLID Server is started should contain text "JDBC option" or "Options: ..., JDBC, ..."

3. Problems after the connection

• SOLID Server version should be 2.30.0026. JDBC Driver 2.3 may get connection to an older SOLID Server release and may appear to get some JDBC calls through. Generally, this combination does not work, however, and probably  leads to peculiar error situations.

Support

Please look for answers in SOLID JDBC Driver FAQ before contacting Solid.

Other SOLID JDBC Driver Documentation

• SOLID JDBC Driver Programmer's Guide
• SOLID JDBC Driver 2.3 Release Notes
• SOLID JDBC Driver FAQ
• More information provided by Javasoft on:
  • JDBC specification
  • 100% Pure Java certification
  • Java

Ordering instructions

The SOLID Server and SOLID Web Engine download packages contain an JDBC enabled evaluation license that allows using the database for 30 days. In order to continue using your database after that you can purchase a run-time license for SOLID Web Engine with JDBC Extension through Solid Express Sales.

Migration from Older SOLID JDBC Drivers

Migration from SOLID JDBC Driver 1.x to version 2.3 requires no other actions than replacing the JDBC Driver and SOLID Server binaries themselves.

Company | Products | Support | Search | Free Eval Packs
Copyright © 1992-1997 Solid Information Technology Ltd. All rights reserved.