Initializing the library
C API

## Detailed Description

To use OCILIB, it first needs to be initialized through a call to OCI_Initialize().

Then, the application connects to server, executes queries...

Finally, OCILIB resources must be released by OCI_Cleanup()

Note

The following objects are automatically freed by the library:

- Connections
- pools
- Statements
- Type info objects
- Thread keys

Warning

All other standalone object instances (mutexes, threads, dates, lobs, ...) ARE NOT freed.

## Functions

OCI_EXPORT boolean OCI_API | OCI_Initialize (POCI_ERROR err_handler, const otext *lib_path, unsigned int mode)
| Initialize the library. More...
OCI_EXPORT boolean OCI_API | OCI_Cleanup (void)
| Clean up all resources allocated by the library. More...
OCI_EXPORT unsigned int OCI_API | OCI_GetOCICompileVersion (void)
| Return the version of OCI used for compilation. More...
OCI_EXPORT unsigned int OCI_API | OCI_GetOCIRuntimeVersion (void)
| Return the version of OCI used at runtime. More...
OCI_EXPORT unsigned int OCI_API | OCI_GetImportMode (void)
| Return the Oracle shared library import mode. More...
OCI_EXPORT unsigned int OCI_API | OCI_GetCharset (void)
| Return the OCILIB charset type. More...
OCI_EXPORT big_uint OCI_API | OCI_GetAllocatedBytes (unsigned int mem_type)
| Return the current number of bytes allocated internally in the library. More...
OCI_EXPORT boolean OCI_API | OCI_EnableWarnings (boolean value)
| Enable or disable Oracle warning notifications. More...
OCI_EXPORT boolean OCI_API | OCI_SetErrorHandler (POCI_ERROR handler)
| Set the global error user handler. More...
OCI_EXPORT boolean OCI_API | OCI_SetHAHandler (POCI_HA_HANDLER handler)
| Set the High availability (HA) user handler. More...

## Function Documentation

## OCI_Initialize()

OCI_EXPORT boolean OCI_API OCI_Initialize | ( | POCI_ERROR | err_handler,
|  | const otext * | lib_path,
|  | unsigned int | mode
| ) |  |

`#include <ocilib.h>`

Initialize the library.

Parameters

  err_handler | - Pointer to error handler procedure (optional)
  lib_path | - Oracle shared library path (optional)
  mode | - Environment mode

Possible values for parameter mode:

- OCI_ENV_DEFAULT : default mode
- OCI_ENV_THREADED : multi-threading support
- OCI_ENV_CONTEXT : thread contextual error handling
- OCI_ENV_EVENTS : enables events for subscription, HA Events, AQ notifications

Note
  This function must be called before any OCILIB library function.

Warning
  - The parameter 'libpath' is only used if OCILIB has been built with the option OCI_IMPORT_RUNTIME
  - If the parameter 'lib_path' is NULL, the Oracle library is loaded from system environment variables
  OCI_Initialize() should be called ONCE per application

Returns
  TRUE on success otherwise FALSE (only with Oracle runtime loading mode if the oracle shared libraries can't be loaded or if OCI subsystem cannot be initialized)

Referenced by ocilib::Environment::SetHAHandler().

## OCI_Cleanup()

OCI_EXPORT boolean OCI_API OCI_Cleanup | ( | void |  | ) |

`#include <ocilib.h>`

Clean up all resources allocated by the library.

Note
  - This function must be the last OCILIB library function call.
  - It deallocates objects not explicitly freed by the program (connections, statements, ...)
  - It unloads the Oracle shared library if it has been dynamically loaded

Warning
  OCI_Cleanup() should be called ONCE per application

Returns
  TRUE

Referenced by ocilib::Environment::SetHAHandler().

## OCI_GetOCICompileVersion()

OCI_EXPORT unsigned int OCI_API OCI_GetOCICompileVersion | ( | void |  | ) |

`#include <ocilib.h>`

Return the version of OCI used for compilation.

Note
  - with linkage build option, the version is determined from the oci.h header through different ways
  - with runtime loading build option, the version is set to the highest version of OCI needed by OCILIB, not necessarily the real OCI version

Referenced by ocilib::Environment::GetCompileMajorVersion(), ocilib::Environment::GetCompileMinorVersion(), ocilib::Environment::GetCompileRevisionVersion(), and ocilib::Environment::GetCompileVersion().

## OCI_GetOCIRuntimeVersion()

OCI_EXPORT unsigned int OCI_API OCI_GetOCIRuntimeVersion | ( | void |  | ) |

`#include <ocilib.h>`

Return the version of OCI used at runtime.

Note
  - with linkage build option, the version is determined from the oci.h header through different ways
  - with runtime loading build option, the version determined from the symbols dynamically loaded.

Referenced by ocilib::Environment::GetRuntimeMajorVersion(), ocilib::Environment::GetRuntimeMinorVersion(), ocilib::Environment::GetRuntimeRevisionVersion(), and ocilib::Environment::GetRuntimeVersion().

## OCI_GetImportMode()

OCI_EXPORT unsigned int OCI_API OCI_GetImportMode | ( | void |  | ) |

`#include <ocilib.h>`

Return the Oracle shared library import mode.

Note
  Possible values are:
  - OCI_IMPORT_MODE_LINKAGE
  - OCI_IMPORT_MODE_RUNTIME

Referenced by ocilib::Environment::GetImportMode().

## OCI_GetCharset()

OCI_EXPORT unsigned int OCI_API OCI_GetCharset | ( | void |  | ) |

`#include <ocilib.h>`

Return the OCILIB charset type.

Note
  Possible values are:
  - OCI_CHAR_ANSI
  - OCI_CHAR_WIDE

Referenced by ocilib::Environment::GetCharset().

## OCI_GetAllocatedBytes()

OCI_EXPORT big_uint OCI_API OCI_GetAllocatedBytes | ( | unsigned int | mem_type | ) |

`#include <ocilib.h>`

Return the current number of bytes allocated internally in the library.

Parameters

  mem_type | : type of memory to request

Note
  Possible values are:
  - OCI_MEM_ORACLE : bytes allocated by Oracle client library
  - OCI_MEM_OCILIB : bytes allocated by OCILIB library
  - OCI_MEM_ORACLE : bytes allocated by all libraries

Referenced by ocilib::Environment::GetAllocatedBytes().

## OCI_EnableWarnings()

OCI_EXPORT boolean OCI_API OCI_EnableWarnings | ( | boolean | value | ) |

`#include <ocilib.h>`

Enable or disable Oracle warning notifications.

Parameters

  value | - enable/disable warnings

Note
  Default value is FALSE

Referenced by ocilib::Environment::EnableWarnings().

## OCI_SetErrorHandler()

OCI_EXPORT boolean OCI_API OCI_SetErrorHandler | ( | POCI_ERROR | handler | ) |

`#include <ocilib.h>`

Set the global error user handler.

Parameters

  handler | - Pointer to error handler procedure

Note
  Use this call to change or remove the user callback error handler installed by OCI_Initialize()

## OCI_SetHAHandler()

OCI_EXPORT boolean OCI_API OCI_SetHAHandler | ( | POCI_HA_HANDLER | handler | ) |

`#include <ocilib.h>`

Set the High availability (HA) user handler.

Parameters

  handler | - Pointer to HA handler procedure

Note
  See POCI_HA_HANDLER documentation for more details
  OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use HA events

Warning
  This call is supported from Oracle 10gR2. For previous versions, it returns FALSE without throwing any exception.

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Environment::SetHAHandler().