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
       require  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
       successful 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
       function. 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
       returns  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
       connection  intact. An example might be a warning if a record couldn't be inserted into the table for any
       reason. 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
       further 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()

                                                 21 October 2016                              odbx_error_type(3)