Error handling

Detailed Description

OcilibCApiInitialization

OCILIB provides two mechanisms for error handling:

• Global error handling through callbacks.
• Thread-contextual error handling.

Errors are raised in the following situations:

• Oracle OCI API call failure.
• Oracle SQL statement execution error.
• Internal OCILIB error (type checking, memory allocation, etc.).
• Oracle warnings (OCI API or SQL).

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

To use thread-contextual error handling, pass the OCI_ENV_CONTEXT flag to OCI_Initialize(). When activated, error handles are stored per thread and the last error within a thread can be retrieved with OCI_GetLastError().

Error properties are accessible through a set of dedicated functions.

Note

Both error handling mechanisms are not mutually exclusive and can be combined.

Thread-contextual error handling is also available in single-threaded applications.

Oracle Warnings

Oracle warnings are raised through the OCI_Error API. Such error handles have their error type property (OCI_ErrorGetType()) set to OCI_ERR_WARNING. Warning handling is disabled by default. To enable or disable 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 const otext *OCI_API	OCI_GetLocaleString (unsigned int code)
	Return the localized error message string for the given OCILIB internal error code.
OCI_SYM_PUBLIC OCI_Error *OCI_API	OCI_GetLastError (void)
	Retrieve the last error or warning that occurred during the most recent OCILIB call.
OCI_SYM_PUBLIC const otext *OCI_API	OCI_ErrorGetString (OCI_Error *err)
	Retrieve the error message string from an error handle.
OCI_SYM_PUBLIC unsigned int OCI_API	OCI_ErrorGetType (OCI_Error *err)
	Retrieve the type of error from an error handle.
OCI_SYM_PUBLIC int OCI_API	OCI_ErrorGetOCICode (OCI_Error *err)
	Retrieve the Oracle error code (ORA-XXXXX) from an error handle.
OCI_SYM_PUBLIC int OCI_API	OCI_ErrorGetInternalCode (OCI_Error *err)
	Retrieve the OCILIB internal error code from an error handle.
OCI_SYM_PUBLIC OCI_Connection *OCI_API	OCI_ErrorGetConnection (OCI_Error *err)
	Retrieve the connection handle associated with the error.
OCI_SYM_PUBLIC OCI_Statement *OCI_API	OCI_ErrorGetStatement (OCI_Error *err)
	Retrieve the statement handle associated with the error.
OCI_SYM_PUBLIC unsigned int OCI_API	OCI_ErrorGetRow (OCI_Error *err)
	Return the row index that caused an error during array DML execution.
OCI_SYM_PUBLIC const otext *OCI_API	OCI_ErrorGetLocation (OCI_Error *err)
	Return the location where the error occurred.

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 the error handler procedure, or NULL to remove the current handler

Note

Use this function to change or remove the error handler callback initially installed by OCI_Initialize().

Returns

TRUE on success, otherwise FALSE.

OCI_GetLocaleString()

OCI_SYM_PUBLIC const otext *OCI_API OCI_GetLocaleString

(

unsigned int

code

)

#include <api.h>

Return the localized error message string for the given OCILIB internal error code.

Parameters

code	- OCILIB internal error code

Returns

The localized error message string, or NULL if the code is invalid.

Referenced by ocilib::Environment::GetLocaleString().

OCI_GetLastError()

OCI_SYM_PUBLIC OCI_Error *OCI_API OCI_GetLastError

(

void

)

#include <api.h>

Retrieve the last error or warning that occurred during the most recent OCILIB call.

Note

OCI_GetLastError() relies on thread-contextual storage. OCILIB must be initialized with the OCI_ENV_CONTEXT flag for this function to work.

Warning

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

• Return TRUE if no error occurred OR if only a warning occurred.
• Return FALSE if an error occurred.

Returns

A pointer to the OCI_Error handle for the last error or warning, or NULL if none occurred.

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

OCI_ErrorGetString()

OCI_SYM_PUBLIC const otext *OCI_API OCI_ErrorGetString

(

OCI_Error *

err

)

#include <api.h>

Retrieve the error message string from an error handle.

Parameters

err	- Error handle

Returns

The error message string, or NULL if the input handle is NULL.

OCI_ErrorGetType()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_ErrorGetType

(

OCI_Error *

err

)

#include <api.h>

Retrieve the type of error from an error handle.

Parameters

err	- Error handle

Returns

One of the following values:

• OCI_ERR_ORACLE : Error reported by the Oracle OCI layer.
• OCI_ERR_OCILIB : Internal OCILIB error.
• OCI_ERR_WARNING : Oracle warning.
• OCI_UNKNOWN : If the input handle is NULL.

OCI_ErrorGetOCICode()

OCI_SYM_PUBLIC int OCI_API OCI_ErrorGetOCICode

(

OCI_Error *

err

)

#include <api.h>

Retrieve the Oracle error code (ORA-XXXXX) from an error handle.

Parameters

err	- Error handle

Returns

The Oracle error code, or 0 if the error is not Oracle-related.

OCI_ErrorGetInternalCode()

OCI_SYM_PUBLIC int OCI_API OCI_ErrorGetInternalCode

(

OCI_Error *

err

)

#include <api.h>

Retrieve the OCILIB internal error code from an error handle.

Parameters

err	- Error handle

Returns

The OCILIB internal error code, or 0 if the error is not OCILIB-related.

OCI_ErrorGetConnection()

OCI_SYM_PUBLIC OCI_Connection *OCI_API OCI_ErrorGetConnection

(

OCI_Error *

err

)

#include <api.h>

Retrieve the connection handle associated with the error.

Parameters

err	- Error handle

Returns

The connection handle, or NULL if the error did not occur within a connection context.

OCI_ErrorGetStatement()

OCI_SYM_PUBLIC OCI_Statement *OCI_API OCI_ErrorGetStatement

(

OCI_Error *

err

)

#include <api.h>

Retrieve the statement handle associated with the error.

Parameters

err	- Error handle

Returns

The statement handle, or NULL if the error did not occur within a statement context.

OCI_ErrorGetRow()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_ErrorGetRow

(

OCI_Error *

err

)

#include <api.h>

Return the row index that caused an error during array DML execution.

Parameters

err	- Error handle

Warning

Row indices start at 1.

Returns

The 1-based index of the row that caused the error, or 0 if the error is not related to an array DML operation.

OCI_ErrorGetLocation()

OCI_SYM_PUBLIC const otext *OCI_API OCI_ErrorGetLocation

(

OCI_Error *

err

)

#include <api.h>

Return the location where the error occurred.

Parameters

err	- Error handle

Returns

The name of the OCILIB function in which the error was raised, or NULL if the input handle is NULL.