Welcome to PrimeBase JDBC 4.5

Copyright © 2008, PrimeBase Systems GmbH. All rights reserved.



CONTENTS

1. Welcome to JDBC for PrimeBase

2. Getting Started

3. PrimeBase JDBC Overview

4. Description of Components & Installation

5. Using the JDBC NetServer for PBAS

6. JDK 1.1.x & 1.2.x Support

7. Loading the PrimeBase JDBC Driver

8. Connecting using PrimeBase JDBC

9. Connection Parameters

10. URL Examples

11. SQLExceptions thrown by PrimeBase JDBC
 


PRIMEBASE LICENSE AGREEMENT


Welcome to JDBC for PrimeBase

PrimeBase(tm) JDBC is an implementation of the Java Database Connectivity standard  for the PrimeBase DBMS. PrimeBase is a high-performance, relational DBMS (Database  Management System) for Mac OS, Windows 95/98/NT and UNIX (including Solaris, AIX, Linux (Intel) and Mac OS X) platforms. PrimeBase supports all common database  access standards, including SQL, ODBC, PHP, Perl, RealBasic, EOF Adaptor and DAL.

If you are currently developing or planning a database application in Java then consider using PrimeBase for your development work. All the software you need is available from our Web site and we offer developer licenses for free.

Just e-mail support@primebase.net and ask for a developer key. We will need to know the following details:

* A brief description of your project

* Estimated duration of the project

* The platform you plan to develop on

* Number of users/connections you need for development and testing

You can find out more about PrimeBase and other products from PrimeBase Systems GmbH by visiting our Web site at http://www.primebase.net.

Included in this package is the JDBC driver in source code form, as well as a simple test program. Other requirements for running an application using PrimeBase JDBC are described below.


Getting Started

This section explains how to run the test application using the PrimeBase JDBC type 2 driver. Using the type 3 driver is explained in the section "Using the JDBC NetServer for PBAS" below.

If your machine is running Mac OS X or some other UNIX system, then run the shell script 'Install_PrimeBase', as user 'root'.

The file 'pbjdbc.jar' contains the compiled PrimeBase JDBC driver. This file must be installed in a sub-folder called 'Extensions' in a folder belonging to the standard Java CLASSPATH. The Install_PrimeBase script should do this for you.

Follow these steps to run the test application:

STEP 1: Install a PrimeBase SQL Database Server


After installation the database server has the following setup:

DataServer Name: PrimeServer
User:            Administrator

By default the user 'Administrator' has no password.

Start the server after installation.

STEP 2: Create the global PrimeBase Setup directory


Windows:   Create a directory called 'PB-SETUP' in the
           Windows system directory.
Mac OS X:
UNIX:      The installer "Install_PrimeBase" will have done this.
           Go to STEP 5.

Macintosh: Create a folder called 'PrimeBase Setup' in the system
           'Preferences' folder.
 

STEP 3: Install the PrimeBase Virtual Machine


Windows:   Copy 'PBVM.DLL' to the Windows system directory.

Mac OS X:
UNIX:      The installer "Install_PrimeBase" will have done this.
           Go to STEP 5.

Macintosh: Copy 'PrimeBase VM Library' to the system
           'Extensions' folder.
 

STEP 4: Install the UNICODE conversion tables


NOTE: The UNICODE conversion tables are shipped with this package in the directory called 'setup'.

Mac OS X:
UNIX:      The installer "Install_PrimeBase" will have done this.
           Go to STEP 5.

Macintosh:
Windows:   Copy the directory 'unicode' and its contents to
           the global PrimeBase setup directory.

STEP 5: Setup the connection URL


Edit the file 'TestApp.java' in the 'source' directory. Select one of the lines beginning with "url = " depending on your platform (Mac OS 8/9, Windows or UNIX / Mac OS X).

You can do this by commenting out the lines containing "url = " for the other platforms.
 

STEP 6: Compile and run the test App


Windows:   The file 'run.bat' contains the commands that will
           compile and run the program from this directory.
           Execute the batch file 'run.bat' from this directory.
           In the batch file:
           javac - compiles the .java source code.
           jar - packs the compiled code into an archive
                 called testapp.jar
           java - runs the program

Mac OS X:
UNIX:      The file 'run.bat' contains the commands that will
           compile and run the program from this directory.
           Make the file executable as follows:
           chmod 777 run.bat
           Now you can execute the file as follows:
           run.bat

Macintosh: Use Metrowerks CodeWarrior Pro 3 or Pro 6 project to
           compile and run the test program.


PrimeBase JDBC Overview

PrimeBase JDBC implements both type 2 and type 3 JDBC technology drivers. These types of drivers are described as follows at http://java.sun.com/products/jdbc/drivers.html:

* Type 2 JDBC technology drivers:

A native-API partly Java technology-enabled driver converts JDBC calls into calls on the client API. This style of driver requires that some binary code be loaded on each client machine.

* Type 3 JDBC technology drivers:

A net-protocol fully Java technology-enabled driver which translates JDBC API calls into a DBMS-independent net protocol which is then translated to a DBMS protocol by a server. This net server middle-ware is able to connect all of its Java technology-based clients to many different databases. The specific protocol used depends on the vendor. In general, this is the most flexible JDBC API alternative. It is likely that all vendors of this solution will provide products suitable for Intranet use. In order for these products to also support Internet access they must handle the additional requirements for security, access through firewalls, etc., that the Web imposes.
 

The PrimeBase Implementations


The PrimeBase Virtual Machine (PBVM) provides a Java Native Interface (JNI) for the support of the type 2 implementation of PrimeBase JDBC. The PBVM is shipped as a single shared library, shared object or DLL, depending on the platform. The name of the library also depends on the platform:

  Macintosh - PrimeBase VM Library
  Windows - PBVM.DLL
  Unix - libpbvm.so

Before you can use the type 2 JDBC access you must install this library on the client machine. This is done by copying the library to the appropriate system location (see Description of Components & Installation below).

The PrimeBase type 3 implementation uses the PrimeBase Application Server (PBAS) as the "net server". The "net protocol" used to communicate with PBAS is tunneled through HTTP (the protocol used between Web browser and Web server) in order to enable easy access over the internet. The PrimeBase type 3 implementation is designed for maximum control from the server side. The net server controls who is allowed to connect, which database servers are accessed and exactly what operations may be performed.

In order to use PBAS as a JDBC net-server you need to install the "JDBC Module" for PBAS.
The same JDBC Driver code is used for both types of access:

* Type 2: To access PrimeBase using the JNI specify a PrimeBase SQL Database Server and the name of the PBVM Library in the "connect URL" (described in detail below).

* Type 3: To access PrimeBase SQL Database Server via the PrimeBase Application Server (acting as a net server), specify the URL of the PrimeBase application server (via Web server or direct).
 


Description of Components & Installation

Type 2 JDBC Implementation

To use the type 2 JDBC implementation you need ONE of the following components:

* For Java Applications running on the Macintosh:

PrimeBase VM Library 4.0 or later - This component is placed in the System Extensions folder. It allows you to access a PrimeBase server running locally or somewhere on your network. The library name (NativeLib option) to be used in the JDBC connect URL is 'SnapLib'. This is the Macintosh "code fragment name" of the PBVM.

As an alternative ot the standard PBVM library you can use the following:

PrimeBase DS Library 4.0 or later - This component is placed in the System Extensions folder. It allows your Java application to incorporate the functionality of a PrimeBase SQL Database Server (PBDS). To use the PBDS library, a valid PBDS "environment" (consisting of a 'Databases' and 'Setup' folder) as shipped with the PrimeBase SQL Database Server must be accessable by the Java application.  The library name (NativeLib option) to be used in the JDBC connect URL is 'SnapRTLib'. NOTE: A server environment currently in use by a PrimeBase SQL Database Server cannot be accessed by the PBDS library.

* For Java Applications running under Windows:

PBVM.DLL 4.0 or later - This is the Windows implementation of PrimeBase Virtual Machine. This component must be placed in the Windows System folder along with the other DLLs used by your PC. Just like the equivalent Mac component this library allows an application to access a PrimeBase SQL Database Server running locally or anywhere on the network. The library name to be used in the JDBC connect URL (NativeLib option) is 'PBVM'.

As an alternative ot the standard PBVM library you can use the following:

PBDS.DLL 4.0 or later - This is the Windows equivalent of the 'PrimeBase DS Library' for Macintosh. This component must be placed in the Windows System folder along with other DLLs used by your PC. A valid server environment under Windows consists of a DATABASE and SETUP folder as shipped with the PrimeBase SQL Database Server for Windows. The library name to be used in the JDBC connect URL (NativeLib option) is 'PBDS'.

* For Java Applications running under UNIX:

libpbvm.so 4.0 or later - This is a UNIX shared library that implements the PrimeBase Virtual Machine. The installation of this library for JNI access is system dependent.

On 'Mac OS X' the library must be given the extension '.jnilib', and placed in the directory:

/usr/lib/java/

On 'Mac OS X Server' the library must be named 'libpbvm.A.dylib' and placed in the directory:

/System/Library/Frameworks/JavaVM.framework/libraries/

For all other UNIX systems the PBVM library must be in the standard search path. We recommend placing the libary in the directory /usr/local/primebase/bin, and placing this directory in your search path.
 

Type 3 JDBC Implementation

To use the type 3 JDBC implementation you need the following components:

* PrimeBase Application Server 4.0 (build #4013) or later - Install and start the PrimeBase Application Server so that the Java application has access to the application server directly (over the built-in HTTP port), or via a Web server.

* JDBC NetServer Module for PBAS Issue #3 - This module implements the server-side of the JDBC access. A .stream page within this module is "requested" by the JDBC driver in order to access the PrimeBase SQL Database Server. Data is returned to the JDBC driver in the form of an "item stream". Request and reply messages are embedded in HTTP post and HTTP reply messages respectively.

How to install and use the JDBC NetServer is explained in the section "Using the JDBC NetServer for PBAS" below.
 
 


Using the JDBC NetServer for PBAS

This section explains how to run the test application using the PrimeBase JDBC type 3 driver. This driver does not require that a native library (PBVM) on the client machine.

To run the test application:

STEP 1: Install a PrimeBase SQL Database Server

After installation the database server has the following setup:

DataServer Name: PrimeServer
User:            Administrator

By default the user 'Administrator' has no password.

Start the server after installation.

STEP 2: Install a PrimeBase Application Server

Download and install PBAS. The JDBC NetServer requires at least version 4.0.13 (build #4013).

After installation the application server has the following setup:

HTTP Port:  47120
Administrator:  admin
Password:       admin
 

STEP 3: Install the JDBC NetServer module

Copy the directory 'jdbc' in the 'docs' folder in this directory to the 'docs' folder of the application server.

Start the application server.
 

STEP 4: Enable the JDBC NetServer

Start a browser, and connect to the application server. By default the URL is:

http://localhost:47120/system/

If the application server is not running on the local machine, then replace 'localhost' with the host name or IP address of the machine on which the application server is running.

Once connected, login to the application server as administrator, and select the JDNC NetServer item from the menu.

Set the status to enabled. In order to run the test program you will also need to set security to "Permit Any Statement".

Now press the "Save Settings" button.
 

STEP 5: Setup the connection URL

To connect to the application server from a Java program, set the URL to refer to the application server, and retrieve the page 'jdbc/service.stream'.

Edit the file 'TestApp.java' in the 'source' directory. Select the first line beginning with "url = ". This line reads as follows:

  url = "jdbc:jdal://127.0.0.1:47120/jdbc/service.stream";

You can select this line by commenting out the other lines containing "url = ".

Relace the IP address '127.0.0.1' with the host name or IP address of the machine on which the application server is running if the application server is not running on the local machine.
 

STEP 6: Compile and run the test App

Compile and run the test program as explained in the section "Getting Started".
 
 


JDK 1.1.x & 1.2.x Support

JDK 1.1.x is no longer supported by PrimeBase JDBC. This version requires JDK 1.2.x compliant tools.

JDBC 2.x methods not supported throw an SQLException with the following attributes when being called:

* Error code set to 1 (constant value of jDALException.ERROR_METHOD_NOT_IMPLEMENTED, retrieve with SQLException.getErrorCode()),

* SQL state set to "" (retrieve with SQLException.getSQLState()), and

* Message set to "<class_name>.<method_name>():" + " Method not implemented." (retrieve with SQLException.getMessage())


 


Loading the PrimeBase JDBC Driver

The PrimeBase JDBC driver is located in the following package: com.primebase.jdbc

In order to make the driver currently located in the "com/primebase/jdbc" directory accessible, use something similar to the following in your application:

  try
  {
    Class.forName( "com.primebase.jdbc.jDALDriver" );
  }
  catch ( Exception e )
  {
    // Add some more thorough exception handling perhaps.
    e.printStackTrace();
  }

The PrimeBase JDBC package directory or a JAR file containing this directory has to be accessible by Java according to the usual Java setup and configuration mechanisms.

That is, either...

* have the "com" directory reside in the working directory of the Java application, or

* have a JAR file containing the "com.primebase.jdbc" package in a sub-folder called 'Extensions' in a folder included in the Java system CLASSPATH.
 


Connecting using PrimeBase JDBC

To obtain a connection with the PrimeBase JDBC driver you call the driver manager method DriverManager.getConnection(). This method takes 3 arguments: URL, user name and password.

The user name and password must specify a valid user of the PrimeBase SQL Database Server. NOTE: A user name must be specified or a connection will not be made to the server. If the user name or password are invalid then you will be able to connect to the server, but will not be able to open a database. The PrimeBase SQL Database Server is pre-installed with one user called 'Administrator' with no password.

NOTE: Some examples of URLs are given in the section '8. URL Examples' later in this document.

In general, the PrimeBase JDBC URL used to make a connection has the following form:

<URL> ::= 'jdbc:jdal:' [ '//' <server> [ '/' <page> ] ] { ';' <parameter> }
---------------------------------------------------------------------------

Components in single quotes are meant literally, components in [ and ] are optional, and components in { and } can be repeated zero or any number of times.

In other words, a <URL> is 'jdbc:jdal:' followed by an optional server and page specification, followed by any number of parameters delimited by a ';'.

<server> ::= <host> [ ':' <port> ]
----------------------------------

This <server> specification is a host address followed by an optional port specification.

When connecting using the type 3 implementation, <server> must refer to the PrimeBase Application Server. In this case, the connection "alias" you specify (see Connection Parameters below) determines which PrimeBase SQL Database Server is then connected to by PBAS. When connecting using the JDBC native (type 2) implementation, the server address refers directly to a PrimeBase SQL Database Server.

The host address is the host name or IP address of the machine on which the server (PrimeBase SQL Database Server or PBAS) is running. You may use the IP address 127.0.0.1 (or 'localhost') to refer to a server running locally.

<port> is a port number or may also be the name of the server (in the case of type 2 implementation only).

For example, by default a PrimeBase SQL Database Server has the name 'PrimeServer' and accepts connections on port 50435, and by default the PrimeBase Application Server will accept connections on port 47120. If you are accessing PBAS via a Web server then port 80 is generally used.

You can determine the name and port of a PrimeBase SQL Database Server by logging in at the console an entering '#status' followed by RETURN. The port number used by PBAS is displayed in the status window when PBAS starts up.

<page>
------

<page> is an optional component which may be specified in addition to <server>.

This component is required when using the type 3 JDBC implementation. It refers to the page requested from PBAS. By default you should request the page 'jdbc/service.stream'.

When using the type 2 native implementation you generally should not specify a page, unless you wish to change the default implementation already provided by the native library.

<parameter> ::= <name> '=' <value>
----------------------------------

A <parameter> is a name/value pair. Parameters specify additional information for the purpose of making a connection. One of the most important parameters is 'NativeLib' which specifies whether to use the type 2 or type 3 JDBC implementation.

All parameters are described in the section below.


Connection Parameters

The following is a list of parameters which you can use in connection URLs.

NOTE: Parameter names are case-insensitive.

* NativeLib

This parameter specifies the name (or internal name) of the PBVM library that is to be used for (type 2) native access to the PrimeBase SQL Database Server. In the case of the Mac, this would be 'SnapLib' or 'SnapRTLib'. Under Windows use 'PBVM.DLL' or 'PBDS.DLLs'. UNIX platforms should specify 'pbvm' or 'pbds'.

NOTE: If this parameter is NOT specified, then the JDBC driver will use the type 3 access.

* Password

This is a password which is only required when accessing PrimeBase using the type 3 JDBC implementation. It is the password that allows access to PBAS (which provides the net server services for the type 3 JDBC driver). This password is required in addition to the user name and password required to connect to the PrimeBase SQL Database Server itself.

* ConnectOptions

Connection options are components of a connection definition which specify various information required to connect to a server.

NOTE: You need not specify connection options if you are using type 2 access to connect to a PrimeBase SQL Database Server via TCP/IP. In this case, you may specify the server to be access directly in the URL, for example:

  jdbc:jdal://127.0.0.1:PrimeServer

If you are using type 3 access, or you wish to connect to the server using a protocol different to TCP/IP, then you can do this by specifying the connection parameters as options, or be specifying a connection alias (see below).

The options you may need when making a JDBC connection are listed below:

\p - Protocol: This is the protocol to be used to connect to the server:

   ipc - This indicates that communication with the server should be done using "shared memory". The server must be on the same machine as the Java application. Using shared memory may be necessary, for example, if the database administrator has disabled TCP/IP communication on the server for security reasons.

   adsp - The Macintosh AppleTalk protocol.

   mem - The Internal protocol. This protocl must be used when using the type 2 implementation to access the PBDS library.

\n - Server Name: Use this option to specify the server name or port number of the PrimeBase SQL Database Server (the default server name is PrimeServer).

\z - Zone Name: Use this options to specify the server zone when connecting using AppleTalk.

\rd - Runtime Directory: If you are using the PBDS library, then use this option to specify the location of the server environment (Databases and Setup folders). The path should be specified with a ':' as delimiter on the Macintosh and a '/' as delimiter currently under both Windows or UNIX.

NOTE: Although '\' is usually used as a delimiter under Windows this will not work because the '\' character will be interpreted as a beginning of new option.

* ConnectionAlias

This parameter is generally only required when accessing the PrimeBase SQL Database Server using the type 3 JDBC implementation. The connection alias refers to a particular connection definition stored in the application server's 'connect.def' file.

* DatabaseName

This is the name of the database to be opened when making a connection. If no database is specified, there are 2 possibilities:

- When making a type 2 connection then it is possible to submit an OPEN DATABASE statement at some later stage using the java.sql.Statement.execute() or java.sql.Statement.executeUpdate() methods.

- When using the type 3 driver, it is possible that a database is automatically opened by the PrimeBase Application Server, as specified in the connection definition.

* ItemsPerPage

This parameter specifies the name of items returned per page request. The default is 1200 items. Settings this parameter lower decreases the initial response time of a SELECT statement when using the type 3 driver.

* AutoCloseCursor

By default this parameter is 'true'. When set to 'true' this parameter causes the network server (or client library on native access) to close the cursor as soon as all data has been retrieved from a select. If you wish to use UPDATE or DELETE WHERE CURRENT OF, then set this parameter to 'false'.

* UseUnicode

By default this parameter is set to 'true'. When set to 'true', all strings are transported to and from the JDBC driver in UNICODE format. This means any conversion to 8-bit characters is done by the PrimeBase system. If set to 'false', strings are transported in 8-bit format. Conversion to and from UNICODE will be done by the JDBC driver.

* KeepAlive

By default this parameter is set to 'true'. When set to 'true', the connection to the JDBC NetServer is held open. We 'false' the connection is closed after the completion of each request.


URL Examples

* jdbc:jdal://localhost:47120/jdbc/service.stream;ConnectionAlias=local_server;Password=snap;ItemsPerPage=200

This URL specifies a type 3 connection to a PrimeBase Application Server running on the local machine using the default port number. The page requested is 'jdbc/service.stream'. It also specifies that PBAS should open a connection using the connection alias 'local_server' and transfer data at a maximum of 200 items per page. The password to access PBAS as a net server is 'snap'.

* jdbc:jdal://127.0.0.1:PrimeServer;DatabaseName=JDBCTypeTest;NativeLib=PBVM

This URL is used to connect directly to a PrimeBase SQL Database Server using the type 2 JDBC driver. It specifies that the server is running localy (IP address 127.0.0.1), and that the name of the server is 'PrimeServer'. The database called 'JDBCTypeTest' will be opened. The Java application is running on a Windows machine and uses the PBVM.DLL (PrimeBase Virtual Machine) to access the server.

* jdbc:jdal:;DatabaseName=JDBCTypeTest;ConnectOptions=\\pmem\\rdSNAP:demo:PrimeBase Server;NativeLib=SnapRTLib

This URL is used to link the Macintosh PBDS library, SnapRTLib (file name: 'PrimeBase DS Library'), directly to a Java application or applet. No host specification is necessary. The database to be opened when the connection is made is 'JDBCTypeTest'.

NOTE: The backslash characters are doubled in order to override the special meaning of the backslash character in Java Strings!

A number of connection options are specified:

- '\pmem' is required and indicates that the internal (runtime) memory protocol is to be used.

- The \rd option specifies the location of the server environment for the runtime library.

NOTE: If no location is specified then the current working directory is used.


SQLExceptions thrown by PrimeBase JDBC

Since the PrimeBase Client/Server RDBMS returns more than a single error code, SQLExceptions may be chained to each other to return each error code separately.

Up to three SQLExceptions might be chained to each other in PrimeBase JDBC.

Use the SQLException.getNextException() method to retrieve further SQLExceptions in case you want to evaluate the PrimeBase Client/Server RDBMS specific errors that might occur.
 

There are two different occasions where SQLExceptions can be thrown:

1) When the PrimeBase Virtual Machine or the PrimeBase Client/Server RDBMS signal any errors

2) When PrimeBase JDBC encounters any errors (I/O errors, network related errors, invalid parameters specified, etc.)
 
 

When SQLExceptions result from 1)...

* the first exception is of class type jDALException (which extends SQLException)

* this first SQLException contains the primary error code reported by the PrimeBase RDBMS (retrieve with SQLException.getErrorCode())

* this first SQLException contains the errorstring reported (retrieve with SQLException.getMessage())

* second and third exception (if present) are always of type SQLException

* the second exception contains the secondary error code (retrieve with SQLException.getErrorCode())

* the second exception contains an additional string (called "itm1" in the Call Level API of PrimeBase) (retrieve with SQLException.getMessage())

* the third exception (if present at all) contains another additional string (called "itm2" in the Call Level API of PrimeBase) (retrieve with SQLException.getMessage())
 

When SQLExceptions result from 2)...

* each exception is of type SQLException

* the error code in the SQLException is set. A list of possible error codes can be found in jDALException.java