Installing & Using the OpenLink ODBC–to–JDBC Bridge Driver on macOS

Connecting ODBC Applications to Third-party JDBC Drivers

Published in

OpenLink ODBC, JDBC, ADO.NET Data Access Drivers Blog

7 min readMay 6, 2017

The following steps guide you through the process of successfully installing and configuring our ODBC-JDBC Bridge drivers for macOS. Once installed, your JDBC Data Sources will be accessible to an ODBC compliant application running on macOS.

License Generation

Visit our License Generator Page, fill in the License Selection Form:

and then click on the “Generate License” button which triggers the following:

Creation of page that includes links to the ODBC-JDBC Bridge installer archive and associated installation and configuration guides

Page Generated by Installer that references installer program and associated guides

Generation and sending of an email that includes a link to the License File you just generated.

Once you’ve located your license file, please save to your macOS computer prior to running the installer program.

Software Installation

Following successful download of the installer package, double-click on its icon and then follow the interaction prompts as and when presented by the installer.

Note: The prompt for the location of your ODBC-JDBC Driver License File is the most important step in this process. Forgetting to install your License will adversely affect usage of these drivers, while also introducing complexity to a very simple process.

Installation Verification

Following successful software installation, you can proceed to creating and configuring ODBC Data Source Names (DSNs) using the iODBC Administrator application.

To confirm that your driver installation was successful, you will need to open up the iODBC Administrator and then select the “ODBC Drivers” tab. This presents you with a list of installed drivers.

Now that installation of your driver has been confirmed you can now proceed to creating and configuring an ODBC Data Source Name (DSN) for your driver.

Data Source Name (DSN) Configuration

Pick the non-Unicode driver if you’re working with any single-byte, 8-bit codepage or character set. Pick the Unicode driver only if you’re working with a multi-byte codepage or character set.

Provide a name that identifies your DSN. You can also include an optional description, but most tools will not show this to you when asking you to pick the DSN to which they’ll connect.

Type your JDBC driver’s classname (e.g., virtuoso.jdbc4.Driver, openlink.jdbc4.Driver) into the JDBC Driver text box. If you already know your JDBC URL, you can type or paste it into the URL String text box. Alternatively, you can click "…" button to bring up the JDBC connection string builder.

The protocol part of your URL will start with "jdbc:" which identifies JDBC as the main protocol followed by a sub-protocol scheme identifier specific to each driver. Generally, URL syntax follow the basic form "jdbc:{driver-name}://{hostname}[:{port}]/". Additional database server connection attributes and values may be added one at a time through the "Add" button.

Note that you need to terminate your URL prefix and attribute=value pairs using termination characters supported by the driver in question. For instance, “/” terminates the prefix and “;” for the connection attributes when using our drivers. Thus, a JDBC URL that included UID and PWD conneciton attributes would be represented as: jdbc:virtuoso://example.com:1111/UID=dba;PWD=xyz;

Dialog that contains a JDBC URL that includes UID and PWD connection attributes generated by the URL Builder

By default, the "Connect now to verify that all settings are correct" box is checked. Input a username and password, and click "Continue" to test the basic connection at this point, before proceeding to the Options, Preferences, and Compatibility setting panes.

Various options are available, to increase compatibility with various ODBC applications and JDBC drivers that don’t fully comply with their respective standards.

Now that you have successfully configured an ODBC Data Source Name for your target JDBC Data Source, proceed to testing connections from your preferred ODBC compliant applications.

Here are the steps to following if using the simple ODBC demo app (iODBC Demo) that we bundle with all our macOS Driver installations (UDA and/or Virtuoso):

Start the iODBC Demo App go to the “Environment” (an ODBC environment handle) menu which presents an option to “Open Connection” (an ODBC connection handle).

Select the DSN configured during this exercise for the JDBC-ODBC Bridge Driver

Respond to authentication challenge with credentials (username and password) for the target data source.

Type in a SQL Query and then click on the “OK” button to execute.

You will be presented with query results as depicted below.

Troubleshooting

License File Location Issues

If you failed to point the installer program to your JDBC-ODBC Driver’s license file, or are upgrading from a Free Evaluation License to a Perpetual License, you will encounter the following error dialog:

This problem is resolved by copying your license from the folder into which it was downloaded over to folder named: /Library/Application\ Support/openlink/Licenses .

Once the license is in place you will need to restart the license manager by performing the following steps:

cd to the folder /Library/Application Support/openlink/bin
type in the command: sudo ./oplmgr +stop
type in the command: sudo ./oplmgr +start +directory /Library/Application\ Support/openlink/Licenses
use output from the command: sudo ps -ef | grep “oplmgr” or the system profile manger to confirm the License Manager is up and running.

Alternatively, you can also use the following sequence:

cd to the folder /Library/Application\ Support/openlink/Licenses
type in the command: sudo ../bin/oplmgr +stop
type in the command: sudo ../bin/oplmgr +start

Ideally, you should add both the “/Library/Application Support/openlink/bin” folder to your system PATH and “/Library/Application\ Support/openlink/Licenses” folder to the OPL_LICENSE_DIR environment variable by issuing the commands:

export PATH=$PATH:/Library/Application\ Support/openlink/bin ;export OPL_LICENSE_DIR=/Library/Application\ Support/openlink/Licenses ;

And then you can start and stop the License Manager by simply issuing the following commands from any folder location: oplmgr +start and oplmgr +stop, respectively.

Now that access to the License Manager has been configured, you can use the output from the command: sudo ps -ef | grep “oplmgr” or the system profile manger to confirm the License Manager is up and running.

Activity Manager Snippet Listing OpenLink License Manager

Java Environment Issues

To successfully use an ODBC-JDBC Bridge driver it is important that your target JDBC Driver is properly installed and functioning. You can use our JDBC demo apps (installed with our Drivers) to simplify this process.

Locate the folder named: /Library/Application Support/openlink/samples/JDBC/, and then go into the folder that matches you current Java Runtime installation (JDK 1.8 is the latest for JVM 8.0+) .

First part of folder tree leading to location of our demo JDBC apps

Second part of folder tree leading to location of our demo JDBC apps

Assuming JDK 1.8, go to the folder named: /Library/Application Support/openlink/samples/JDBC/jdk1.8/JDBCDemo, and then type in the following command: sh JDBCDemo.sh .

At this point you have a simple JDBC application instantiated for testing with your JDBC Driver. Here are some screenshots that guide you through the process of establishing a connection using our JDBC Drivers for Virtuoso.