Initializing the library

Detailed Description

Before using any OCILIB functionality, the library must be initialized by calling OCI_Initialize().

Once initialized, the application can connect to Oracle databases, execute statements, fetch data, etc.

When the application is done, all OCILIB resources must be released by calling OCI_Cleanup().

Note

The following objects are automatically freed by the library during cleanup:

• Connections
• Pools
• Statements
• Type info objects
• Thread keys

Warning

All other standalone object instances (mutexes, threads, dates, lobs, ...) ARE NOT automatically freed and must be explicitly released by the application before calling OCI_Cleanup().

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

Function Documentation

OCI_Initialize()

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

#include <api.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 (combinable with bitwise OR):

• OCI_ENV_DEFAULT : Default mode
• OCI_ENV_THREADED : Enable multi-threading support
• OCI_ENV_CONTEXT : Enable thread-contextual error handling
• OCI_ENV_EVENTS : Enable events for subscriptions, HA events, and AQ notifications

Note

This function must be called before any other OCILIB function.

All OCILIB functions (except OCI_GetLastError()) will fail if OCI_Initialize() has not been called. In that case, the error reported by OCI_GetLastError() is OCI_ERR_NOT_INITIALIZED.

Warning

• The parameter 'lib_path' is only used when 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. Possible reasons for failure:

• When OCI_ErrorGetType() returns OCI_ERR_ORACLE, OCI_ErrorGetOCICode() returns:
  • Any ORA-XXXXXX error code. Refer to Oracle documentation.
• When OCI_ErrorGetType() returns OCI_ERR_OCILIB, OCI_ErrorGetInternalCode() may return:
  • OCI_ERR_LOADING_SHARED_LIB : OCILIB could not load the Oracle shared library at runtime (32/64-bit mismatch, invalid lib_path, or missing MSVC runtime required by oci.dll on Windows).
  • OCI_ERR_LOADING_SYMBOLS : The loaded shared library does not contain the expected OCI symbols.
  • OCI_ERR_NOT_AVAILABLE : OCILIB was built with OCI_CHARSET_WIDE and the Oracle shared library does not support UTF16 (Oracle 8i).
  • OCI_ERR_CREATE_OCI_ENVIRONMENT : Oracle OCI environment initialization failed (in such cases, the underlying reason cannot be determined).

OCI_Cleanup()

OCI_SYM_PUBLIC boolean OCI_API OCI_Cleanup

(

void

)

#include <api.h>

Clean up all resources allocated by the library.

Note

This function must be the last OCILIB function call in the application.

• It deallocates objects not explicitly freed by the program (connections, statements, etc.).
• It unloads the Oracle shared library if it was dynamically loaded.

Warning

OCI_Cleanup() should be called ONCE per application.

Returns

TRUE on success, otherwise FALSE. Possible reasons for failure:

• OCI_Initialize() was not previously called (OCI_GetLastError() reports OCI_ERR_NOT_INITIALIZED).
• OCI_Cleanup() has already been called.
• Some OCILIB local data type handles have not been freed.

OCI_GetOCICompileVersion()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetOCICompileVersion

(

void

)

#include <api.h>

Return the version of OCI used for compilation.

Note

• With the linkage build option, the version is determined from the oci.h header.
• With the runtime loading build option, the version is set to the highest OCI version required by OCILIB to support all library features. This version serves as an indicator, as OCILIB is compatible with all Oracle 8+ OCI versions and adapts itself to the runtime-loaded Oracle libraries.

The return value is an integer following the pattern 'MMmmRR':

• 'MM' : Oracle OCI major version
• 'mm' : Oracle OCI minor version
• 'RR' : Oracle OCI revision version

Manipulating this value directly is not recommended. Use the following macros instead:

• OCI_VER_MAJ() : Retrieve the OCI major version.
• OCI_VER_MIN() : Retrieve the OCI minor version.
• OCI_VER_REV() : Retrieve the OCI revision version.

For example:

if (OCI_VER_MAJ(OCI_GetOCICompileVersion()) >= 21) {...} 

Note

To compare the return value against a specific version, use OCI_VER_MAKE().

For example:

if (OCI_GetOCICompileVersion() > OCI_VER_MAKE(21, 3, 0)) {...} 

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

OCI_GetOCIRuntimeVersion()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetOCIRuntimeVersion

(

void

)

#include <api.h>

Return the version of OCI used at runtime.

Note

• With the linkage build option, the version is determined from the oci.h header.
• With the runtime loading build option, the version is determined from the symbols dynamically loaded. This is a best-effort estimate, as a given Oracle release may not introduce new OCI symbols.

The return value is an integer following the pattern 'MMmmRR':

• 'MM' : Oracle OCI major version
• 'mm' : Oracle OCI minor version
• 'RR' : Oracle OCI revision version

Manipulating this value directly is not recommended. Use the following macros instead:

• OCI_VER_MAJ() : Retrieve the OCI major version.
• OCI_VER_MIN() : Retrieve the OCI minor version.
• OCI_VER_REV() : Retrieve the OCI revision version.

For example:

if (OCI_VER_MAJ(OCI_GetOCIRuntimeVersion()) >= 21) {...} 

Note

To compare the return value against a specific version, use OCI_VER_MAKE().

For example:

if (OCI_GetOCIRuntimeVersion() > OCI_VER_MAKE(21, 3, 0)) {...} 

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

OCI_GetImportMode()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetImportMode

(

void

)

#include <api.h>

Return the Oracle shared library import mode.

Returns

The import mode used by OCILIB. Possible values are:

• OCI_IMPORT_MODE_LINKAGE : OCI is linked at compile time.
• OCI_IMPORT_MODE_RUNTIME : OCI is loaded dynamically at runtime.

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

OCI_GetCharset()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetCharset

(

void

)

#include <api.h>

Return the character set type used by OCILIB.

Returns

The character set mode used by OCILIB. Possible values are:

• OCI_CHAR_ANSI : ANSI (single-byte or multi-byte) character set.
• OCI_CHAR_WIDE : Unicode (wide character) character set.

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

OCI_GetAllocatedBytes()

OCI_SYM_PUBLIC big_uint OCI_API OCI_GetAllocatedBytes

(

unsigned int

mem_type

)

#include <api.h>

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

Parameters

mem_type

- Type of memory allocation to query

Note

Possible values for parameter mem_type:

• OCI_MEM_ORACLE : Bytes allocated by the Oracle client library.
• OCI_MEM_OCILIB : Bytes allocated by the OCILIB library.
• OCI_MEM_ALL : Total bytes allocated by all libraries combined.

Returns

The number of bytes currently allocated for the specified memory type.

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

OCI_EnableWarnings()

OCI_SYM_PUBLIC boolean OCI_API OCI_EnableWarnings

(

boolean

value

)

#include <api.h>

Enable or disable Oracle warning notifications.

Parameters

value

- TRUE to enable warnings, FALSE to disable them

Note

By default, warnings are disabled (FALSE).

Returns

TRUE on success, otherwise FALSE.

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

OCI_SetHAHandler()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetHAHandler

(

POCI_HA_HANDLER

handler

)

#include <api.h>

Set the High Availability (HA) event handler.

Parameters

handler

- Pointer to the HA handler procedure (see POCI_HA_HANDLER)

Note

The OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to enable HA event notifications.

Warning

This feature requires Oracle 10gR2 or later. For earlier versions, the function returns FALSE without raising an exception.

Returns

TRUE on success, otherwise FALSE.

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