ocilib::Environment Class Reference

Static class in charge of library initialization / cleanup. More...

`#include <ocilib.hpp>`

## Public Types

enum | HAEventSourceValues { SourceInstance = OCI_HES_INSTANCE, SourceDatabase = OCI_HES_DATABASE, SourceNode = OCI_HES_NODE, SourceService = OCI_HES_SERVICE, SourceServiceMember = OCI_HES_SERVICE_MEMBER, SourceASMInstance = OCI_HES_ASM_INSTANCE, SourcePreConnect = OCI_HES_PRECONNECT }
| HA Event sources enumerated values. More...
enum | HAEventTypeValues { EventDown = OCI_HET_DOWN, EventUp = OCI_HET_UP }
| HA Event types enumerated values. More...
enum | EnvironmentFlagsValues { Default = OCI_ENV_DEFAULT, Threaded = OCI_ENV_THREADED, Events = OCI_ENV_EVENTS }
| Environment Flags enumerated values. More...
enum | ImportModeValues { ImportLinkage = OCI_IMPORT_MODE_LINKAGE, ImportRuntime = OCI_IMPORT_MODE_RUNTIME }
| OCI libraries import mode enumerated values. More...
enum | CharsetModeValues { CharsetAnsi = OCI_CHAR_ANSI, CharsetWide = OCI_CHAR_WIDE }
| Charset mode enumerated values. More...
enum | SessionFlagsValues { SessionDefault = OCI_SESSION_DEFAULT, SessionXa = OCI_SESSION_XA, SessionSysDba = OCI_SESSION_SYSDBA, SessionSysOper = OCI_SESSION_SYSOPER }
| Session flags enumerated values. More...
enum | StartModeValues { StartOnly = OCI_DB_SPM_START, StartMount = OCI_DB_SPM_MOUNT, StartOpen = OCI_DB_SPM_OPEN, StartFull = OCI_DB_SPM_FULL }
| Oracle instance start modes enumerated values. More...
enum | StartFlagsValues { StartDefault = OCI_DB_SPF_DEFAULT, StartForce = OCI_DB_SPF_FORCE, StartRestrict = OCI_DB_SPF_RESTRICT }
| Oracle instance start flags enumerated values. More...
enum | ShutdownModeValues { ShutdownOnly = OCI_DB_SDM_SHUTDOWN, ShutdownClose = OCI_DB_SDM_CLOSE, ShutdownDismount = OCI_DB_SDM_DISMOUNT, ShutdownFull = OCI_DB_SDM_FULL }
| Oracle instance shutdown modes enumerated values. More...
enum | ShutdownFlagsValues { ShutdowntDefault = OCI_DB_SDF_DEFAULT, ShutdowTrans = OCI_DB_SDF_TRANS, ShutdownTransLocal = OCI_DB_SDF_TRANS_LOCAL, ShutdownImmediate = OCI_DB_SDF_IMMEDIATE, ShutdownAbort = OCI_DB_SDF_ABORT }
| Oracle instance shutdown flags enumerated values. More...
enum | AllocatedBytesValues { OracleClientBytes = OCI_MEM_ORACLE, OcilibBytes = OCI_MEM_OCILIB, AllBytes = OCI_MEM_ALL }
| Allocated Bytes enumerated values. More...
typedef Enum< HAEventSourceValues > | HAEventSource
| Source of HA events. More...
typedef Enum< HAEventTypeValues > | HAEventType
| Type of HA events. More...
typedef Flags< EnvironmentFlagsValues > | EnvironmentFlags
| Environment Flags. More...
typedef Enum< ImportModeValues > | ImportMode
| OCI libraries import mode. More...
typedef Enum< CharsetModeValues > | CharsetMode
| Environment charset mode. More...
typedef Flags< SessionFlagsValues > | SessionFlags
| Sessions flags. More...
typedef Flags< StartModeValues > | StartMode
| Oracle instance start modes. More...
typedef Flags< StartFlagsValues > | StartFlags
| Oracle instance start flags. More...
typedef Flags< ShutdownModeValues > | ShutdownMode
| Oracle instance shutdown modes. More...
typedef Flags< ShutdownFlagsValues > | ShutdownFlags
| Oracle instance shutdown flags. More...
typedef Flags< AllocatedBytesValues > | AllocatedBytesFlags
| Allocated Bytes. More...
typedef void(* | HAHandlerProc) (Connection &con, HAEventSource eventSource, HAEventType eventType, Timestamp &time)
| User callback for HA event notifications.

## Static Public Member Functions

static void | Initialize (EnvironmentFlags mode=Environment::Default, const ostring &libpath=OTEXT(""))
| Initialize the OCILIB environment. More...
static void | Cleanup ()
| Clean up all resources allocated by the environment. More...
static Environment::EnvironmentFlags | GetMode ()
| Return the Environment mode flags. More...
static Environment::ImportMode | GetImportMode ()
| Return the Oracle shared library import mode.
static Environment::CharsetMode | GetCharset ()
| Return the OCILIB charset type.
static big_uint | GetAllocatedBytes (AllocatedBytesFlags type)
| Return the current number of bytes allocated internally in the library. More...
static bool | Initialized ()
| Return true if the environment has been successfully initialized.
static OracleVersion | GetCompileVersion ()
| Return the version of OCI used for compiling OCILIB. More...
static unsigned int | GetCompileMajorVersion ()
| Return the major version number of OCI used for compiling OCILIB.
static unsigned int | GetCompileMinorVersion ()
| Return the minor version number of OCI used for compiling OCILIB.
static unsigned int | GetCompileRevisionVersion ()
| Return the revision version number of OCI used for compiling OCILIB.
static OracleVersion | GetRuntimeVersion ()
| Return the version of OCI used at runtime. More...
static unsigned int | GetRuntimeMajorVersion ()
| Return the major version number of OCI used at runtime.
static unsigned int | GetRuntimeMinorVersion ()
| Return the minor version number of OCI used at runtime.
static unsigned int | GetRuntimeRevisionVersion ()
| Return the revision version number of OCI used at runtime.
static void | EnableWarnings (bool value)
| Enable or disable Oracle warning notifications. More...
static bool | SetFormat (FormatType formatType, const ostring &format)
| Set the format string for implicit string conversions of the given type. More...
static ostring | GetFormat (FormatType formatType)
| Return the format string for implicit string conversions of the given type. More...
static void | StartDatabase (const ostring &db, const ostring &user, const ostring &pwd, Environment::StartFlags startFlags, Environment::StartMode startMode, Environment::SessionFlags sessionFlags=SessionSysDba, const ostring &spfile=OTEXT(""))
| Start a database instance. More...
static void | ShutdownDatabase (const ostring &db, const ostring &user, const ostring &pwd, Environment::ShutdownFlags shutdownFlags, Environment::ShutdownMode shutdownMode, Environment::SessionFlags sessionFlags=SessionSysDba)
| Shutdown a database instance. More...
static void | ChangeUserPassword (const ostring &db, const ostring &user, const ostring &pwd, const ostring &newPwd)
| Change the password of the given user on the given database. More...
static void | SetHAHandler (HAHandlerProc handler)
| Set the High availability (HA) user handler. More...

## Detailed Description

Static class in charge of library initialization / cleanup.

Definition at line 610 of file ocilib.hpp.

## Member Typedef Documentation

## HAEventSource

typedef Enum<HAEventSourceValues> ocilib::Environment::HAEventSource

Source of HA events.

Possible values are Environment::HAEventSourceValues

Definition at line 652 of file ocilib.hpp.

## HAEventType

typedef Enum<HAEventTypeValues> ocilib::Environment::HAEventType

Type of HA events.

Possible values are Environment::HAEventTypeValues

Definition at line 674 of file ocilib.hpp.

## EnvironmentFlags

typedef Flags<EnvironmentFlagsValues> ocilib::Environment::EnvironmentFlags

Environment Flags.

Possible values are Environment::EnvironmentFlagsValues

Definition at line 698 of file ocilib.hpp.

## ImportMode

typedef Enum<ImportModeValues> ocilib::Environment::ImportMode

OCI libraries import mode.

Possible values are Environment::ImportMode

Definition at line 720 of file ocilib.hpp.

## CharsetMode

typedef Enum<CharsetModeValues> ocilib::Environment::CharsetMode

Environment charset mode.

Possible values are Environment::CharsetModeValues

Definition at line 742 of file ocilib.hpp.

## SessionFlags

typedef Flags<SessionFlagsValues> ocilib::Environment::SessionFlags

Sessions flags.

Possible values are Environment::SessionFlagsValues

Definition at line 768 of file ocilib.hpp.

## StartMode

typedef Flags<StartModeValues> ocilib::Environment::StartMode

Oracle instance start modes.

Possible values are Environment::StartModeValues

Definition at line 794 of file ocilib.hpp.

## StartFlags

typedef Flags<StartFlagsValues> ocilib::Environment::StartFlags

Oracle instance start flags.

Possible values are Environment::StartFlagsValues

Definition at line 818 of file ocilib.hpp.

## ShutdownMode

typedef Flags<ShutdownModeValues> ocilib::Environment::ShutdownMode

Oracle instance shutdown modes.

Possible values are Environment::ShutdownModeValues

Definition at line 844 of file ocilib.hpp.

## ShutdownFlags

typedef Flags<ShutdownFlagsValues> ocilib::Environment::ShutdownFlags

Oracle instance shutdown flags.

Possible values are Environment::ShutdownFlagsValues

Definition at line 881 of file ocilib.hpp.

## AllocatedBytesFlags

typedef Flags<AllocatedBytesValues> ocilib::Environment::AllocatedBytesFlags

Allocated Bytes.

Possible values are Environment::AllocatedBytesValues

Definition at line 905 of file ocilib.hpp.

## Member Enumeration Documentation

## HAEventSourceValues

enum ocilib::Environment::HAEventSourceValues

HA Event sources enumerated values.

Enumerator
SourceInstance | The event has been generated by an Oracle instance
SourceDatabase | The event has been generated by an Oracle database
SourceNode | The event has been generated by an Oracle Node
SourceService | The event has been generated by an Oracle service
SourceServiceMember | The event has been generated by an Oracle service member
SourceASMInstance | The event has been generated by an Oracle ASM instance
SourcePreConnect | The event has been generated at service pre connecting stage

Definition at line 627 of file ocilib.hpp.

## HAEventTypeValues

enum ocilib::Environment::HAEventTypeValues

HA Event types enumerated values.

Enumerator
EventDown | The source of the event is down
EventUp | The source of the event is up (not generated yet by Oracle)

Definition at line 659 of file ocilib.hpp.

## EnvironmentFlagsValues

enum ocilib::Environment::EnvironmentFlagsValues

Environment Flags enumerated values.

Enumerator
Default | Default mode
Threaded | Enable support for multi-threading
Events | Enable support for events related to subscriptions, HA and AQ notifications

Definition at line 681 of file ocilib.hpp.

## ImportModeValues

enum ocilib::Environment::ImportModeValues

OCI libraries import mode enumerated values.

Enumerator
ImportLinkage | OCI libraries are linked at compile time
ImportRuntime | OCI libraries are dynamically loaded at runtime

Definition at line 705 of file ocilib.hpp.

## CharsetModeValues

enum ocilib::Environment::CharsetModeValues

Charset mode enumerated values.

Enumerator
CharsetAnsi | Environment is ANSI string or UTF8 string
CharsetWide | Environment is UNICODE using wide character string

Definition at line 727 of file ocilib.hpp.

## SessionFlagsValues

enum ocilib::Environment::SessionFlagsValues

Session flags enumerated values.

Enumerator
SessionDefault | Default session mode
SessionXa | Requested session will be created through the XA interface
SessionSysDba | the user is authenticated for SYSDBA access.
SessionSysOper | the user is authenticated for SYSOPER access

Definition at line 749 of file ocilib.hpp.

## StartModeValues

enum ocilib::Environment::StartModeValues

Oracle instance start modes enumerated values.

Enumerator
StartOnly | Start the instance without mounting and opening it
StartMount | Mount (only) the instance
StartOpen | Open (only) the instance
StartFull | Start, mount and open the instance

Definition at line 775 of file ocilib.hpp.

## StartFlagsValues

enum ocilib::Environment::StartFlagsValues

Oracle instance start flags enumerated values.

Enumerator
StartDefault | Default start flags
StartForce | Shuts down a running instance (if needed) using ABORT command and starts a new instance
StartRestrict | Allows database access only to users with both CREATE SESSION and RESTRICTED SESSION privileges

Definition at line 801 of file ocilib.hpp.

## ShutdownModeValues

enum ocilib::Environment::ShutdownModeValues

Oracle instance shutdown modes enumerated values.

Enumerator
ShutdownOnly | Shutdown the instance
ShutdownClose | Close (only) the instance
ShutdownDismount | Dismount (only) the instance
ShutdownFull | Shutdown, close and dismount the instance

Definition at line 825 of file ocilib.hpp.

## ShutdownFlagsValues

enum ocilib::Environment::ShutdownFlagsValues

Oracle instance shutdown flags enumerated values.

Enumerator

ShutdowntDefault

- Further connects are prohibited.
  - Waits for users to disconnect from the database

ShutdowTrans

- Further connects are prohibited
  - No new transactions are allowed.

ShutdownTransLocal

- Further connects are prohibited
  - No new transactions are allowed.
  - Waits for active transactions to complete

ShutdownImmediate

- Does not wait for current calls to complete or users to disconnect from the database.
  - All uncommitted transactions are terminated and rolled back

ShutdownAbort

- Does not wait for current calls to complete or users to disconnect from the database.
  - All uncommitted transactions are terminated and are not rolled back.
  - This is the fastest possible way to shut down the database, but the next database startup may require instance recovery.
  - Therefore, this option should be used only in unusual circumstances

Definition at line 851 of file ocilib.hpp.

## AllocatedBytesValues

enum ocilib::Environment::AllocatedBytesValues

Allocated Bytes enumerated values.

Enumerator
OracleClientBytes | Allocated bytes by Oracle Client
OcilibBytes | Allocated bytes by OCILIB
AllBytes | All Allocated bytes

Definition at line 888 of file ocilib.hpp.

## Member Function Documentation

## Initialize()

void ocilib::Environment::Initialize | ( | EnvironmentFlags | mode = `Environment::Default`,
|  | const ostring & | libpath = `OTEXT("")`
| ) |  |

inlinestatic

Initialize the OCILIB environment.

Parameters

  mode | - Environment mode
  libpath | - Oracle shared library path (optional)

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

Warning
  It should be called ONCE per application
  - 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

Definition at line 976 of file ocilib_impl.hpp.

## Cleanup()

void ocilib::Environment::Cleanup | ( |  | ) |

inlinestatic

Clean up all resources allocated by the environment.

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
  It should be called ONCE per application

Definition at line 981 of file ocilib_impl.hpp.

## GetMode()

Environment::EnvironmentFlags ocilib::Environment::GetMode | ( |  | ) |

inlinestatic

Return the Environment mode flags.

Note
  It returns the value of the parameter 'mode' passed to Initialize()

Definition at line 986 of file ocilib_impl.hpp.

Referenced by ocilib::MakeRaw().

## GetAllocatedBytes()

big_uint ocilib::Environment::GetAllocatedBytes | ( | AllocatedBytesFlags | type | ) |

inlinestatic

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

Parameters

  type | : type of memory to request

Definition at line 1001 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_GetAllocatedBytes().

## GetCompileVersion()

OracleVersion ocilib::Environment::GetCompileVersion | ( |  | ) |

inlinestatic

Return the version of OCI used for compiling OCILIB.

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

Definition at line 1011 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_GetOCICompileVersion().

## GetRuntimeVersion()

OracleVersion ocilib::Environment::GetRuntimeVersion | ( |  | ) |

inlinestatic

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.

Definition at line 1016 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_GetOCIRuntimeVersion().

## EnableWarnings()

void ocilib::Environment::EnableWarnings | ( | bool | value | ) |

inlinestatic

Enable or disable Oracle warning notifications.

Parameters

  value | - enable/disable warnings

Note
  Default value is false

Definition at line 1051 of file ocilib_impl.hpp.

References OCI_EnableWarnings().

## SetFormat()

bool ocilib::Environment::SetFormat | ( | FormatType | formatType,
|  | const ostring & | format
| ) |  |

inlinestatic

Set the format string for implicit string conversions of the given type.

Parameters

  formatType | - Type of format
  format | - Format string

Formats can set at 2 levels:

- Environment level
- Connection level

When the library needs to perform a string conversion, it search for a valid format using the following order:

- Connection format
- Library format
- Default format

Note
  Default format values are :
  - OCI_FMT_DATE : constant OCI_STRING_FORMAT_DATE
  - OCI_FMT_TIMESTAMP : constant OCI_STRING_FORMAT_TIMESTAMP
  - OCI_FMT_NUMERIC : constant OCI_STRING_FORMAT_NUMERIC
  - OCI_FMT_BINARY_DOUBLE : constant OCI_STRING_FORMAT_BINARY_DOUBLE
  - OCI_FMT_BINARY FLOAT : constant OCI_STRING_FORMAT_BINARY_FLOAT
  Conversions are performed by Oracle built-in functions whenever possible. For DATE, TIMESTAMP and numeric types, see documentation of Oracle SQL to_char() function for more details For BINARY_DOUBLE and BINARY_FLOAT, refer to the C Standard Library printf() family documentation

Definition at line 1056 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_SetFormat().

## GetFormat()

ostring ocilib::Environment::GetFormat | ( | FormatType | formatType | ) |

inlinestatic

Return the format string for implicit string conversions of the given type.

Parameters

  formatType | - Type of format

Note
  See SetFormat() for possible values

Definition at line 1061 of file ocilib_impl.hpp.

References ocilib::Check(), ocilib::MakeString(), and OCI_GetFormat().

Referenced by ocilib::Number::FromString(), ocilib::Date::FromString(), ocilib::Timestamp::FromString(), ocilib::Number::ToString(), ocilib::Date::ToString(), and ocilib::Timestamp::ToString().

## StartDatabase()

void ocilib::Environment::StartDatabase | ( | const ostring & | db,
|  | const ostring & | user,
|  | const ostring & | pwd,
|  | Environment::StartFlags | startFlags,
|  | Environment::StartMode | startMode,
|  | Environment::SessionFlags | sessionFlags = `SessionSysDba`,
|  | const ostring & | spfile = `OTEXT("")`
| ) |  |

inlinestatic

Start a database instance.

Parameters

  db | - Oracle Service Name
  user | - Oracle User name
  pwd | - Oracle User password
  startFlags | - Start flags
  startMode | - Start mode
  sessionFlags | - Session Flags
  spfile | - Client-side spfile to start up the database (optional)

Note
  The only valid modes for sessionFlags are SessionSysDba and SessionSysOper.
  Start modes and flags parameters values can be combined.
  External credentials are supported by supplying a empty strings for the 'user' and 'pwd' parameters If the parameter 'db' is empty then a connection to the default local DB is done.
  If the client side spfile is not provided, the database is started with its server-side spfile.

Definition at line 1066 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DatabaseStartup().

## ShutdownDatabase()

void ocilib::Environment::ShutdownDatabase | ( | const ostring & | db,
|  | const ostring & | user,
|  | const ostring & | pwd,
|  | Environment::ShutdownFlags | shutdownFlags,
|  | Environment::ShutdownMode | shutdownMode,
|  | Environment::SessionFlags | sessionFlags = `SessionSysDba`
| ) |  |

inlinestatic

Shutdown a database instance.

Parameters

  db | - Oracle Service Name
  user | - Oracle User name
  pwd | - Oracle User password
  shutdownFlags | - Shutdown flags
  shutdownMode | - Shutdown mode
  sessionFlags | - Session flags

Note
  The only valid modes for sessionFlags are SessionSysDba and SessionSysOper.
  Shutdown modes values can be combined.
  Shutdown flag values are exclusive.
  External credentials are supported by supplying a empty strings for the 'user' and 'pwd' parameters If the param 'db' is empty then a connection to the default local DB is done.

Definition at line 1073 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DatabaseShutdown().

## ChangeUserPassword()

void ocilib::Environment::ChangeUserPassword | ( | const ostring & | db,
|  | const ostring & | user,
|  | const ostring & | pwd,
|  | const ostring & | newPwd
| ) |  |

inlinestatic

Change the password of the given user on the given database.

Parameters

  db | - Oracle Service Name
  user | - Oracle User name
  pwd | - Oracle User password
  newPwd | - Oracle User New password

Definition at line 1080 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_SetUserPassword().

## SetHAHandler()

void ocilib::Environment::SetHAHandler | ( | HAHandlerProc | handler | ) |

inlinestatic

Set the High availability (HA) user handler.

Parameters

  handler | - HA handler procedure

Note
  See POCI_HA_HANDLER documentation for more details
  EnvMode::Events flag must be passed to Initialize() to be able to use HA events

Warning
  This call is supported from Oracle 10gR2.

Definition at line 1085 of file ocilib_impl.hpp.

References ocilib::Check(), OCI_Cleanup(), OCI_EventGetSubscription(), OCI_HandleGetEnvironment(), OCI_Initialize(), OCI_SetHAHandler(), and Threaded.