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

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;
}


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 occured.
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_Connection* OCI_API OCI_ErrorGetConnection ( OCI_Error err  ) 

Retrieve connection handle within the error occurred.

Parameters:
err - Error handle

Definition at line 169 of file error.c.

References OCI_Error::con.

OCI_EXPORT int OCI_API OCI_ErrorGetInternalCode ( OCI_Error err  ) 

Retrieve Internal Error code from error handle.

Parameters:
err - Error handle

Definition at line 158 of file error.c.

References OCI_Error::icode.

OCI_EXPORT int OCI_API OCI_ErrorGetOCICode ( OCI_Error err  ) 

Retrieve Oracle Error code from error handle.

Parameters:
err - Error handle

Definition at line 147 of file error.c.

References OCI_Error::ocode.

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 191 of file error.c.

References OCI_Error::row.

OCI_EXPORT OCI_Statement* OCI_API OCI_ErrorGetStatement ( OCI_Error err  ) 

Retrieve statement handle within the error occured.

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

Definition at line 180 of file error.c.

References OCI_Error::stmt.

OCI_EXPORT const mtext* OCI_API OCI_ErrorGetString ( OCI_Error err  ) 

Retrieve error message from error handle.

Parameters:
err - Error handle

Definition at line 125 of file error.c.

References OCI_Error::str.

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 :

Returns:
Object type or OCI_UNKNOWN the input handle is NULL

Definition at line 136 of file error.c.

References OCI_Error::type.

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 1256 of file library.c.

References OCI_Error::raise.


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