DOCSEARCHbyAlgolia
Submit Docs

OCILIB Oracle Driver for C and C++

repository·master·Indexed 43 days ago

https://github.com/vrogier/ocilib

An open-source, cross-platform Oracle driver for C and C++ that encapsulates the Oracle Call Interface (OCI). It supports ISO C99 and standard C++03 (with optional C++11) APIs, providing full support for Oracle SQL/PL-SQL types, Oracle Pooling, XA connectivity, Advanced Queuing (AQ), and Transparent Application Failover (TAF). Compatible with Oracle versions 8.0 and higher on 32/64-bit architectures.

Tokens
5.5K
Snippets
25
Records
30
Agent score
55%

What's inside OCILIB

  1. Install OCILIB on GNU (Unix / Linux) platforms

    master

    To install OCILIB on Unix/Linux systems, build from source using the provided configuration script:

    1. Untar the archive.
    2. Navigate to the directory: cd ocilib-x.y.z.
    3. Run ./configure.
    4. Run make.
    5. Run make install (you may need su or sudo privileges).

    Note: Ensure that the Oracle and OCILIB library paths are defined in your shared library environment variable (e.g., LD_LIBRARY_PATH). If using Oracle Instant Client, additional configuration parameters may be required during the ./configure step.

    $ cd ocilib-x.y.z
$ ./configure
$ make
$ make install

  2. Install OCILIB on Windows

    master

    To install OCILIB on Windows, use the release package and manually place the files in your development environment paths:

    1. Unzip the archive.
    2. Copy ocilib\include\ocilib.h to your include path.
    3. Copy ocilib\lib32\ocilib[x].lib or ocilib\lib64\ocilib[x].lib to your library path.
    4. Copy ocilib\lib32\ocilib[x].dll or ocilib\lib64\ocilib[x].dll to your Windows PATH.
    # Manual steps for Windows:
1. unzip the archive
2. copy ocilib\include\ocilib.h to any place located in your include’s path
3. copy ocilib\lib32|64\ocilib[x].lib to any place located in your libraries path
4. copy ocilib\lib32|64\ocilib[x].dll to any place located in your windows path

  3. Overview of OCILIB

    master

    OCILIB is an open-source, cross-platform Oracle driver for C and C++. It provides a fast and reliable API that encapsulates the Oracle Call Interface (OCI), allowing for easier access to Oracle databases.

    Key Capabilities:

    • Language Support: Provides an ISO C99 API and a standard C++03 API (with optional C++11 features).
    • Unicode Support: Full ANSI and Unicode support (via ISO C wide strings or UTF-8).
    • Oracle Compatibility: Compatible with Oracle versions 8.0 and higher.
    • Advanced Features: Supports SQL/Object APIs, PL/SQL (blocks, cursors, collections), Oracle Pooling (connections/sessions), XA connectivity, Advanced Queuing (AQ), and Transparent Application Failover (TAF).
    • Data Types: Full support for Oracle SQL and PL/SQL data types including scalars, objects, refs, and collections.

  4. OCILIB Feature Overview

    master

    OCILIB is a high-performance, cross-platform C/C++ driver for Oracle that encapsulates the Oracle Call Interface (OCI).

    Key Capabilities:

    • API Support: ISO C99 and standard C++03 (with optional C++11) APIs.
    • Data Types: Full support for Oracle SQL/PL-SQL types (scalars, objects, refs, collections, cursors, index-by tables, nested tables).
    • Advanced Oracle Features:
      • Oracle Pooling (connections and sessions).
      • Oracle XA connectivity (distributed transactions).
      • Oracle AQ (Advanced Queuing).
      • Oracle TAF (Transparent Application Failover) and High Availability.
      • Database Change Notification / Continuous Query Notification.
    • Performance: Statement caching, binding array interface, Direct Path loading, and scrollable statements.
    • Compatibility: Supports Oracle versions 8.0 and higher; compatible with 32/64-bit architectures.

  5. Compile a program with OCILIB on Linux/Unix

    master

    When compiling your own application on Linux/Unix, you must define the charset and link both OCILIB and the Oracle client library.

    Required Compiler/Linker Flags:

    1. Charset: Add -DOCI_CHARSET_xxxx to your CFLAGS (where xxxx is ANSI or WIDE).
    2. OCILIB Linkage: Add -L$(OCILIB_PREFIX)/lib -locilib to your LDFLAGS (where OCILIB_PREFIX is your installation directory, e.g., /usr/local).
    3. Oracle Linkage: If using linkage mode (default), add -L$(ORACLE_HOME)/lib -lclntsh to your LDFLAGS.
    # Example Makefile snippet
CFLAGS += -DOCI_CHARSET_ANSI
LDFLAGS += -L/usr/local/lib -locilib -L$(ORACLE_HOME)/lib -lclntsh

  6. Install and build OCILIB on Linux/Unix

    master

    To install OCILIB from source on Linux or Unix-based systems, use the standard GNU build system:

    ./configure
make
make install

    Note: You may need sudo (or su) to execute make install if installing to system directories like /usr/local.

    Customizing the Build

    You can pass the following flags to ./configure:

    • --with-oracle-charset=ansi|wide: Specify charset (default: ansi).
    • --with-oracle-import=linkage|runtime: Specify import mode (default: linkage).
    • --with-oracle-home=<path>: Specify Oracle home location (only for linkage mode).
    • --with-oracle-headers-path=<path>: Specify OCI public headers path (only for linkage mode).
    • --with-oracle-lib-path=<path>: Specify OCI shared library path (must contain libclntsh) (only for linkage mode).
    • --with-custom-loader=<flag>: Specify the linker flag for loaders other than ld (default: -ldl). Only used in runtime mode.
    ./configure --with-oracle-charset=wide --with-oracle-import=linkage --with-oracle-home=/opt/oracle/client
make
make install

  7. Install OCILIB on Linux and Unix-based systems

    master

    To install OCILIB from source on Linux/Unix, use the standard GNU build system:

    ./configure
./make
./make install

    Note: You may need su privileges for the make install step.

    Custom Configuration Flags for ./configure:

    • --with-oracle-charset=[ansi|wide]: Specify charset (default: ansi).
    • --with-oracle-import=[linkage|runtime]: Specify import mode (default: linkage).
    • --with-oracle-home=[path]: Specify Oracle home (only for linkage mode).
    • --with-oracle-headers-path=[path]: Specify OCI public headers path (only for linkage mode).
    • --with-oracle-lib-path=[path]: Specify OCI shared library path (must contain libclntsh) (only for linkage mode).
    • --with-custom-loader=[flag]: Specify linker flag for loaders other than ld (default: -ldl). (only for runtime mode).
    ./configure --with-oracle-charset=wide --with-oracle-import=runtime
./make
./make install

  8. Compile a C/C++ program with OCILIB on Linux/Unix

    master

    To use OCILIB in your own Linux/Unix application, update your Makefile with the following settings:

    1. Define Charset: Add -DOCI_CHARSET_ANSI or -DOCI_CHARSET_WIDE to your CFLAGS.
    2. Link OCILIB: Add -L$(OCILIB_PREFIX)/lib -locilib to your LDFLAGS (where $(OCILIB_PREFIX) is your installation path, e.g., /usr/local).
    3. Link Oracle (if using linkage mode): Add -L$(ORACLE_HOME)/lib -lclntsh to your LDFLAGS.
    # Example Makefile snippet
CFLAGS += -DOCI_CHARSET_ANSI
LDFLAGS += -L/usr/local/lib -locilib -L$ORACLE_HOME/lib -lclntsh

all:
	$(CC) $(CFLAGS) my_program.c -o my_program $(LDFLAGS)

  9. Install OCILIB on Windows using precompiled binaries

    master

    You can integrate precompiled OCILIB dynamic or static libraries into your Windows project using two methods:

    Method 1: Path Configuration

    1. Add the ocilib\include directory to your compiler's include path.
    2. Add the ocilib\lib32 or ocilib\lib64 directory to your libraries path.
    3. Add the ocilib\lib32 or ocilib\lib64 directory to your Windows system PATH.

    Method 2: Manual File Copy

    1. Copy ocilib\include\ocilib.h to your include path.
    2. Copy ocilib\lib32\ocilib[x].lib (or lib64) to your libraries path.
    3. Copy ocilib\lib32\ocilib[x].dll (or lib64) to your Windows PATH.
    4. For MinGW, copy ocilib\lib32\libocilib[x].a to your Windows PATH.
    # Example directory structure for binaries
ocilib\lib32  # 32-bit binaries
ocilib\lib64  # 64-bit binaries
ocilib\include # Header files

  10. Minimal OCILIB C++ application example

    master

    This example demonstrates the basic workflow for a C++ application using the standard C++03 API: Initialize the environment, create a connection object, execute a statement, and iterate through a resultset using template-based type fetching (rs.Get<T>()). The process is wrapped in a try-catch block for error handling.

    #include "ocilib.hpp"
 
using namespace ocilib;
 
int main(void)
{
    try
    {
        Environment::Initialize();
 
        Connection con("db", "usr", "pwd");
 
        Statement st(con);
        st.Execute("select intcol, strcol from table");
 
        Resultset rs = st.GetResultset();
        while (rs.Next())
        {
            std::cout << rs.Get<int>(1) << " - " <<  rs.Get<ostring>(2) << std::endl;
        }
    }
    catch(std::exception &ex)
    {
         std::cout << ex.what() << std::endl;
    }
 
    Environment::Cleanup();
 
    return EXIT_SUCCESS;
}

  11. Configure OCILIB build options on Windows

    master

    When building OCILIB from source or using precompiled binaries on Windows, you must manage three main configuration categories via preprocessor defines:

    1. Oracle Import Mode

    Determines how OCILIB interacts with Oracle OCI libraries:

    • OCI_IMPORT_LINKAGE: Linkage at compile time (default).
    • OCI_IMPORT_RUNTIME: Runtime loading of Oracle libraries.

    2. Charset Mode

    Determines the string handling capabilities:

    • OCI_CHARSET_ANSI: Uses ANSI / UTF-8 (uses ociliba.dll or libociliba.a).
    • OCI_CHARSET_WIDE: Uses Unicode / UTF-16 / UCS-2 / wchar_t (uses ocilibw.dll or libocilibw.a).

    3. Calling Convention

    Required if you need to use functions with variable number of parameters (OCI_xxxxFmt):

    • OCI_API = __stdcall: Default; used to link OCILIB to language-independent modules.
    • OCI_API = __cdecl: Required for C/C++ only if you need variable parameter functions.
    // Example preprocessor definitions
#define OCI_CHARSET_ANSI
#define OCI_IMPORT_RUNTIME
#define OCI_API __stdcall

  12. Retrieve numeric values from a ResultSet

    master

    Use the OcilibResultsetGet... family of functions to extract integer, floating-point, or large integer values from a specific column in the current row of an OCI_Resultset. You can access columns either by their 1-based index or by their name (using the ...2 suffix).

    // By index
short val = OcilibResultsetGetShort(rs, 1);
int i = OcilibResultsetGetInt(rs, 2);
double d = OcilibResultsetGetDouble(rs, 3);
big_int bi = OcilibResultsetGetBigInt(rs, 4);

// By name
short val2 = OcilibResultsetGetShort2(rs, "COLUMN_NAME");
int i2 = OcilibResultsetGetInt2(rs, "COLUMN_NAME");