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 previously pointer to user data associated with the connection.
OCI_EXPORT boolean OCI_API OCI_SetUserData (OCI_Connection *con, void *data)
 Associate to the given connection a pointer to user data.
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 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 :

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 transaction is automatically created and started

Returns:
Connection handle on success or NULL on failure

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

References OCI_Error::con, and OCI_Connection::pool.

Referenced by OCI_ConnectionCreate(), OCI_ConnPoolGetConnection(), OCI_DatabaseShutdown(), and OCI_DatabaseStartup().

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 743 of file connection.c.

References OCI_Connection::db.

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 1028 of file connection.c.

References OCI_Connection::fmt_date, and OCI_SetDefaultFormatDate().

Referenced by OCI_GetString().

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 1065 of file connection.c.

References OCI_Connection::fmt_num, and OCI_SetDefaultFormatNumeric().

Referenced by OCI_GetString().

OCI_EXPORT const mtext* OCI_API OCI_GetPassword ( OCI_Connection con  ) 

Return the current logged user password.

Parameters:
con - Connection handle

Definition at line 769 of file connection.c.

References OCI_Connection::pwd.

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 904 of file connection.c.

References OCI_GetVersionServer(), and OCI_Connection::ver_num.

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 920 of file connection.c.

References OCI_GetVersionServer(), and OCI_Connection::ver_num.

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 936 of file connection.c.

References OCI_GetVersionServer(), and OCI_Connection::ver_num.

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 809 of file connection.c.

References OCI_Connection::mode.

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 1388 of file connection.c.

References OCI_Connection::trace.

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 952 of file connection.c.

References OCI_Connection::trs.

OCI_EXPORT void* OCI_API OCI_GetUserData ( OCI_Connection con  ) 

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

Parameters:
con - Connection handle

Definition at line 715 of file connection.c.

References OCI_Connection::usrdata.

OCI_EXPORT const mtext* OCI_API OCI_GetUserName ( OCI_Connection con  ) 

Return the current logged user name.

Parameters:
con - Connection handle

Definition at line 756 of file connection.c.

References OCI_Connection::user.

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 :

Definition at line 986 of file connection.c.

References OCI_GetOCIRuntimeVersion(), OCI_GetServerMajorVersion(), and OCI_Connection::ver_num.

Referenced by OCI_RegisterDate().

OCI_EXPORT const mtext* OCI_API OCI_GetVersionServer ( OCI_Connection con  ) 

Return the connected database server version.

Parameters:
con - Connection handle

Definition at line 822 of file connection.c.

References OCI_Connection::cxt, OCI_Connection::err, OCI_Connection::mode, OCI_Connection::ver_num, and OCI_Connection::ver_str.

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

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 689 of file connection.c.

References OCI_Connection::err, and OCI_Connection::svr.

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 1434 of file connection.c.

References OCI_Connection::cxt, and OCI_Connection::err.

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'

Possible values are the string date format supported by Oracle. See documentation of Oracle SQL to_date() function for more details

Definition at line 1007 of file connection.c.

References OCI_Connection::fmt_date.

Referenced by OCI_GetDefaultFormatDate().

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

Defauft format is :

  • 'FM99999999999999999999999999999999999990.999999999999999999999999'
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 1044 of file connection.c.

References OCI_Connection::fmt_num.

Referenced by OCI_GetDefaultFormatNumeric().

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 782 of file connection.c.

References OCI_Connection::cxt, OCI_Connection::err, OCI_Connection::pwd, and OCI_Connection::user.

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:

Note:
Possible values of parameter 'trace type' :

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 :

Definition at line 1257 of file connection.c.

References OCI_Connection::err, OCI_Connection::ses, and OCI_Connection::trace.

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 965 of file connection.c.

References OCI_TransactionStop(), and OCI_Connection::trs.

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

Associate to the given connection a pointer to user data.

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

Definition at line 728 of file connection.c.

References OCI_Connection::usrdata.


Generated on Thu Jul 30 17:41:54 2009 for OCILIB (C Driver for Oracle) by  doxygen 1.5.4