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)
 Return the current transaction attached to the 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.

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
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
On success, a local transaction is automatically created and started
Returns:
Connection handle on success or NULL on failure

Definition at line 770 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 805 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 932 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 962 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 978 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 997 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 1037 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 1053 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 1069 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 1085 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 1101 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 1155 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 1199 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 1215 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 1302 of file connection.c.

References OCI_GetVersionServer().

Referenced by OCI_GetVersionConnection().

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 1321 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 1340 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
Possible values are the string date format supported by Oracle. See documentation of Oracle SQL to_date() function for more details

Definition at line 1423 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 1448 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:
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

Definition at line 1467 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 1492 of file connection.c.

References OCI_SetDefaultFormatNumeric().

Referenced by OCI_GetString().

OCI_EXPORT OCI_Transaction* OCI_API OCI_GetTransaction ( OCI_Connection con )

Return the current transaction of the connection.

Parameters:
con- Connection handle

Definition at line 1359 of file connection.c.

OCI_EXPORT boolean OCI_API OCI_SetTransaction ( OCI_Connection con,
OCI_Transaction trans 
)

Return the current transaction attached to the connection.

Parameters:
con- Connection handle
trans- Transaction handle to assign
Note:
The current transaction is automatically stopped but the newly assigned is not started or resumed

Definition at line 1375 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 1400 of file connection.c.

References OCI_GetOCIRuntimeVersion(), and OCI_GetServerMajorVersion().

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 1708 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 1843 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 version, it returns FALSE without throwing any exception.

Definition at line 1893 of file connection.c.