Omnis Technical Note TNSQ0010b January 2017, Updated July 2019

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

For Omnis Studio 8.0 and later
By Gary Ashford

Introduction

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 instantclient-basic-macosx-11.2.0.4.0.zip.
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.

Example. Create Symbolic Links from the Local User's lib folder. (~/lib)

On the Mac, the standard library search path includes: /usr/lib, /usr/local/lib and ~/lib.

Please note: We no longer advise placing third-party library inside the Omnis.app/Contents/Frameworks folder. This breaks the code signature of the Omnis app and causes a malware warning in newer versions of macOS.

To create symbolic links from the local user's lib folder (~/lib), open a terminal window and type the following::

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. instantclient-basic-macos.x64-12.2.0.1.0.zip 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 links would change to:

ln -s ~/instantclient_12_2/libclntsh.dylib.12.1 libclntsh.dylib.11.1
ln -s ~/instantclient_12_2/libociei.dylib libociei.dylib
ln -s ~/instantclient_12_2/libnnz12.dylib libnnz12.dylib
ln -s ~/instantclient_12_2/libons.dylib libons.dylib    (note the additional library dependency)

Note for Omnis Studio 10.0 and later. Please note that the Oracle DAM in Omnis Studio 10.0 and later is linked against "libclntsh.dylib", i.e. there is no dependency on a specific version number. In this case, the above example becomes:

ln -s ~/instantclient_12_2/libclntsh.dylib.12.1 libclntsh.dylib
ln -s ~/instantclient_12_2/libociei.dylib libociei.dylib
ln -s ~/instantclient_12_2/libnnz12.dylib libnnz12.dylib
ln -s ~/instantclient_12_2/libons.dylib libons.dylib

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:

TNS_ADMIN=~/instantclient_11_2
NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1

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.

Troubleshooting

  • 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. Omnis Studio 8.0 and later for macOS 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

You can also verify that the symbolic links are created correctly by typing:

cd ~/lib    (or cd /Applications/"Omnis....app"/Contents/Frameworks folder if you followed Example 2)
otool -L libcntsh.dylib.11.1    (or libcntsh.dylib if using Omnis Studio 10.x)

In the returned information, there should be no dependencies listed as "not found".

 

References: Using SQL*Plus Instant Client 11.2 on OS X El Capitan (https://blogs.oracle.com/opal/entry/using_instant_client_11_2)

 

Search Omnis Developer Resources

 

Hit enter to search

X