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.
|
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 OCILIB charset type.
|
|
OCI_SYM_PUBLIC big_uint OCI_API | OCI_GetAllocatedBytes (unsigned int mem_type) |
| Return the current number of bytes allocated internally in 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) user handler.
|
|
◆ 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:
- 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. Possible reasons for failures:
- when OCI_ErrorGetType() return OCI_ERR_ORACLE, OCI_ErrorGetOCICode() returns:
- any ORA-XXXXXX error code. Refer to Oracle documentation
- when OCI_ErrorGetType() return OCI_ERR_OCILIB, possible error code returned by OCI_ErrorGetInternalCode()
- OCI_ERR_LOADING_SHARED_LIB : OCILIB could not load oracle shared libraries at runtime (32/64bits mismatch, wrong
lib_path
, missing MSVC runtime required by oci.dll (MS Windows)
- OCI_ERR_LOADING_SYMBOLS : the loaded shared library does not contain OCI symbols
- OCI_ERR_NOT_AVAILABLE : OCILIb was built with OCI_CHARSET_WIDE and the oracle shared library dos not supports UTF16 (Oracle 8i)
- OCI_ERR_CREATE_OCI_ENVIRONMENT: Oracle OCI environment initialization failed (in such cases, it is impossible to get the reason)
◆ 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 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
◆ 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 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 that is required by OCILIB to support all library features. Thus this version is just an indicator as OCILIB is compatible with all Oracle 8+ OCI versions and adapt itself runtime loaded Oracle libraries
-
Retun value is an integer using the following pattern 'MMmmRR'
- 'MM' digits are the Oracle OCI major version
- 'mm' digits are the Oracle OCI minor version
- 'RR' digits are the Oracle OCI revision version
-
Manipulating direclty this value is not recommended.
- For retrieving OCI major version from it, use the maro OCI_VER_MAJ()
- For retrieving OCI minor version from it, use the maro OCI_VER_MIN()
- For retrieving OCI revision version from it, use the maro OCI_VER_REV() For example: if (OCI_VER_MAJ(OCI_GetOCICompileVersion()) >= 21) {...}
-
For testing this return value agains a specific 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 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. This is a best effort guess as a given Oracle release may not introduce new OCI symbols
-
Retun value is an integer using the following pattern 'MMmmRR'
- 'MM' digits are the Oracle OCI major version
- 'mm' digits are the Oracle OCI minor version
- 'RR' digits are the Oracle OCI revision version
-
Manipulating direclty this value is not recommended.
- For retrieving OCI major version from it, use the maro OCI_VER_MAJ()
- For retrieving OCI minor version from it, use the maro OCI_VER_MIN()
- For retrieving OCI revision version from it, use the maro OCI_VER_REV() For example: if (OCI_VER_MAJ(OCI_GetOCIRuntimeVersion()) >= 21) {...}
-
For testing this return value agains a specific 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.
- Note
- Possible values are:
- OCI_IMPORT_MODE_LINKAGE
- OCI_IMPORT_MODE_RUNTIME
Referenced by ocilib::Environment::GetImportMode().
◆ OCI_GetCharset()
OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetCharset |
( |
void |
| ) |
|
◆ 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 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_SYM_PUBLIC boolean OCI_API OCI_EnableWarnings |
( |
boolean |
value | ) |
|
#include <api.h>
Enable or disable Oracle warning notifications.
- Parameters
-
value | - enable/disable warnings |
- Note
- Default value is FALSE
Referenced by ocilib::Environment::EnableWarnings().
◆ OCI_SetHAHandler()
#include <api.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().