Functions

Error handling


Detailed Description

OCILIB provides two mechanisms for error handling:

Exceptions are raised:

If an error handler was provided to OCI_Initialize(), when an error occurs, the library generates an OCI_Error handle and pass it to the error handler.

In order to use the thread contextual error handling, you must call OCI_Initialize() with the flag OCI_ENV_CONTEXT for the mode parameter. When activated, error handles are stored per thread and the last error within a thread can be retrieved with OCI_GetLastError()

Exception properties are accessible through a set of functions

Note:
The two ways to handle errors are not exclusive and can be mixed.
Thread contextual error is also available for single thread based applications
Oracle Warnings

Oracle warnings are raised through OCI_Error API. Such error handles have their error type property (OCI_ErrorGetType()) set to OCI_ERR_WARNING. Warning handing is disabled by default. To activate/deactivate it, use OCI_EnableWarnings()

Example with callbacks
#include "ocilib.h"

void err_handler(OCI_Error *err)
{
    printf(
                "code  : ORA-%05i\n"
                "msg   : %s\n"
                "sql   : %s\n",
                OCI_ErrorGetOCICode(err), 
                OCI_ErrorGetString(err),
                OCI_GetSql(OCI_ErrorGetStatement(err))
           );
}

int main(void)
{
    OCI_Connection *cn;

    if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("wrong_db", "wrong_usr", "wrong_pwd", 
                              OCI_SESSION_DEFAULT);

    /* ... application code here ... */

    OCI_Cleanup();

 
    return EXIT_SUCCESS;
}
Example with thread context
#include "ocilib.h"

int main(void)
{
    OCI_Connection *cn;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT | OCI_ENV_CONTEXT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("wrong_db", "wrong_usr", "wrong_pwd", 
                              OCI_SESSION_DEFAULT);

    if (cn == NULL)
    {
        OCI_Error *err = OCI_GetLastError();

        printf("errcode %d, errmsg %s", OCI_ErrorGetOCICode(err), 
                                        OCI_ErrorGetString(err));
    }

    OCI_Cleanup();

 
    return EXIT_SUCCESS;
}
Example of warning handling
#include "ocilib.h"

void err_handler(OCI_Error *err)
{
    int   err_type = OCI_ErrorGetType(err);
    char *err_msg  = OCI_ErrorGetString(err);

    printf("%s - %s\n", err_type == OCI_ERR_WARNING ? "warning" : "error", err_msg);
}

int main(void)
{
    OCI_Connection *cn;

    if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    OCI_EnableWarnings(TRUE);

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

    /* ... application code here ... */

    OCI_Cleanup();

 
    return EXIT_SUCCESS;
}

Functions

OCI_EXPORT OCI_Error *OCI_API OCI_GetLastError (void)
 Retrieve the last error occurred within the last OCILIB call.
OCI_EXPORT const mtext *OCI_API OCI_ErrorGetString (OCI_Error *err)
 Retrieve error message from error handle.
OCI_EXPORT unsigned int OCI_API OCI_ErrorGetType (OCI_Error *err)
 Retrieve the type of error from error handle.
OCI_EXPORT int OCI_API OCI_ErrorGetOCICode (OCI_Error *err)
 Retrieve Oracle Error code from error handle.
OCI_EXPORT int OCI_API OCI_ErrorGetInternalCode (OCI_Error *err)
 Retrieve Internal Error code from error handle.
OCI_EXPORT OCI_Connection *OCI_API OCI_ErrorGetConnection (OCI_Error *err)
 Retrieve connection handle within the error occurred.
OCI_EXPORT OCI_Statement *OCI_API OCI_ErrorGetStatement (OCI_Error *err)
 Retrieve statement handle within the error occurred.
OCI_EXPORT unsigned int OCI_API OCI_ErrorGetRow (OCI_Error *err)
 Return the row index which caused an error during statement execution.

Function Documentation

OCI_EXPORT OCI_Error* OCI_API OCI_GetLastError ( void   )

Retrieve the last error occurred within the last OCILIB call.

Note:
OCI_GetLastError() is based on thread context and thus OCILIB must be initialized with the flag OCI_ENV_CONTEXT

Definition at line 1390 of file library.c.

OCI_EXPORT const mtext* OCI_API OCI_ErrorGetString ( OCI_Error err )

Retrieve error message from error handle.

Parameters:
err- Error handle

Definition at line 148 of file error.c.

OCI_EXPORT unsigned int OCI_API OCI_ErrorGetType ( OCI_Error err )

Retrieve the type of error from error handle.

Parameters:
err- Error handle
Note:
Returns one of the following values:
  • OCI_ERR_ORACLE
  • OCI_ERR_OCILIB
  • OCI_ERR_WARNING
Returns:
Object type or OCI_UNKNOWN the input handle is NULL

Definition at line 162 of file error.c.

OCI_EXPORT int OCI_API OCI_ErrorGetOCICode ( OCI_Error err )

Retrieve Oracle Error code from error handle.

Parameters:
err- Error handle

Definition at line 176 of file error.c.

OCI_EXPORT int OCI_API OCI_ErrorGetInternalCode ( OCI_Error err )

Retrieve Internal Error code from error handle.

Parameters:
err- Error handle

Definition at line 190 of file error.c.

OCI_EXPORT OCI_Connection* OCI_API OCI_ErrorGetConnection ( OCI_Error err )

Retrieve connection handle within the error occurred.

Parameters:
err- Error handle

Definition at line 204 of file error.c.

OCI_EXPORT OCI_Statement* OCI_API OCI_ErrorGetStatement ( OCI_Error err )

Retrieve statement handle within the error occurred.

Parameters:
err- Error handle
Note:
If the error occurred outside of a statement context, it returns NULL

Definition at line 218 of file error.c.

OCI_EXPORT unsigned int OCI_API OCI_ErrorGetRow ( OCI_Error err )

Return the row index which caused an error during statement execution.

Parameters:
err- Error handle
Warning:
Row index start at 1.
Returns:
0 is the error is not related to array DML otherwise the index of the given row which caused the error

Definition at line 232 of file error.c.