Log In    |    Knowledge Base    |    4D Home
Tech Tip: Installing 4D for OCI on Mac OS X
Published On: June 23, 2006

In order to use the 4D for OCI plug-in on a Mac OS X machine you need to have an Oracle Client installed . The same is true for Windows but the situation on Mac OS is a complicated by the fact that Oracle does not support the installation of the Oracle Client on a Mac OS X machine (installation instructions are only provided for OS X Server). While the installation of a full Oracle client is possible on a non-Server OS X machine, it is not a trivial process.

There is a simpler alternative that involves installing a smaller set of files to get 4D for OCI working on your Mac OS X machine.

This Tech Tip contains steps for both the Oracle 10g Client and Oracle 8.1.7 Client.

Oracle 10g Instant Client Instructions:

To install the OCI Library on Mac OS X, the Oracle 10g Instant Client for Mac OS X can be used. You can download the Instant Client at this location:

The file you want is called "" (if a newer version is available you may be able to try these same steps with that version, just keep in mind the version these steps pertain to if it does not work).

Here are the steps to perform to install the Instant Client and make it work with 4D for OCI:

NOTE: All Terminal commands are CASE SENSITIVE!

  1. Install the Oracle 10g Instant Client files to the proper location:

    To get the Instant Client working with 4D for OCI the files must be in a directory called "/Oracle". Additionally you need the files to be owned by "root". Here are the steps to place the files in the proper location:

    • Extract the "" archive to your desktop. This will create a folder called "instantclient10_1".
    • Open a Terminal window.
    • Execute the command 'sudo sh'. This opens an sh shell as root.
    • Enter your password when prompted. If you can not complete this step stop, you need 'sudo' access to do this install.
    • Execute the command 'mkdir /Oracle'.
    • Type 'cp ' and then drag the "instantclient10_1" folder from your desktop to the Terminal window. Do not press return.
    • Type backspace, then '/* /Oracle'. At this point the command should look like:
      sh-2.05b# cp /Desktop/instantclient10_1/* /Oracle

    • Press return. This will copy all of the Instant Client files to the "/Oracle" folder.
    • Keep the terminal window open and move to step 2.

  2. Copy the required Oracle library to the proper location:

    • Execute the command 'cp /Oracle/libclntsh.dylib.10.1 /usr/lib/libclntsh.dylib'.
    • Execute the command 'chmod 777 /usr/lib/libclntsh.dylib'.
    • Execute the command 'exit'. This takes you out of "root" mode.
    • Keep the terminal window open and move to step 3.

  3. Create/Update an "environment.plist" file for the user that will be using 4D for OCI:

    • Execute the command 'cd ~'. This takes you to your home directory.
    • Execute the command 'mkdir .MacOSX'. Note the '.' is required.
    • You now need to create a file called "environment.plist". This is a Macintosh properties file and is a plain text, XML file. How you create it will vary depending on how your machine is set up. E.g. there is a Property List Editor in Mac OS X that you can use. You can also use a plain text editor, or 'vi' from the Terminal. However when you create the file, the contents should be:
      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "">
      <plist version="1.0">

    • If you did not create this file in the ".MacOSX" folder, move it there. You may need to do this from a Terminal as, by default, Finder does not display folders that start with a '.' (these are hidden folders in *nix). To copy the file from a Terminal execute the following command:
      cp /environment.plist ~/.MacOSX

    • Once the file is in place, log out and log back in.

      Note: If you do not want to install the Instant Client files to /Oracle you must use the 4D for OCI command "OCISetEnv" to set the values for "ORACLE_HOME", "ORA_NLS33" and "TNS_ADMIN". The 4D for OCI plug-in uses the following values as defaults (as seen in "environment.plist"):


  4. Create a TNSNAMES.ORA file:

    Just like in a Windows setup, the TNSNAMES.ORA file should be created and properly configured to set the target IP address of the oracle machine. Here are the steps to do this:

    • Create a TNSNAMES.ORA file using a text editor and type entries like the example below:
      oracle4d =
      (ADDRESS = (PROTOCOL =TCP)(HOST = = 1521))
      (SERVICE_NAME = oracle4d)

      Make sure you have the correct IP address for your Oracle server provided in the HOST parameter.
    • Open your Terminal window and copy the file to /private/etc directory.

You should now be able to use the 4D for OCI plug-in with your Oracle 10g Instant Client.

Note: If the 4D for OCI plug-in shows as "disabled" in the Components page of the Explorer window this usually means the OCI Library was not installed properly or could not be found. Double-check that you correctly completed the above steps.

Oracle 8.1.7 client instructions:

You will need to download the Oracle client files found here:

Select the link labeled "Oracle 8i v8.1.7.1 OCI / Mac OS X download".

The library you need to install to make 4D for OCI work is called "libclntsh.dylib".

This needs to be installed to /usr/lib on your Mac.

The above download should contain a zip file named "". Extract this. The file "libclntsh.dylib" is in the "Oracle_8.1.7.1_Client\lib" directory. To install the library:

  1. Open a Terminal Window.
  2. Type "sudo sh" and press RETURN.
  3. Enter your password (you need an admin password).
  4. Type "cp " and then drag the "libclntsh.dylib" file into the Terminal window (or type the path out).
  5. You should see something like:
    sh2.05b# cp /blah/Oracle_8.1.7.1_Client/lib/libclntsh.dylib

  6. Type "/usr/lib/libclntsh.dylib" and press RETURN.

That should do it, the 4D for OCI plugin should now work with the Oracle 8.1.7 client.