| Database Independent Abstraction Layer for C: libdbi Programmer's Guide | ||
|---|---|---|
| Prev | Chapter 7. libdbi API Reference | Next |
Creates a connection instance of the driver specified by "name" loaded by the given libdbi instance. This is a shortcut for calling dbi_driver_open_r and passing the result to dbi_conn_open.
name: The name of the desired driver.
Inst: The instance handle.
A connection instance of the specified driver, or NULL if there was an error.
Creates a connection instance of the driver specified by "name". This is a shortcut for calling dbi_driver_open and passing the result to dbi_conn_open.
Note: This function is deprecated. Use dbi_conn_new_r instead.
name: The name of the desired driver.
A connection instance of the specified driver, or NULL if there was an error.
Creates a connection instance of the specified driver. This connection can be used to perform queries and set options.
Driver: The target driver.
A connection instance of the specified driver, or NULL if there was an error.
Disconnects the specified connection connection from the database and cleans up the connection session.
Conn: The target connection.
Returns the driver type of the specified connection.
Conn: The target connection.
The driver type of the target connection.
Sets a specified connection option to a string value.
Conn: The target connection.
key: The name of the target setting. Must only contain alphanumerics and the underscore character.
value: The string value of the target setting.
-1 on error, 0 on success. In case of an error, the error number is DBI_ERROR_NOMEM.
Sets a specified connection option to a numeric value.
Conn: The target connection.
key: The name of the target setting. Must only contain alphanumerics and the underscore character.
value: The numeric value of the target setting.
-1 on error, 0 on success. In case of an error, the error number is DBI_ERROR_NOMEM.
Retrieves the string value of the specified option set for a connection if available.
Conn: The target connection.
key: The name of the target setting.
A read-only string with the setting, or NULL if it is not available. It is not considered an error if the setting is not available.
Retrieves the string value of the specified option set for a connection and throws an error if the option was not set.
Conn: The target connection.
key: The name of the target setting.
A read-only string with the setting, or NULL if it is not available. In the latter case, the error number is DBI_ERROR_BADNAME.
Retrieves the integer value of the specified option set for a connection if available.
Conn: The target connection.
key: The name of the target setting.
The value of the setting, or 0 (zero) if it is not available. It is not considered an error if the option has not been set.
Retrieves the integer value of the specified option set for a connection and throws an error if it is not available.
Conn: The target connection.
key: The name of the target setting.
The value of the setting, or -1 if it is not available. In the latter case, the error number is DBI_ERROR_BADNAME.
Enumerates the list of available options for a connection. If current is NULL, the first available option will be returned. If current is a valid option name, the next available option will be returned.
Conn: The target connection.
current: The key name of the target option.
The key name of the next option, or NULL if there are no more options or if there was an error. In the latter case the error number is set to DBI_ERROR_BADPTR.
Removes the target option setting from a connection. It is not considered an error if the requested option was not set before.
Conn: The target connection.
key: The name of the target setting.
Removes all option settings from a connection.
Conn: The target connection.
Requests the value of a driver capability associated with the current connection. The name of the capability is specified as an argument.
Conn: The target connection.
capname: A pointer to a string containing the name of the driver capability to be queried.
The numeric value of the driver capability.
Obtain the file descriptor number for the backend connection socket.
Conn: The target connection
-1 on failure, the file descriptor number on success
Requests the character encoding used by the current connection. This may be different from the encoding requested when the connection was opened, most notably if the connection option was set to "auto".
Conn: The current encoding.
A string containing the IANA name of the connection encoding. If the encoding option was set to "auto", the function returns the encoding the database was created with. In all other cases, the current connection encoding is returned, which may be different from the database encoding. Use the dbi_driver_encoding_from_iana function to translate the encoding name to that of the currently used database engine if necessary.
Requests the version of the database engine that serves the current connection as a string.
Conn: The current connection.
versionstring: A string buffer that can hold at least VERSIONSTRING_LENGTH bytes.
A string representation of the version. This will be something like "4.1.10". The result is written to the buffer that versionstring points to. If successful, the function returns a pointer to that buffer. If the version cannot be determined, the function returns the string "0".
Note: This string is useful to display the version to the user. In order to check for particular version requirements in your program, dbi_conn_get_engine_version is the better choice.
0.8.0
Requests the version of the database engine that serves the current connection in a numeric form.
Conn: The current connection.
A numeric representation of the version. String representations of the version (e.g. "4.1.10") do not lend themselves to an easy comparison in order to find out whether a particular engine feature is already implemented. For example, a string comparison would claim that "4.1.9" is a later version than "4.1.10". Therefore libdbi computes a numeric representation of the version number [[[[A.]B.]C.]D.]E[.] according to the formula E + D*100 + C*10000 + B*1000000 + A*100000000. The resulting integers (40109 and 40110 in the example above) will be sorted correctly. Returns 0 if the version number cannot be retrieved.
0.8.0
Returns a formatted message with the error number and description resulting from the previous database operation.
Conn: The target connection.
errmsg_dest: The target string pointer, which will point to the error message. If NULL, no error message will be created, but the error number will still be returned. This string is managed by libdbi, so it must not be modified or freed. The pointer to the string is only valid until the next call to this function, so make a copy in time if you need to keep the error message.
The error number of the most recent database operation if it resulted in an error. If not, this will return DBI_ERROR_NONE. See Chapter 4 for further information.
void dbi_conn_error_handler(dbi_conn Conn, dbi_conn_error_handler_func function, void *user_argument);
Registers an error handler callback to be triggered whenever the database encounters an error. The callback function should perform as little work as possible, since the state in which it is called can be uncertain. The actual function declaration must accept two parameters (and return nothing):
dbi_conn Conn: the connection object that triggered the error, from which dbi_conn_error() can be called, and
void *user_argument: a pointer to whatever data (if any) was registered along with the handler.
To remove the error handler callback, specify NULL as the function and user_argument.
Conn: The target connection.
function: A pointer to the function to call when the error handler should be triggered.
user_argument: Any data to pass along to the function when it is triggered. Set to NULL if unused.
The libdbi query functions set an error flag in order to distinguish e.g. the return value "0" from a "0" returned due to an error condition. Use this function after each query that may fail to read out the error status.
Conn: The target connection.
0 means the previous query finished without errors. A value larger than zero means an error occurred.
Note: This function is deprecated. Use dbi_conn_error instead. Both functions return the same error code to maintain backwards compatibility.
Applications may set an error status and an error message which are accessible through the libdbi error API function dbi_conn_error.
Conn: The target connection.
errnum: An application-defined error code. Applications should use only positive nonzero integers to indicate errors.
The remainder of the argument list is interpreted using a printf(3)-like syntax to define an error message.
The length of the error message in bytes, or 0 if there was an error.
Starts a transaction.
Conn: The target connection.
0 (zero) if successful, otherwise nonzero.
Commits a transaction, i.e. writes all changes since the transaction was started to the database.
Conn: The target connection.
0 (zero) if successful, otherwise nonzero.
Rolls back a transaction, i.e. reverts all changes since the transaction started.
Conn: The target connection.
0 (zero) if successful, otherwise nonzero.
Sets a savepoint named savepoint within the current transaction.
Conn: The target connection.
savepoint: a pointer to a string containing the name of the savepoint.
0 (zero) if successful, otherwise nonzero.
Rolls back all changes since the savepoint named savepoint was established within the current transaction.
Conn: The target connection.
savepoint: a pointer to a string containing the name of the savepoint.
0 (zero) if successful, otherwise nonzero.
Removes the savepoint named savepoint within the current transaction and releases all resources associated with it. Changes can no longer be rolled back to that particular savepoint. However, changes may still be rolled back to different savepoints, or to the beginning of the entire transaction.
Conn: The target connection.
savepoint: a pointer to a string containing the name of the savepoint.
0 (zero) if successful, otherwise nonzero.