ODBC Driver for Mac

Owned by Boaz Raufman
Feb 26, 2019
5 min read

The Jethro ODBC driver for Mac, enables access to the data stored in Jethro instances, from Business Intelligence (BI) applications with ODBC support.

The following sections specify the steps required for the installation and configuration of Jethro ODBC driver:

Installation and configuration

Download

Jethro ODBC drivers can be downloaded from the drivers download page.

Prerequisites

  1. MacOS version 10.12.6 (Sierra)
  2. 51 MB of available disk space
  3. iODBC version 3.52.12 installed or ODBC Manager 1.0.12 installed

Installation

To install the ODBC driver:

  1. In Finder, Control-click or right click the icon of the app.

  2. Select Open from the top of contextual menu that appears.

    Please note

    Some organizational policies do not allow to open applications which are not signed by "identified developers". In that case, double clicking the icon of the PKG file won't work, and it is important to use right click+open, or to temporary allow installation of apps from "unidentified developers". For more details, see OS X: About Gatekeeper.

  3. Click Open in the dialog box. If prompted, enter an administrator name and password.

  4. The installer installs the ODBC driver files in the following directories:

    1. <INSTALLATION-PATH>/jethro/jethroodbc/lib/         (By default <INSTALLATION-PATH> is '/opt/')

    2. /Library/ODBC/

Setting up the driver in the Driver Manager

In order to create a connection, the driver manager need to have Jethro defined as a driver.

This action can be done in two ways:

Manually

  1. Open the configuration file '/Library/ODBC/odbcinst.ini' in a text editor. If the file doesn't exist, create it.

  2. Add the following configs:

    [ODBC Drivers]
JethroODBCDriver=installed

[JethroODBCDriver]
APILevel=1
ConnectFunctions=YYY
Description=64-bit JethroData DSII
Driver=/opt/jethro/jethroodbc/lib/libJethroODBC64.dylib
DriverODBCVer=03.80
SQLLevel=1

ODBC Manager

  1. Open ODBC Manager, Navigate to 'Drivers' tab, and click on 'Add...':

  2. Enter the following details:
    1. Driver Name: JethroODBCDriver
    2. Driver File: /opt/jethro/jethroodbc/lib/libJethroODBC64.dylib

    3. Add the following Keywords and Values:

      KeywordValue
      APILevel1
      ConnectFunctionsYYY
      Description64-bit JethroData DSII
      DriverODBCVer03.80
      SQLLevel1
  3. Click on 'OK' to save the driver.

Setting a new connection (DSN)

To setup a DSN based connection to a Jethro instance on Mac, create a user/system DSN with the instance connection details, depending on the type of DSN you create:

User DSNs: ~/Library/ODBC/odbc.ini

System DSNs: /Library/ODBC/odbc.ini

To create a DSN, either use ODBC Manager, or edit the appropriate odbc.ini file manually.

Manually

Create/Edit the ODBC.ini file, (located at /Library/ODBC/odbc.ini for system DSN) and add the following configs into the file:

To connect to a single Jethro server, specify:

    • SERVER- Host name or IP address of the machine that runs JethroServer.
    • PORT - The port to which JethroServer listens, on the machine running JethroServer (The default port is 9111, but the actual port number can be verified on the jethro server machine, by viewing the configuration file $JETHRO_HOME/instances/services.ini)

To connect to multiple Jethro servers, by using the driver client-side load balancing feature, specify:

In both cases, also specify:

    • DATABASE -The name of the Jethro instance on the server.
    • UID & PWD - The Default username & password is jethro.
    • [<DSN name>] - see the example below
    • Driver - under [ODBC Data Sources], add <DSN name>=JethroODBCDriver (see the example below)

For example:

[ODBC Data Sources]
JethroDataDSII=JethroODBCDriver

[JethroDataDSII]
Description=64-bit JethroData DSII
Driver=/opt/jethro/jethroodbc/lib/libJethroODBC64.dylib
Locale=en-US
UID=jethro
PWD=jethro
SERVER=jethro01.mycorp.com
PORT=9111
DATABASE=demo

ODBC Manager

  1. Open the ODBC Manager and navigate to the appropriate DSN you wish to create (System DSN or User DSN)

  2. Click on 'Add...'

  3. Select JethroODBCDriver

  4. Enter the name of the DSN and optionally a description.

  5. Add the following Keywords and Values:

    KeywordValue
    Locale
    en-US
    SERVER

    DATABASE

    PORT

    UID

    PWD

  6. As for the empty 'values' in the table above, edit them according to your connection details:

    To connect to a single Jethro server, specify:

        • SERVER- Host name or IP address of the machine that runs JethroServer.
        • PORT - The port to which JethroServer listens, on the machine running JethroServer (The default port is 9111, but the actual port number can be verified on the jethro server machine, by viewing the configuration file $JETHRO_HOME/instances/services.ini)

       To connect to multiple Jethro servers, by using the driver client-side load balancing feature, specify:

       In both cases, also specify:

        • DATABASE -The name of the Jethro instance on the server.
        • UID & PWD - The Default username & password is jethro.
  7. Click on 'OK' to save the new DSN connection.

Setting a new connection (DSN-less)

Some BI applications allow setting up a DSN-less connection. The interface for setting up a DNS-less connection is BI tools specific, and it should generate a Jethro ODBC connection string. Jethro recommends using a DSN connection if possible, but some tools requires DSN-less connection string only.

To connect to your instance without a DSN, provide your application with a connection string. The elements format of the connection string are:

DRIVER={JethroODBCDriver};HOST={host};PORT={port};INSTANCE={instance_name};UID={user};PWD={password};

For example:

DRIVER=JethroODBCDriver;HOST=localhost;PORT=9111;INSTANCE=demo;UID=jethro;PWD=jethro;

Tableau Datasource Customization (TDC)

If Tableau is installed, Jethro will need a jethro specific connection settings for Tableau, to be copied into the required Tableau directory. To do so:

  1. Copy the TDC file from: /<INSTALLATION-PATH>/jethro/jethroodbc/conf/jethro.tdc       (By default <INSTALLATION-PATH> is '/opt/')
  2. Locate it under your repository: Documents/My Tableau Repository/Datasources

Testing the connection

To test the connection, use any BI or query tool of your choice. Here are two examples using iODBC:

  1. iODBC administrator offers a built in 'Test' button whithin the DSN tab.
  2. Using a Terminal screen:

    1. Type 'iodbctest'

    2. Type '?' to see all the DSNs defined
    3. Type DSN=<DSN-name> (don't use '<>')
    4. If the connection succeded, you should see 'SQL>'
    5. According to your schema, run any query and verify the results

Troubleshooting Connection Issues

If connection with the client is not successfully established, check the following troubleshooting suggestions:

  • Verify that the JethroServer process is running on the server provided.
  • Verify that the JethroServer port is accessible from the client (no firewalls are blocking the connection).
  • Check the ODBC logs for valuable information (by default, located on /var/log/jethro/odbc/).
    To enable logging:
    1. Edit <INSTALLATION-PATH>/jethro/jethroodbc/lib/JethroODBC.ini, and set LogLevel to 6. 
    2. Restart your BI application to create a new session.

    Please notice

    - In order to use the logs, you should provide the right permissions (write) for the user of the application. For example if user john is using iodbctest with Jethro ODBC driver, this user should have permission for write to the logs folder (usually /var/log/jethro/jethroodbc).

    - Reinstalling the driver (upgrade/downgrade) will overide all the files installed, including the conf files (JethroODBC.ini). This means that if, for example the logs were enabled, after upgrading the logs will behave as default ("off").

  • If you receive ODBC system error 193 when trying to connect – this is a generic ODBC error message meaning that a 32-bit application is trying to use a 64-bit driver. Ensure that you use a 64-bit version of the client application (BI tool and so on).

Uninstalling

In order to uninstall the driver, perform the following steps:

  1. Remove /opt/jethro and its content
  2. Remove /var/log/jethro and its content
  3. Remove Jethro's configurations from odbc.ini and odbcinst.ini

Configure Jethro ODBC connections with BI applications

Any general-purpose BI/SQL query tool that supports the SQL-92 standard should be able to connect with Jethro.

The instructions below refer to Tableau, Qlik Sense, MicroStrategy, and SAS JMP, but other tools would most probably require a similar process to establish that connection.

Please note

The instructions are not Mac specific.