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:

Function return values

- 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.

Error numbers and error messages

- 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.

# Connection error numbers and messages

If your application has successfully opened a connection to a database, all operations on this connection may cause errors. There are two classes of errors:

Client library errors

- libdbi retrieves and stores the error codes of the database engine client library if it provides error codes in a suitable format. If the client library does not support error numbers as positive integers, the value DBI_ERROR_CLIENT indicates an error status instead. In addition a string may be provided which describes or further elaborates the error status. The possible values of error number and error message depend on the database engine used for the connection.

libdbi errors

- A number of errors may occur within the libdbi framework or within a database driver, e.g. if your program queries nonexistent columns or attempts to read past the last row of a result set. The possible error numbers and error messages are predefined by libdbi.

Use the function dbi_conn_error to access the error number and error message of the most recent connection operation.

## Error numbers

dbi_conn_error returns DBI_ERROR_NONE (internally 0) if the last operation was successful, and a nonzero value if not. Client library errors use positive error numbers, whereas libdbi errors use negative error numbers as listed in the following table:

## libdbi error numbers

value | description
DBI_ERROR_USER | This indicates an error status set by the application itself, see dbi_conn_set_error
DBI_ERROR_BADOBJECT | invalid connection or result structure
DBI_ERROR_BADTYPE | the accessor function does not match the actual column type
DBI_ERROR_BADIDX | out-of-range index
DBI_ERROR_BADNAME | incorrect column or option name
DBI_ERROR_UNSUPPORTED | feature not supported by driver
DBI_ERROR_NOCONN | no valid connection
DBI_ERROR_NOMEM | out of memory
DBI_ERROR_BADPTR | invalid pointer
DBI_ERROR_NONE | no error occurred
DBI_ERROR_CLIENT | client library error