1odbx_error_type(3)                  OpenDBX                 odbx_error_type(3)
2
3
4

NAME

6       odbx_error_type - Returns the severity of an error
7

SYNOPSIS

9       #include <opendbx/api.h>
10
11
12       int odbx_error_type (odbx_t* handle, int error);
13

DESCRIPTION

15       odbx_error_type()  gives  an indication about the severity of the error
16       code returned by the last function call and supplied via the error  pa‐
17       rameter.  It  can  be used to distinguish critical errors from warnings
18       and enables an application to react appropriately.  While  applications
19       usually can continue if warnings occur by informing the user and taking
20       measures on the application logic level, severe errors  always  require
21       to  recreate  the  connection.  On  both cases, all errors returned are
22       overwritten when the next odbx_*() function is called. This function is
23       available since release 1.1.2.
24
25       Let's  take  odbx_query() (or any other function) as example, which re‐
26       turned an error. If the return value of odbx_error_type() is  negative,
27       you've  hit a severe error like the connection to the server is broken.
28       In this case you have to call odbx_unbind(), odbx_finish(), odbx_init()
29       and odbx_bind() in this order to recreate the connection. Otherwise, if
30       the return value was positive your statement might have been not under‐
31       stood  by  the  database server. Here you can continue to send the next
32       statement to the server without the need to recreate the connection.
33
34       The handle parameter is the connection object created and  returned  by
35       odbx_init()  if  the call was successful and it becomes invalid as soon
36       as it was supplied to odbx_finish(). Anyhow, it isn't necessary to sup‐
37       ply  a  valid  handle  for  errors  which  use error codes not equal to
38       -ODBX_ERR_BACKEND. Therefore, it's possible  to  use  odbx_error_type()
39       even if odbx_init() returned an error. If -ODBX_ERR_BACKEND is supplied
40       in this case nevertheless, the return value will  indicate  a  critical
41       error.
42
43       All  values returned by odbx_*() functions can be feed directly via the
44       error parameter into this function. If the given value doesn't indicate
45       an  error, the returned code will always be zero for successful comple‐
46       tion. Negative values will be separated into classes for  critical  er‐
47       rors and warnings instead.
48

RETURN VALUE

50       On success, i.e. if ODBX_ERR_SUCCESS or a positive value is supplied as
51       value of error, the function returns zero.  Otherwise,  there  will  be
52       positive and negative values returned, depending on the severity of the
53       error occurred.
54
55       Positive values (values greater than zero) indicate recoverable  errors
56       which leave the database connection intact. An example might be a warn‐
57       ing if a record couldn't be inserted into the table for any reason.  In
58       this  case,  further  statements can be send to the database server and
59       they are likely to succeed.
60
61       On the other hand, if negative values (values less than zero)  are  re‐
62       turned,  there  has  happened a severe error in the backend module, the
63       native database client library or the database server.  The  connection
64       to  the  server  might  be lost or an out of memory condition might has
65       been occurred. This means that all further calls to the OpenDBX library
66       will  probably  fail and the only way to recover from this situation is
67       to clean up the connection by using odbx_unbind() and odbx_finish() and
68       trying to create a new connection from ground up.
69

ERRORS

71       This function doesn't return any errors.
72

SEE ALSO

74       odbx_finish(), odbx_init(), odbx_unbind()
75
76
77
78                               17 February 2019             odbx_error_type(3)
Impressum