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 June 2023                        odbx_error_type(3)