A connection or session with a specific database. More...

#include <ocilib.hpp>

Inherits ocilib::HandleHolder< OCI_Connection * >.

Public Types
enum	FailoverRequestValues { FailoverRequestSession = OCI_FOT_SESSION, FailoverRequestSelect = OCI_FOT_SELECT }
	Failover request enumerated values. More...

enum	FailoverEventValues { FailoverEventEnd = OCI_FOE_END, FailoverEventAbort = OCI_FOE_ABORT, FailoverEventReauthentificate = OCI_FOE_REAUTH, FailoverEventBegin = OCI_FOE_BEGIN, FailoverEventError = OCI_FOE_ERROR }
	Failover events enumerated values. More...

enum	FailoverResultValues { FailoverOk = OCI_FOC_OK, FailoverRetry = OCI_FOC_RETRY }
	Failover callback results enumerated values. More...

enum	SessionTraceValues { TraceIdentity = OCI_TRC_IDENTITY, TraceModule = OCI_TRC_MODULE, TraceAction = OCI_TRC_ACTION, TraceDetail = OCI_TRC_DETAIL }
	Session trace enumerated values. More...

typedef Enum < FailoverRequestValues >	FailoverRequest
	Failover requests. More...

typedef Enum< FailoverEventValues >	FailoverEvent
	Failover events. More...

typedef Enum < FailoverResultValues >	FailoverResult
	Failover callback results. More...

typedef Enum< SessionTraceValues >	SessionTrace
	Session traces. More...

typedef FailoverResult(*	TAFHandlerProc )(Connection &con, FailoverRequest failoverRequest, FailoverEvent failoverEvent)
	User callback for TAF event notifications.

Public Member Functions
	Connection ()
	Default constructor.

	Connection (const ostring &db, const ostring &user, const ostring &pwd, Environment::SessionFlags sessionFlags=Environment::SessionDefault)
	Constructor that creates an opens an underlying DB connection with the given information. More...

void	Open (const ostring &db, const ostring &user, const ostring &pwd, Environment::SessionFlags sessionFlags=Environment::SessionDefault)
	Create a physical connection to an Oracle database server. More...

void	Close ()
	Close the physical connection to the DB server.

void	Commit ()
	Commit current pending changes.

void	Rollback ()
	Cancel current pending changes.

void	Break ()
	Perform an immediate abort of any currently Oracle OCI call on the given connection. More...

void	SetAutoCommit (bool enabled)
	Enable or disable auto commit mode (implicit commits after every SQL execution) More...

bool	GetAutoCommit () const
	Indicates if auto commit is currently activated.

bool	IsServerAlive () const
	Indicate if the connection is still connected to the server. More...

bool	PingServer () const
	Performs a round trip call to the server to confirm that the connection to the server is still valid. More...

ostring	GetConnectionString () const
	Return the name of the connected database/service name. More...

ostring	GetUserName () const
	Return the current logged user name. More...

ostring	GetPassword () const
	Return the current logged user password. More...

ostring	GetServerVersion () const
	Return the connected database server string version. More...

unsigned int	GetVersion () const
	Return the Oracle version supported by the connection. More...

unsigned int	GetServerMajorVersion () const
	Return the major version number of the connected database server.

unsigned int	GetServerMinorVersion () const
	Return the minor version number of the connected database server.

unsigned int	GetServerRevisionVersion () const
	Return the revision version number of the connected database server.

void	ChangePassword (const ostring &newPwd)
	Change the password of the logged user. More...

ostring	GetSessionTag () const
	Return the tag associated with the given connection.

void	SetSessionTag (const ostring &tag)
	Associate a tag to the given connection/session. More...

Transaction	GetTransaction () const
	Return the current transaction of the connection.

void	SetTransaction (const Transaction &transaction)
	Set a transaction to a connection. More...

void	SetDefaultDateFormat (const ostring &format)
	Set the date format for implicit string / date conversions. More...

ostring	GetDefaultDateFormat () const
	Return the current date format for implicit string / date conversions. More...

void	SetDefaultNumericFormat (const ostring &format)
	Set the numeric format for implicit string / numeric conversions. More...

ostring	GetDefaultNumericFormat () const
	Return the current numeric format for implicit string / numeric conversions. More...

void	EnableServerOutput (unsigned int bufsize, unsigned int arrsize, unsigned int lnsize)
	Enable the server output. More...

void	DisableServerOutput ()
	Disable the server output. More...

bool	GetServerOutput (ostring &line) const
	Retrieve one line of the server buffer. More...

void	GetServerOutput (std::vector< ostring > &lines) const
	Retrieve all remaining lines of the server buffer.

void	SetTrace (SessionTrace trace, const ostring &value)
	Set tracing information for the session. More...

ostring	GetTrace (SessionTrace trace) const
	Get the current trace for the trace type from the given connection. More...

ostring	GetDatabase () const
	Return the Oracle server database name of the connected database/service name. More...

ostring	GetInstance () const
	Return the Oracle server Instance name of the connected database/service name. More...

ostring	GetService () const
	Return the Oracle server Service name of the connected database/service name. More...

ostring	GetServer () const
	Return the Oracle server Hos name of the connected database/service name. More...

ostring	GetDomain () const
	Return the Oracle server Domain name of the connected database/service name. More...

Timestamp	GetInstanceStartTime () const
	Return the date and time (Timestamp) server instance start of the. More...

unsigned int	GetStatementCacheSize () const
	Return the maximum number of statements to keep in the statement cache. More...

void	SetStatementCacheSize (unsigned int value)
	Set the maximum number of statements to keep in the statement cache. More...

unsigned int	GetDefaultLobPrefetchSize () const
	Return the default LOB prefetch buffer size for the connection. More...

void	SetDefaultLobPrefetchSize (unsigned int value)
	Enable or disable prefetching for all LOBs fetched in the connection. More...

bool	IsTAFCapable () const
	Verify if the connection support TAF events. More...

void	SetTAFHandler (TAFHandlerProc handler)
	Set the Transparent Application Failover (TAF) user handler. More...

AnyPointer	GetUserData ()
	Return the pointer to user data previously associated with the connection.

void	SetUserData (AnyPointer value)
	Associate a pointer to user data to the given connection. More...

Detailed Description

A connection or session with a specific database.

This class wraps the OCILIB object handle OCI_Connection and its related methods

Definition at line 1465 of file ocilib.hpp.

Member Typedef Documentation

typedef Enum<FailoverRequestValues> ocilib::Connection::FailoverRequest

Failover requests.

Possible values are Connection::FailoverRequestValues

Definition at line 1505 of file ocilib.hpp.

typedef Enum<FailoverEventValues> ocilib::Connection::FailoverEvent

Failover events.

Possible values are Connection::FailoverEventValues

Definition at line 1533 of file ocilib.hpp.

typedef Enum<FailoverResultValues> ocilib::Connection::FailoverResult

Failover callback results.

Possible values are Connection::FailoverResultValues

Definition at line 1555 of file ocilib.hpp.

typedef Enum<SessionTraceValues> ocilib::Connection::SessionTrace

Session traces.

Possible values are Connection::SessionTraceValues

Definition at line 1581 of file ocilib.hpp.

Member Enumeration Documentation

enum ocilib::Connection::FailoverRequestValues

Failover request enumerated values.

Enumerator
FailoverRequestSession	User has requested only session failover
FailoverRequestSelect	User has requested select failover as well

Definition at line 1490 of file ocilib.hpp.

enum ocilib::Connection::FailoverEventValues

Failover events enumerated values.

Enumerator
FailoverEventEnd	Successful completion of failover
FailoverEventAbort	Failover was unsuccessful. Retrying is not allowed
FailoverEventReauthentificate	Multiple authentication and failover has occurred after the original authentication. User has been re authenticated
FailoverEventBegin	Failover has detected a lost connection and failover is starting
FailoverEventError	Failover was unsuccessful. Retrying is allowed

Definition at line 1512 of file ocilib.hpp.

enum ocilib::Connection::FailoverResultValues

Failover callback results enumerated values.

Enumerator
FailoverOk	Default acknowledgment of a failover event
FailoverRetry	Triggers a new failover attempt

Definition at line 1540 of file ocilib.hpp.

enum ocilib::Connection::SessionTraceValues

Session trace enumerated values.

Enumerator
TraceIdentity	Specifies the user defined identifier in the session. It's recorded in the column CLIENT_IDENTIFIER of the system view V$SESSION
TraceModule	Name of the current module in the client application. It's recorded in the column MODULE of the system view V$SESSION
TraceAction	Name of the current action within the current module. It's recorded in the column ACTION of the system view V$SESSION
TraceDetail	Client application additional information. It's recorded in the column CLIENT_INFO of the system view V$SESSION

Definition at line 1562 of file ocilib.hpp.

Constructor & Destructor Documentation

ocilib::Connection::Connection	(	const ostring &	db,
		const ostring &	user,
		const ostring &	pwd,
		Environment::SessionFlags	sessionFlags = `Environment::SessionDefault`
	)

inline

Constructor that creates an opens an underlying DB connection with the given information.

Parameters

db	- Oracle Service Name
user	- Oracle User name
pwd	- Oracle User password
sessionFlags	- Session Flags

Note: it calls Open() with the given parameters

Definition at line 1041 of file ocilib_impl.hpp.

References Open().

Member Function Documentation

void ocilib::Connection::Open	(	const ostring &	db,
		const ostring &	user,
		const ostring &	pwd,
		Environment::SessionFlags	sessionFlags = `Environment::SessionDefault`
	)

inline

Create a physical connection to an Oracle database server.

Parameters

db	- Oracle Service Name
user	- Oracle User name
pwd	- Oracle User password
sessionFlags	- Session Flags

Note: External credentials are supported by supplying an empty string for the 'user' and 'pwd' parameters If the param 'db' is empty then a connection to the default local DB is done

Oracle XA support

OCILIB supports Oracle XA connectivity. In order to get a connection using the XA interface :

For parameter 'db' : pass the value of the 'DB' parameter of the given XA connection string passed to the Transaction Processing Monitor (TPM)
Pass empty strings for 'user' and 'pwd' parameters
Use SessionFlags::SessionXa for parameter 'sessionFlags'

Oracle XA Connection String

The XA connection string used in a transaction monitor to connect to Oracle must be compatible with OCILIB :

the XA parameter 'Objects' MUST be set to 'true'
If EnvMode::Threaded is passed to Environment::Initialize(), the XA parameter 'Threads' must be set to 'true', otherwise to 'false'
If EnvMode::Events is passed to Environment::Initialize(), the XA parameter 'Events' must be set to 'true', otherwise to 'false'
As Oracle does not support Unicode UTF16 character set through the XA interface, Only OCI_CHARSET_ANSI builds of OCILIB can be used
You still can use UTF8 if the NLS_LANG environment variable is set with a valid UTF8 NLS value
DO NOT USE UNICODE OCILIB builds with XA connections

Note: On success, a local transaction is automatically created and started ONLY for regular standalone connections and connections retrieved from connection pools. No transaction is created for a XA connection or q connection retrieved from session pools.

Definition at line 1051 of file ocilib_impl.hpp.

References ocilib::Check(), OCI_ConnectionCreate(), and OCI_ConnectionFree().

Referenced by Connection().

void ocilib::Connection::Break ( )

inline

Perform an immediate abort of any currently Oracle OCI call on the given connection.

Note: The current call will abort and will raise an exception

Definition at line 1072 of file ocilib_impl.hpp.

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

void ocilib::Connection::SetAutoCommit ( bool enabled )

inline

Enable or disable auto commit mode (implicit commits after every SQL execution)

Parameters

enabled - auto commit new status

Definition at line 1077 of file ocilib_impl.hpp.

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

bool ocilib::Connection::IsServerAlive ( ) const

inline

Indicate if the connection is still connected to the server.

Note: the returned value is not real-time and is based on client library last heart beat status

Definition at line 1087 of file ocilib_impl.hpp.

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

bool ocilib::Connection::PingServer ( ) const

inline

Performs a round trip call to the server to confirm that the connection to the server is still valid.

Warning: This call is supported from Oracle 10g.

Definition at line 1092 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetConnectionString ( ) const

inline

Return the name of the connected database/service name.

Note: The returned value is the value of the 'db' parameter of the Open() method

Definition at line 1097 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetUserName ( ) const

inline

Return the current logged user name.

Note: The returned value is the value of the 'user' parameter of the Open() method

Definition at line 1102 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetPassword ( ) const

inline

Return the current logged user password.

Note: The returned value is the value of the 'pwd' parameter of the Open() method

Definition at line 1107 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetServerVersion ( ) const

inline

Return the connected database server string version.

Note: The returned value is the server version banner displayed by SQL*PLUS when connected to a DB server

Definition at line 1117 of file ocilib_impl.hpp.

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

unsigned int ocilib::Connection::GetVersion ( ) const

inline

Return the Oracle version supported by the connection.

Note

The supported version is the lower version between client and server:

OCI_UNKNOWN
OCI_8_0
OCI_8_1
OCI_9_0
OCI_9_2
OCI_10_1
OCI_10_2
OCI_11_1
OCI_11_2
OCI_12_1

Definition at line 1112 of file ocilib_impl.hpp.

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

void ocilib::Connection::ChangePassword ( const ostring & newPwd )

inline

Change the password of the logged user.

Parameters

newPwd - New password

Definition at line 1137 of file ocilib_impl.hpp.

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

void ocilib::Connection::SetSessionTag ( const ostring & tag )

inline

Associate a tag to the given connection/session.

Parameters

tag	- user tag string

Note: Use this call only for connections retrieved from a session pool See Pool::GetConnection() for more details; To untag a session, call SetSessionTag() with an empty 'tag' parameter

Definition at line 1147 of file ocilib_impl.hpp.

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

void ocilib::Connection::SetTransaction ( const Transaction & transaction )

inline

Set a transaction to a connection.

Parameters

transaction - Transaction to assign

Note: The current transaction (if any) is automatically stopped but the newly assigned is not started or resumed

Warning: Do not set a transaction to a XA connection or a connection retrieved from a session pool

Definition at line 1157 of file ocilib_impl.hpp.

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

void ocilib::Connection::SetDefaultDateFormat ( const ostring & format )

inline

Set the date format for implicit string / date conversions.

Parameters

format - Date format

Note: Default format is 'YYYY-MM-DD' defined by the public constant OCI_STRING_FORMAT_DATE; Conversions are performed by Oracle built-in functions. Possible values are string date formats supported by Oracle. See documentation of Oracle SQL to_date() function for more details

Definition at line 1162 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetDefaultDateFormat ( ) const

inline

Return the current date format for implicit string / date conversions.

Note: See SetDefaultDateFormat() for possible values

Definition at line 1172 of file ocilib_impl.hpp.

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

void ocilib::Connection::SetDefaultNumericFormat ( const ostring & format )

inline

Set the numeric format for implicit string / numeric conversions.

Parameters

format - Numeric format

Note: Conversions are performed by Oracle built-in functions. Possible format values are the numeric formats supported by Oracle. See documentation of Oracle SQL to_number() function for more details; Default format is 'FM99999999999999999999999999999999999990.999999999999999999999999' defined by the public constant OCI_STRING_FORMAT_NUM

Warning: It does not applies to binary double and binary floats data types that are converted from/to strings using the standard C library

Definition at line 1167 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetDefaultNumericFormat ( ) const

inline

Return the current numeric format for implicit string / numeric conversions.

Note: See SetDefaultNumericFormat() for possible values

Definition at line 1177 of file ocilib_impl.hpp.

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

void ocilib::Connection::EnableServerOutput	(	unsigned int	bufsize,
		unsigned int	arrsize,
		unsigned int	lnsize
	)

inline

Enable the server output.

Parameters

bufsize	- server buffer max size (server side)
arrsize	- number of lines to retrieve per server round-trip
lnsize	- maximum size of one line

Note

This call is equivalent to the command 'set serveroutput on' in SQL*PLUS

'bufsize' minimum value is 2000, maximum 1000000 with Oracle < 10.2g and can be unlimited above
'lnsize' maximum value is 255 with Oracle < 10g R2 and 32767 above

Warning: If EnableServerOutput() is not called, GetServerOutput() will return false

Definition at line 1182 of file ocilib_impl.hpp.

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

void ocilib::Connection::DisableServerOutput ( )

inline

Disable the server output.

Note: After this call, GetServerOutput() will return false.

Definition at line 1187 of file ocilib_impl.hpp.

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

bool ocilib::Connection::GetServerOutput ( ostring & line ) const

inline

Retrieve one line of the server buffer.

Returns: true if a line has been retrieved otherwise false (server buffer is empty or all lines have been retrieved)

Definition at line 1192 of file ocilib_impl.hpp.

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

void ocilib::Connection::SetTrace	(	SessionTrace	trace,
		const ostring &	value
	)

inline

Set tracing information for the session.

Parameters

trace	- trace type
value	- trace content

Store current trace information to the given connection handle. These information:

is stored in the system view V$SESSION
can be retrieved from the connection property of an OCI_Error handle

system view V$SESSION

Warning: The system view V$SESSION is updated on Oracle versions >= 10g; Oracle limits the size of these traces content and thus OCILIB will truncate the given values if needed :

TraceIdentity : 64 bytes
TraceModule : 48 bytes
TraceAction : 32 bytes
TraceDetail : 64 bytes

Definition at line 1212 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetTrace ( SessionTrace trace ) const

inline

Get the current trace for the trace type from the given connection.

Parameters

trace - trace type

Note: See SetTrace() for more details.

Definition at line 1217 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetDatabase ( ) const

inline

Return the Oracle server database name of the connected database/service name.

Warning: This call is supported from Oracle 10gR2.

Definition at line 1222 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetInstance ( ) const

inline

Return the Oracle server Instance name of the connected database/service name.

Warning: This call is supported from Oracle 10gR2.

Definition at line 1227 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetService ( ) const

inline

Return the Oracle server Service name of the connected database/service name.

Warning: This call is supported from Oracle 10gR2.

Definition at line 1232 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetServer ( ) const

inline

Return the Oracle server Hos name of the connected database/service name.

Warning: This call is supported from Oracle 10gR2.

Definition at line 1237 of file ocilib_impl.hpp.

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

ostring ocilib::Connection::GetDomain ( ) const

inline

Return the Oracle server Domain name of the connected database/service name.

Warning: This call is supported from Oracle 10gR2.

Definition at line 1242 of file ocilib_impl.hpp.

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

Timestamp ocilib::Connection::GetInstanceStartTime ( ) const

inline

Return the date and time (Timestamp) server instance start of the.

Warning: This call is supported from Oracle 10gR2.

Definition at line 1247 of file ocilib_impl.hpp.

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

unsigned int ocilib::Connection::GetStatementCacheSize ( ) const

inline

Return the maximum number of statements to keep in the statement cache.

Note: Default value is 20 (value from Oracle Documentation)

Warning: Requires Oracle Client 9.2 or above

Definition at line 1252 of file ocilib_impl.hpp.

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

void ocilib::Connection::SetStatementCacheSize ( unsigned int value )

inline

Set the maximum number of statements to keep in the statement cache.

Parameters

value - maximum number of statements in the cache

Warning: Requires Oracle Client 9.2 or above

Definition at line 1257 of file ocilib_impl.hpp.

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

unsigned int ocilib::Connection::GetDefaultLobPrefetchSize ( ) const

inline

Return the default LOB prefetch buffer size for the connection.

Warning: Requires Oracle Client AND Server 11gR1 or above

Note

Prefetch size is:

number of bytes for BLOBs (Blob) and BFILEs (File)
number of characters for CLOBs (Clob / NClob).

Default is 0 (prefetching disabled)

Definition at line 1262 of file ocilib_impl.hpp.

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

void ocilib::Connection::SetDefaultLobPrefetchSize ( unsigned int value )

inline

Enable or disable prefetching for all LOBs fetched in the connection.

Parameters

value - default prefetch buffer size

Note

If parameter 'value':

is == 0, it disables prefetching for all LOBs fetched in the connection.
is > 0, it enables prefetching for all LOBs fetched in the connection and the given buffer size is used for prefetching LOBs

LOBs prefetching is disabled by default

Warning: Requires Oracle Client AND Server 11gR1 or above.

Note

Prefetch size is:

number of bytes for BLOBs (Blob) and BFILEs (File)
number of characters for CLOBs (Clob / NClob).

Definition at line 1267 of file ocilib_impl.hpp.

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

bool ocilib::Connection::IsTAFCapable ( ) const

inline

Verify if the connection support TAF events.

Warning: This call is supported from Oracle 10gR2.

Definition at line 1272 of file ocilib_impl.hpp.

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

void ocilib::Connection::SetTAFHandler ( TAFHandlerProc handler )

inline

Set the Transparent Application Failover (TAF) user handler.

Parameters

handler - TAF handler procedure

Note: See TAFHandlerProc documentation for more details

Warning: This call is supported from Oracle 10gR2.

Definition at line 1277 of file ocilib_impl.hpp.

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

void ocilib::Connection::SetUserData ( AnyPointer value )

inline

Associate a pointer to user data to the given connection.

Parameters

value - User data pointer

Returns: TRUE on success otherwise FALSE

Definition at line 1291 of file ocilib_impl.hpp.

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

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation