Developers

Omnis Technical Note TNSQ0010c March 2021

Using Oracle Instant Client with macOS 11 "Big Sur" and Later

For Omnis Studio 10.2 and later
By Gary Ashford

Introduction

This tech note concerns Oracle Instant Client 19.1 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.15 (Catalina) and MacOSX 11.0 (Big Sur). There is also an older version of this technote, in case you are using a version of MacOSX pre-10.15, available here: tnsq0010b.

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 BasicLite package provides the following files:

libclntsh.dylib -> libclntsh.dylib.19.1	OCI API C client library
libnnz19.dylib	Security library
libclntshcore.dylib.19.1	NLS and core functionality
libocci.dylib -> libocci.dylib.19.1	Oracle C++ Call Interface library
libociei.dylib	OCI Instant Client data shared library

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 open the applicable ZIP or DMG archive.
For example: instantclient-basiclite-macos.x64-19.8.0.0.0dbru.dmg.

2. Install the client libraries
To do this, copy the required dylibs (plus the symlink; libcntsh.dylib) into the /usr/local/lib folder (creating this folder if necessary).

Once created, the Studio 10.2 Oracle DAM (which links against libclntsh.dylib) should load successfully when you open Omnis Studio. If you download a newer version of Instant Client, then the same principle applies albeit with different file version numbers.

Note: Newer releases of Instant Client are code-signed by Oracle. This means that libclntsh.dylib can be placed into the /usr/local/lib folder and Studio is permitted to open it. If you are using a version of Instant Client that is not code-signed, you will need to place client files inside the Omnis Studio.app/Frameworks or Omnis Studio.app/MacOS folder instead.

3. Edit your Studio config.json file.
The file can be found in your writable files folder, for example:
/Users/myUser/Library/Application Support/Omnis/Omnis Studio 10.2 29802/studio/config.json

This file can be used to set additional environment variables required by the Oracle client library.
Edit this file using TextEdit, and locate the "macOS" section which contains a key named "oracledam.ini"
(Note: Prior to Omnis Studio 11, this key was named; "oracle8dam.ini")
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. For example:

The above example assumes that your tnsnames.ora file will be placed directly in your home folder. Note that the full path must be specified; the short-cut tilde (˜) character cannot be resolved.
Also, note that the BasicLite package has English error messages and Unicode, ASCII, and Western European character set support only, i.e. you should use AMERICAN_AMERICA.WE8ISO8859P1 for localisation and character set.

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.

In case of problems, open the Omnis Trace Log and verify that there is no error message relating the DAMORA8 component. Any such error indicates that there was a problem opening the client library (libclntsh.dylib), i.e. the symlink or one of the dependent libraries needed by libclntsh.dylib.19.1 was not found.

Please check that you have downloaded and installed the x86_x64 version of Oracle Instantclient. Omnis Studio 10.2 is not compatible with native (ARM) arcitecture used by newer Macs.