odbx_error_type(3)

NAME
odbx_error_type - Returns the severity of an error

SYNOPSIS
\FC#include <opendbx/api.h>\F[]

\FCint odbx_error_type\F[]
\FC(odbx_t* handle, int error);\F[]

DESCRIPTION
\FCodbx_error_type\F[]() gives an indication about the severity of the error code returned by the last function call and supplied via the \FCerror\F[] 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 \FCodbx_query\F[]() (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 \FCodbx_unbind\F[](), \FCodbx_finish\F[](), \FCodbx_init\F[]() and \FCodbx_bind\F[]() 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 \FChandle\F[] parameter is the connection object created and returned by \FCodbx_init\F[]() if the call was successful and it becomes invalid as soon as it was supplied to \FCodbx_finish\F[](). Anyhow, it isn't necessary to supply a valid handle for errors which use error codes not equal to -\FCODBX_ERR_BACKEND\F[]. Therefore, it's possible to use \FCodbx_error_type\F[]() even if \FCodbx_init\F[]() returned an error. If -\FCODBX_ERR_BACKEND\F[] 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 \FCerror\F[] 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 \FCODBX_ERR_SUCCESS\F[] or a positive value is supplied as value of \FCerror\F[], 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 \FCodbx_unbind\F[]() and \FCodbx_finish\F[]() and trying to create a new connection from ground up.

ERRORS
This function doesn't return any errors.

SEE ALSO
\FCodbx_finish\F[](), \FCodbx_init\F[](), \FCodbx_unbind\F[]()