Pervasive PSQL v9 JDBC - May 2006

This document contains the following topics:

About the Pervasive JDBC Driver
Features
System Requirements
Getting Started
Known Issues
Useful Links
Disclaimer

About the Pervasive JDBC Driver

The Pervasive PSQL v9 JDBC driver is a Type 4, 100% Pure Java^TM certified client driver. The driver supports the JDBC^TM 2.0 standard. As it is a certified 100% Pure Java^TM driver, it will work on all platforms that support the JVM.

Pervasive PSQL v9 JDBC driver is a thin client that does the bare minimum amount of processing and relies on the server for the core processing logic like syntax analysis, query processing etc. Communication to the Pervasive SQL Server is via the server's native LNA network protocol.

Additional information on JDBC is available on the Javasoft JDBC web page: http://java.sun.com/products/jdbc

The JDBC driver for Pervasive PSQL is shipped with the Pervasive PSQL engine. This Pervasive PSQL SDK release adds the following JDBC resources:

JDBC samples
JDBC documentation
Files relating to redistributing JDBC driver with your application

Features

Supports thread safe operation.
Supports transactions isolation levels provided by the Pervasive PSQL server engine: READ_COMMITTED and SERIALIZIBLE.
Performs result set caching to reduce network access.
Supports long text data through the LONGVARCHAR datatype ( 2 GB limit ).
Supports huge binary data through the LONGVARBINARY datatype ( 2 GB limit ).
Supports stored procedures with parameters.

System Requirements

Windows: Java Development Kit version 1.5 or greater
Linux: Java Development Kit version 1.5 or greater
The CLASSPATH environment variable should be modified to include complete path to the pvjdbc2.jar file including the file name.
Pervasive PSQL v9 engine installed with TCP/IP support. The driver will not work with previous versions of Btrieve, Scalable SQL, or Pervasive.SQL.

Getting Started

Installation

The JDBC driver is shipped with the Pervasive PSQL engine. This release installs samples and documentation for the driver. See the following JDBC section of the Developer Center for more information: http://www.pervasive.com/developerzone/access_methods/jdbc.asp

Components Updated

The following components are in the bin directory. These files need to be included in the the bin directory of your Pervasive PSQL engine. For example, assuming a default installation, c:\pvsw\bin on Windows and /usr/local/psql/bin on Linux.

Component
pvjdbc2.dll
pvjdbc2.jar
pvjdbc2x.jar
jpscs.jar

Setting the CLASSPATH

So that Java applications and applets recognize the Pervasive PSQL JDBC Driver, set your CLASSPATH environment variable to include the pvjdbc2.jar, pvjdbc2x.jar, and jpscs.jar files.

From Windows:

set CLASSPATH=%CLASSPATH%;<path to pvjdbc2.jar directory>
     /pvjdbc2.jar

set CLASSPATH=%CLASSPATH%;<path to pvjdbc2x.jar directory>
     /pvjdbc2x.jar

set CLASSPATH=%CLASSPATH%;<path to jpscs.jar directory>
     /jpscs.jar

From Linux:

export CLASSPATH=$CLASSPATH:<path to pvjdbc2.jar directory>
     /pvjdbc2.jar

export CLASSPATH=$CLASSPATH:<path to pvjdbc2x.jar directory>
     /pvjdbc2x.jar

export CLASSPATH=$CLASSPATH:<path to jpscs.jar directory>
     /jpscs.jar

Setting the SYSTEM PATH

Windows Only. Typically, the system path is properly set at installation. However, under certain circumstances it might be necessary to set it directly.

From Windows:

set PATH=%PATH%;<path to pvjdbc2.jar directory>
     /pvjdbc2.dll

Loading the Pervasive JDBC Driver into the Java Environment

After setting the CLASSPATH, you can now reference the Pervasive JDBC Driver from your Java application. You do this by using the java.lang.Class class:

Class.forName("com.pervasive.jdbc.v2.Driver");

Specifying a Data Source

After loading the PervasiveDriver class into your Java environment, you need to pass a URL-style string to the java.sql.DriverManager class to connect to a Pervasive PSQL database. The syntax for URL for the Pervasive JDBC driver is:

jdbc:pervasive://<machinename>:<portnumber>/<datasource>

<machinename>	is the host name or IP address of the machine that runs the Pervasive DB Server
<portnumber>	is the port on which the Pervasive DB Server is listening – by default it is 1583
<datasource>	is the name of the ODBC DSN on the Pervasive database server that the application intends to use.

For example, if your Pervasive PSQL engine is on a machine named DBSERV, and you wish to connect to the DEMODATA database, your URL would look like this (assuming the server is configured to use the default port):

jdbc:pervasive://DBSERV/DEMODATA

So to connect to the database using the DriverManager class, you would use the syntax:

Connection conn =
          DriverManager.getConnection("jdbc:pervasive://DBSERV:1583/DEMODATA",
          loginString, passwordString);

...where "loginString" is the string that represents a user login and "passwordString" is the string that represents a user password.

Note: The Pervasive PSQL engine must be running on the specified host in order for JDBC applets and applications to access data.

Developing JDBC Applets

To develop web based applications using JDBC, you need to place the JDBC jar file in the codebase directory containing the applet classes.

For example, if you are developing an application called MyFirstJDBCapplet, you need to place the pvjdbc2.jar file in the directory containing the MyFirstJDBCapplet class. For example, it might be C:\inetpub\wwwroot\myjdbc\.

This enables the client web browser to be able to download the JDBC driver over the network and connect to the database.

You also need to put the archive parameter within the <APPLET> tag. For example:

<applet CODE="MyFirstJDBCapplet.class"
        ARCHIVE="pvjdbc2.jar" WIDTH=641 HEIGHT=554>

Note: The Pervasive PSQL v9 engine must be running on the web server that hosts the applet.

Known Issues in this Release

The following are known issues with this release.

Issue Number	Description
n/a	n/a

Useful Links

Discuss all your Pervasive development issues at DevTalk at http://www.pervasive.com/devtalk.

See some creative applications and code snippets and share your own at Pervasive ComponentZone at http://www.pervasive.com/componentzone.

Disclaimer

PERVASIVE SOFTWARE INC. LICENSES THE SOFTWARE AND DOCUMENTATION PRODUCT TO YOU OR YOUR COMPANY SOLELY ON AN "AS IS" BASIS AND SOLELY IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE ACCOMPANYING LICENSE AGREEMENT.
PERVASIVE SOFTWARE INC. MAKES NO OTHER WARRANTIES WHATSOEVER, EITHER EXPRESS OR IMPLIED, REGARDING THE SOFTWARE OR THE CONTENT OF THE DOCUMENTATION; PERVASIVE SOFTWARE INC. HEREBY EXPRESSLY STATES AND YOU OR YOUR COMPANY ACKNOWLEDGES THAT PERVASIVE SOFTWARE INC. DOES NOT MAKE ANY WARRANTIES, INCLUDING, FOR EXAMPLE, WITH RESPECT TO MERCHANTABILITY, TITLE, OR FITNESS FOR ANY PARTICULAR PURPOSE OR ARISING FROM COURSE OF DEALING OR USAGE OF TRADE, AMONG OTHERS.