1odbx_error_type(3) OpenDBX odbx_error_type(3)
2
6 odbx_error_type - Returns the severity of an error
7
9 #include <opendbx/api.h>
10 int odbx_error_type (odbx_t* handle, int error);
13
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 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 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 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
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 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 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
71 This function doesn't return any errors.
72
74 odbx_finish(), odbx_init(), odbx_unbind()
75 17 February 2019 odbx_error_type(3)