OCILIB (C Driver for Oracle) 3.12.1
Functions
Connecting to Database

Detailed Description

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"

int main(void)
{
    OCI_Connection *cn;

    if (!OCI_Initialize(NULL, 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_Cleanup();

    return EXIT_SUCCESS;
}

Functions

OCI_EXPORT OCI_Connection *OCI_API OCI_ConnectionCreate (const mtext *db, const mtext *user, const mtext *pwd, unsigned int mode)
 Create a physical connection to an Oracle database server.
OCI_EXPORT boolean OCI_API OCI_ConnectionFree (OCI_Connection *con)
 Close a physical connection to an Oracle database server.
OCI_EXPORT boolean OCI_API OCI_IsConnected (OCI_Connection *con)
 Returns TRUE is the given connection is still connected otherwise FALSE.
OCI_EXPORT void *OCI_API OCI_GetUserData (OCI_Connection *con)
 Return the pointer to user data previously associated with the connection.
OCI_EXPORT boolean OCI_API OCI_SetUserData (OCI_Connection *con, void *data)
 Associate a pointer to user data to the given connection.
OCI_EXPORT boolean OCI_API OCI_SetSessionTag (OCI_Connection *con, const mtext *tag)
 Associate a tag to the given connection/session.
OCI_EXPORT const mtext *OCI_API OCI_GetSessionTag (OCI_Connection *con)
 Return the tag associated the the given connection.
OCI_EXPORT const mtext *OCI_API OCI_GetDatabase (OCI_Connection *con)
 Return the name of the connected database/service name.
OCI_EXPORT const mtext *OCI_API OCI_GetUserName (OCI_Connection *con)
 Return the current logged user name.
OCI_EXPORT const mtext *OCI_API OCI_GetPassword (OCI_Connection *con)
 Return the current logged user password.
OCI_EXPORT boolean OCI_API OCI_SetPassword (OCI_Connection *con, const mtext *password)
 Change the password of the logged user.
OCI_EXPORT boolean OCI_API OCI_SetUserPassword (const mtext *db, const mtext *user, const mtext *pwd, const mtext *new_pwd)
 Change the password of the given user on the given database.
OCI_EXPORT unsigned int OCI_API OCI_GetSessionMode (OCI_Connection *con)
 Return the current session mode.
OCI_EXPORT const mtext *OCI_API OCI_GetVersionServer (OCI_Connection *con)
 Return the connected database server version.
OCI_EXPORT unsigned int OCI_API OCI_GetServerMajorVersion (OCI_Connection *con)
 Return the major version number of the connected database server.
OCI_EXPORT unsigned int OCI_API OCI_GetServerMinorVersion (OCI_Connection *con)
 Return the minor version number of the connected database server.
OCI_EXPORT unsigned int OCI_API OCI_GetServerRevisionVersion (OCI_Connection *con)
 Return the revision version number of the connected database server.
OCI_EXPORT boolean OCI_API OCI_SetDefaultFormatDate (OCI_Connection *con, const mtext *format)
 Set the date format for implicit string / date conversions.
OCI_EXPORT const mtext *OCI_API OCI_GetDefaultFormatDate (OCI_Connection *con)
 Return the current date format for implicit string / date conversions.
OCI_EXPORT boolean OCI_API OCI_SetDefaultFormatNumeric (OCI_Connection *con, const mtext *format)
 Set the numeric format for implicit string / numeric conversions.
OCI_EXPORT const mtext *OCI_API OCI_GetDefaultFormatNumeric (OCI_Connection *con)
 Return the current numeric format for implicit string / numeric conversions.
OCI_EXPORT OCI_Transaction *OCI_API OCI_GetTransaction (OCI_Connection *con)
 Return the current transaction of the connection.
OCI_EXPORT boolean OCI_API OCI_SetTransaction (OCI_Connection *con, OCI_Transaction *trans)
 Set a transaction to a connection.
OCI_EXPORT unsigned int OCI_API OCI_GetVersionConnection (OCI_Connection *con)
 Return the highest Oracle version is supported by the connection.
OCI_EXPORT boolean OCI_API OCI_SetTrace (OCI_Connection *con, unsigned int trace, const mtext *value)
 Set tracing information to the session of the given connection.
OCI_EXPORT const mtext *OCI_API OCI_GetTrace (OCI_Connection *con, unsigned int trace)
 Get the current trace for the trace type from the given connection.
OCI_EXPORT 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_EXPORT const mtext *OCI_API OCI_GetDBName (OCI_Connection *con)
 Return the Oracle server database name of the connected database/service name.
OCI_EXPORT const mtext *OCI_API OCI_GetInstanceName (OCI_Connection *con)
 Return the Oracle server Instance name of the connected database/service name.
OCI_EXPORT const mtext *OCI_API OCI_GetServiceName (OCI_Connection *con)
 Return the Oracle server service name of the connected database/service name.
OCI_EXPORT const mtext *OCI_API OCI_GetServerName (OCI_Connection *con)
 Return the Oracle server machine name of the connected database/service name.
OCI_EXPORT const mtext *OCI_API OCI_GetDomainName (OCI_Connection *con)
 Return the Oracle server domain name of the connected database/service name.
OCI_EXPORT 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_EXPORT boolean OCI_API OCI_IsTAFCapable (OCI_Connection *con)
 Verifiy if the given connection support TAF events.
OCI_EXPORT boolean OCI_API OCI_SetTAFHandler (OCI_Connection *con, POCI_TAF_HANDLER handler)
 Set the Transparent Application Failover (TAF) user handler.
OCI_EXPORT unsigned int OCI_API OCI_GetStatementCacheSize (OCI_Connection *con)
 Return the maximum number of statements to keep in the statement cache.
OCI_EXPORT boolean OCI_API OCI_SetStatementCacheSize (OCI_Connection *con, unsigned int value)
 Set the maximum number of statements to keep in the statement cache.
OCI_EXPORT unsigned int OCI_API OCI_GetDefaultLobPrefetchSize (OCI_Connection *con)
 Return the default LOB prefetch buffer size for the connection.
OCI_EXPORT boolean OCI_API OCI_SetDefaultLobPrefetchSize (OCI_Connection *con, unsigned int value)
 Enable or disable prefetching for all LOBs fetched in the connection.

Function Documentation

OCI_EXPORT OCI_Connection* OCI_API OCI_ConnectionCreate ( const mtext *  db,
const mtext *  user,
const mtext *  pwd,
unsigned int  mode 
)

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 :

  • Pass to the parameter 'db' the value of the 'DB' parameter of the given XA connection string pased 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 characterset 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_MIXED or 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 connection retrieved from session pools.
Returns:
Connection handle on success or NULL on failure

Definition at line 952 of file connection.c.

References OCI_ConnectionFree().

Referenced by OCI_DatabaseShutdown(), and OCI_DatabaseStartup().

OCI_EXPORT boolean OCI_API OCI_ConnectionFree ( OCI_Connection con)

Close a physical connection to an Oracle database server.

Parameters:
con- Connection handle
Returns:
TRUE on success otherwise FALSE

Definition at line 992 of file connection.c.

Referenced by OCI_ConnectionCreate(), OCI_DatabaseShutdown(), OCI_DatabaseStartup(), OCI_PoolGetConnection(), and OCI_SetUserPassword().

OCI_EXPORT boolean OCI_API OCI_IsConnected ( OCI_Connection con)

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

Parameters:
con- Connection handle

Definition at line 1123 of file connection.c.

OCI_EXPORT void* OCI_API OCI_GetUserData ( OCI_Connection con)

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

Parameters:
con- Connection handle

Definition at line 1151 of file connection.c.

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

Associate a pointer to user data to the given connection.

Parameters:
con- Connection handle
data- User data pointer
Returns:
TRUE on success otherwise FALSE

Definition at line 1167 of file connection.c.

OCI_EXPORT boolean OCI_API OCI_SetSessionTag ( OCI_Connection con,
const mtext *  tag 
)

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 ot 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

Definition at line 1186 of file connection.c.

OCI_EXPORT const mtext* OCI_API OCI_GetSessionTag ( OCI_Connection con)

Return the tag associated the the given connection.

Parameters:
con- Connection handle

Definition at line 1226 of file connection.c.

OCI_EXPORT const mtext* OCI_API OCI_GetDatabase ( OCI_Connection con)

Return the name of the connected database/service name.

Parameters:
con- Connection handle

Definition at line 1242 of file connection.c.

OCI_EXPORT const mtext* OCI_API OCI_GetUserName ( OCI_Connection con)

Return the current logged user name.

Parameters:
con- Connection handle

Definition at line 1258 of file connection.c.

OCI_EXPORT const mtext* OCI_API OCI_GetPassword ( OCI_Connection con)

Return the current logged user password.

Parameters:
con- Connection handle

Definition at line 1274 of file connection.c.

OCI_EXPORT boolean OCI_API OCI_SetPassword ( OCI_Connection con,
const mtext *  password 
)

Change the password of the logged user.

Parameters:
con- Connection handle
password- New password
Returns:
TRUE on success otherwise FALSE

Definition at line 1290 of file connection.c.

OCI_EXPORT boolean OCI_API OCI_SetUserPassword ( const mtext *  db,
const mtext *  user,
const mtext *  pwd,
const mtext *  new_pwd 
)

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

Definition at line 1343 of file connection.c.

References OCI_ConnectionFree().

OCI_EXPORT unsigned int OCI_API OCI_GetSessionMode ( OCI_Connection con)

Return the current session mode.

Parameters:
con- Connection handle
Note:
See OCI_ConnectionCreate() for possible values

Definition at line 1388 of file connection.c.

OCI_EXPORT const mtext* OCI_API OCI_GetVersionServer ( OCI_Connection con)

Return the connected database server version.

Parameters:
con- Connection handle

Definition at line 1404 of file connection.c.

Referenced by OCI_GetServerMajorVersion(), OCI_GetServerMinorVersion(), and OCI_GetServerRevisionVersion().

OCI_EXPORT unsigned int OCI_API OCI_GetServerMajorVersion ( OCI_Connection con)

Return the major version number of the connected database server.

Parameters:
con- Connection handle
Returns:
Version number or 0 on failure

Definition at line 1492 of file connection.c.

References OCI_GetVersionServer().

OCI_EXPORT unsigned int OCI_API OCI_GetServerMinorVersion ( OCI_Connection con)

Return the minor version number of the connected database server.

Parameters:
con- Connection handle
Returns:
Version number or 0 on failure

Definition at line 1513 of file connection.c.

References OCI_GetVersionServer().

OCI_EXPORT unsigned int OCI_API OCI_GetServerRevisionVersion ( OCI_Connection con)

Return the revision version number of the connected database server.

Parameters:
con- Connection handle
Returns:
Version number or 0 on failure

Definition at line 1534 of file connection.c.

References OCI_GetVersionServer().

OCI_EXPORT boolean OCI_API OCI_SetDefaultFormatDate ( OCI_Connection con,
const mtext *  format 
)

Set the date format for implicit string / date conversions.

Parameters:
con- Connection handle
format- Date format
Note:
Default format is 'YYYY-MM-DD' defined by the public constant OCI_STRING_FORMAT_DATE
Conversions are performed by Oracle builtin functions. Possible values are the string date format supported by Oracle. See documentation of Oracle SQL to_date() function for more details

Definition at line 1630 of file connection.c.

Referenced by OCI_GetDefaultFormatDate().

OCI_EXPORT const mtext* OCI_API OCI_GetDefaultFormatDate ( OCI_Connection con)

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

Parameters:
con- Connection handle
Note:
See OCI_SetFormatDate() for possible values

Definition at line 1655 of file connection.c.

References OCI_SetDefaultFormatDate().

Referenced by OCI_GetString().

OCI_EXPORT boolean OCI_API OCI_SetDefaultFormatNumeric ( OCI_Connection con,
const mtext *  format 
)

Set the numeric format for implicit string / numeric conversions.

Parameters:
con- Connection handle
format- Numeric format
Note:
Conversions are performed by Oracle builtin functions. Possible values are the string numeric format supported by Oracle. See documentation of Oracle SQL to_number() function for more details
Default format is 'FM99999999999999999999999999999999999990.999999999999999999999999' defined by the public constant OCI_STRING_FORMAT_NUM
Warning:
If data fetched from a string column cannot be converted to a number value with the given format, an error will be raised
It does not applies to binary double and binary floats data types that are converted from/to strings using the standard C library

Definition at line 1676 of file connection.c.

Referenced by OCI_GetDefaultFormatNumeric().

OCI_EXPORT const mtext* OCI_API OCI_GetDefaultFormatNumeric ( OCI_Connection con)

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

Parameters:
con- Connection handle
Note:
See OCI_SetFormatNumeric() for possible values

Definition at line 1701 of file connection.c.

References OCI_SetDefaultFormatNumeric().

OCI_EXPORT OCI_Transaction* OCI_API OCI_GetTransaction ( OCI_Connection con)

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

Definition at line 1555 of file connection.c.

OCI_EXPORT boolean OCI_API OCI_SetTransaction ( OCI_Connection con,
OCI_Transaction trans 
)

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

Definition at line 1571 of file connection.c.

References OCI_TransactionStop().

OCI_EXPORT unsigned int OCI_API OCI_GetVersionConnection ( OCI_Connection con)

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

Definition at line 1612 of file connection.c.

Referenced by OCI_RegisterDate().

OCI_EXPORT boolean OCI_API OCI_SetTrace ( OCI_Connection con,
unsigned int  trace,
const mtext *  value 
)

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 the system view V$SESSION
  • 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
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 :
  • OCI_TRC_IDENTITY : 64 bytes
  • OCI_TRC_MODULE : 48 bytes
  • OCI_TRC_ACTION : 32 bytes
  • OCI_TRC_DETAIL : 64 bytes

Definition at line 1921 of file connection.c.

OCI_EXPORT const mtext* OCI_API OCI_GetTrace ( OCI_Connection con,
unsigned int  trace 
)

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.

Definition at line 2069 of file connection.c.

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

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.

Definition at line 2121 of file connection.c.

OCI_EXPORT const mtext* OCI_API OCI_GetDBName ( OCI_Connection con)

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.

Definition at line 2157 of file connection.c.

OCI_EXPORT const mtext* OCI_API OCI_GetInstanceName ( OCI_Connection con)

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.

Definition at line 2185 of file connection.c.

OCI_EXPORT const mtext* OCI_API OCI_GetServiceName ( OCI_Connection con)

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.

Definition at line 2213 of file connection.c.

OCI_EXPORT const mtext* OCI_API OCI_GetServerName ( OCI_Connection con)

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.

Definition at line 2241 of file connection.c.

OCI_EXPORT const mtext* OCI_API OCI_GetDomainName ( OCI_Connection con)

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.

Definition at line 2269 of file connection.c.

OCI_EXPORT OCI_Timestamp* OCI_API OCI_GetInstanceStartTime ( OCI_Connection con)

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.

Definition at line 2297 of file connection.c.

OCI_EXPORT boolean OCI_API OCI_IsTAFCapable ( OCI_Connection con)

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

Definition at line 2338 of file connection.c.

Referenced by OCI_SetTAFHandler().

OCI_EXPORT boolean OCI_API OCI_SetTAFHandler ( OCI_Connection con,
POCI_TAF_HANDLER  handler 
)

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

Definition at line 2373 of file connection.c.

References OCI_IsTAFCapable().

OCI_EXPORT unsigned int OCI_API OCI_GetStatementCacheSize ( OCI_Connection con)

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

Definition at line 2421 of file connection.c.

OCI_EXPORT boolean OCI_API OCI_SetStatementCacheSize ( OCI_Connection con,
unsigned int  value 
)

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

Parameters:
con- Connection handle
value- maximun number of statements in the cache
Warning:
Requires Oracle Client 9.2 or above
Returns:
TRUE on success otherwise FALSE

Definition at line 2456 of file connection.c.

Referenced by OCI_PoolGetConnection().

OCI_EXPORT unsigned int OCI_API OCI_GetDefaultLobPrefetchSize ( OCI_Connection con)

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)

Definition at line 2496 of file connection.c.

OCI_EXPORT boolean OCI_API OCI_SetDefaultLobPrefetchSize ( OCI_Connection con,
unsigned int  value 
)

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

Definition at line 2531 of file connection.c.