OCILIB (C and C++ Driver for Oracle)  4.7.5
Open source and cross platform Oracle Driver delivering efficient access to Oracle databases.
Loading...
Searching...
No Matches
ocilib::Connection Class Reference

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

#include <types.hpp>

Inherits ocilib::core::HandleHolder< OCI_Connection * >.

Public Types

enum  TimeoutTypeValues { TimeoutSend = OCI_NTO_SEND , TimeoutReceive = OCI_NTO_RECEIVE , TimeoutCall = OCI_NTO_CALL }
 Timeout enumerated values. More...
 
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 core::Enum< TimeoutTypeValuesTimeoutType
 Timeout Types.
 
typedef core::Enum< FailoverRequestValuesFailoverRequest
 Failover requests.
 
typedef core::Enum< FailoverEventValuesFailoverEvent
 Failover events.
 
typedef core::Enum< FailoverResultValuesFailoverResult
 Failover callback results.
 
typedef core::Enum< SessionTraceValuesSessionTrace
 Session traces.
 
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.
 
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.
 
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.
 
void SetAutoCommit (bool enabled)
 Enable or disable auto commit mode (implicit commits after every SQL execution)
 
bool GetAutoCommit () const
 Indicates if auto commit is currently activated.
 
bool IsServerAlive () const
 Indicate if the connection is still connected to the server.
 
bool PingServer () const
 Performs a round trip call to the server to confirm that the connection to the server is still valid.
 
ostring GetConnectionString () const
 Return the name of the connected database/service name.
 
ostring GetUserName () const
 Return the current logged user name.
 
ostring GetPassword () const
 Return the current logged user password.
 
ostring GetServerVersion () const
 Return the connected database server string version.
 
OracleVersion GetVersion () const
 Return the Oracle version supported by the connection.
 
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.
 
ostring GetSessionTag () const
 Return the tag associated with the given connection.
 
void SetSessionTag (const ostring &tag)
 Associate a tag to the given connection/session.
 
Transaction GetTransaction () const
 Return the current transaction of the connection.
 
void SetTransaction (const Transaction &transaction)
 Set a transaction to a connection.
 
bool SetFormat (FormatType formatType, const ostring &format)
 Set the format string for implicit string conversions of the given type.
 
ostring GetFormat (FormatType formatType)
 Return the format string for implicit string conversions of the given type.
 
void EnableServerOutput (unsigned int bufsize, unsigned int arrsize, unsigned int lnsize)
 Enable the server output.
 
void DisableServerOutput ()
 Disable the server output.
 
bool GetServerOutput (ostring &line) const
 Retrieve one line of the server buffer.
 
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.
 
ostring GetTrace (SessionTrace trace) const
 Get the current trace for the trace type from the given connection.
 
ostring GetDatabase () const
 Return the Oracle server database name of the connected database/service name.
 
ostring GetInstance () const
 Return the Oracle server Instance name of the connected database/service name.
 
ostring GetService () const
 Return the Oracle server Service name of the connected database/service name.
 
ostring GetServer () const
 Return the Oracle server Hos name of the connected database/service name.
 
ostring GetDomain () const
 Return the Oracle server Domain name of the connected database/service name.
 
Timestamp GetInstanceStartTime () const
 Return the date and time (Timestamp) server instance start of the.
 
unsigned int GetStatementCacheSize () const
 Return the maximum number of statements to keep in the statement cache.
 
void SetStatementCacheSize (unsigned int value)
 Set the maximum number of statements to keep in the statement cache.
 
unsigned int GetDefaultLobPrefetchSize () const
 Return the default LOB prefetch buffer size for the connection.
 
void SetDefaultLobPrefetchSize (unsigned int value)
 Enable or disable pre-fetching for all LOBs fetched in the connection.
 
unsigned int GetMaxCursors () const
 Return the maximum number of SQL statements that can be opened in one session.
 
bool IsTAFCapable () const
 Verify if the connection support TAF events.
 
void SetTAFHandler (TAFHandlerProc handler)
 Set the Transparent Application Failover (TAF) user handler.
 
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.
 
unsigned int GetTimeout (TimeoutType timeout)
 Returns the requested timeout value for OCI calls that require server round-trips to the given database.
 
void SetTimeout (TimeoutType timeout, unsigned int value)
 Set a given timeout for OCI calls that require server round-trips to the given database.
 

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 1576 of file types.hpp.

Member Typedef Documentation

◆ TimeoutType

Timeout Types.

Possible values are Connection::TimeoutValues

Definition at line 1633 of file types.hpp.

◆ FailoverRequest

Failover requests.

Possible values are Connection::FailoverRequestValues

Definition at line 1655 of file types.hpp.

◆ FailoverEvent

Failover events.

Possible values are Connection::FailoverEventValues

Definition at line 1683 of file types.hpp.

◆ FailoverResult

Failover callback results.

Possible values are Connection::FailoverResultValues

Definition at line 1705 of file types.hpp.

◆ SessionTrace

Session traces.

Possible values are Connection::SessionTraceValues

Definition at line 1731 of file types.hpp.

◆ TAFHandlerProc

ocilib::Connection::TAFHandlerProc

User callback for TAF event notifications.

Definition at line 1740 of file types.hpp.

Member Enumeration Documentation

◆ TimeoutTypeValues

Timeout enumerated values.

Enumerator
TimeoutSend 
  • Time to wait for send operations completion to the database server
  • Requires Oracle 12cR1 client
TimeoutReceive 
  • Time to wait for read operations completion from the database server
  • Requires Oracle 12cR1 client
TimeoutCall 
  • Time to wait for a database round-trip to complete ( Client processing is not taken into account)
  • Requires Oracle 18c client

Definition at line 1607 of file types.hpp.

◆ FailoverRequestValues

Failover request enumerated values.

Enumerator
FailoverRequestSession 

User has requested only session failover

FailoverRequestSelect 

User has requested select failover as well

Definition at line 1640 of file types.hpp.

◆ 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 1662 of file types.hpp.

◆ FailoverResultValues

Failover callback results enumerated values.

Enumerator
FailoverOk 

Default acknowledgment of a failover event

FailoverRetry 

Triggers a new failover attempt

Definition at line 1690 of file types.hpp.

◆ 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 1712 of file types.hpp.

Constructor & Destructor Documentation

◆ Connection() [1/2]

ocilib::Connection::Connection ( )
inline

Default constructor.

Definition at line 33 of file Connection.hpp.

◆ Connection() [2/2]

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 38 of file Connection.hpp.

References Open().

Member Function Documentation

◆ Open()

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 48 of file Connection.hpp.

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

Referenced by Connection().

◆ Close()

void ocilib::Connection::Close ( )
inline

Close the physical connection to the DB server.

Definition at line 57 of file Connection.hpp.

◆ Commit()

void ocilib::Connection::Commit ( )
inline

Commit current pending changes.

Definition at line 62 of file Connection.hpp.

References ocilib::core::Check(), and OCI_Commit().

◆ Rollback()

void ocilib::Connection::Rollback ( )
inline

Cancel current pending changes.

Definition at line 67 of file Connection.hpp.

References ocilib::core::Check(), and OCI_Rollback().

◆ Break()

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 72 of file Connection.hpp.

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

◆ SetAutoCommit()

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 77 of file Connection.hpp.

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

◆ GetAutoCommit()

bool ocilib::Connection::GetAutoCommit ( ) const
inline

Indicates if auto commit is currently activated.

Definition at line 82 of file Connection.hpp.

References ocilib::core::Check(), and OCI_GetAutoCommit().

◆ IsServerAlive()

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 87 of file Connection.hpp.

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

◆ PingServer()

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 92 of file Connection.hpp.

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

◆ GetConnectionString()

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 97 of file Connection.hpp.

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

◆ GetUserName()

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 102 of file Connection.hpp.

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

◆ GetPassword()

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 107 of file Connection.hpp.

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

◆ GetServerVersion()

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 117 of file Connection.hpp.

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

◆ GetVersion()

OracleVersion 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:

Definition at line 112 of file Connection.hpp.

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

◆ GetServerMajorVersion()

unsigned int ocilib::Connection::GetServerMajorVersion ( ) const
inline

Return the major version number of the connected database server.

Definition at line 122 of file Connection.hpp.

References ocilib::core::Check(), and OCI_GetServerMajorVersion().

◆ GetServerMinorVersion()

unsigned int ocilib::Connection::GetServerMinorVersion ( ) const
inline

Return the minor version number of the connected database server.

Definition at line 127 of file Connection.hpp.

References ocilib::core::Check(), and OCI_GetServerMinorVersion().

◆ GetServerRevisionVersion()

unsigned int ocilib::Connection::GetServerRevisionVersion ( ) const
inline

Return the revision version number of the connected database server.

Definition at line 132 of file Connection.hpp.

References ocilib::core::Check(), and OCI_GetServerRevisionVersion().

◆ ChangePassword()

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

Change the password of the logged user.

Parameters
newPwd- New password

Definition at line 137 of file Connection.hpp.

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

◆ GetSessionTag()

ostring ocilib::Connection::GetSessionTag ( ) const
inline

Return the tag associated with the given connection.

Definition at line 142 of file Connection.hpp.

References ocilib::core::Check(), ocilib::core::MakeString(), and OCI_GetSessionTag().

◆ SetSessionTag()

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 147 of file Connection.hpp.

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

◆ GetTransaction()

Transaction ocilib::Connection::GetTransaction ( ) const
inline

Return the current transaction of the connection.

Definition at line 152 of file Connection.hpp.

References ocilib::core::Check(), and OCI_GetTransaction().

◆ SetTransaction()

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 157 of file Connection.hpp.

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

◆ SetFormat()

bool ocilib::Connection::SetFormat ( FormatType  formatType,
const ostring format 
)
inline

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:

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

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 162 of file Connection.hpp.

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

◆ GetFormat()

ostring ocilib::Connection::GetFormat ( FormatType  formatType)
inline

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 167 of file Connection.hpp.

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

◆ EnableServerOutput()

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 172 of file Connection.hpp.

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

◆ DisableServerOutput()

void ocilib::Connection::DisableServerOutput ( )
inline

Disable the server output.

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

Definition at line 177 of file Connection.hpp.

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

◆ GetServerOutput() [1/2]

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 182 of file Connection.hpp.

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

◆ GetServerOutput() [2/2]

void ocilib::Connection::GetServerOutput ( std::vector< ostring > &  lines) const
inline

Retrieve all remaining lines of the server buffer.

Definition at line 191 of file Connection.hpp.

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

◆ SetTrace()

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 202 of file Connection.hpp.

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

◆ GetTrace()

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 207 of file Connection.hpp.

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

◆ GetDatabase()

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 212 of file Connection.hpp.

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

◆ GetInstance()

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 217 of file Connection.hpp.

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

◆ GetService()

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 222 of file Connection.hpp.

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

◆ GetServer()

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 227 of file Connection.hpp.

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

◆ GetDomain()

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 232 of file Connection.hpp.

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

◆ GetInstanceStartTime()

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 237 of file Connection.hpp.

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

◆ GetStatementCacheSize()

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 242 of file Connection.hpp.

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

◆ SetStatementCacheSize()

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 247 of file Connection.hpp.

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

◆ GetDefaultLobPrefetchSize()

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 (pre-fetching disabled)

Definition at line 252 of file Connection.hpp.

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

◆ SetDefaultLobPrefetchSize()

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

Enable or disable pre-fetching for all LOBs fetched in the connection.

Parameters
value- default prefetch buffer size
Note
If parameter 'value':
  • is == 0, it disables pre-fetching for all LOBs fetched in the connection.
  • is > 0, it enables pre-fetching for all LOBs fetched in the connection and the given buffer size is used for pre-fetching LOBs
LOBs pre-fetching 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 257 of file Connection.hpp.

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

◆ GetMaxCursors()

unsigned int ocilib::Connection::GetMaxCursors ( ) const
inline

Return the maximum number of SQL statements that can be opened in one session.

Warning
Requires Oracle Client AND Server 12cR1 or above
Note
the returned value is the same as the db parameter 'open_cursors' from server's parameter file
Return 0 if the client and server version are < 12cR1

Definition at line 262 of file Connection.hpp.

References ocilib::core::Check(), and OCI_GetMaxCursors().

◆ IsTAFCapable()

bool ocilib::Connection::IsTAFCapable ( ) const
inline

Verify if the connection support TAF events.

Warning
This call is supported from Oracle 10gR2.

Definition at line 267 of file Connection.hpp.

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

◆ SetTAFHandler()

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 272 of file Connection.hpp.

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

◆ GetUserData()

AnyPointer ocilib::Connection::GetUserData ( )
inline

Return the pointer to user data previously associated with the connection.

Definition at line 279 of file Connection.hpp.

References ocilib::core::Check(), and OCI_GetUserData().

◆ SetUserData()

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

Associate a pointer to user data to the given connection.

Parameters
value- User data pointer

Definition at line 284 of file Connection.hpp.

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

◆ GetTimeout()

unsigned int ocilib::Connection::GetTimeout ( TimeoutType  timeout)
inline

Returns the requested timeout value for OCI calls that require server round-trips to the given database.

Parameters
timeout- Type of timeout
Note
: See Connection::SetTimeout() for more information
Returns
The given timeout value if supported, otherwise 0

Definition at line 289 of file Connection.hpp.

References ocilib::core::Check(), and OCI_GetTimeout().

◆ SetTimeout()

void ocilib::Connection::SetTimeout ( TimeoutType  timeout,
unsigned int  value 
)
inline

Set a given timeout for OCI calls that require server round-trips to the given database.

Parameters
timeout- Type of timeout to set
value- Timeout in milliseconds

OCI client raises an timeout type related error when a given timeout is reached.

Note
To disable a given timeout, pass the value 0
Warning
OCI client is using the following precedence rules when applying timeouts:
  • 1 - Timeout set using TimeoutCall (all other timeouts are discarded)
  • 2 - Timeouts set using TimeoutSend and/or TimeoutReceive
  • 3 - Timeouts set in sqlnet.ora file

Here is a summary:

FLAG Min. Version OCI Error raised OCI Error description sqlnet.ora equivalent
TimeoutSend OCI_12_1 ORA-12608 TNS: Send timeout occurred SQLNET.SEND_TIMEOUT
TimeoutReceive OCI_12_1 ORA-12609 TNS: Receive timeout occurred SQLNET.RECV_TIMEOUT
TimeoutCall OCI_18_1 ORA-03136 inbound connection timed out

Definition at line 294 of file Connection.hpp.

References ocilib::core::Check(), and OCI_SetTimeout().