Applications should check all libdbi function calls for errors and respond appropriately to avoid entering an undefined status. libdbi uses two mechanisms to indicate errors:
Essentially all libdbi functions return a value, a concept not unfamiliar to the seasoned C programmer. For example, the dbi_initialize function returns the number of loaded drivers, or -1 if an error occurred. In this case checking the return value is sufficient to detect an error condition. However, other functions like the family of "getters" cannot indicate error conditions with a return value. Consider e.g. the dbi_result_get_string function which is used to retrieve strings from a database. If there was an error in accessing the value, the function will return the string "ERROR". However, this string is a legal value of such a field (the problem is the same for any other conceivable return value, including the empty string and the NULL pointer). Therefore we need an additional mechanism to report errors.
Connections store the status of the most recent operation which can be queried by the accessor function dbi_conn_error. This is equivalent to the errno variable of the standard C library which is used by most system calls and can be printed in human-readable form by the perror system call. This mechanism implies that your program queries the status right after each operation, as the values will be overwritten by subsequent operations.
The return values of all libdbi functions are listed in the reference chapter below. The error numbers will be briefly discussed in the following sections.