ODBC-JDBC Bridge Installation Guide

OpenLink Single-Tier 'Lite' Edition for Windows

Platform: Microsoft Windows | Edition: Lite | Driver Type: ODBC-to-JDBC Bridge

Overview

The OpenLink Single-Tier 'Lite' Edition ODBC Driver for JDBC Data Sources (ODBC-JDBC Bridge) enables Windows applications to access JDBC-compliant data sources through the ODBC interface. This guide provides comprehensive installation and configuration instructions for Windows operating systems.

What is the ODBC-JDBC Bridge?

The ODBC-JDBC Bridge is a database driver that employs ODBC to connect to databases while providing a bridge between the JDBC and ODBC APIs. This allows applications designed for ODBC to seamlessly access JDBC data sources without modification.

Key Features

  • Single-Tier architecture (no separate database server required)
  • Universal support for any JDBC-compliant data source
  • Full ODBC API compliance
  • Support for both 32-bit and 64-bit Windows
  • Advanced configuration options for performance tuning

Pre-Installation Requirements

Before beginning installation, ensure your system meets all the following requirements.

System Requirements

Operating System: Microsoft Windows (Vista, 7, 8, 10, 11 or Server editions)
Processor: Intel-compatible processor with SSE2 support
RAM: Minimum 1 GB (2 GB recommended)
Disk Space: Minimum 500 MB for installation

Software Requirements

Java Virtual Machine (JVM): A compatible JVM matching the driver bitness (32-bit or 64-bit)
JDBC Driver: The JDBC driver for your target database
Administrator Privileges: Required for driver installation

Configuration Requirements

Before configuration, you must have:

JDBC Driver Information: The driver class name and connection URL
Database Credentials: Username and password for your database
Environment Variables: Knowledge of PATH and CLASSPATH configuration

Installation Steps

Follow these steps to install the ODBC-JDBC Bridge driver on your Windows system. Each step includes a screenshot for reference.

1

Launch the Installer

Locate and double-click the OJDBC installation executable to launch the installer. The setup wizard will appear with the installation welcome screen.

Installer Launch Screen
2

Welcome Screen

The Welcome screen presents an overview of what will be installed. Review the information and click "Next >" to continue to the License Agreement.

Welcome Screen
3

License Agreement

Read the License Agreement carefully. You must accept the terms to continue with the installation. Select "I Agree" and click "Next >".

License Agreement
4

Licensing Information

Enter your licensing details if applicable. For evaluation versions, this may be optional. Review the licensing information and proceed with "Next >".

Licensing Information
5

Installation Options

Select your installation preferences. Choose whether to install to the default location or specify a custom installation path. Standard installation is recommended for most users.

Installation Options
6

Begin Installation

Review your installation settings and click "Install" to begin copying files to your system. The installation process may take a few moments. Do not close this window during installation.

Begin Installation
7

Installation Complete

Once installation is complete, the Finish screen will appear. Click "Finish" to close the installer. The OJDBC driver is now installed and ready for configuration.

Installation Complete
Installation Complete! You can now proceed to configuration and environment setup.

Java Environment Setup & JDBC Testing

Proper Java configuration is critical for the ODBC-JDBC Bridge to function correctly. This section covers environment setup and includes a complete JDBC testing utility to verify your configuration before proceeding to ODBC setup.

Step 1: Locate the JVM

Find the jvm.dll file location in your Java installation. Typically located at:

C:\Program Files\Java\jdk1.8.0_version\jre\bin\server\jvm.dll
C:\Program Files (x86)\Java\jre1.8.0_version\bin\server\jvm.dll

Step 2: Configure PATH Environment Variable

Add the directory containing jvm.dll to your system PATH:

  1. Open System Properties (Win+Pause or Control Panel → System)
  2. Click "Advanced system settings"
  3. Click "Environment Variables"
  4. Under "System variables", click "New" and add:
    • Variable name: PATH
    • Value: C:\path\to\jvm\bin\server
  5. Click OK and restart your applications

Step 3: Locate JDBC Driver

Find the JDBC driver .jar file for your target database. Common locations:

C:\Program Files\JDBC Drivers\postgresql-42.2.14.jar
C:\Program Files\JDBC Drivers\mysql-connector-java-8.0.22.jar
C:\Program Files\JDBC Drivers\ojdbc8.jar
C:\Program Files\JDBC Drivers\jtds-1.3.3.jar

Step 4: Configure CLASSPATH Environment Variable

Add the JDBC driver .jar file to your system CLASSPATH:

  1. Open Environment Variables (as described in Step 2)
  2. Click "New" and add:
    • Variable name: CLASSPATH
    • Value: C:\path\to\jdbc\driver.jar
  3. For multiple drivers, separate paths with semicolons:
    C:\drivers\postgresql.jar;C:\drivers\mysql.jar
  4. Click OK and restart your applications

Step 5: Optional - Configure JVM Options

Set the OPL_JVM_OPTS environment variable for custom JVM parameters:

Variable name: OPL_JVM_OPTS
Value: -Xms64m -Xmx512m -XX:+UseG1GC

Common options: -Xms (initial heap size), -Xmx (maximum heap size), -XX:+UseG1GC (garbage collection)

Step 6: Verify Java Installation

Test your Java setup by running these commands in Command Prompt:

java -version
javac -version

Both commands should display version information without errors.

JDBC Testing Utility - UniversalJDBCTest

Before configuring the ODBC DSN, verify your JDBC driver is properly installed and your connection parameters are correct using this comprehensive testing utility:

How to use:
  1. Copy the code below into a file named UniversalJDBCTest.java
  2. Modify the connection parameters (driverClass, jdbcURL, user, password)
  3. Save the file in your project directory
  4. Compile and run following the instructions below
UniversalJDBCTest.java
import java.sql.Connection;
import java.sql.DatabaseMetaData;
import java.sql.Driver;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;

public class UniversalJDBCTest {
    public static void main(String[] args) {
        // ============================================
        // EDIT THESE VALUES FOR YOUR DATABASE
        // ============================================
        String driverClass = "org.postgresql.Driver";
        String jdbcURL = "jdbc:postgresql://localhost:5432/mydb";
        String username = "myuser";
        String password = "mypassword";
        
        // ============================================
        // CONNECTION TEST BEGINS
        // ============================================
        Connection conn = null;
        Statement stmt = null;
        ResultSet rs = null;
        
        try {
            System.out.println("=== JDBC Connection Test ===\n");
            
            // Step 1: Load JDBC Driver
            System.out.println("[1] Loading JDBC Driver: " + driverClass);
            Class.forName(driverClass);
            System.out.println("    ✓ Driver loaded successfully\n");
            
            // Step 2: Establish Connection
            System.out.println("[2] Connecting to: " + jdbcURL);
            conn = DriverManager.getConnection(jdbcURL, username, password);
            System.out.println("    ✓ Connection established successfully\n");
            
            // Step 3: Get Connection Metadata
            System.out.println("[3] Database Metadata:");
            DatabaseMetaData meta = conn.getMetaData();
            System.out.println("    Database: " + meta.getDatabaseProductName());
            System.out.println("    Version: " + meta.getDatabaseProductVersion());
            System.out.println("    Driver: " + meta.getDriverName());
            System.out.println("    Driver Version: " + meta.getDriverVersion() + "\n");
            
            // Step 4: Execute Test Query
            System.out.println("[4] Executing test query...");
            stmt = conn.createStatement();
            rs = stmt.executeQuery("SELECT 1 as test_column");
            
            if (rs.next()) {
                System.out.println("    ✓ Query executed successfully");
                System.out.println("    Test value: " + rs.getInt("test_column") + "\n");
            }
            
            // Step 5: Display Available Tables
            System.out.println("[5] Available Tables in Database:");
            ResultSet tables = meta.getTables(null, null, "%", new String[]{"TABLE"});
            int tableCount = 0;
            while (tables.next() && tableCount < 10) {
                System.out.println("    - " + tables.getString("TABLE_NAME"));
                tableCount++;
            }
            if (tableCount == 10) {
                System.out.println("    (showing first 10 tables)\n");
            } else {
                System.out.println();
            }
            
            // Step 6: Connection Close Test
            System.out.println("[6] Closing connection...");
            if (rs != null) rs.close();
            if (stmt != null) stmt.close();
            if (conn != null) conn.close();
            System.out.println("    ✓ Connection closed successfully\n");
            
            System.out.println("=== TEST COMPLETED SUCCESSFULLY ===");
            System.out.println("\nYour JDBC driver is properly configured.");
            System.out.println("You can now proceed with ODBC DSN configuration.");
            
        } catch (ClassNotFoundException e) {
            System.err.println("ERROR: JDBC Driver not found!");
            System.err.println("Make sure the driver .jar is in your CLASSPATH");
            System.err.println("Details: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("ERROR: Connection failed!");
            System.err.println("Details: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Compiling the Test Utility

Open Command Prompt and navigate to your project directory, then compile:

javac UniversalJDBCTest.java

This creates UniversalJDBCTest.class if compilation succeeds.

Running the Test

Execute the test utility to verify your JDBC connection:

java UniversalJDBCTest

Expected output: Successful connection message with database metadata and available tables.

Successful Test Output Example:
=== JDBC Connection Test ===

[1] Loading JDBC Driver: org.postgresql.Driver
    ✓ Driver loaded successfully

[2] Connecting to: jdbc:postgresql://localhost:5432/mydb
    ✓ Connection established successfully

[3] Database Metadata:
    Database: PostgreSQL
    Version: 12.5
    Driver: PostgreSQL JDBC Driver
    Driver Version: 42.2.14

[4] Executing test query...
    ✓ Query executed successfully
    Test value: 1

[5] Available Tables in Database:
    - users
    - products
    - orders

[6] Closing connection...
    ✓ Connection closed successfully

=== TEST COMPLETED SUCCESSFULLY ===

Your JDBC driver is properly configured.
You can now proceed with ODBC DSN configuration.
Troubleshooting Test Failures:
  • ClassNotFoundException: JDBC driver .jar not in CLASSPATH. Verify CLASSPATH environment variable.
  • Connection refused: Database server not running or invalid host/port. Check jdbcURL parameter.
  • Invalid username/password: Credentials are incorrect. Verify username and password parameters.
  • No suitable driver found: CLASSPATH not properly set. Restart Command Prompt after setting environment variables.

ODBC DSN Configuration

After installation, configure a Data Source Name (DSN) to establish connections through the ODBC-JDBC Bridge. Follow these visual steps to complete the configuration process.

8

Open ODBC Administrator

Access the ODBC Data Source Administrator. On Windows, open Control Panel → Administrative Tools → ODBC Data Sources (32-bit or 64-bit as appropriate).

ODBC Administrator
9

Navigate to System DSN Tab

Click on the "System DSN" tab in the ODBC Administrator. This tab displays all system-wide data sources available to all users on the computer.

System DSN Tab
10

View Available Drivers

Click the "Add..." button to create a new data source. A dialog will appear showing all available ODBC drivers, including the recently installed OJDBC driver.

Available Drivers
11

Configure DSN Name

Enter a descriptive name for your data source and optionally add a description. This name will be used by applications to connect to your JDBC data source (e.g., "MyVirtuoso", "OracleDB_DSN").

DSN Name Configuration
12

Connection Tab Settings

Configure the connection parameters. Enter the JDBC driver class, URL string, username, and password for your database connection. Example: JDBC Driver: virtuoso.jdbc3.Driver, URL: jdbc:virtuoso://localhost:1111/, Username: dba

Connection Tab
13

Database-Specific Settings

Configure database-specific parameters if needed. These settings allow fine-tuning of the connection based on your specific database requirements and optimization needs.

Database Specific Settings
14

Options Tab Configuration

The Options tab provides additional configuration parameters such as row buffer size, fetch size, maximum rows, and other performance-related settings. Adjust these settings as needed for your environment.

Options Tab
15

Compatibility Settings

Configure compatibility options to ensure optimal behavior with your specific applications and database. These settings help resolve compatibility issues with certain applications and improve performance.

Compatibility Settings
16

Test Connection

Click the "Test" or "Connection Test" button to verify that your configuration is correct and that the connection to your database is successful. A success message indicates proper configuration.

Test Connection
Configuration Complete! Your OJDBC DSN is now configured and ready to use. You can now use this DSN in your applications to connect to your JDBC data source through ODBC.

Key Configuration Fields Summary

DSN Name: A descriptive name for your connection (e.g., "MyJDBCDB")
JDBC Driver Class: The fully qualified JDBC driver class name (e.g., "org.postgresql.Driver")
JDBC Connection URL: The JDBC connection string (e.g., "jdbc:postgresql://localhost:5432/mydb")
Database Username: Your database login username
Database Password: Your database login password

Advanced Options

Read-only Connection: Check this option if you want connections to be read-only. Leave unchecked for INSERT, UPDATE, DELETE operations.
Max Rows Override: Set a limit on returned rows (default 0 = unlimited)
SQL Server Compatibility Mode: Enable if using with Microsoft InfoPath or SQL Server tools
Defer Long Data Fetching: Improves performance when large BLOB/BINARY fields are not needed
Dynamic Cursor Sensitivity: Choose between High (detects updates, slower) or Low (faster, less aware)

Frequently Asked Questions

Find answers to common questions about ODBC-JDBC Bridge installation and configuration.

What software bit format is required for the ODBC driver?
The Single-Tier 'Lite' Edition ODBC Driver for JDBC Data Sources must match the bit format (32-bit or 64-bit) of the client application.
What Java component is necessary for the driver to function?
A compatible JVM (Java Virtual Machine) is required. For a 32-bit driver, a 32-bit JVM is needed, even on 64-bit Windows.
What key pieces of information are needed for DSN configuration?
You must know the driver class name of your JDBC driver and the full details of the JDBC connection URL.
How do you configure the PATH environment variable?
You must add the full directory path to the 'jvm.dll' file to your system's PATH Environment Variable.
How do you configure the CLASSPATH environment variable?
You must add the full file path to the JDBC driver's .jar file to your system's CLASSPATH Environment Variable.
What is the purpose of the OPL_JVM_OPTS environment variable?
It is used to provide a list of special JVM command line arguments (e.g., -Xms64m) to be passed to the JDBC Driver on connect.
What does the 'Read-only connection' DSN option do?
It specifies whether the connection is 'Read-only'. It must be unchecked to perform INSERT, UPDATE, or DELETE operations.
What is the purpose of the 'Max Rows Override' DSN setting?
It allows you to set a limit for the maximum number of rows to be returned from a query. The default value of 0 means no limit.
How can you make the driver compatible with Microsoft InfoPath?
Manually override the SQLGetInfo(SQL_DBMS_NAME) response by setting the 'SQL_DBMS Name' field to 'SQL Server'.
What is the purpose of the 'Defer fetching of long data' option?
It defers fetching of LONG data types (like BINARY, BLOB) in wildcard queries, providing significant performance increases when those fields are not included in the query.
How does 'Dynamic Cursor Sensitivity' affect performance?
High sensitivity detects row updates but carries a performance overhead. Low sensitivity improves performance but cannot detect updates. To enable it, the 'oplrvc' table must be created beforehand.
What is 'Multiple Active Statements Emulation' used for?
It enables the use of Multiple Active Statements in an ODBC application by emulating this functionality within the driver, even if the underlying database does not support it.
When should you use the Unicode version of the driver?
You should select the Unicode version of the driver if and only if you are working with multi-byte character sets.
What happens if you don't install a license file immediately?
This option will permit you to install the product; however, you will not be able to use the product until you obtain and install a commercial or evaluation license key.

Technical Glossary

Key terms and concepts used throughout this guide.

CLASSPATH

An environment variable that tells the Java Virtual Machine where to find the necessary class libraries, such as the JDBC driver .jar file.

DSN (Data Source Name)

A user-friendly name for an ODBC data source that stores connection details like driver name, server, and database.

JDBC (Java Database Connectivity)

An application programming interface (API) for the programming language Java, which defines how a client may access a database.

JDBC-ODBC Bridge

A database driver implementation that employs an ODBC driver to connect to a database, providing a bridge between the JDBC and ODBC APIs.

JVM (Java Virtual Machine)

An abstract computing machine that enables a computer to run a Java program, required for the ODBC-to-JDBC bridge to function.

ODBC (Open Database Connectivity)

A standard application programming interface (API) for accessing database management systems (DBMS).

ODBC Data Source Administrator

A Windows system tool used to manage ODBC data sources, drivers, and DSN configurations.

System DSN

A Data Source Name that is stored in the system registry and is available to all users on a specific machine.

PATH Environment Variable

A system variable specifying directories where the operating system searches for executable files and libraries like jvm.dll.

Microsoft Windows

A group of operating systems developed and maintained by Microsoft for personal computers and servers.

SQL (Structured Query Language)

A standardized programming language for managing and querying relational databases.

Java

A general-purpose, object-oriented programming language designed to be platform-independent through the Java Virtual Machine.