Omnis Technical Note TNSQ0010b January 2017

Using Oracle Instant Client with MacOSX 10.11 "El Capitan" and later

For Omnis Studio 8.0 and later
By Gary Ashford


This tech note concerns Oracle Instant Client 11.2 for Mac-Intel 64-bit architecture, which at the time of writing is available to download from Oracle's website.
The procedure outlined here is also relevant to MacOSX 10.9 (Mavericks) and MacOSX 10.10 (Yosemite) as well as the newer macOS 10.12 (Sierra). There is also an older version of this technote, in case you are using a version of MacOSX pre-10.9, available here: tnsq0010a.

About Oracle Instant Client

Oracle Instant Client is a free, re-distributable version of the Oracle Client which provides the OCI and JDBC client libraries used by most OCI applications. The benefits of Instant Client are that it provides all the functionality of the full client with only a fraction of the download overhead. The Basic package provides the following files:

libclntsh.dylib.11.1 OCI API C client library
libnnz11.dylib Security library
libocci.dylib.11.1 OCI API C++ code library
libociei.dylib OCI Instant Client data shared library
ojdbc5.dylib Oracle JDBC driver for JDK 1.5
ojdbc6.jar Oracle JDBC driver for JDK 1.6

Of these, only the three files marked in bold are required in order to use the Omnis Studio Oracle DAM.
In addition to these files one other file may be needed; the tnsnames.ora file- which contains a list of Oracle database connections (service names). This can be copied from a full client install if necessary (created using a Net Configuration Assistant). Care should be taken if creating/editing this file manually as OCI is very particular about syntax.

Setting-up Oracle Instant Client

1. Download and Unzip
The compressed files will extract to a folder named instantclient_11_2. It is advisable to move this folder into your $HOME directory (CMD+SHIFT+H using the Finder) so as to avoid any potential problems with Mac System Integrity Protection (SIPs).
Your Oracle client files will exist at the following location:

  /Users/myUser/instantclient_11_2   or simply    ~/instantclient_11_2

2. Provide the Location of the Client Libraries
Before the Oracle DAM will load, the location of the Oracle Client library and its dependencies needs to be provided. Failure to provide the operating system with the location of the client library usually results in the following error in the Omnis Trace Log:

damora8.u_xcomp component couldn't be loaded because the code fragment is missing.

The recommended way to locate the client libraries is to create symbolic links from a location on the standard library search path using a terminal window as follows:

cd ~
mkdir lib    (in case this directory does not already exist)
cd lib
ln -s ~/instantclient_11_2/libclntsh.dylib.11.1 libclntsh.dylib.11.1
ln -s ~/instantclient_11_2/libociei.dylib libociei.dylib
ln -s ~/instantclient_11_2/libnnz11.dylib libnnz11.dylib

Once created, any Oracle DAM that is linked against libclntsh.dylib.11.1 should load successfully when you open Omnis.
If you download a newer version of Instant Client, e.g. then you will need to adjust the symbolic links and directory names accordingly. Please note however that the Oracle DAMs supplied with Studio 8.0.x are linked against libclntsh.dylib.11.1, so in this case the symbolic link would change to:

ln -s ~/instantclient_12_1/libclntsh.dylib.12.1 libclntsh.dylib.11.1

3. Edit your Omnis xcomp/ini/oracle8dam.ini file.
This file is used to set additional environment variables required by the Oracle client library.
NLS_LANG is used to set the language, territory and character set (the locale) to be used.
TNS_ADMIN is used to indicate the folder that contains the tnsnames.ora file. If tnsnames.ora will reside in the same folder as the client libraries, then oracle8dam.ini might look like this:


4. Open Omnis Studio.
You should now be able Open Omnis Studio and log on to Oracle via the DAM using any of the service names specified in your tnsnames.ora file.


  • If you receive the following error when attempting to login:
Oracle Internal Error - Invalid Handle

please check that you have downloaded and installed the 64-bit version of Oracle Instantclient. The COCOA edition of Omnis Studio is not compatible with 32-bit libraries.

  • DAM not loaded?

Check the Omnis Trace Log for the error mentioned above. This message indicates that libclntsh.dylib.11.1 still cannot be found, in which case you should double-check the symbolic links created earlier, e.g. by executing:

ls -al ~/lib/instantclient.dylib.11.1   and
file ~/lib/instantclient.dylib.11.1

The latter should produce output similar to:

Mach-O 64-bit dynamically linked shared library x86_64


References: Using SQL*Plus Instant Client 11.2 on OS X El Capitan (