Omnis Technical Note TNSQ0010 July 2006 (updated Nov 2009)

Using Oracle Instant Client with PPC Mac

For Omnis Studio 3.x/4.x
By Gary Ashford (Omnis). With thanks to Gary R. Schaecher (TMA Systems, LLC)

Introduction

This technical note pertains to the Oracle Instant Client- basic package available (at time of writing) from Oracle's website: instantclient-basic-macosx-10.1.0.3.zip and is relevent to Omnis Studio 4.1.1

If you are using an Intel Mac, please refer to Technote TNSQ0010a instead which contains revised notes.

About Oracle Instant Client (for PPC architecture)

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

The following procedure assumes that you have write permission to the /usr/local/lib folder on your system. If this folder does not exist you should obtain the root user's password and create it before proceeding.

1. Unzip instantclient-basic-macosx-10.1.0.3.zip and copy the files highlighted above into the appropriate folder.
Copy the files into the /usr/local/lib folder. Copying files here ensures that the dynamic loader will be able to locate the libraries at runtime. Note: To get the Finder to show the contents of the /usr/local/lib folder you should use the Go & Go to Folder... menu commands. You will also be prompted to 'Authenticate' before you are allowed to paste files into this location.
If it is not possible (or desirable) to copy files into /usr/local/lib, it *may be possible to edit your user's environment.plist file instead and add an entry for DYLD_LIBRARY_PATH. In this way the dynamic loader will also search in the location you specify. TechNote TNSQ0009 has details on how to create/edit this file. Assuming an install location of /Oracle, you should create this folder as appropriate and copy the files into this folder instead.

*Some system configurations overwrite the value of DYLD_LIBRARY_PATH after reading from the environment.plist file, in which case this procedure will not work.

2. Create a symbolic link to the Client Library.
This step is necessary becasue the Oracle DAM's bundle file (xoracle.bundle) is linked against libclntsh.dylib (and not libclntsh.dylib.X.X) as shipped by Oracle.
Using a terminal window, enter the following commands

sudo sh                                     (enter root password when prompted)
cd /usr/local/lib                          (or /Oracle, as appropriate)
ln -s libclntsh.dylib.10.1 libclntsh.dylib

Without this symbolic link the DAM will not load and the Omnis trace log will report an error.

3. Edit your Omnis xcomp/ini/damora.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 damora.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=/Oracle
NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1

where /Oracle is the location of your tnsnames.ora file. Note that if you have copied the client libraries into /usr/local/lib, the /Oracle folder will be empty apart from this single file.

4. (Close &) Re-Open Omnis Studio.
Closing Omnis ensures that any existing environment variable settings (i.e. ORACLE_HOME) are discarded. (Environment variables set via damora.ini persist for the life of the Omnis process).
You should now be able to log on to Oracle via the DAM using any of the tnsnames specified in your tnsnames.ora file.