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, SessionSysAsm = OCI_SESSION_SYSASM, SessionSysBkp = OCI_SESSION_SYSBKP, SessionSysDgD = OCI_SESSION_SYSDGD, SessionSysKmt = OCI_SESSION_SYSKMT, SessionSysRac = OCI_SESSION_SYSRAC, SessionPreAuth = OCI_SESSION_PRELIM_AUTH }
	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 unsigned int	GetCharMaxSize ()
	Return maximum size for a character. More...

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 661 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 703 of file ocilib.hpp.

◆ HAEventType

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

Type of HA events.

Possible values are Environment::HAEventTypeValues

Definition at line 725 of file ocilib.hpp.

◆ EnvironmentFlags

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

Environment Flags.

Possible values are Environment::EnvironmentFlagsValues

Definition at line 749 of file ocilib.hpp.

◆ ImportMode

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

OCI libraries import mode.

Possible values are Environment::ImportMode

Definition at line 771 of file ocilib.hpp.

◆ CharsetMode

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

Environment charset mode.

Possible values are Environment::CharsetModeValues

Definition at line 793 of file ocilib.hpp.

◆ SessionFlags

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

Sessions flags.

Possible values are Environment::SessionFlagsValues

Definition at line 831 of file ocilib.hpp.

◆ StartMode

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

Oracle instance start modes.

Possible values are Environment::StartModeValues

Definition at line 857 of file ocilib.hpp.

◆ StartFlags

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

Oracle instance start flags.

Possible values are Environment::StartFlagsValues

Definition at line 881 of file ocilib.hpp.

◆ ShutdownMode

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

Oracle instance shutdown modes.

Possible values are Environment::ShutdownModeValues

Definition at line 907 of file ocilib.hpp.

◆ ShutdownFlags

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

Oracle instance shutdown flags.

Possible values are Environment::ShutdownFlagsValues

Definition at line 944 of file ocilib.hpp.

◆ AllocatedBytesFlags

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

Allocated Bytes.

Possible values are Environment::AllocatedBytesValues

Definition at line 968 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 678 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 710 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 732 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 756 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 778 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
SessionSysAsm	the user is authenticated for SYSASM access
SessionSysBkp	the user is authenticated for SYSBKP access
SessionSysDgD	the user is authenticated for SYSDGD access
SessionSysKmt	the user is authenticated for SYSKMT access
SessionSysRac	the user is authenticated for SYSRAC access
SessionPreAuth	the user is authenticated for PRELIM_AUTH access

Definition at line 800 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 838 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 864 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 888 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 914 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 951 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
It is not thread safe

Note

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 1027 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
It is not thread safe

Definition at line 1032 of file ocilib_impl.hpp.

References OCI_GetUserData(), and OCI_SetUserData().

◆ 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 1040 of file ocilib_impl.hpp.

Referenced by ocilib::MakeRaw().

◆ GetCharMaxSize()

unsigned int ocilib::Environment::GetCharMaxSize ( )

inlinestatic

Return maximum size for a character.

Note: When Charset is Environment::CharsetAnsi and NLS_LANG is UTF8 based, return value is 4 Otherwise, it is sizeof(ostring::value_type)

Definition at line 1055 of file ocilib_impl.hpp.

Referenced by ocilib::Lob< T, U >::Lob().

◆ 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 1060 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 1070 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 1075 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 1110 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 1115 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 1120 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 1125 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 1132 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 1139 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 1144 of file ocilib_impl.hpp.

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

Public Types

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ HAEventSource

◆ HAEventType

◆ EnvironmentFlags

◆ ImportMode

◆ CharsetMode

◆ SessionFlags

◆ StartMode

◆ StartFlags

◆ ShutdownMode

◆ ShutdownFlags

◆ AllocatedBytesFlags

Member Enumeration Documentation

◆ HAEventSourceValues

◆ HAEventTypeValues

◆ EnvironmentFlagsValues

◆ ImportModeValues

◆ CharsetModeValues

◆ SessionFlagsValues

◆ StartModeValues

◆ StartFlagsValues

◆ ShutdownModeValues

◆ ShutdownFlagsValues

◆ AllocatedBytesValues

Member Function Documentation

◆ Initialize()

◆ Cleanup()

◆ GetMode()

◆ GetCharMaxSize()

◆ GetAllocatedBytes()

◆ GetCompileVersion()

◆ GetRuntimeVersion()

◆ EnableWarnings()

◆ SetFormat()

◆ GetFormat()

◆ StartDatabase()

◆ ShutdownDatabase()

◆ ChangeUserPassword()

◆ SetHAHandler()