DbVisualizer is a database management and analysis tool for all major databases (e.g. Oracle, SQL Server, DB2, Sybase, MySQL, SQLite) on Windows, macOS, Linux and Unix platforms. Installing an Oracle database on a Mac computer is a bit different to installing it on a Windows or Linux computer. Oracle doesn’t support running an Oracle database directly on a Mac computer. You can’t install Oracle Express, for example, in the same way that you can on a Windows computer. The good news is that you can use a Virtual Machine.

Omnis Technical Note TNSQ0010a November 2009

Using Oracle Instant Client with an Intel Mac

For Omnis Studio 4.3/5.0
By Gary Ashford

Download the Oracle Instant Client Basic, SDK and SQL.Plus ZIP files. Unzip them, create the two symbolic links given in the install instructions, and set DYLDLIBRARYPATH to the Instant Client directory. Update: with Instant Client 12.1, you do not need to set DYLDLIBRARYPATH.

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.

Overview

At Indiana University, to download the Oracle 12c client for Windows, use either of the following methods:

Oracle Thin Client Connection String

• Download directly from Oracle's website: This method requires a valid OTN (Oracle Technology Network) username and password. If you do not have a valid OTN username and password, visit Oracle Database Software Downloads. At the top, hover over 'Sign In', click Create an account, and then follow the on-screen instructions.
• Download from IUware: This method requires a valid IU username and passphrase.

For either download method, you must be logged into your computer as an administrator.

Download the client directly from Oracle's website

To download the Oracle client directly from Oracle's website:

1. Go to Oracle Database Software Downloads.
2. Under 'Oracle Database 12c Release 1', below '(12.1.0.2.0) - Enterprise Edition', to the far right of 'Microsoft Windows x64 (64-bit)', click See All.
3. Click OTN License Agreement, read the license agreement, and then close the window.
4. Select Accept License Agreement. You will see a notification thanking you for accepting the OTN License Agreement and permitting you to download the software.
5. Scroll down to the appropriate Oracle client for your operating system:
   • 32-bit: Under 'Oracle Database Client (12.1.0.2.0) for Microsoft Windows (32-bit)', click winnt_12102_client32.zip. This file requires 826.1 MB of free space on your hard drive.
   • 64-bit: Under 'Oracle Database Client (12.1.0.2.0) for Microsoft Windows (x64)', click winx64_12102_client.zip. This file requires 846.3 MB of free space on your hard drive.

   You may be prompted to enter a valid OTN username and password. Once you have done so, you will see the 'File Download' dialog box. If you do not have an OTN username and password, see the instructions for getting one above.

6. Save the file.
7. In Windows, navigate to the file, right-click it, and then select Extract all.
8. Select a destination folder for the extracted files, and then perform the extraction.
9. To launch the Oracle Client Installer, go to the destination folder, open the client directory, and then double-click setup.exe (the Oracle 12c setup file).

   At this point:

   • Windows may prompt you for an administrator username and password. Enter an administrator username and password to proceed.
   • Windows may present an 'Open File - Security Warning' dialog box. Click Run to proceed.

   It may take a minute for the 'Oracle Client Installer' window to appear. To see it, you may need to minimize any other application windows that are open.

Download the client from IUware

To download the Oracle client from IUware:

Oracle Thin Client Driver Download

1. Go to Oracle Client 12c and select the Oracle version that corresponds to your operating system (32-bit or 64-bit).
2. If you see a button that says Log in for access, click it. If prompted, log in with your IU username and passphrase.
3. Under 'DOWNLOADS', click the .exe file listed (either Oracle 12c Client 32-bit.exe - 826.1 MB for 32-bit, or Oracle 12c Client 64-bit.exe - 853 MB for 64-bit).
4. In the 'File Download - Security Warning' dialog box, click Save, select a destination folder, and then click Save.

   You may see a warning similar to 'Oracle 12c Client . . . is not commonly downloaded and could harm your computer.' It is safe to ignore this warning and close the dialog box.

5. When the download is complete, to open the IUware installer, go to the destination folder, and then double-click the Oracle .exe file you just downloaded.
6. You'll see an 'Open File - Security Warning' dialog box. Click Run.
7. A '7-Zip self-extracting archive' dialog box will open. For 'Extract to:', either accept the default (for example, c:usernameDownloads), or change to another directory to which to extract the contents of this file. Click Extract. The extraction will take a few minutes.
8. In the extraction directory you specified above, double-click the folder called Oracle 12c Client 32-bit or Oracle 12c Client 64-bit.
9. Double-click the client folder.
10. Double-click the setup file (of type 'Application', not 'Configuration Settings') to start the installation process.

    It may take a minute for the 'Oracle Client Installer' window to appear. To see it, you may need to minimize any other application windows that are open.