Compatibility

The current version of OCILIB has been validated on:

Platforms: Windows, HP/UX, Linux, macOS, Solaris, AIX
Architectures: 32-bit and 64-bit
Compilers: GCC, MinGW, MSVC, IBM XLC, vendor C compilers, LabVIEW
Oracle versions: 8, 9, 10, 11, 12, 18, 19, 21

Note

OCILIB is compatible with:

Any existing Oracle version starting from 8i
Future Oracle versions (subject to Oracle backward compatibility)

Please contact the author if you have validated OCILIB on platforms or compilers not listed here.

Global build options

OCILIB supports the following global build options:

=> Oracle import modes

OCI_IMPORT_LINKAGE for linking OCI shared libraries at compile time (default on Unix-like systems)
OCI_IMPORT_RUNTIME for loading OCI shared libraries at runtime (default with prebuilt OCILIB libraries on Windows)

=> Oracle charset modes

OCI_CHARSET_ANSI: ANSI or UTF-8 strings with char* (default)
OCI_CHARSET_WIDE: wide strings with wchar_t*

=> Calling convention

OCI_API = __cdecl (or empty) for C/C++ (default on Unix-like systems and non-MSVC projects)
OCI_API = __stdcall when linking the OCILIB shared library on Windows (default for MSVC projects)

Note

On Windows, OCI_API MUST be set to __stdcall in order to use the prebuilt libraries. The header file "ocilib.h" automatically sets OCI_API to __stdcall when using MSVC.

Using OCILIB on Unix-like systems

OCILIB uses GNU Autotools for compilation and installation on Unix-like platforms.

Uncompress the archive (ocilib-x.y.z-gnu.tar.gz)

$ cd ocilib-x.y.z
$ ./configure
$ make
$ make install (this step might require administrator privileges)

Check the shared library path environment variable (LD_LIBRARY_PATH, LD_PATH, ...):

it must include $ORACLE_HOME/[lib|lib32|lib64]
it must include the path where OCILIB has been installed (by example, typically /usr/local/lib under Linux)

In order to get these values loaded at logon time, export these values in your .profile configuration file :

> export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib:/usr/local/lib

GNU Installation options :

OCILIB supports some options that are not needed for most common configurations.

List of available options:

–with-oracle-import=(linkage|runtime)
–with-oracle-charset=(ansi|wide)
–with-oracle-home=(custom oracle regular client directory)
–with-oracle-headers-path=(oracle header files directory)
–with-oracle-lib-path=(oracle shared lib directory)
–with-oracle-lib-name=(oracle shared lib name)
–with-custom-loader=(linker flag telling the linker which loader to use when loading dynamically at runtime Oracle shared libs. This option must be provide if the platform does not use the default loader flag '-ldl') and the –with-oracle-import is set to 'runtime'

Note

–with-oracle-headers-path and –with-oracle-lib-path are primarily meant to be used with Instant Client, but can also be used with a regular client when libraries and headers are not located in standard system paths.

Note

If the Oracle OCI linkage mode is set to 'linkage' (default) and no Oracle lib path is provided, the OCILIB configure script tries to locate the Oracle library folder following this sequence :

$ORACLE_HOME/lib32 (32 bits libs)
$ORACLE_HOME/lib (32 or 64 bits libs)
$ORACLE_HOME/lib64 (64 bits libs)

Note

To compile native 64-bit versions of OCILIB, you might need to pass compiler-specific flags to the configure script (e.g. '-m64' for GCC).

To use OCILIB in a project:

include "ocilib.h" in your application
Add the flag -I$USER_LIBS/include to your compiler
Define OCILIB modes:
- OCI import mode (-DOCI_IMPORT_LINKAGE | -DOCI_IMPORT_RUNTIME)
- OCI charset mode (-DOCI_CHARSET_ANSI | -DOCI_CHARSET_WIDE)
Add the flag -L/$ORACLE_HOME/[lib|lib32|lib64] -lclntsh to the linker
Add the flag -L$USER_LIBS/lib -locilib to the linker

where :

$USER_LIBS is the folder where OCILIB was installed
$ORACLE_LIB_PATH is Oracle client shared library path

Some older version of Oracle 8 have direct path API symbols located in the library libclient8. With these versions, you must include as well the linker flag -lclient8 to use Direct Path API.

Using OCILIB on Microsoft Windows

OCILIB distribution packages provide prebuilt 32-bit and 64-bit DLLs.

Uncompress the archive (ocilib-x.y.z-windows.zip)
Copy ocilib/include/ocilib.h to a folder listed in the compiler headers folders
Copy ocilib/lib[32|64]/ocilib[x].lib to a folder listed in the linker libraries folders
Copy ocilib/lib[32|64]/ocilib[x].dll to a folder included in the PATH environment variable

[x] is the compiled version of OCILIB ('a' -> ANSI / UTF-8, 'w' -> wide character, e.g. UTF-16 on Windows)

To use OCILIB in a project :

include "ocilib.h" in your application
define the calling convention (OCI_API) as __stdcall
define the charset mode (OCI_CHARSET_ANSI | OCI_CHARSET_WIDE)

Note for recompiling OCILIB:

Microsoft Visual Studio solutions (2022) are also provided to compile OCILIB Dlls and demos.
OCILIB library code compiles at highest warning level without any warnings with provided MSVC projects
These projects deactivate the following warnings generated by the inclusion of Windows SDK headers: 4255, 4668, 4996, 4710, 4711, 4738, 4774, 4820

Note

The OCI import mode (OCI_IMPORT_LINKAGE or OCI_IMPORT_RUNTIME) is only used when compiling OCILIB source code.

Oracle Instant Client Support

OCILIB supports Oracle Instant Client.

On Windows, there is no difference between using a regular Oracle Client and an Instant Client with OCILIB.

On Unix-like systems, the Instant Client is divided in different packages.

Public headers and shared libs are not part of the same package.

So, you must provide the following options to the configure command:

with-oracle-headers-path: location of the public header files
with-oracle-lib-path: location of the Oracle shared library

If your instant client package containing the shared libs does not have a symbolic link 'libclntsh.[shared lib extension]' to the fully qualified shared lib real name, you must create it:

Example on Linux:

$ ln -s $ORALIBPATH/libclntsh.so.10.1 $ORALIBPATH/libclntsh.so