Using KTL JDBC driver for Oracle Rdb

System requirements

The driver connects to your Oracle Rdb database via Oracle SQL/Services and SQL/Services client API. To use the driver, at least the following conditions must be met:

Application programming

The KTL JDBC driver for Oracle Rdb is used as any other JDBC driver. The name of the class implementing the driver is fi.ktl.rdb.jdbc.KTLDriver. This class must be loaded and registered by the JDBC driver manager. This is done either by specifying the driver class in the system property jdbc.drivers or by loading the class in the application code, for example:

Class.forName("fi.ktl.rdb.jdbc.KTLDriver");

You then create a connection using any of the getConnection methods of java.sql.DriverManager. The URL for the database connection is always passed to the getConnection method. The syntax of an URL for this driver is:

jdbc:ktlrdb://host[:port]/service?parameter1=value1&parameter2=value2&...

where

URL parameters
Name Value(s) Description
application character string Name of the application using the driver may be specified here. This is useful for monitoring the SQL/Services activities.
attach an SQL statement SQL attach statement, for example attach 'filename myRdbDatabase'. This parameter is used with SQL/Services service class without an attach statement (universal service).
clientlog integer (0-511) Specifies the level of detail for the information written to the SQL/Services client API log file. Value 0 means that no log file will be created. Refer to the Oracle SQL/Services client API documentation about this feature. Default is 0.
debug true, false If true, debug information will be printed on System.out or whatever JDBC log stream specified by java.sql.DriverManager.setLogWriter. If false, no debug information will be printed. Default is false.
declare an SQL statementOptional SQL declare statement, for example declare transaction ready only.
dialect SQL92, SQL89, MIA, SQLV40, ORACLE_LEVEL1 SQL dialect used. Default is SQLV40 (or whatever is the default of Oracle Rdb version being used).
hold_cursors commit, rollback, all, none Defines whether cursors remain open across commits, rollback, both or none. Default is all.

When the application is run, the classes implementing the driver must be accessible in the Java CLASSPATH. Common ways to achieve this is to include the JAR file KTLJdbc4Rdb.jar of this driver either in the CLASSPATH environment variable or in the -classpath switch of the java command.

Additionally, the driver requires the native library Rdbsqs. The name of this library and the rules for locating and loading the library are specific to each operating system.

In OpenVMS Rdbsqs is implemented as a shareable image rdbsqs.exe. To active this shareable image at runtime define a logical name Rdbsqs which translates to the correct file specification. See your OpenVMS reference for more details.

In Unix environments Rdbsqs is implemented as a shareable object rdbsqs.so. See your Unix reference for more details. Note: At the time of writing, we have not yet tested the driver in Unix.

In Windows Rdbsqs is implemented as a dynamic link library rdbsqs.dll. To active the DLL at runtime either place rdbsqs.dll in any directory pointed by Windows environment variable PATH or into the current working directory of your application. See your Windows reference for more details.

Finally, the Oracle SQL/Services client API must be installed.

HelloWorld example

The following is an example of a simple Java application that uses this driver to connect to an Oracle Rdb database, executes a query, retrieves the result and prints the result in stardard output. 
import java.sql.*;
public class HelloWorld {

  public static void main (String argv[]) {
    try {
      Class.forName( "fi.ktl.rdb.jdbc.KTLDriver" );
      String url = "jdbc:ktlrdb://myhost.somewhere.somedomain/myservice";
      Connection con = DriverManager.getConnection(url, "myusername", "mypassword");
      Statement st = con.createStatement();
      st.execute( "select current_date from rdb$database" );
      ResultSet rs = st.getResultSet();
      rs.next();
      Date d = rs.getDate(1);
      System.out.println( "Hello world, today is " + d + "!");
      rs.close();
      st.close();
      con.close();
    }
    catch (java.lang.Throwable ex ) {
      System.out.println("Error in HelloWorld: " + ex);
    }
  }
}
The application can be compiled using the following command line command: 
javac -classpath /myJARdirectory/KTLJdbc4Rdb.jar:. HelloWorld.java
The application can then be started with the following command line command: 
java -classpath /myJARdirectory/KTLJdbc4Rdb.jar:. HelloWorld
Note that at this point, the native library Rdbsqs and the Oracle SQL/Services client API is used. If everything is properly configured, the output produced should be similar to: 
Hello world, today is 2001-10-04!
If Rdbsqs is not found, java.lang.UnsatisfiedLinkError is produced and the output is similar to: 
Error in HelloWorld: java.lang.UnsatisfiedLinkError: no Rdbsqs in java.library.path

Setup on OpenVMS

For OpenVMS, we have provided a DCL command file KTLJdbc4Rdb.com which may be used to define the required logical name and to setup CLASSPATH to include the JAR file. You should find this file from the same location as KTLJdbc4Rdb.jar and Rdbsqs.exe. In our own environment this command file can be invoked by our setup convention: 
$ setup ktljdbc4rdb

Copyright © 2001 National Public Health Institute KTL, Finland

Matti Sarjakoski 2002-03-18.