SESAM-DBAccess (JDBC) Driver V6.0A

Contents

Introduction.

New Features.

Getting Started. How to install the JDBC driver.

Establishing a Connection with DriverManager. Loading the driver and

connecting to the database.

Establishing a Connection with DataSource. Connecting to the database by using

the DataSource interface.

Connection Pooling. Connecting faster by using Connection Pooling.

Using Statements. Creating and executing statements.

RowSets. Using WebRowSets

Extensions. Features of this driver extending JDBC.

Restrictions. JDBC features not supported.

Applets. How to make applets with the JDBC driver.

Troubleshooting.

References. Further informations on JDBC.

This software is © Copyright 2009 Fujitsu Technology Solutions GmbH. All Rights

Reserved.

Introduction

The SESAM-DBAccess (JDBC) driver V6.0A can be used for any operating system which

provides a Java Virtual Machine (for example Windows XP, LINUX, BS2000/OSD etc). It

enables Java applications or Java applets to access SESAM/SQL databases using JDBC.

The SESAM-DBAccess (JDBC) driver is a type 4 driver that uses Java sockets to connect

directly to the server component SESAM-DBAccess (JDBC) of the SESAM/SQL server.

Because it is entirely written in Java, this driver is plattform-independent.

There is a short description of the DataSource interface, which is available since version

V4.0A.

In this document you will find a brief description on how to install the SESAM-DBAccess

(JDBC) driver, how to connect to a SESAM/SQL database using the SESAM-DBAccess

(JDBC) driver and how to retrieve data from or update data in a SESAM/SQL database.

You will find a detailed description of the JDBC interfaces in the JDBC specifications ( see

chapter "References" ).

New Features

The SESAM-DBAccess (JDBC) driver V6.0A now supports the JDBC 4.0

feature WebRowSet; see RowSets.

Also some missing features of JDBC 3.0 are available now, especially the option to use

statement pooling; see Connection Pooling.

Getting Started

Distribution files

Installing JDBC driver from CD

You will find the SESAM-DBAccess (JDBC) driver in the subdirectory

\DBACCESS\JDBC_060\CLIENT\LIB of the CD SES\SQL-SE V6.0A. The driver class

files are stored in the dbaccess.jar file.

Installing downloaded JDBC driver

All driver class files are shipped in one dbaccess.jar file.

Requirements

The SESAM-DBAccess (JDBC) driver requires the following prerequesites:

a JRE 1.6 (or higher) compliant Java Virtual Machine (including JDBC 4.0),

the server component SESAM-DBAccess(JDBC) V6.0A.

The following paragraph contains informations how to install these components on the

supported platforms.

Installation instructions

Before you can use the SESAM-DBAccess (JDBC) driver in a Java application, you have to

perform the following steps:

1. Make sure that a Java Virtual Machine is installed. As of SESAM-DBAccess

(JDBC) driver, Java version 1.4 or higher is required.

On Windows

You can get Sun's Java Virtual Machine for free from: http://www.javasoft.com

To install the Java Virtual Machine start the installation program and follow the

installation instructions on the screen.

On UNIX / BS2000/OSD

If the Java Virtual Machine has not been installed, please ask your system

administrator for installation.

2. Make sure that the server component is available. To access SESAM/SQL

databases, the server component SESAM-DBAccess (JDBC) must have been

installed. If this component has not been installed, please ask your SESAM/SQL

administrator for installation.

3. Set your CLASSPATH environment variable in order to include the classes of the

SESAM-DBAccess (JDBC) driver. To do this:

On Windows

set CLASSPATH=<path>\dbaccess.jar

On UNIX / BS2000/OSD

CLASSPATH=<path>/dbaccess.jar

export CLASSPATH

Where <path> should be substituted with the absolute path of the directory in which

you put the SESAM-DBAccess (JDBC) driver.

Establishing a connection via DriverManager

Loading and registering the JDBC driver

The first step in using the JDBC driver is to load the driver

com.fujitsu.ts.sesam.dbaccess.SesamDriver into the Java interpreter with one of the

following methods:

First of all you can call the method Class.forName() to load the driver:

Class.forName( "com.fujitsu.ts.sesam.dbaccess.SesamDriver" );

Although this is the preferred method to load the driver, there are two further methods

to load the driver:

Driver sesamdriver = new com.fujitsu.ts.sesam.dbaccess.SesamDriver();

Driver sesamdriver = Class.forName(

"com.fujitsu.ts.sesam.dbaccess.SesamDriver" ).newInstance();

The benefit of these alternative methods is, that you have a Driver object which

allows you direct access to the Driver methods.

A fourth method of loading the driver is to add the driver to the system property:

java -Djdbc.drivers=com.fujitsu.ts.sesam.dbaccess.SesamDriver jdbcapp

No matter which method you choose to load the driver, the driver will register itself by the

DriverManager.

Connection parameters

When the driver is loaded, you can establish a connection to a SESAM/SQL database by

using one of the following methods:

DriverManager.getConnection( String url, String user, String password )

DriverManager.getConnection( String url, java.util.Properties info )

DriverManager.getConnection( String url )

Each of these methods enables you to create a connection to the database. You can use the

third method only if authentication has been disabled by the server component SESAM-

DBAccess(JDBC). The parameters of these methods are described in the following:

Parameter Meaning

url The parameter url provides necessary information that a connection

request needs to access a database.

The parameter url must have the following structure:

jdbc:<subprotocol>:<subname>

with:

<subprotocol> ::= name of subprotocol, value: sesam

<subname> ::= the subname identifies server and database

The parameter subname must have the following structure:

//<hostname>[:<port>][/<database>]

with:

<hostname> ::= name or IP address of server host

<port> ::= port number of server application (optional)

<database> ::= <catalogname>[.<schemaname>] (optional)

<catalogname> ::= catalogname of SESAM/SQL database (optional)

<schemaname> ::= schemaname of SESAM/SQL database (optional)

Note: If the parameter subname does not contain a database name, you

will get as default catalog and schema the default values set by the server.

If the parameter port is not specified, the default value 2112 is used.

Example: jdbc:sesam://myhost:2112/mycatalog.myschema

user username, has to be registered at the SESAM-DBAccess (JDBC) server

and the SESAM/SQL database

password password, has to be registered at the SESAM-DBAccess (JDBC) server

info the parameters user and password can be handed over alternately as

properties.

Note: User and password are only optional, if server authentication has

been disabled.

Connection samples

The following are code examples for establishing a connection to a SESAM/SQL database

using the SESAM-DBAccess (JDBC) driver.

Definition of url:

String url = "jdbc:sesam://myhost:3112/mycatalog.myschema";

Example 1: Class.forName( "com.fujitsu.ts.sesam.dbaccess.SesamDriver" );

DriverManager.getConnection( url, "myuserid", "mypasswd" );

After loading the driver with Class.forName() the connection is

established with the method getConnection() of the DriverManager

interface. This form of method getConnection() allows you to set the user

and password but no further properties.

Example 2: Class.forName( "com.fujitsu.ts.sesam.dbaccess.SesamDriver" );

Properties info = new Properties();

info.put( "user", "myuser" );

info.put( "password", "mypwd" );

info.put( "prefetch", "20" );

DriverManager.getConnection( url, info );

This form of method getConnection() allows you to set other properties,

for example to set the prefetch size property "prefetch".

Example 3: Class.forName( "com.fujitsu.ts.sesam.dbaccess.SesamDriver" );

DriverManager.getConnection( url );

This form of the method getConnection() is only supported, if

authentication has been disabled by the server component SESAM-

DBAccess(JDBC).

Establishing a connection via DataSource

Another method to get a connection to a SESAM/SQL database is provided by the interface

DataSource.

The first step is to instantiate an object of class DataSource:

SesamDataSource sds = new

com.fujitsu.ts.sesam.dbaccess.SesamDataSource(

serverName,

portNumber,

databaseName,

databaseSchema,

description,

user,

password

);

DataSource ds = (DataSource) sds;

(Description of constructors and parameters see Connection Pooling.)

Then a connection can be created by:

Connection mycon = ds.getConnection();

(For compilation of your application you have to provide the SESAM-DBAccess driver in

the classpath; otherwise the class name com.fujitsu.ts.sesam.dbaccess.SesamDataSource

could not be resolved.)

This connection can be used as any connection which is created by using the DriverManager

class (see above).

If you want to use another JDBC driver, then you have only to change the definition of the

DataSource object; all other parts of the applications remain unchanged.

In a 3tier architecture like (Application - ApplicationServer - Database) or (Browser -

WebServer(ServletEngine) - Database) the DataSource object will be created by the

ApplicationServer or the init method of servlets and then provided using the JNDI interface.

In a simple 2tier application one can generate the DataSource object during initialization and

then provide it for example by using a Singleton class.

Connection Pooling

When using the DataSource interface with SESAM/SQL you have the option to use

Connection Pooling. Creating a connection is an expensive operation (in terms of resources);

to reduce this resource consumption, there is the ConnectionPooling functionality: When a

connection is closed, it will not be closed really. Instead of, it is stored into a pool of

connections and can be restored when a new connection is required.This function is

completly transparent, that means the application doesn't know whether there is connection

pooling or not (except it should notice better performance).

For using ConnectionPooling, you have to generate the DataSource object as follows:

Create a ConnectionPoolDataSource object:

com.fujitsu.ts.sesam.dbaccess.SesamCon

nectionPoolDataSource

scpds = new

com.fujitsu.ts.sesam.dbaccess.SesamConn

ectionPoolDataSource(

serverName,

portNumber,

databaseName,

databaseSchema,

description,

user,

password

);

scpds.setInitialPoolSize(3); // the figure 3 is an example

scpds.setMaxPoolSize(10); // the figure 10 is an example

scpds.setWaitIfBusy(true);

// If you want to use statement pooling, you could additionally specify the

following statement

// to create a connection specific statement pool for a maximum of n statements:

scpds.setMaxStatements(n); // n should be replaced by an integer > 0

// (Statement Pooling is a feature for performance improvement when using

prepared statements.

// With statement pooling, prepared statements are cached in a so called statement

pool.

// Please see JDBC 3.0 documentation.)

ConnectionPoolDataSource cpds = (ConnectionPoolDataSource) scpds;

Now you can create a DataSource object:

com.fujitsu.ts.sesam.dbaccess.SesamDataSource sds = new

com.fujitsu.ts.sesam.dbaccess.SesamDataSource(cpds);

DataSource ds = (DataSource) sds;

(Please note that you should set the properties serverName, portNumber etc. for the

SesamConnectionPoolDataSource object (using the constructor or the corresponding

setter methods) instead of for the SesamDataSource object.)

This DataSource object can be used as usual; the connections generated by this DataSource

will be automatically handled with ConnectionPooling.

The connections of a DataSource with ConnectionPooling are automatically closed when the

creating application or servlet is finished. If you want to close the connections of a

ConnectionPool explicitly, you can use the (non JDBC standard !) method

closeAllConnections of a SesamDataSource:

// DataSource ds = ... (see above)

SesamDataSource sds = (SesamDataSource)ds;

sds.closeAllConnections();

This method closes all connections of the ConnectionPool which are currently not busy; if

there are busy connections in the pool, an SQLException is thrown after the non-busy

connections of the pool are closed. Calling this method for a DataSource without

ConnectionPooling is allowed (no action done in that case).

Constructors for SesamDataSource

(parameter and property description see below)

SesamDataSource();

(properties must be set with set methods)

SesamDataSource(

ConnectionPoolDataSource

connectionPoolDataSource

);

(constructor for DataSource with ConnectionPooling)

SesamDataSource(

String serverName,

int portNumber,

String databaseName,

String databaseSchema,

String description

);

(constructor with DataSource properties; without user and

password)

SesamDataSource(

String serverName,

int portNumber,

String databaseName,

String databaseSchema,

String description,

String user,

String password

);

(constructor with DataSource properties; with user and

password)

Setter and Getter for SesamDataSource properties

void setServerName(String serverName)

String getServerName()

void setPortNumber(int portNumber)

int getPortNumber()

void setDatabaseName(String databaseName)

String getDatabaseName()

void setDatabaseSchema(String databaseSchema)

String getDatabaseSchema()

void setUser(String user)

String getUser()

void setPassword(String password)

String getPassword()

void setDescription(String description)

String getDescription()

void setConnectionPoolDataSource(ConnectionPoolDataSource

connectionPoolDataSource)

ConnectionPoolDataSource getConnectionPoolDataSource()

Constructors for SesamConnectionPoolDataSource

(parameter and property description see below)

SesamConnectionPoolDataSource();

(properties must be set with set methods)

SesamConnectionPoolDataSource(

String serverName,

int portNumber,

String databaseName,

String databaseSchema,

String description

);

(constructor with DataSource properties; without user and

password)

SesamConnectionPoolDataSource(

String serverName,

int portNumber,

String databaseName,

String databaseSchema,

String description,

String user,

String password

);

(constructor with DataSource properties; with user and

password)

Setter and Getter for SesamConnectionPoolDataSource properties

void setServerName(String serverName)

String getServerName()

void setPortNumber(int portNumber)

int getPortNumber()

void setDatabaseName(String databaseName)

String getDatabaseName()

void setDatabaseSchema(String databaseSchema)

String getDatabaseSchema()

void setUser(String user)

String getUser()

void setPassword(String password)

String getPassword()

void setDescription(String description)

String getDescription()

void setInitialPoolSize(int initialPoolSize)

int getInitialPoolSize()

void setMaxPoolSize(int maxPoolSize)

int getMaxPoolSize()

void setWaitIfBusy(boolean waitIfBusy)

boolean getWaitIfBusy()

void setMaxStatements(int maxStatements)

int getMaxStatements()

Parameter and property description

serverName see <hostname> in Connection parameters

portNumber see <port> in Connection parameters

databaseName see <catalogname> in Connection parameters

databaseSchema see <schemaname> in Connection parameters

user see user in Connection parameters

password see password in Connection parameters

description description of the DataSource

connectionPoolDataSource underlying ConnectionPoolDataSource object

initialPoolSize number of Connections which will be created when

initializing the ConnectionPool

maxPoolSize maximum number of connections allowed in the pool

waitIfBusy controls behaviour when maximum number of

connections is reached and a new connection is requested:

true: wait until a connection gets free

false: do not wait, raise SQL error

maxStatements maximum number of statements in statement pool of a

pooled connection

Using statements

Creating statements

A Statement object is created from the Connection object as follows:

Statement statement = connection.createStatement();

Execute a statement

Once you have a Statement object, you can use it, to execute a query or an update statement.

To execute a statement, you use one of the following execute methods of the Statement

interface:

executeQuery():

The executeQuery() method is used to execute any SQL statement that returns a data

result set.

executeUpdate():

The executeUpdate() method is used to execute any SQL statement that does not

return a data result set. This may be a SQL INSERT, UPDATE or DELETE

statement. In addition SQL statements such as SQL DLL statements can be executed.

In case of SQL DDL statements open transactions and open result sets are implicitly

closed. In auto-commit mode each update statement will close open result sets.

execute():

The execute() method can be used in circumstances where the SQL statement to be

executed is unknown. To perform a query with this method the query must start with

the key word SELECT. Statements with more than one result set or multiple update

counts or a combination of result sets and update counts are not supported.

executeBatch():

The executeBatch() method can be used, to perform a batch of update statements.

Process the results

Results of a query are stored in a ResultSet object. To retrieve the data out of the ResultSet

object and into a Java variable you use the ResultSet getXXX() methods.

Each ResultSet getXXX() method is used to retrieve the value of a data field of a particular

type. Since not all SQL data types can be mapped to all Java types, you must use the

"appropriate" method to retrieve data. To determine the appropriate method, you will need to

determine the SQL data type for the column. The following table will show you which

getXXX() method is compatible with which SQL data types.

Result method

S M A L L I N T

I N T E G E R

R E A L

F L O A T

D O U B L E

D E C I

M A L

N U M E R I

C

C H A R

V A R C H A R

N C H A R

N V A R C H A R

D A T E

T I

M E

T I

M E S T A M P

getByte x x x x x x x x x x x

getShort X x x x x x x x x x x

getInt x X x x x x x x x x x

getLong x x x x x x x x x x x

getFloat x x x x x x x x x x x

getDouble x x x X X x x x x x x

getBigDecimal x x x x x X X x x x x

getBoolean x x x x x x x x x x x

getString x x x x x x x X X x x x x x

getCharacterStream X X

getNString X X

getNCharacterStream X X

getAsciiStream x x

getDate x x x x X x

getTime x x x x X x

getTimestamp x x x x x x X

getObject x x x x x x x x x x x x x x

getBlob x

Remarks:

X Recommended method to retrieve data of this

data type

x Permitted method to retrieve data of this data

type

1. In addition to method getBytes() the methods

getAsciiStream() and getBinaryStream() are not

supported.

2. It is recommended to retrieve data of type REAL

with getDouble() because a REAL may be

smaller or larger than a Java float.

3. In SESAM/SQL, references to blobs are stored in

fields of type CHAR. With getBlob() you get the

blob value for such a reference. With getString()

you get the reference itself.

Statement samples

The following are code examples for executing a query or an update statement.

Example 1: Execute a query

String query = "SELECT * FROM CUSTOMERS";

ResultSet results = statement.executeQuery( query );

// The following code assumes that the query has returned

// a result set with three result columns.

while( results.next() )

{

System.out.println( results.getString(1) + " "

+ results.getInt(2) + " " + results.getTimestamp(3);

}

Example 2: Execute a query for retrieving a blob object

...

String refval;

Blob blobobj;

String query = "SELECT blobref FROM tab WHERE pk = 1";

ResultSet results = statement.executeQuery( query );

while( results.next() )

{

// getting the reference value ...

refval = results.getString(1);

...

// getting the blob object ...

blobobj = results.getBlob(1);

...

// storing the blob value into a file ...

FileOutputStream fos = new FileOutputStream("myfilename");

fos.write(blobobj.getBytes(0,(int)(blobobj.length())), 0,

(int)(blobobj.length()));

fos.flush();

fos.close();

...

}

Example 3: Execute an update statement

// The return variable updCount contains

// the number of updated rows.

String update = "UPDATE customers SET col1 = 'testvalue' WHERE

col2 = 'key'";

int updCount = statement.executeUpdate( update );

Using prepared statements

To create dynamic SQL statements that contain input parameters you use a

PreparedStatement object. A PreparedStatement object is created from the Connection object

as follows:

PreparedStatement statement = connection.prepareStatement( sql );

Each PreparedStatement setXXX() method is used to assign a value of a particular type to an

input parameter. Since not all Java types can be mapped to all SQL data types, you must use

the "appropriate" method to assign a value to an input parameter. To determine the

appropriate method you will need to determine the SQL data type for the parameter. The

following table will show you which setXXX() method is compatible with which SQL data

types.

PreparedStatement method

S M A L L I N T

I N T E G E R

R E A L

F L O A T

D O U B L E

D E C I

M A L

N U M E R I

C

C H A R

V A R C H A R

N C H A R

N V A R C H A R

D A T E

T I

M E

T I

M E S T A M P

setByte x x x x x x x x x x x

setShort X x x x x x x x x x x

setInt x X x x x x x x x x x

setLong x x x x x x x x x x x

setFloat x x x x x x x x x x x

setDouble x x x X X x x x x x x

setBigDecimal x x x x x X X x x x x

setBoolean x x x x x x x x x x x

setString x x x x x x x X X x x x x x

setCharacterStream X X

setNString X X

setNCharacterStream X X

setAsciiStream x x

setDate x x x x X x

setTime x x x x X x

setTimestamp x x x x x x X

setObject x x x x x x x x x x x x x x

setBlob x

Remarks:

X Recommended method to assign a value to an

input parameter of this SQL data type

x Permitted method to assign a value to an input

parameter of this data type

1. In addition to method setBytes() the methods

setAsciiStream() and setBinaryStream() are not

supported.

2. With setBlob() you create a new blob object

containing the value of the existing blob object

which is specified in the setBlob operation and a

new reference value referencing this new blob

object. The new reference value is inserted into

the reference field (specified in setBlob) and the

new blob object is inserted into the referenced

blob table.

3. With setObject() using appropriate parameters

you can create a new blob object with a value

specified by an input stream (s. below for an

example).

4. If you want to insert a reference value for an

existing blob object without creating a new blob

object you should use setString() with the

reference value for the existing blob object as

parameter.

To execute a prepared statement you use one of the following execute methods of the

PreparedStatement interface:

executeQuery():

The executeQuery() method is used to execute a SQL statement that returns a data

result set.

executeUpdate():

The executeUpdate() method is used to execute a SQL statement that does not return

a data result set. This may be a SQL INSERT, UPDATE or DELETE statement. In

addition SQL statements such as SQL DLL statements can be executed. In case of

SQL DDL statements open transactions and open result sets are implicitly closed. In

auto-commit mode each update statement will close open result sets.

execute():

The execute() method can be used in circumstances where the SQL statement to be

executed is unknown. Statements with more than one result set or multiple update

counts or a combination of result sets and update counts are not supported.

executeBatch():

The executeBatch() method can be used, to perform a batch of prepared update

statements.

The following are code examples for preparing end executing a statement with parameters.

Example 1: Execute an update statement

String update = "UPDATE customers SET col1='testvalue' WHERE col2

= ?";

PreparedStatement pstmt = connection.prepareStatement(update);

pstmt.setString(1,"key");

pstmt.execute();

Example 2: Execute an insert statement that inserts a file as a blob object

PreparedStatement pinsert = connection.prepareStatement(

"INSERT INTO tab(pk,blobref) VALUES(?,?)");

pinsert.setInt( 1, 4711);

pinsert.setObject(

2,

new FileInputStream("myfilename"),

Types.BLOB);

pinsert.execute();

RowSets

SESAM-DBAccess (JDBC) Driver 6.0A offers the option to use the interface WebRowSet;

please see the JDBC documentation about using these type of RowSet.

You can create a WebRowSet object by

SesamWebRowSet swrs = new

com.fujitsu.ts.sesam.dbaccess.SesamWebRowSet()

These objects now can be used as a WebRowSet according to the JDBC interfaces.

Extensions

Performance tuning

The JDBC interface does not offer the possibility to read several result data within a single

method call. To reduce network communication the driver requests chunks of result data not

single rows. The number of rows read in a single request is 10. You can change this value by

setting the property "prefetch" or by using the method setFetchSize() of the interfaces

Statement and ResultSet.

Using SESAM/SQL vectors

SESAM/SQL has a special data object, called vector. A vector is a collection of values of the

same data type.

You can use the SESAM/SQL syntax when creating tables, retrieving or updating tables with

vectors. Though vectors are a collection of values of the same data type but not a special data

type, meta information about vectors is returned for the elements of a vector and not for the

vector as an object.

Restrictions

Due to some minor differences to the JDBC specification this release is not fully JDBC

compliant. A description of known differences you will find in the following paragraphs.

Escape clauses

The escape clauses of the JDBC are all supported except escape clauses for stored

procedures. The escape clauses for scalar functions have the following restrictions:

String functions

The following String functions are supported:

CONCAT(string1, string2)

LCASE(string)

LENGTH(string)

LOCATE(string1, string2[,start]):

This function is only supported without the optional parameter start.

LTRIM(string), RTRIM(string)

SUBSTRING(string,start,length)

Time functions

The following time functions are supported: CURDATE(),CURTIME() and NOW(). Other

time functions are not supported.

Conversion functions

The data types BIGINT, BINARY, BIT, LONGVARBINARY, LONGVARCHAR,

TINYINT and VARBINARY are not supported in function CONVERT.

DatabaseMetaData

The following restrictions apply to methods of the DatabaseMetaData interface:

Parameter columnPattern in methods getColumns() and getColumnPrivileges() must

be null. Another value for this parameter will throw the SQLException "22023

Invalid parameter value".

Result column ORDINAL_POSITION of method getColumns():

In the resultset of method getColumns() all elements of a vector are given the same

ordinal number. Therefore you should not use the value of this result column as

column index.

Transactions

A new transaction is implicitly initiated when disabling auto-commit mode or switching from

manual mode to auto-commit mode. In both cases an open transaction is automatically

committed.

If the actual access mode is not read-only, a call to setTransaction() with isolation level

TRANSACTION_READ_UNCOMMITTED will change the isolation level to

TRANSACTION_READ_COMMITTED. The same applies when switching the access

mode from read-only to read-write and the actual isolation level is

TRANSACTION_READ_UNCOMMITTED.

Executing an update statement in auto-commit mode will close all open result sets.

Method setMaxFieldSize()

The method setMaxFieldSize() of interface Statement may only be called before the first call

of method next() of interface ResultSet.

Positioned updates and deletes

If you want to use positioned updates or positioned deletes, you have to set the property

prefetch to 1. Additionally the fetch size of the updatable cursor must be implicitly or

explicitly set to 1. Positioned updates and deletes should only be used, when auto-commit is

switched off.

Callable statements

The method prepareCall() of interface Connection is not supported, because SESAM/SQL

does not offer the execution of stored procedures. When you call this method, you will get a

SQLException.

Applets

The Web Browser you use should be a JDK 1.4 enabled Web Browser. To enable JDK 1.4

you can use the java plug-in offered by Sun.

Browser Security

To connect to a database running on a different host from the web server host, the applet

requires socket connection privileges. In Netscape 4.x this involves signing your applet and

granting the "UniversalConnect" privilege to the applet:

netscape.security.PrivilegeManager.enablePrivilege( "UniversalConnect" );

When using the java plug-in , the policy files of the java runtime environment must be

adapted accordingly (Privilege "Connect").

Firewalls

The SESAM-DBAccess (JDBC) driver can be used in Java applications as well as in applets.

The SESAM-DBAccess (JDBC) driver opens a TCP/IP socket connection to communicate

with the database server. Therefore this driver can only be used in configurations, which

permit such an operation.

Troubleshooting

For diagnostic purposes a driver logging can be created by using the following statements in

your Java application:

PrintWriter w = new PrintWriter(new FileOutputStream("sesamDriver.log"));

DriverManager.setLogWriter ( w );

In case of a Java Applet the logging stream can be directed to the standard output:

DriverManager.setLogWriter ( System.out );

If the logging of the DriverManager is enabled, the SESAM-DBAccess (JDBC) Driver traces

the method calls of the JDBC interfaces. It may therefore be necessary to change the logging

level. This can be done by calling the method setLevel() of class SesamLog as follows:

SesamLog.setLevel( 15 );

If logging has been enabled, it can be switched off with the following statement:

DriverManager.setLogWriter ( null );

Because this method requires changes of the application code, there is another method for

activating driver logging. This (preferred) method uses a property file named

sesamjdbc.properties:

If a file named sesamjdbc.properties is found within the working directory or - if used within

a servlet - the webroot-directory, the properties in this file are used and "overrule"

setLogWriter.

The following properties can be set:

Traceon: possible values are true or false; when set to false no trace is written.

Tracefile: the name of the tracefile to be written (default: sesamjdbctrace.txt).

Tracelevel: the desired tracelevel; possible values are:

ERROR Logging of thrown exceptions.

CONNECTION Logging of connectio related methods (including ConnectionPooling

and StatementPooling.

STMT

Logging of SQL statements executed. The SQL statement is shown

as handed over (and if modified by the driver, additionally as handed

over to the server).

INFO Logging of method calls of the JDBC interfaces. This level includes

level STMT.

STD Logging of method calls of the JDBC interfaces. This level includes

level ERROR.

SERVER Logging of server requests and server responses.

DEBUG Logging of internal interfaces.

ROWSET Logging of main method calls of RowSets.

ROWSET_DETAIL Logging of special method calls of RowSets.

ROWSET_ALL Logging of all method calls of RowSets (includes other ROWSET

levels).

ALL All other levels are included (default).

Tracestyle: style of logging entries; possible values are:

NO_TIME Logging without timestamp.

NO_PREFIX Logging without prefix.

TIME_AND_PREFIX Logging with timestamp and prefix (default).

References

You will find detailed informations about the JDBC API in the following documents:

[JDBC1API] Graham Hamiltion & Rick Cattel,

JDBC: A Java SQL API, JavaSoft 1997

[JDBC2API] Seth White & Mark Hapner,

JDBC 2.0 API, Sun Microsystems 1998

[JDBC3API] Jon Ellis & Linda Ho,

JDBC 3.0 API, Sun Microsystems 2001

[JDBC4API] JDBC 4.0 API, Sun Microsystems 2006

[JDBCREF] Graham Hamiltion & Rick Cattel & Maydene Fisher,

JDBC Database Access with Java, A Tutorial and Annotated Reference

Addison-Wesley 1997