Error handling

Detailed Description

OcilibCApiInitialization

OCILIB provides two mechanisms for error handling:

• Global error handling through callbacks.
• Contextual thread error handling

Exceptions are raised:

• On Oracle OCI API call error
• On Oracle SQL statement error
• On Internal OCILIB error (type checking, memory allocations ...)
• On Oracle warnings (OCI API or SQL)

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("db", "wrong_usr", "wrong_pwd", OCI_SESSION_DEFAULT);
 
    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("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);
 
    OCI_Cleanup();
 
    return EXIT_SUCCESS;
}
 

Functions
OCI_SYM_PUBLIC boolean OCI_API	OCI_SetErrorHandler (POCI_ERROR handler)
	Set the global error user handler.
OCI_SYM_PUBLIC OCI_Error *OCI_API	OCI_GetLastError (void)
	Retrieve the last error or warning occurred within the last OCILIB call.
OCI_SYM_PUBLIC const otext *OCI_API	OCI_ErrorGetString (OCI_Error *err)
	Retrieve error message from error handle.
OCI_SYM_PUBLIC unsigned int OCI_API	OCI_ErrorGetType (OCI_Error *err)
	Retrieve the type of error from error handle.
OCI_SYM_PUBLIC int OCI_API	OCI_ErrorGetOCICode (OCI_Error *err)
	Retrieve Oracle Error code from error handle.
OCI_SYM_PUBLIC int OCI_API	OCI_ErrorGetInternalCode (OCI_Error *err)
	Retrieve Internal Error code from error handle.
OCI_SYM_PUBLIC OCI_Connection *OCI_API	OCI_ErrorGetConnection (OCI_Error *err)
	Retrieve connection handle within the error occurred.
OCI_SYM_PUBLIC OCI_Statement *OCI_API	OCI_ErrorGetStatement (OCI_Error *err)
	Retrieve statement handle within the error occurred.
OCI_SYM_PUBLIC unsigned int OCI_API	OCI_ErrorGetRow (OCI_Error *err)
	Return the row index which caused an error during statement execution.
OCI_SYM_PUBLIC const otext *OCI_API	OCI_ErrorGetLocation (OCI_Error *err)
	Return the location where the error occured.

Function Documentation

OCI_SetErrorHandler()

OCI_SYM_PUBLIC boolean OCI_API OCI_SetErrorHandler

(

POCI_ERROR

handler

)

#include <api.h>

Set the global error user handler.

Parameters

handler

- Pointer to error handler procedure

Note

Use this call to change or remove the user callback error handler installed by OCI_Initialize()

OCI_GetLastError()

OCI_SYM_PUBLIC OCI_Error *OCI_API OCI_GetLastError

(

void

)

#include <api.h>

Retrieve the last error or warning 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

Warning

OCILIB functions that returns a boolean value to indicate their success :

• return TRUE if no error occurred OR if a warning occurred
• return FALSE if an error occurred

Referenced by ocilib::core::Check().

OCI_ErrorGetString()

OCI_SYM_PUBLIC const otext *OCI_API OCI_ErrorGetString

(

OCI_Error *

err

)

#include <api.h>

Retrieve error message from error handle.

Parameters

err	- Error handle

OCI_ErrorGetType()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_ErrorGetType

(

OCI_Error *

err

)

#include <api.h>

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

OCI_ErrorGetOCICode()

OCI_SYM_PUBLIC int OCI_API OCI_ErrorGetOCICode

(

OCI_Error *

err

)

#include <api.h>

Retrieve Oracle Error code from error handle.

Parameters

err	- Error handle

OCI_ErrorGetInternalCode()

OCI_SYM_PUBLIC int OCI_API OCI_ErrorGetInternalCode

(

OCI_Error *

err

)

#include <api.h>

Retrieve Internal Error code from error handle.

Parameters

err	- Error handle

OCI_ErrorGetConnection()

OCI_SYM_PUBLIC OCI_Connection *OCI_API OCI_ErrorGetConnection

(

OCI_Error *

err

)

#include <api.h>

Retrieve connection handle within the error occurred.

Parameters

err	- Error handle

OCI_ErrorGetStatement()

OCI_SYM_PUBLIC OCI_Statement *OCI_API OCI_ErrorGetStatement

(

OCI_Error *

err

)

#include <api.h>

Retrieve statement handle within the error occurred.

Parameters

err	- Error handle

Note

If the error occurred outside of a statement context, it returns NULL

OCI_ErrorGetRow()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_ErrorGetRow

(

OCI_Error *

err

)

#include <api.h>

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

OCI_ErrorGetLocation()

OCI_SYM_PUBLIC const otext *OCI_API OCI_ErrorGetLocation

(

OCI_Error *

err

)

#include <api.h>

Return the location where the error occured.

Parameters

err	- Error handle

Returns

The method name that has generated the error