Detailed Description

OcilibCApiErrorHandling

Connecting to an Oracle database server is done with a single call to OCI_ConnectionCreate().

OCI_ConnectionFree() closes the established connection and releases its resources.

Connection properties are accessible through a set of dedicated 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 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:410

OCI_ErrorGetString
OCI_SYM_PUBLIC const otext *OCI_API OCI_ErrorGetString(OCI_Error *err)
Retrieve the error message string from an 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)
	Check if the given connection is still active.

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 with the given connection.

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

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

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

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetUserName (OCI_Connection *con)
	Return the user name of the currently logged-in session.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_GetPassword (OCI_Connection *con)
	Return the password of the currently logged-in session.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetPassword (OCI_Connection con, const otext password)
	Change the password of the currently logged-in 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 specified 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 (server banner), 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 associated with the connection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_SetTransaction (OCI_Connection con, OCI_Transaction trans)
	Associate a transaction with a connection.

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

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

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

OCI_SYM_PUBLIC boolean OCI_API	OCI_Ping (OCI_Connection *con)
	Perform a round-trip call to the server to verify that the connection and 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)
	Return the requested timeout value for OCI calls that require server round-trips.

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

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

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

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

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

OCI_SYM_PUBLIC OCI_Timestamp *OCI_API	OCI_GetInstanceStartTime (OCI_Connection *con)
	Return the date and time (Timestamp) at which the server instance was started.

OCI_SYM_PUBLIC boolean OCI_API	OCI_IsTAFCapable (OCI_Connection *con)
	Check if the given connection supports Transparent Application Failover (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 (or NULL for the default local database)
user	- Oracle user name (or NULL for external credentials)
pwd	- Oracle user password (or NULL for external credentials)
mode	- Session mode

Possible values for parameter mode (mutually exclusive, cannot be combined):

OCI_SESSION_DEFAULT : Standard user session.
OCI_SESSION_SYSDBA : SYSDBA privileged session.
OCI_SESSION_SYSOPER : SYSOPER privileged session.
OCI_SESSION_XA : XA (distributed transaction) session.

Note: External credentials are supported by supplying NULL for both the 'user' and 'pwd' parameters. If the 'db' parameter is NULL, a connection to the default local database is established.

Oracle XA Support

OCILIB supports Oracle XA connectivity. To obtain a connection through the XA interface:

For parameter 'db': pass the value of the 'DB' parameter from the XA connection string provided to the Transaction Processing Monitor (TPM).
Pass NULL for the 'user' and 'pwd' parameters.
Pass OCI_SESSION_XA for the 'mode' parameter.

Oracle XA Connection String Requirements

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 set it to 'false'.
If OCI_ENV_EVENTS is passed to OCI_Initialize(), the XA parameter 'Events' must be set to 'true'; otherwise set it to 'false'.
Oracle does not support Unicode UTF16 through the XA interface; only OCI_CHARSET_ANSI builds of OCILIB can be used.
UTF-8 encoding is still available if the NLS_LANG environment variable is set to a valid UTF-8 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 XA connections or connections 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

Note: All resources (statements, type info objects, etc.) associated with the connection are automatically freed.

Returns: TRUE on success, otherwise FALSE.

◆ OCI_IsConnected()

OCI_SYM_PUBLIC boolean OCI_API OCI_IsConnected ( OCI_Connection * con )

#include <api.h>

Check if the given connection is still active.

Parameters

con	- Connection handle

Returns: TRUE if the connection is still active, otherwise FALSE.

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: Passing NULL for the con parameter is valid. In that case, the function returns the user data stored with global (program-wide) scope.

Returns: The user data pointer, or NULL if none was previously set.

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

◆ OCI_SetUserData()

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

#include <api.h>

Associate a pointer to user data with the given connection.

Parameters

con	- Connection handle
data	- User data pointer

Note: Passing NULL for the con parameter is valid. In that case, the user data is stored with global (program-wide) scope.

Returns: TRUE on success, otherwise FALSE.

Referenced by 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 with the given connection/session.

Parameters

con	- Connection handle
tag	- User tag string

Note: This function is intended for connections retrieved from a session pool. See OCI_PoolGetConnection() for more details.; To remove the tag from a session, call OCI_SetSessionTag() with the 'tag' parameter set to NULL.

Warning: No error is raised if the connection is a standalone connection or was 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 with the given connection.

Parameters

con	- Connection handle

Returns: The session tag string, or NULL if no tag has been set.

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 or service name.

Parameters

con	- Connection handle

Returns: The database/service name string, or NULL on failure.

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

◆ OCI_GetUserName()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetUserName ( OCI_Connection * con )

#include <api.h>

Return the user name of the currently logged-in session.

Parameters

con	- Connection handle

Returns: The user name string, or NULL on failure.

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

◆ OCI_GetPassword()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetPassword ( OCI_Connection * con )

#include <api.h>

Return the password of the currently logged-in session.

Parameters

con	- Connection handle

Returns: The password string, or NULL on failure.

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 currently logged-in 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 specified database.

Parameters

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

Note: This function does not require an active connection; it connects internally to perform the password change.

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

Returns: The session mode. 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 (server banner), as reported by SQL*Plus.

Parameters

con	- Connection handle

Returns: The server version banner string, or NULL on failure.

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 (or NULL for library-level format)
type	- Type of format
format	- Format string

Formats can be set at two levels:

Library level: by passing NULL for the connection handle.
Connection level: by passing a valid connection handle.

When a string conversion is needed, OCILIB searches for a valid format in the following order:

Connection-level format.
Library-level format.
Built-in default format.

Note: Possible values for parameter 'type':

OCI_FMT_DATE : Format for converting DATE to string.
OCI_FMT_TIMESTAMP : Format for converting TIMESTAMP and TIMESTAMP WITH LOCAL TIME ZONE to string.
OCI_FMT_TIMESTAMP_TZ : Format for converting TIMESTAMP WITH TIME ZONE to string.
OCI_FMT_NUMERIC : Format for converting numeric types to string.
OCI_FMT_BINARY_DOUBLE : Format for converting BINARY_DOUBLE to string.
OCI_FMT_BINARY_FLOAT : Format for converting BINARY_FLOAT to string.

Note

Default format values:

OCI_FMT_DATE : OCI_STRING_FORMAT_DATE
OCI_FMT_TIMESTAMP : OCI_STRING_FORMAT_TIMESTAMP
OCI_FMT_TIMESTAMP_TZ : OCI_STRING_FORMAT_TIMESTAMP_TZ
OCI_FMT_NUMERIC : OCI_STRING_FORMAT_NUMERIC
OCI_FMT_BINARY_DOUBLE : OCI_STRING_FORMAT_BINARY_DOUBLE
OCI_FMT_BINARY_FLOAT : OCI_STRING_FORMAT_BINARY_FLOAT

Conversions are performed by Oracle built-in functions whenever possible. For DATE, TIMESTAMP, and numeric types, refer to the Oracle SQL TO_CHAR() function documentation. For BINARY_DOUBLE and BINARY_FLOAT, refer to the C Standard Library printf() family documentation.

Returns: TRUE on success, otherwise FALSE.

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 (or NULL for library-level format)
type	- Type of format

Note: See OCI_SetFormat() for possible values of the 'type' parameter.

Returns: The format string for the specified type, or NULL on failure.

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 associated with the connection.

Parameters

con	- Connection handle

Note: Since version 3.9.4, no default transaction object is created for new connections.

Returns: The transaction handle, or NULL if no transaction is associated with the 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>

Associate a transaction with a connection.

Parameters

con	- Connection handle
trans	- Transaction handle to assign

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

Warning: Do not assign a transaction object to an XA connection or a connection retrieved from a session pool.

Returns: TRUE on success, otherwise FALSE.

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 supported by the connection.

Parameters

con	- Connection handle

Note: The highest supported version is the lower of the client and server versions.

Returns: One of the OCI version constants (e.g., OCI_8_0, OCI_9_2, OCI_10_1, OCI_11_2, OCI_12_1, OCI_18_3, etc.), or OCI_UNKNOWN on failure.

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 on the session of the given connection.

Parameters

con	- Connection handle
trace	- Trace type
value	- Trace content string

Stores trace information on the given connection session. This information:

Is recorded in the system views V$SESSION and/or V$SQL_MONITOR.
Can be used for application monitoring and diagnostics.

Note: Possible values for parameter 'trace':

OCI_TRC_IDENTITY : User-defined identifier. Recorded in V$SESSION.CLIENT_IDENTIFIER.
OCI_TRC_MODULE : Current module name. Recorded in V$SESSION.MODULE.
OCI_TRC_ACTION : Current action within the module. Recorded in V$SESSION.ACTION.
OCI_TRC_DETAIL : Additional client information. Recorded in V$SESSION.CLIENT_INFO.
OCI_TRC_OPERATION : Database operation name. Recorded in V$SQL_MONITOR.DBOP_NAME.

Warning: The V$SESSION view is updated on Oracle versions >= 10gR1. The V$SQL_MONITOR view is updated on Oracle versions >= 12cR1.; Oracle limits the size of trace 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 these limits.

Returns: TRUE on success, otherwise FALSE.

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>

Return the current trace value for the given trace type from the connection.

Parameters

con	- Connection handle
trace	- Trace type

Note: See OCI_SetTrace() for possible values of the 'trace' parameter.

Returns: The trace string value, or NULL if not set or on failure.

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

◆ OCI_Ping()

OCI_SYM_PUBLIC boolean OCI_API OCI_Ping ( OCI_Connection * con )

#include <api.h>

Perform a round-trip call to the server to verify that the connection and server are active.

Parameters

con	- Connection handle

Warning: This feature requires Oracle 10g or later. For earlier versions, the function returns FALSE without raising an exception.

Returns: TRUE if the connection is still alive, otherwise FALSE.

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

The OCI client raises a timeout-related error when a given timeout is reached.

Note: To disable a given timeout, pass the value 0.

Warning

The OCI client applies the following precedence rules for 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 the sqlnet.ora file.

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 raising an exception if the Oracle client does not support the given flag.

Returns: TRUE on success, otherwise FALSE.

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>

Return the requested timeout value for OCI calls that require server round-trips.

Parameters

con	- Connection handle
type	- Type of timeout

Note: See OCI_SetTimeout() for possible values of the 'type' parameter.

Returns: The timeout value in milliseconds 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.

Parameters

con	- Connection handle

Warning: This feature requires Oracle 10gR2 or later. For earlier versions, the function returns NULL without raising an exception.

Returns: The database name string, or NULL on failure or if not supported.

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.

Parameters

con	- Connection handle

Warning: This feature requires Oracle 10gR2 or later. For earlier versions, the function returns NULL without raising an exception.

Returns: The instance name string, or NULL on failure or if not supported.

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.

Parameters

con	- Connection handle

Warning: This feature requires Oracle 10gR2 or later. For earlier versions, the function returns NULL without raising an exception.

Returns: The service name string, or NULL on failure or if not supported.

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.

Parameters

con	- Connection handle

Warning: This feature requires Oracle 10gR2 or later. For earlier versions, the function returns NULL without raising an exception.

Returns: The server machine name string, or NULL on failure or if not supported.

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.

Parameters

con	- Connection handle

Warning: This feature requires Oracle 10gR2 or later. For earlier versions, the function returns NULL without raising an exception.

Returns: The domain name string, or NULL on failure or if not supported.

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) at which the server instance was started.

Parameters

con	- Connection handle

Warning: This feature requires Oracle 10gR2 or later. For earlier versions, the function returns NULL without raising an exception.

Returns: A timestamp handle representing the instance start time, or NULL on failure or if not supported.

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

◆ OCI_IsTAFCapable()

OCI_SYM_PUBLIC boolean OCI_API OCI_IsTAFCapable ( OCI_Connection * con )

#include <api.h>

Check if the given connection supports Transparent Application Failover (TAF) events.

Parameters

con	- Connection handle

Warning: This feature requires Oracle 10gR2 or later. For earlier versions, the function returns FALSE without raising an exception.

Returns: TRUE if the connection supports TAF events, otherwise FALSE.

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 the TAF handler procedure (see POCI_TAF_HANDLER)

Warning: This feature requires Oracle 10gR2 or later. For earlier versions, the function returns FALSE without raising an 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: The default value is 20 (as documented by Oracle).

Warning: Requires Oracle Client 9.2 or later.

Returns: The maximum number of cached statements.

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 later.

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 later.

Note

The prefetch size unit is:

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

The default value is 0 (prefetching disabled).

Returns: The prefetch buffer size, or 0 if prefetching is 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, prefetching is disabled for all LOBs fetched in the connection.
Is greater than 0, prefetching is enabled with the specified buffer size.

LOB prefetching is disabled by default.

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

Note

The prefetch size unit 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 later.

Note: The returned value corresponds to the 'open_cursors' database parameter from the server's parameter file.

Returns: The maximum number of open cursors, or 0 if the client and server versions are earlier than 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()