NAME

       odbx_error_type - Returns the severity of an error

SYNOPSIS

       #include <opendbx/api.h>

       int odbx_error_type (odbx_t* handle, int error);

DESCRIPTION

       odbx_error_type()  gives an indication about the severity of the error code returned by the last function
       call and supplied via the error parameter. It can be used to distinguish critical  errors  from  warnings
       and  enables  an  application to react appropriately. While applications usually can continue if warnings
       occur by informing the user and taking measures on the application logic level, severe errors always  re‐
       quire  to  recreate  the  connection.  On  both  cases, all errors returned are overwritten when the next
       odbx_*() function is called. This function is available since release 1.1.2.

       Let's take odbx_query() (or any other function) as example, which returned an error. If the return  value
       of  odbx_error_type() is negative, you've hit a severe error like the connection to the server is broken.
       In this case you have to call odbx_unbind(), odbx_finish(), odbx_init() and odbx_bind() in this order  to
       recreate  the  connection. Otherwise, if the return value was positive your statement might have been not
       understood by the database server. Here you can continue to send the next statement to the server without
       the need to recreate the connection.

       The handle parameter is the connection object created and returned by odbx_init() if the  call  was  suc‐
       cessful and it becomes invalid as soon as it was supplied to odbx_finish(). Anyhow, it isn't necessary to
       supply  a  valid  handle for errors which use error codes not equal to -ODBX_ERR_BACKEND. Therefore, it's
       possible to use odbx_error_type() even if odbx_init() returned an error. If -ODBX_ERR_BACKEND is supplied
       in this case nevertheless, the return value will indicate a critical error.

       All values returned by odbx_*() functions can be feed directly via the error parameter  into  this  func‐
       tion.  If the given value doesn't indicate an error, the returned code will always be zero for successful
       completion. Negative values will be separated into classes for critical errors and warnings instead.

RETURN VALUE

       On success, i.e. if ODBX_ERR_SUCCESS or a positive value is supplied as value of error, the function  re‐
       turns  zero. Otherwise, there will be positive and negative values returned, depending on the severity of
       the error occurred.

       Positive values (values greater than zero) indicate recoverable errors which leave the  database  connec‐
       tion  intact.  An example might be a warning if a record couldn't be inserted into the table for any rea‐
       son. In this case, further statements can be send to the database server and they are likely to succeed.

       On the other hand, if negative values (values less than zero) are returned, there has happened  a  severe
       error in the backend module, the native database client library or the database server. The connection to
       the  server might be lost or an out of memory condition might has been occurred. This means that all fur‐
       ther calls to the OpenDBX library will probably fail and the only way to recover from this  situation  is
       to clean up the connection by using odbx_unbind() and odbx_finish() and trying to create a new connection
       from ground up.

ERRORS

       This function doesn't return any errors.

SEE ALSO

       odbx_finish(), odbx_init(), odbx_unbind()

                                                  3 April 2024                                odbx_error_type(3)