Omnis Technical Note TNSQ0010a November 2009

Using Oracle Instant Client with an Intel Mac

For Omnis Studio 4.3/5.0
By Gary Ashford

Introduction

This technical note pertains to the Oracle Instant Client 10.2 for Mac-Intel architecture, which at the time of writing is available for download from Oracle's website.

  • If you are using an older Mac with PPC architecture, please refer to Technote TNSQ0010 instead which contains the original version of this Technote.

About Oracle Instant Client

Oracle Instant Client is a free, re-distributable cut-down version of the full Oracle client which provides just 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 Mac package provides the following files:

classes12.jar JDBC support file
libclntsh.dylib.10.1 OCI API C client library
libnnz10.dylib Security library
libocci.dylib.10.1 OCI API C++ code library
libociei.dylib OCI Instant Client data shared library
libjdbc10.dylib JDBC API library
ojdbc.jar Oracle JDBC driver

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. 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-10.2.0.4.0.zip.
The compressed files will extract to a folder named instantclient_10_2. It is advisable to move this folder to the root of the primary volume such that the Oracle client files will exist at the following location:

  /instantclient_10_2

2. Provide the Location of the Client Library
Before the Oracle DAM will load, the location of the Oracle Client library 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.

Technote TNSQ0025 describes several ways in which the location of client libraries can be specified.
In summary however there are two ways of achieving this:

  • Copy or place a link to the client library to a location already on the operating system's standard library seach path, i.e. inside /usr/lib or /usr/local/lib.
  • Tell the operating system to look in an additional location for the client library. This is achieved by setting or modifying the DYLD_LIBRARY_PATH environment variable.

To create a symbolic link to the client library inside the /usr/lib or /usr/local/lib folder you need to have root permissions. The symbolic link is typically created as follows:

su root
cd /usr/lib
ln -s /instantclient_10_2/libclntsh.dylib.10.1 libclntsh.dylib.10.1

To set the DYLD_LIBRARY_PATH variable, you can either edit the user's environment.plist file or set DYLD_LIBRARY_PATH in the context of a terminal session. In the latter case however, you will need to start Omnis from the command line since the environment variable only exists for the terminal session:

cd /Applications
export DYLD_LIBRARY_PATH=/instantclient_10_2
open "Omnis Studio 5.0.app"

Alternatively, Technote TNSQ0025 discusses the environment.plist file which can be used to set environment variables globally. Using this approach Omnis can be started as normal by double-clicking on the Omnis icon.

3. Edit your Omnis xcomp/ini/oracle8dam.ini file.
In order to use Oracle Instant Client in "thin client mode" you must ensure that ORACLE_HOME is not set. Leaving this entry in your oracle8dam.ini file prompts the client library to behave as a "fat client". In this mode the DAM will fail to log on unless certain files are copied from an existing full Oracle Client install. You should replace the ORACLE_HOME entry with a TNS_ADMIN entry instead which is used to locate your tnsnames.ora file. Thus, your damora.ini file should look similar to:

TNS_ADMIN=/instantclient_10_2
NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1

where /instantclient_10_2 is the location of your tnsnames.ora file. The tnsnames.ora file should be copied from an existing oracle client installation or created on a platform which provides a client configuration utility.

If using environment.plist, it may be noted that the damora.ini file can be discarded if required: the environment variables contained here can be moved into the environment.plist file instead.
Conversely, if running Omnis from the command prompt, you can set these environment variables explicitly or via a custom startup script if required.

4. Open Omnis Studio.
(Please note that the users needs to log-out and back in again in order for changes to environment.plist to take effect.) Otherwise, you should now be able to log on to Oracle via the DAM using any of the tnsnames 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 32-bit version of Oracle Instantclient. Omnis Studio is not compatible with 64-bit libraries.