Detailed Description

OcilibCApiErrorHandling

Connecting to a database server is done with one call to OCI_ConnectionCreate().

OCI_ConnectionFree() closes the established connection.

Connection properties are accessible through a set of functions

Example: #include "ocilib.h"

void err_handler(OCI_Error *err)

{

printf("%s\n", OCI_ErrorGetString(err));

}

int main(void)

{

OCI_Connection *cn;

if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))

{

return EXIT_FAILURE;

}

cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);

printf("Server major version : %i\n", OCI_GetServerMajorVersion(cn));

printf("Server minor version : %i\n", OCI_GetServerMinorVersion(cn));

printf("Server revision version : %i\n\n", OCI_GetServerRevisionVersion(cn));

printf("Connection version : %i\n\n", OCI_GetVersionConnection(cn));

OCI_ConnectionFree(cn);

OCI_Cleanup();

return EXIT_SUCCESS;

}

OCI_GetServerRevisionVersion
OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetServerRevisionVersion(OCI_Connection *con)
Return the revision version number of the connected database server.

OCI_GetServerMinorVersion
OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetServerMinorVersion(OCI_Connection *con)
Return the minor version number of the connected database server.

OCI_ConnectionFree
OCI_SYM_PUBLIC boolean OCI_API OCI_ConnectionFree(OCI_Connection *con)
Close a physical connection to an Oracle database server.

OCI_GetVersionConnection
OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetVersionConnection(OCI_Connection *con)
Return the highest Oracle version is supported by the connection.

OCI_ConnectionCreate
OCI_SYM_PUBLIC OCI_Connection *OCI_API OCI_ConnectionCreate(const otext *db, const otext *user, const otext *pwd, unsigned int mode)
Create a physical connection to an Oracle database server.

OCI_GetServerMajorVersion
OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetServerMajorVersion(OCI_Connection *con)
Return the major version number of the connected database server.

OCI_Connection
struct OCI_Connection OCI_Connection
Oracle physical connection.
Definition: types.h:124

OCI_Error
struct OCI_Error OCI_Error
Encapsulates an Oracle or OCILIB exception.
Definition: types.h:390

OCI_ErrorGetString
OCI_SYM_PUBLIC const otext *OCI_API OCI_ErrorGetString(OCI_Error *err)
Retrieve error message from error handle.

OCI_Cleanup
OCI_SYM_PUBLIC boolean OCI_API OCI_Cleanup(void)
Clean up all resources allocated by the library.

OCI_Initialize
OCI_SYM_PUBLIC boolean OCI_API OCI_Initialize(POCI_ERROR err_handler, const otext *lib_path, unsigned int mode)
Initialize the library.

Functions
OCI_SYM_PUBLIC OCI_Connection *OCI_API	OCI_ConnectionCreate (const otext db, const otext user, const otext *pwd, unsigned int mode)
	Create a physical connection to an Oracle database server.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ConnectionFree (OCI_Connection *con)
	Close a physical connection to an Oracle database server.

OCI_SYM_PUBLIC boolean OCI_API	OCI_IsConnected (OCI_Connection *con)
	Returns TRUE is the given connection is still connected otherwise FALSE.

OCI_SYM_PUBLIC void *OCI_API	OCI_GetUserData (OCI_Connection *con)
	Return the pointer to user data previously associated with the connection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetUserData (OCI_Connection con, void data)
	Associate a pointer to user data to the given connection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetSessionTag (OCI_Connection con, const otext tag)
	Associate a tag to the given connection/session.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetSessionTag (OCI_Connection *con)
	Return the tag associated the given connection.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetDatabase (OCI_Connection *con)
	Return the name of the connected database/service name.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetUserName (OCI_Connection *con)
	Return the current logged user name.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetPassword (OCI_Connection *con)
	Return the current logged user password.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetPassword (OCI_Connection con, const otext password)
	Change the password of the logged user.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetUserPassword (const otext db, const otext user, const otext pwd, const otext new_pwd)
	Change the password of the given user on the given database.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_GetSessionMode (OCI_Connection *con)
	Return the current session mode.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetVersionServer (OCI_Connection *con)
	Return the connected database server version string (aka server banner version) as reported by SQL*Plus.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_GetServerMajorVersion (OCI_Connection *con)
	Return the major version number of the connected database server.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_GetServerMinorVersion (OCI_Connection *con)
	Return the minor version number of the connected database server.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_GetServerRevisionVersion (OCI_Connection *con)
	Return the revision version number of the connected database server.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetFormat (OCI_Connection con, unsigned int type, const otext format)
	Set the format string for implicit string conversions of the given type.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetFormat (OCI_Connection *con, unsigned int type)
	Return the format string for implicit string conversions of the given type.

OCI_SYM_PUBLIC OCI_Transaction *OCI_API	OCI_GetTransaction (OCI_Connection *con)
	Return the current transaction of the connection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetTransaction (OCI_Connection con, OCI_Transaction trans)
	Set a transaction to a connection.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_GetVersionConnection (OCI_Connection *con)
	Return the highest Oracle version is supported by the connection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetTrace (OCI_Connection con, unsigned int trace, const otext value)
	Set tracing information to the session of the given connection.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetTrace (OCI_Connection *con, unsigned int trace)
	Get the current trace for the trace type from the given connection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_Ping (OCI_Connection *con)
	Makes a round trip call to the server to confirm that the connection and the server are active.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetTimeout (OCI_Connection *con, unsigned int type, unsigned int value)
	Set a given timeout for OCI calls that require server round-trips to the given database.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_GetTimeout (OCI_Connection *con, unsigned int type)
	Returns the requested timeout value for OCI calls that require server round-trips to the given database.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetDBName (OCI_Connection *con)
	Return the Oracle server database name of the connected database/service name.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetInstanceName (OCI_Connection *con)
	Return the Oracle server Instance name of the connected database/service name.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetServiceName (OCI_Connection *con)
	Return the Oracle server service name of the connected database/service name.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetServerName (OCI_Connection *con)
	Return the Oracle server machine name of the connected database/service name.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetDomainName (OCI_Connection *con)
	Return the Oracle server domain name of the connected database/service name.

OCI_SYM_PUBLIC OCI_Timestamp *OCI_API	OCI_GetInstanceStartTime (OCI_Connection *con)
	Return the date and time (Timestamp) server instance start of the connected database/service name.

OCI_SYM_PUBLIC boolean OCI_API	OCI_IsTAFCapable (OCI_Connection *con)
	Verify if the given connection support TAF events.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetTAFHandler (OCI_Connection *con, POCI_TAF_HANDLER handler)
	Set the Transparent Application Failover (TAF) user handler.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_GetStatementCacheSize (OCI_Connection *con)
	Return the maximum number of statements to keep in the statement cache.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetStatementCacheSize (OCI_Connection *con, unsigned int value)
	Set the maximum number of statements to keep in the statement cache.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_GetDefaultLobPrefetchSize (OCI_Connection *con)
	Return the default LOB prefetch buffer size for the connection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetDefaultLobPrefetchSize (OCI_Connection *con, unsigned int value)
	Enable or disable prefetching for all LOBs fetched in the connection.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_GetMaxCursors (OCI_Connection *con)
	Return the maximum number of SQL statements that can be opened in one session.

Function Documentation

◆ OCI_ConnectionCreate()

OCI_SYM_PUBLIC OCI_Connection *OCI_API OCI_ConnectionCreate	(	const otext *	db,
		const otext *	user,
		const otext *	pwd,
		unsigned int	mode
	)

#include <api.h>

Create a physical connection to an Oracle database server.

Parameters

db	- Oracle Service Name
user	- Oracle User name
pwd	- Oracle User password
mode	- Session mode

Possible values for parameter mode :

OCI_SESSION_DEFAULT
OCI_SESSION_SYSDBA
OCI_SESSION_SYSOPER
OCI_SESSION_XA

Note: External credentials are supported by supplying a null value for the 'user' and 'pwd' parameters. If the param 'db' is NULL then a connection to the default local DB is done; For parameter 'mode', the possible values are exclusive and cannot be combined

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 NULL to the 'user' and 'pwd' parameters
Pass the value OCI_SESSION_XA to parameter 'mode'

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 OCI_ENV_THREADED is passed to OCI_Initialize(), the XA parameter 'Threads' must be set to 'true', otherwise to 'false'
If OCI_ENV_EVENTS is passed to OCI_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 OCI_CHARSET_WIDE 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.

Returns: Connection handle on success or NULL on failure

Referenced by ocilib::Connection::Open().

◆ OCI_ConnectionFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_ConnectionFree ( OCI_Connection * con )

#include <api.h>

Close a physical connection to an Oracle database server.

Parameters

con	- Connection handle

Returns: TRUE on success otherwise FALSE

◆ OCI_IsConnected()

OCI_SYM_PUBLIC boolean OCI_API OCI_IsConnected ( OCI_Connection * con )

#include <api.h>

Returns TRUE is the given connection is still connected otherwise FALSE.

Parameters

con	- Connection handle

Referenced by ocilib::Connection::IsServerAlive().

◆ OCI_GetUserData()

OCI_SYM_PUBLIC void *OCI_API OCI_GetUserData ( OCI_Connection * con )

#include <api.h>

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

Parameters

con	- Connection handle

Note: Value NULL for parameter con is a valid value. It returns then previously stored data with global scope (program wide)

Referenced by ocilib::Environment::Cleanup(), and ocilib::Connection::GetUserData().

◆ OCI_SetUserData()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetUserData	(	OCI_Connection *	con,
		void *	data
	)

#include <api.h>

Associate a pointer to user data to the given connection.

Parameters

con	- Connection handle
data	- User data pointer

Note: Value NULL for parameter con is a valid value. It allows users to associate a pointer to user data with global scope (program wide)

Returns: TRUE on success otherwise FALSE

Referenced by ocilib::Environment::Cleanup(), and ocilib::Connection::SetUserData().

◆ OCI_SetSessionTag()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetSessionTag	(	OCI_Connection *	con,
		const otext *	tag
	)

#include <api.h>

Associate a tag to the given connection/session.

Parameters

con	- Connection handle
tag	- user tag string

Note: Use this call only for connections retrieved from a session pool See OCI_PoolGetConnection() for more details; To untag a session, call OCI_SetSessionTag() with 'tag' parameter set to NULL

Warning: No error is raised if the connection is a standalone connection or retrieved from a connection pool

Returns: TRUE on success otherwise FALSE

Referenced by ocilib::Connection::SetSessionTag().

◆ OCI_GetSessionTag()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetSessionTag ( OCI_Connection * con )

#include <api.h>

Return the tag associated the given connection.

Parameters

con	- Connection handle

Referenced by ocilib::Connection::GetSessionTag().

◆ OCI_GetDatabase()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetDatabase ( OCI_Connection * con )

#include <api.h>

Return the name of the connected database/service name.

Parameters

con	- Connection handle

Referenced by ocilib::Connection::GetConnectionString().

◆ OCI_GetUserName()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetUserName ( OCI_Connection * con )

#include <api.h>

Return the current logged user name.

Parameters

con	- Connection handle

Referenced by ocilib::Connection::GetUserName().

◆ OCI_GetPassword()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetPassword ( OCI_Connection * con )

#include <api.h>

Return the current logged user password.

Parameters

con	- Connection handle

Referenced by ocilib::Connection::GetPassword().

◆ OCI_SetPassword()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetPassword	(	OCI_Connection *	con,
		const otext *	password
	)

#include <api.h>

Change the password of the logged user.

Parameters

con	- Connection handle
password	- New password

Returns: TRUE on success otherwise FALSE

Referenced by ocilib::Connection::ChangePassword().

◆ OCI_SetUserPassword()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetUserPassword	(	const otext *	db,
		const otext *	user,
		const otext *	pwd,
		const otext *	new_pwd
	)

#include <api.h>

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

Parameters

db	- Oracle Service Name
user	- Oracle User name
pwd	- Oracle User password
new_pwd	- Oracle User New password

Returns: TRUE on success otherwise FALSE

Referenced by ocilib::Environment::ChangeUserPassword().

◆ OCI_GetSessionMode()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetSessionMode ( OCI_Connection * con )

#include <api.h>

Return the current session mode.

Parameters

con	- Connection handle

Note: See OCI_ConnectionCreate() for possible values

◆ OCI_GetVersionServer()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetVersionServer ( OCI_Connection * con )

#include <api.h>

Return the connected database server version string (aka server banner version) as reported by SQL*Plus.

Parameters

con	- Connection handle

Referenced by ocilib::Connection::GetServerVersion().

◆ OCI_GetServerMajorVersion()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetServerMajorVersion ( OCI_Connection * con )

#include <api.h>

Return the major version number of the connected database server.

Parameters

con	- Connection handle

Returns: Version number or 0 on failure

Referenced by ocilib::Connection::GetServerMajorVersion().

◆ OCI_GetServerMinorVersion()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetServerMinorVersion ( OCI_Connection * con )

#include <api.h>

Return the minor version number of the connected database server.

Parameters

con	- Connection handle

Returns: Version number or 0 on failure

Referenced by ocilib::Connection::GetServerMinorVersion().

◆ OCI_GetServerRevisionVersion()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetServerRevisionVersion ( OCI_Connection * con )

#include <api.h>

Return the revision version number of the connected database server.

Parameters

con	- Connection handle

Returns: Version number or 0 on failure

Referenced by ocilib::Connection::GetServerRevisionVersion().

◆ OCI_SetFormat()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetFormat	(	OCI_Connection *	con,
		unsigned int	type,
		const otext *	format
	)

#include <api.h>

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

Parameters

con	- Connection handle (optional)
type	- Type of format
format	- Format string

Formats can set at 2 levels:

Library level: by passing a NULL Connection handle
Connection level: by passing a valid Connection handle

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: Possible values of parameter 'type' :

OCI_FMT_DATE : format used to convert DATE to string
OCI_FMT_TIMESTAMP : format used to convert TIMESTAMP and TIMESTAMP WITH LOCAL TIMEZONE to string
OCI_FMT_TIMESTAMP_TZ : format used to convert TIMESTAMP WITH TIME ZONE to string
OCI_FMT_NUMERIC : format used to convert numeric types to string
OCI_FMT_BINARY_DOUBLE : format used to convert BINARY_DOUBLE to string
OCI_FMT_BINARY FLOAT : format used to convert BINARY_FLOAT to string

Note

Default format values are :

OCI_FMT_DATE : constant OCI_STRING_FORMAT_DATE
OCI_FMT_TIMESTAMP : constant OCI_STRING_FORMAT_TIMESTAMP
OCI_FMT_TIMESTAMP_TZ : constant OCI_STRING_FORMAT_TIMESTAMP_TZ
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

Referenced by ocilib::Environment::SetFormat(), and ocilib::Connection::SetFormat().

◆ OCI_GetFormat()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetFormat	(	OCI_Connection *	con,
		unsigned int	type
	)

#include <api.h>

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

Parameters

con	- Connection handle
type	- Type of format

Note: See OCI_SetFormat() for possible values

Referenced by ocilib::Environment::GetFormat(), and ocilib::Connection::GetFormat().

◆ OCI_GetTransaction()

OCI_SYM_PUBLIC OCI_Transaction *OCI_API OCI_GetTransaction ( OCI_Connection * con )

#include <api.h>

Return the current transaction of the connection.

Parameters

con	- Connection handle

Note: From v3.9.4, no more default transaction object is created for a new connection

Referenced by ocilib::Connection::GetTransaction().

◆ OCI_SetTransaction()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetTransaction	(	OCI_Connection *	con,
		OCI_Transaction *	trans
	)

#include <api.h>

Set a transaction to a connection.

Parameters

con	- Connection handle
trans	- Transaction handle to assign

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

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

Referenced by ocilib::Connection::SetTransaction().

◆ OCI_GetVersionConnection()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetVersionConnection ( OCI_Connection * con )

#include <api.h>

Return the highest Oracle version is supported by the connection.

Parameters

con	- connection handle

Note: The highest supported version is the lower version between client and server:; Returns one of the following values:

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
OCI_18_3

Referenced by ocilib::Connection::GetVersion().

◆ OCI_SetTrace()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetTrace	(	OCI_Connection *	con,
		unsigned int	trace,
		const otext *	value
	)

#include <api.h>

Set tracing information to the session of the given connection.

Parameters

con	- connection handle
trace	- trace type
value	- trace content

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

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

Note: Possible values of parameter 'trace' :

OCI_TRC_IDENTITY : Specifies the user defined identifier in the session. It's recorded in the column CLIENT_IDENTIFIER of the system view V$SESSION
OCI_TRC_MODULE : name of the current module in the client application. It's recorded in the column MODULE of the system view V$SESSION
OCI_TRC_ACTION : name of the current action within the current module. It's recorded in the column ACTION of the system view V$SESSION
OCI_TRC_DETAIL : Client application additional information. It's recorded in the column CLIENT_INFO of the system view V$SESSION
OCI_TRC_OPERATION: Client application database operation. It's recorded in the column DBOP_NAME of the system view V$SQL_MONITOR
Warning
The system view V$SESSION is updated on Oracle versions >= 10gR1 The system view V$SQL_MONITOR is updated on Oracle versions >= 12cR1

Oracle limits the size of these traces content:
OCI_TRC_IDENTITY : 64 bytes
OCI_TRC_MODULE : 48 bytes
OCI_TRC_ACTION : 32 bytes
OCI_TRC_DETAIL : 64 bytes
OCI_TRC_OPERATION: 32 bytes

OCILIB truncates input values to match theses limits

Referenced by ocilib::Connection::SetTrace().

◆ OCI_GetTrace()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetTrace	(	OCI_Connection *	con,
		unsigned int	trace
	)

#include <api.h>

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

Parameters

con	- connection handle
trace	- trace type

Note: See OCI_SetTrace() for more details.

Referenced by ocilib::Connection::GetTrace().

◆ OCI_Ping()

OCI_SYM_PUBLIC boolean OCI_API OCI_Ping ( OCI_Connection * con )

#include <api.h>

Makes a round trip call to the server to confirm that the connection and the server are active.

Parameters

con	- Connection handle

Note: Returns TRUE is the connection is still alive otherwise FALSE

Warning: This call is supported from Oracle 10g. For previous versions, it returns FALSE without throwing any exception.

Referenced by ocilib::Connection::PingServer().

◆ OCI_SetTimeout()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetTimeout	(	OCI_Connection *	con,
		unsigned int	type,
		unsigned int	value
	)

#include <api.h>

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

Parameters

con	- Connection handle
type	- Type of timeout to set
value	- Timeout in milliseconds

Possible values for parameter 'type':

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

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 OCI_NTO_CALL (all other timeouts are discarded)
2 - Timeouts set using OCI_NTO_SEND and/or OCI_NTO_RECEIVE
3 - Timeouts set in sqlnet.ora file

Here is a summary:

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

Warning: Returns FALSE without throwing any exception if the Oracle client does not support the given flag

Referenced by ocilib::Connection::SetTimeout().

◆ OCI_GetTimeout()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetTimeout	(	OCI_Connection *	con,
		unsigned int	type
	)

#include <api.h>

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

Parameters

con	- Connection handle
type	- Type of timeout

Note: : See OCI_SetTimeout() for more information

Returns: The given timeout value if supported, otherwise 0

Referenced by ocilib::Connection::GetTimeout().

◆ OCI_GetDBName()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetDBName ( OCI_Connection * con )

#include <api.h>

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

Parameters

con	- Connection handle

Warning: This call is supported from Oracle 10gR2. For previous versions, it returns NULL without throwing any exception.

Referenced by ocilib::Connection::GetDatabase().

◆ OCI_GetInstanceName()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetInstanceName ( OCI_Connection * con )

#include <api.h>

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

Parameters

con	- Connection handle

Warning: This call is supported from Oracle 10gR2. For previous versions, it returns NULL without throwing any exception.

Referenced by ocilib::Connection::GetInstance().

◆ OCI_GetServiceName()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetServiceName ( OCI_Connection * con )

#include <api.h>

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

Parameters

con	- Connection handle

Warning: This call is supported from Oracle 10gR2. For previous versions, it returns NULL without throwing any exception.

Referenced by ocilib::Connection::GetService().

◆ OCI_GetServerName()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetServerName ( OCI_Connection * con )

#include <api.h>

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

Parameters

con	- Connection handle

Warning: This call is supported from Oracle 10gR2. For previous versions, it returns NULL without throwing any exception.

Referenced by ocilib::Connection::GetServer().

◆ OCI_GetDomainName()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetDomainName ( OCI_Connection * con )

#include <api.h>

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

Parameters

con	- Connection handle

Warning: This call is supported from Oracle 10gR2. For previous versions, it returns NULL without throwing any exception.

Referenced by ocilib::Connection::GetDomain().

◆ OCI_GetInstanceStartTime()

OCI_SYM_PUBLIC OCI_Timestamp *OCI_API OCI_GetInstanceStartTime ( OCI_Connection * con )

#include <api.h>

Return the date and time (Timestamp) server instance start of the connected database/service name.

Parameters

con	- Connection handle

Warning: This call is supported from Oracle 10gR2. For previous versions, it returns NULL without throwing any exception.

Referenced by ocilib::Connection::GetInstanceStartTime().

◆ OCI_IsTAFCapable()

OCI_SYM_PUBLIC boolean OCI_API OCI_IsTAFCapable ( OCI_Connection * con )

#include <api.h>

Verify if the given connection support TAF events.

Parameters

con	- Connection handle

Note: Returns TRUE is the connection supports TAF event otherwise FALSE

Warning: This call is supported from Oracle 10gR2. For previous versions, it returns FALSE without throwing any exception.

Referenced by ocilib::Connection::IsTAFCapable().

◆ OCI_SetTAFHandler()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetTAFHandler	(	OCI_Connection *	con,
		POCI_TAF_HANDLER	handler
	)

#include <api.h>

Set the Transparent Application Failover (TAF) user handler.

Parameters

con	- Connection handle
handler	- Pointer to TAF handler procedure

Note: See POCI_TAF_HANDLER documentation for more details

Warning: This call is supported from Oracle 10gR2. For previous versions, it returns FALSE without throwing any exception.

Returns: TRUE on success otherwise FALSE

Referenced by ocilib::Connection::SetTAFHandler().

◆ OCI_GetStatementCacheSize()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetStatementCacheSize ( OCI_Connection * con )

#include <api.h>

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

Parameters

con	- Connection handle

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

Warning: Requires Oracle Client 9.2 or above

Referenced by ocilib::Connection::GetStatementCacheSize().

◆ OCI_SetStatementCacheSize()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetStatementCacheSize	(	OCI_Connection *	con,
		unsigned int	value
	)

#include <api.h>

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

Parameters

con	- Connection handle
value	- maximum number of statements in the cache

Warning: Requires Oracle Client 9.2 or above

Returns: TRUE on success otherwise FALSE

Referenced by ocilib::Connection::SetStatementCacheSize().

◆ OCI_GetDefaultLobPrefetchSize()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetDefaultLobPrefetchSize ( OCI_Connection * con )

#include <api.h>

Return the default LOB prefetch buffer size for the connection.

Parameters

con	- Connection handle

Warning: Requires Oracle Client AND Server 11gR1 or above

Note

Prefetch size is:

number of bytes for BLOBs and BFILEs
number of characters for CLOBs.

Default is 0 (prefetching disabled)

Referenced by ocilib::Connection::GetDefaultLobPrefetchSize().

◆ OCI_SetDefaultLobPrefetchSize()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetDefaultLobPrefetchSize	(	OCI_Connection *	con,
		unsigned int	value
	)

#include <api.h>

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

Parameters

con	- Connection handle
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 and BFILEs
number of characters for CLOBs.

Returns: TRUE on success otherwise FALSE

Referenced by ocilib::Connection::SetDefaultLobPrefetchSize().

◆ OCI_GetMaxCursors()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_GetMaxCursors ( OCI_Connection * con )

#include <api.h>

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

Parameters

con	- Connection handle

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

Referenced by ocilib::Connection::GetMaxCursors().

Detailed Description

Functions

Function Documentation

◆ OCI_ConnectionCreate()

◆ OCI_ConnectionFree()

◆ OCI_IsConnected()

◆ OCI_GetUserData()

◆ OCI_SetUserData()

◆ OCI_SetSessionTag()

◆ OCI_GetSessionTag()

◆ OCI_GetDatabase()

◆ OCI_GetUserName()

◆ OCI_GetPassword()

◆ OCI_SetPassword()

◆ OCI_SetUserPassword()

◆ OCI_GetSessionMode()

◆ OCI_GetVersionServer()

◆ OCI_GetServerMajorVersion()

◆ OCI_GetServerMinorVersion()

◆ OCI_GetServerRevisionVersion()

◆ OCI_SetFormat()

◆ OCI_GetFormat()

◆ OCI_GetTransaction()

◆ OCI_SetTransaction()

◆ OCI_GetVersionConnection()

◆ OCI_SetTrace()

◆ OCI_GetTrace()

◆ OCI_Ping()

◆ OCI_SetTimeout()

◆ OCI_GetTimeout()

◆ OCI_GetDBName()

◆ OCI_GetInstanceName()

◆ OCI_GetServiceName()

◆ OCI_GetServerName()

◆ OCI_GetDomainName()

◆ OCI_GetInstanceStartTime()

◆ OCI_IsTAFCapable()

◆ OCI_SetTAFHandler()

◆ OCI_GetStatementCacheSize()

◆ OCI_SetStatementCacheSize()

◆ OCI_GetDefaultLobPrefetchSize()

◆ OCI_SetDefaultLobPrefetchSize()

◆ OCI_GetMaxCursors()