ODBC Driver for Mac
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
- MacOS version 10.12.6 (Sierra)
- 51 MB of available disk space
- iODBC version 3.52.12 installed or ODBC Manager 1.0.12 installed
Installation
To install the ODBC driver:
In Finder, Control-click or right click the icon of the app.
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.
Click Open in the dialog box. If prompted, enter an administrator name and password.
The installer installs the ODBC driver files in the following directories:
<INSTALLATION-PATH>/jethro/jethroodbc/lib/ (By default <INSTALLATION-PATH> is '/opt/')
/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
- Open the configuration file '/Library/ODBC/odbcinst.ini' in a text editor. If the file doesn't exist, create it.
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
Open ODBC Manager, Navigate to 'Drivers' tab, and click on 'Add...':
- Enter the following details:
- Driver Name: JethroODBCDriver
- Driver File: /opt/jethro/jethroodbc/lib/libJethroODBC64.dylib
Add the following Keywords and Values:
Keyword Value APILevel 1 ConnectFunctions YYY Description 64-bit JethroData DSII DriverODBCVer 03.80 SQLLevel 1
- 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:
- SERVER - A list of host:port pairs, separated by semi-colons (or alternativaly - commas). For example: jethro01.mycorp.com:9111;jethro02.mycorp.com:9111;jethro03.mycorp.com:9111
- PORT - Leave empty.
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
Open the ODBC Manager and navigate to the appropriate DSN you wish to create (System DSN or User DSN)
Click on 'Add...'
Select JethroODBCDriver
- Enter the name of the DSN and optionally a description.
Add the following Keywords and Values:
Keyword Value Locale
en-US
SERVER
DATABASE
PORT
UID
PWD
- 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:
- SERVER - A list of host:port pairs, separated by semi-colons (or alternativaly - commas). For example: jethro01.mycorp.com:9111;jethro02.mycorp.com:9111;jethro03.mycorp.com:9111
- PORT - Leave empty.
In both cases, also specify:
- DATABASE -The name of the Jethro instance on the server.
- UID & PWD - The Default username & password is jethro.
- 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:
- Copy the TDC file from: /<INSTALLATION-PATH>/jethro/jethroodbc/conf/jethro.tdc (By default <INSTALLATION-PATH> is '/opt/')
- 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:
- iODBC administrator offers a built in 'Test' button whithin the DSN tab.
- Using a Terminal screen:
Type 'iodbctest'
- Type '?' to see all the DSNs defined
- Type DSN=<DSN-name> (don't use '<>')
- If the connection succeded, you should see 'SQL>'
- 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:- Edit <INSTALLATION-PATH>/jethro/jethroodbc/lib/JethroODBC.ini, and set LogLevel to 6.
- 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:
- Remove /opt/jethro and its content
- Remove /var/log/jethro and its content
- 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.