| odbx_error_type(3) | OpenDBX | odbx_error_type(3) |
odbx_error_type - Returns the severity of an error
#include <opendbx/api.h>
int odbx_error_type
(odbx_t* handle, int error);
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.
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.
This function doesn't return any errors.
odbx_finish(), odbx_init(), odbx_unbind()
| 20 November 2020 |