2.1. Quick Overview

libdbi uses a plugin system that allows various databases to be supported simultaneously, and can dynamically load or unload drivers that are supplied by libdbi or a third party. The library is initiallized by calling dbi_initialize and a connection instance is started by calling either dbi_conn_new or both dbi_driver_open and dbi_conn_open.

The connection's options (username, password, hostname, etc.) are set with dbi_conn_set_option and dbi_conn_set_option_numeric. Once all options are set, dbi_conn_connect will connect to the database, waiting to handle a dbi_conn_query. After a successful query, you can retrieve rows with dbi_result_first_row, dbi_result_last_row, dbi_result_prev_row, dbi_result_next_row, and dbi_result_seek_row.

There are two methods for fetching field data, and two ways to perform each method. You can either "pull" the data from DBI using the dbi_result_get_* family of functions, or have DBI automatically "push" the data into predefined variables with the dbi_result_bind_* family of functions.

Pulling the data from the database can be done with one of the "get" functions such as dbi_result_get_long or dbi_result_get_string, which simply return the data in the field you asked for. You can also get more than one field at a time with dbi_result_get_fields, which uses a printf-like syntax.

If you want DBI to automatically fill your program's variables with field values whenever a new row is fetched, you can "bind" fields to your variables. Bindings are set up with dbi_result_bind_long, dbi_result_bind_string, and the rest of the bind family of functions. Like the associated "get" function, you can set up multiple bindings at once with the dbi_result_bind_fields function.

Caveats:

• For fields holding integers (not fractional numbers), DBI differentiates between signed and unsigned variables. By default, DBI returns signed values. If you want an unsigned value, prepend a "u" to the name of the target type. For example, dbi_result_bind_short becomes dbi_result_bind_ushort.

• You must set up any bindings AFTER a successful query but BEFORE you fetch any rows. Even if you are using field bindings, you can still use the dbi_result_get_* functions as usual. (actually, I lied... setting up a binding should theoretically work at any time, but don't plan on this behavior in future versions)

• All string and binary data returned or bound from DBI is READ-ONLY. If you want your own local copy that can be modified at will, use dbi_result_get_string_copy, dbi_result_get_binary_copy, dbi_result_bind_string_copy, or dbi_result_bind_binary_copy. You will be responsible for freeing the memory allocated by these functions.

dbi_result_next_row and the other row-seeking functions will return zero when there are no more rows available. Before the next database operation is performed, you must call dbi_result_free. Before the program terminates, the connection must be disconnected and unloaded with dbi_conn_close and libdbi must be unloaded with dbi_shutdown.