Error handling
C API

## Detailed Description

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_EXPORT OCI_Error *OCI_API | OCI_GetLastError (void)
| Retrieve the last error or warning occurred within the last OCILIB call. More...
OCI_EXPORT const otext *OCI_API | OCI_ErrorGetString (OCI_Error *err)
| Retrieve error message from error handle. More...
OCI_EXPORT unsigned int OCI_API | OCI_ErrorGetType (OCI_Error *err)
| Retrieve the type of error from error handle. More...
OCI_EXPORT int OCI_API | OCI_ErrorGetOCICode (OCI_Error *err)
| Retrieve Oracle Error code from error handle. More...
OCI_EXPORT int OCI_API | OCI_ErrorGetInternalCode (OCI_Error *err)
| Retrieve Internal Error code from error handle. More...
OCI_EXPORT OCI_Connection *OCI_API | OCI_ErrorGetConnection (OCI_Error *err)
| Retrieve connection handle within the error occurred. More...
OCI_EXPORT OCI_Statement *OCI_API | OCI_ErrorGetStatement (OCI_Error *err)
| Retrieve statement handle within the error occurred. More...
OCI_EXPORT unsigned int OCI_API | OCI_ErrorGetRow (OCI_Error *err)
| Return the row index which caused an error during statement execution. More...

## Function Documentation

## OCI_GetLastError()

OCI_EXPORT OCI_Error* OCI_API OCI_GetLastError | ( | void |  | ) |

`#include <ocilib.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::Check().

## OCI_ErrorGetString()

OCI_EXPORT const otext* OCI_API OCI_ErrorGetString | ( | OCI_Error * | err | ) |

`#include <ocilib.h>`

Retrieve error message from error handle.

Parameters

  err | - Error handle

Referenced by ocilib::Exception::~Exception().

## OCI_ErrorGetType()

OCI_EXPORT unsigned int OCI_API OCI_ErrorGetType | ( | OCI_Error * | err | ) |

`#include <ocilib.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

Referenced by ocilib::Exception::~Exception().

## OCI_ErrorGetOCICode()

OCI_EXPORT int OCI_API OCI_ErrorGetOCICode | ( | OCI_Error * | err | ) |

`#include <ocilib.h>`

Retrieve Oracle Error code from error handle.

Parameters

  err | - Error handle

Referenced by ocilib::Exception::~Exception().

## OCI_ErrorGetInternalCode()

OCI_EXPORT int OCI_API OCI_ErrorGetInternalCode | ( | OCI_Error * | err | ) |

`#include <ocilib.h>`

Retrieve Internal Error code from error handle.

Parameters

  err | - Error handle

Referenced by ocilib::Exception::~Exception().

## OCI_ErrorGetConnection()

OCI_EXPORT OCI_Connection* OCI_API OCI_ErrorGetConnection | ( | OCI_Error * | err | ) |

`#include <ocilib.h>`

Retrieve connection handle within the error occurred.

Parameters

  err | - Error handle

Referenced by ocilib::Exception::~Exception().

## OCI_ErrorGetStatement()

OCI_EXPORT OCI_Statement* OCI_API OCI_ErrorGetStatement | ( | OCI_Error * | err | ) |

`#include <ocilib.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

Referenced by ocilib::Exception::~Exception().

## OCI_ErrorGetRow()

OCI_EXPORT unsigned int OCI_API OCI_ErrorGetRow | ( | OCI_Error * | err | ) |

`#include <ocilib.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

Referenced by ocilib::Exception::~Exception().