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 |
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.