2. Installing ODPI-C

2.1. Overview

To use ODPI-C in your own project, download its source from GitHub. A sample Makefile is provided if you wish to build ODPI-C as a shared library. Otherwise, add the ODPI-C source code to your project. On Windows, Visual Studio 2008 or higher is required. On macOS, Xcode 6 or higher is required. On Linux, GCC 4.4 or higher is required.

ODPI-C has been tested on Linux, Windows and macOS. Other platforms should also work but have not been tested.

Projects using ODPI-C require Oracle Client libraries to be installed. The libraries provide the necessary network connectivity allowing applications to access an Oracle Database instance. They also provide basic and advanced connection management and data features to ODPI-C applications.

2.1.1. Oracle Client Library Loading

The simplest Oracle Client is the free Oracle Instant Client. Only the “Basic” or “Basic Light” package is required. Oracle Client libraries are also available in any Oracle Database installation or full Oracle Client installation.

ODPI-C dynamically loads available Oracle Client libraries at runtime. This allows code using ODPI-C to be built only once, and then run using any available Oracle Client 21, 19, 18, 12, or 11.2 libraries. If Oracle Client libraries are not found, the error “DPI-1047: Cannot locate an Oracle Client library” is raised. If an Oracle Client library is found but the version cannot be determined, the error “DPI-1072: the Oracle Client library version is unsupported” is raised. For example, this could be because the Oracle Client library version is too old (prior to 10g) or entirely unsupported (such as Oracle Client 19 on Windows 7).

If the member dpiContextCreateParams.oracleClientLibDir is specified when calling dpiContext_createWithParams(), then only that directory is searched for the Oracle Client libraries.

If no directory is specified, then the Oracle Client libraries are looked for in the same directory that the ODPI-C library (or application binary) is located in. If they are not found, then they are searched for in the standard operating system search path, for example PATH on Windows or LD_LIBRARY_PATH on Linux. See standard Windows library search order or standard Linux library search order. Finally, on platforms other than Windows, $ORACLE_HOME/lib is also searched.

Note

• When using Instant Client on Linux and related operating systems, then that directory must always be in the system library search path.

• When using the library directory from a full client or database installation, then you additionally need to set the application environment to use this software, for example by setting the ORACLE_HOME environment variable. This should be done prior to ODPI-C initialization.

Make sure the application has directory and file access permissions for the Oracle Client libraries. On Linux ensure libclntsh.so exists. On macOS ensure libclntsh.dylib exists. ODPI-C will not directly load libclntsh.*.XX.1 files in dpiContextCreateParams.oracleClientLibDir or from the directory where the ODPI-C library (or application binary) is. Note other files used by libclntsh* are also required.

To trace the loading of Oracle Client libraries, the environment variable DPI_DEBUG_LEVEL can be set to 64 before starting your application. See ODPI-C Debugging.

The following sections explain how to ensure the Oracle Client is installed and configured correctly on the various platforms so that ODPI-C is able to find it.

2.1.2. Oracle Client and Oracle Database Interoperability

Oracle’s standard client-server network interoperability allows connections between different versions of Oracle Client and Oracle Database. For certified configurations see Oracle Support’s Doc ID 207303.1. In summary, Oracle Client 21 can connect to Oracle Database 12.1 or later. Oracle Client 19, 18 and 12.2 can connect to Oracle Database 11.2 or greater. Oracle Client 12.1 can connect to Oracle Database 10.2 or greater. Oracle Client 11.2 can connect to Oracle Database 9.2 or greater. The technical restrictions on creating connections may be more flexible. For example Oracle Client 12.2 can successfully connect to Oracle Database 10.2.

Since a single ODPI-C binary can use multiple client versions and access multiple database versions, it is important your application is tested in your intended release environments. Newer Oracle clients support new features, such as the oraaccess.xml external configuration file available with 12.1 or later clients, session pool improvements, call timeouts with 18 or later clients, and other enhancements.

The function dpiContext_getClientVersion() can be used to determine which Oracle Client version is in use and the function dpiConn_getServerVersion() can be used to determine which Oracle Database version a connection is accessing. These can then be used to adjust application behavior accordingly. Attempts to use some Oracle features that are not supported by a particular client/server combination may result in runtime errors. These include:

• when attempting to access attributes that are not supported by the current Oracle Client library you will get the error “ORA-24315: illegal attribute type”

• when attempting to use implicit results with Oracle Client 11.2 against Oracle Database 12c you will get the error “ORA-29481: Implicit results cannot be returned to client”

• when attempting to get array DML row counts with Oracle Client 11.2 you will get the error “DPI-1050: Oracle Client library must be at version 12.1 or higher”

2.2. Linux

ODPI-C requires Oracle Client libraries, which are found in Oracle Instant Client, or an Oracle Database installation, or in a full Oracle Client installation, see Oracle Client Library Loading. The libraries must be either 32-bit or 64-bit, matching your application and ODPI-C library (if one is created separately).

2.2.1. Oracle Instant Client Zip Files

To run ODPI-C applications with Oracle Instant Client zip files:

1. Download an Oracle 21, 19, 18, 12, or 11.2 “Basic” or “Basic Light” zip file matching your application 64-bit or 32-bit architecture:

   • x86-64 64-bit

   • x86 32-bit

   • ARM (aarch64) 64-bit

2. Unzip the package into a directory that is accessible to your application. For example:

   mkdir -p /opt/oracle
   cd /opt/oracle
   unzip instantclient-basic-linux.x64-21.1.0.0.0.zip
   

3. Install the operating system libaio package with sudo or as the root user. For example:

   sudo yum install libaio
   

   On some Linux distributions this package is called libaio1 instead.

   On recent Linux versions, such as Oracle Linux 8, you may also need to install the libnsl package when using Oracle Instant Client 19.

4. If there is no other Oracle software on the machine that will be impacted, permanently add Instant Client to the runtime link path. For example, with sudo or as the root user:

   sudo sh -c "echo /opt/oracle/instantclient_21_1 > /etc/ld.so.conf.d/oracle-instantclient.conf"
   sudo ldconfig
   

   Alternatively, set the environment variable LD_LIBRARY_PATH to the appropriate directory for the Instant Client version. For example:

   export LD_LIBRARY_PATH=/opt/oracle/instantclient_21_1:$LD_LIBRARY_PATH
   

5. If you use optional Oracle configuration files such as tnsnames.ora, sqlnet.ora or oraaccess.xml, put the files in an accessible directory. Then set the member dpiContextCreateParams.oracleClientConfigDir when calling dpiContext_createWithParams().

   Alternatively, set the environment variable TNS_ADMIN to that directory name.

   Alternatively, create a network/admin subdirectory of Instant Client, if it does not exist. For example, with Instant Client 12.2:

   mkdir -p /opt/oracle/instantclient_12_2/network/admin
   

   Put the files in this directory. This is the default Oracle configuration directory for applications linked with this Instant Client.

2.2.2. Oracle Instant Client RPM Files

To run ODPI-C applications with Oracle Instant Client RPMs:

1. Download an Oracle 21,19, 18, 12, or 11.2 “Basic” or “Basic Light” RPM matching your application architecture:

   • x86-64 64-bit

   • x86 32-bit

   • ARM (aarch64) 64-bit

   Oracle’s yum server has convenient repositories:

   • Instant Client 21 RPMs for Oracle Linux x86-64 8, Older Instant Client RPMs for Oracle Linux x86-64 8

   • Instant Client 21 RPMs for Oracle Linux x86-64 7, Older Instant Client RPMs for Oracle Linux x86-64 7

   • Instant Client RPMs for Oracle Linux x86-64 6

   • Instant Client RPMs for Oracle Linux ARM (aarch64) 8

   • Instant Client RPMs for Oracle Linux ARM (aarch64) 7

2. Install the downloaded RPM with sudo or as the root user. For example:

   sudo yum install oracle-instantclient-basic-21.1.0.0.0-1.x86_64.rpm
   

   On recent Linux versions, such as Oracle Linux 8, you may also need to manually install the libnsl package package when using Oracle Instant Client 19. Yum will automatically install other required dependencies, such as libaio.

   Oracle Linux users can alternatively automate download and installation. For example:

   yum install oracle-instantclient-release-el7
   yum install oracle-instantclient-basic
   

   Refer to Instant Client for Oracle Linux for details.

3. For Instant Client 19, or later, RPMs, the system library search path is automatically configured during installation.

   For older versions, if there is no other Oracle software on the machine that will be impacted, permanently add Instant Client to the runtime link path. For example, with sudo or as the root user:

   sudo sh -c "echo /usr/lib/oracle/18.5/client64/lib > /etc/ld.so.conf.d/oracle-instantclient.conf"
   sudo ldconfig
   

   Alternatively, for version 18 and earlier, every shell will need to have the environment variable LD_LIBRARY_PATH set to the appropriate directory for the Instant Client version. For example:

   export LD_LIBRARY_PATH=/usr/lib/oracle/18.5/client64/lib:$LD_LIBRARY_PATH
   

4. If you use optional Oracle configuration files such as tnsnames.ora, sqlnet.ora or oraaccess.xml, put the files in an accessible directory. Then set the member dpiContextCreateParams.oracleClientConfigDir when calling dpiContext_createWithParams().

   Alternatively, set the environment variable TNS_ADMIN to that directory name.

   Alternatively, create a network/admin subdirectory of Instant Client, if it does not exist. For example, with Instant Client 12.2:

   sudo mkdir -p /usr/lib/oracle/12.2/client64/lib/network/admin
   

   Put the files in this directory. This is the default Oracle configuration directory for applications linked with this Instant Client.

2.2.3. Local Database or Full Oracle Client

ODPI-C applications can use Oracle Client 21, 19, 18, 12, or 11.2 libraries from a local Oracle Database or full Oracle Client installation.

The libraries must be either 32-bit or 64-bit, matching your application and ODPI-C library (if one is created separately).

1. Set required Oracle environment variables by running the Oracle environment script. For example:

   source /usr/local/bin/oraenv
   

   For Oracle Database XE 11.2, run:

   source /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh
   

2. Optional Oracle configuration files such as tnsnames.ora, sqlnet.ora or oraaccess.xml can be placed in $ORACLE_HOME/network/admin.

   Alternatively, Oracle configuration files can be put in another, accessible directory. Then set the member dpiContextCreateParams.oracleClientConfigDir when calling dpiContext_createWithParams(), or set the environment variable TNS_ADMIN to that directory name.

2.2.4. Containers

2.2.4.1. Dockerfiles

ODPI-C applications can easily be used in containers by basing your deployments on the Instant Client Dockerfiles on GitHub.

To build an Instant Client image, create a Dockerfile, for example:

FROM oraclelinux:8-slim

RUN  microdnf install oracle-instantclient-release-el8 && \
     microdnf install oracle-instantclient-basic oracle-instantclient-devel oracle-instantclient-sqlplus && \
     microdnf clean all

Then run:

docker build -t oracle/instantclient:21 .

The new image can be used as the basis for your application.

2.2.4.2. Pre-built Containers

Pre-built images for Instant Client are in the GitHub Container Registry:

• https://github.com/orgs/oracle/packages/container/package/oraclelinux8-instantclient

• https://github.com/orgs/oracle/packages/container/package/oraclelinux7-instantclient

These are easily used. For example, to pull an Oracle Linux 8 image with Oracle Instant Client 21c already installed, execute:

docker pull ghcr.io/oracle/oraclelinux8-instantclient:21

2.3. Windows

ODPI-C requires Oracle Client libraries, which are found in Oracle Instant Client, or an Oracle Database installation, or in a full Oracle Client installation, see Oracle Client Library Loading. The libraries must be either 32-bit or 64-bit, matching your application and ODPI-C library (if one is created separately).

Oracle Client libraries require the presence of the correct Visual Studio redistributable:

• For Instant Client 21 install VS 2019 or later.

• For Instant Client 19 install VS 2017.

• For Instant Client 18 or 12.2 install VS 2013

• For Instant Client 12.1 install VS 2010

• For Instant Client 11.2 install VS 2005 64-bit

2.3.1. Oracle Instant Client Zip Files

To run ODPI-C applications with Oracle Instant Client zip files:

1. Download an Oracle 19, 18, 12, or 11.2 “Basic” or “Basic Light” zip file: 64-bit or 32-bit, matching your application architecture.

   Note that 19c is not supported on Windows 7.

2. Unzip the package into a directory that is accessible to your application. For example unzip instantclient-basic-windows.x64-19.11.0.0.0dbru.zip to C:\oracle\instantclient_19_11.

2.3.1.1. Configure Oracle Instant Client

1. There are several alternative ways to tell your application where your Oracle Instant Client libraries are.

   • Set this directory in the member dpiContextCreateParams.oracleClientLibDir when calling dpiContext_createWithParams().

   • Alternatively, move the unzipped Instant Client files to the directory containing ODPIC.DLL (or into the directory of the application’s binary, if ODPI-C is compiled into the application).

   • Alternatively, add the Instant Client directory to the PATH environment variable. For example, on Windows 7, update PATH in Control Panel -> System -> Advanced System Settings -> Advanced -> Environment Variables -> System Variables -> PATH. The Instant Client directory must occur in PATH before any other Oracle directories.

     Restart any open command prompt windows.

     To avoid interfering with existing tools that require other Oracle Client versions, instead of updating the system-wide PATH variable, you may prefer to write a batch file that sets PATH, for example:

     REM mywrapper.bat
     SET PATH=C:\oracle\instantclient_19_11;%PATH%
     myapp %*
     

     Invoke this batch file every time you want to run your application.

     Or simply use SET to change your PATH in each command prompt window before you run your application.

2. If you use optional Oracle configuration files such as tnsnames.ora, sqlnet.ora or oraaccess.xml, put the files in an accessible directory. Then set the member dpiContextCreateParams.oracleClientConfigDir when calling dpiContext_createWithParams().

   Alternatively, set the environment variable TNS_ADMIN to that directory name.

   Alternatively, create a network\admin subdirectory of Instant Client, if it does not exist. For example C:\oracle\instantclient_19_11\network\admin.

   Put the files in this directory. This is the default Oracle configuration directory for applications linked with this Instant Client.

If you wish to package Instant Client with your application, you can move the Instant Client libraries to the same directory as the ODPI-C library (or application). Refer to the Instant Client documentation for the minimal set of Instant Client files required. There is no need to set dpiContextCreateParams.oracleClientConfigDir or to set PATH.

2.3.2. Local Database or Full Oracle Client

ODPI-C applications can use Oracle Client 19, 18, 12, or 11.2 libraries from a local Oracle Database or full Oracle Client installation.

The Oracle libraries must be either 32-bit or 64-bit, matching your application and ODPI-C library (if one is created separately).

To run ODPI-C applications using client libraries from a local Oracle Database (or full Oracle Client) 19, 18, 12, or 11.2 installation:

1. Set the environment variable PATH to include the path that contains OCI.dll, if it is not already set. For example, on Windows 7, update PATH in Control Panel -> System -> Advanced System Settings -> Advanced -> Environment Variables -> System Variables -> PATH.

   Restart any open command prompt windows.

2. Optional Oracle configuration files such as tnsnames.ora, sqlnet.ora or oraaccess.xml can be placed in the network/admin subdirectory of the Oracle software.

   Alternatively, Oracle configuration files can be put in another, accessible directory. Then set the member dpiContextCreateParams.oracleClientConfigDir when calling dpiContext_createWithParams(), or set the environment variable TNS_ADMIN to that directory name.

2.4. macOS

ODPI-C requires Oracle Client libraries, which are found in Oracle Instant Client for macOS.

The Instant Client DMG packages are notarized and are recommended for all newer macOS versions. In some future Oracle release, only DMG packages will be available.

2.4.1. Oracle Instant Client DMG Files

Manual or scripted installation of Oracle Instant Client DMG files can be performed.

2.4.1.1. Manual Installation

• Download the Basic or Basic Light 64-bit DMG from Oracle.

• In Finder, double click on the DMG to mount it.

• Open a terminal window and run the install script in the mounted package, for example:

  /Volumes/instantclient-basic-macos.x64-19.8.0.0.0dbru/install_ic.sh
  

  This copies the contents to $HOME/Downloads/instantclient_19_8. Applications may not have access to the Downloads directory, so you should move Instant Client somewhere convenient.

• In Finder, eject the mounted Instant Client package.

If you have multiple Instant Client DMG packages mounted, you only need to run install_ic.sh once. It will copy all mounted Instant Client DMG packages at the same time.

2.4.1.2. Scripted Installation

Instant Client installation can alternatively be scripted, for example:

cd $HOME/Downloads
curl -O https://download.oracle.com/otn_software/mac/instantclient/198000/instantclient-basic-macos.x64-19.8.0.0.0dbru.dmg
hdiutil mount instantclient-basic-macos.x64-19.8.0.0.0dbru.dmg
/Volumes/instantclient-basic-macos.x64-19.8.0.0.0dbru/install_ic.sh
hdiutil unmount /Volumes/instantclient-basic-macos.x64-19.8.0.0.0dbru

The Instant Client directory will be $HOME/Downloads/instantclient_19_8. Applications may not have access to the Downloads directory, so you should move Instant Client somewhere convenient.

2.4.2. Oracle Instant Client Zip Files

To install Oracle Instant Client zip files:

1. Download the 19, 18, 12, or 11.2 “Basic” or “Basic Light” zip file from Oracle. Choose either a 64-bit or 32-bit package, matching your application architecture. Most applications use 64-bit.

2. Unzip the package into a single directory that is accessible to your application. For example, in Terminal you could unzip:

   mkdir /opt/oracle
   cd /opt/oracle
   unzip /your/path/to/instantclient-basic-macos.x64-19.8.0.0.0dbru.zip
   

2.4.3. Configure Oracle Instant Client

1. There are several alternative ways to tell your application where your Oracle Instant Client libraries are.

   • Use the extracted directory for the member dpiContextCreateParams.oracleClientLibDir in a call to dpiContext_createWithParams()

   • Alternatively, copy Oracle Instant Client to the directory containing the ODPI-C module binary. For example, if libodpic.dylib (or your binary containing the ODPI-C code) is in ~/myprograms you can then run ln -s ~/Downloads/instantclient_19_8/libclntsh.dylib ~/myprograms. You can also copy the Instant Client libraries to that directory.

   • Alternatively, set DYLD_LIBRARY_PATH to the Instant Client directory. Note this variable does not propagate to sub-shells.

   • Alternatively, you might decide to compile the ODPI-C library with an RPATH option like -Wl,-rpath,/usr/local/lib. Then you can link Oracle Instant Client to this directory, for example:

     ln -s /opt/oracle/instantclient_19_8/libclntsh.dylib /usr/local/lib/
     

     Or, instead of a link you can copy the required OCI libraries. For example:

     cp /opt/oracle/instantclient_19_8/{libclntsh.dylib.19.1,libclntshcore.dylib.19.1,libons.dylib,libnnz12.dylib,libociei.dylib} /usr/local/lib/
     

   • Alternatively, on older versions of macOS, you could add a link to $HOME/lib or /usr/local/lib to enable applications to find Instant Client. If the lib sub-directory does not exist, you can create it. For example:

     mkdir ~/lib
     ln -s ~/Downloads/instantclient_19_8/libclntsh.dylib ~/lib/
     

     Instead of linking, you can copy the required OCI libraries. For example:

     mkdir ~/lib
     cp ~/Downloads/instantclient_19_8/{libclntsh.dylib.19.1,libclntshcore.dylib.19.1,libnnz19.dylib,libociei.dylib} ~/lib/
     

     For Instant Client 11.2, the OCI libraries must be copied. For example:

     mkdir ~/lib
     cp ~/Downloads/instantclient_11_2/{libclntsh.dylib.11.1,libnnz11.dylib,libociei.dylib} ~/lib/
     

2. If you use optional Oracle configuration files such as tnsnames.ora, sqlnet.ora or oraaccess.xml, put the files in an accessible directory. Then set the member dpiContextCreateParams.oracleClientConfigDir when calling dpiContext_createWithParams().

   Alternatively, set the environment variable TNS_ADMIN to that directory name.

   Alternatively, create a network/admin subdirectory of Instant Client, if it does not exist. For example:

   mkdir -p ~/Downloads/instantclient_19_8/network/admin
   

   Put the files in this directory. This is the default Oracle configuration directory for applications linked with this Instant Client.

2.5. Other Platforms

To run ODPI-C applications on other platforms (such as Solaris and AIX), follow the same general directions as for Linux Instant Client zip files or Local Database. Add the Oracle libraries to the appropriate library path variable, such as LD_LIBRARY_PATH on Solaris, or LIBPATH on AIX.