Database Independent Abstraction Layer for C: libdbi Driver Author's Guide
Prev | Chapter 3. Driver Functions | Next

# 3.3. Public Database Query Functions

## 3.3.1. dbd_get_encoding

``const char *dbd_get_encoding`(dbi_conn_t *conn);`

Returns the character encoding used by the current connection.

Arguments

  `conn`: The target connection.

Returns

  A zero-terminated string containing the IANA name of the character encoding.

## 3.3.2. dbd_encoding_to_iana

``const char *dbd_encoding_to_iana`(const char *db_encoding);`

Converts the database-engine-specific name of a character encoding to the corresponging IANA name.

Arguments

  `db_encoding`: A pointer to a string containing the character encoding name.

Returns

  A zero-terminated string containing the IANA name of the character encoding. If there is no equivalent IANA name, the original string will be returned.

## 3.3.3. dbd_encoding_from_iana

``const char *dbd_encoding_from_iana`(const char *iana_encoding);`

Converts the IANA name of a character encoding to the corresponging database-engine-specific name.

Arguments

  `iana_encoding`: A pointer to a string containing the character encoding name.

Returns

  A zero-terminated string containing the database-engine-specific name of the character encoding. If there is no equivalent IANA name, the original string will be returned.

## 3.3.4. dbd_get_engine_version

``char *dbd_get_engine_version`(dbi_conn_t *conn, char *versionstring);`

Returns the version string of the database engine that serves the current connection.

Arguments

  `conn`: The current connection.

  `versionstring`: A pointer to a string that can hold at least VERSIONSTRING_LENGTH bytes, including the trailing NULL byte. The function will write the version string to this buffer.

Returns

  `versionstring` which now contains a zero-terminated string representing the database engine version. This string contains only digits and periods. Returns an empty string in case of an error.

## 3.3.5. dbd_list_dbs

``dbi_result_t *dbd_list_dbs`(dbi_conn_t *conn, const char *pattern);`

Performs a query that retrieves the list of databases, with the database name as the first column in the result set. If `pattern` is non-NULL, only databases whose name match `pattern` are listed.

Arguments

  `conn`: The target connection.

  `pattern`: A SQL regular expression that limits the search, or NULL to list all tables.

Returns

  A DBI result object, or NULL if an error occurs.

## 3.3.6. dbd_list_tables

``dbi_result_t *dbd_list_tables`(dbi_conn_t *conn, const char *db, const char *pattern);`

Performs a query that retrieves the list of tables in the specified database, with the table name as the first column in the result set. If `pattern` is non-NULL, lists only the tables that match `pattern`.

Arguments

  `conn`: The target connection.

  `db`: The name of the database where tables should be looked for.

  `pattern`: A SQL regular expression that limits the search, or NULL to list all tables.

Returns

  A DBI result object, or NULL if an error occurs.

## 3.3.7. dbd_quote_string

``size_t dbd_quote_string`(dbi_driver_t *driver, const char *orig, char *dest);`

Given a string, wrap quotes around that string and escape any characters that the database server needs escaped.

> Note: The use of this function in user programs is deprecated, but drivers must still implement it at the moment. If the quoting and escaping does not depend on the connection parameters, it is perfectly legal to let your implementation of dbd_conn_quote_string call this function (it is not possible to do it the other way). libdbi makes sure that both `orig` and `dest` are non-NULL before calling this function.

Arguments

  `driver`: A pointer to the driver itself, which may be useful in weird cases.

  `orig`: The string to quote and escape.

  `dest`: The destination for the new string, which is already allocated as (strlen(orig)*2)+4+1. In the worst case, each character will need to be escaped, with two quote characters at both the beginning and end of the string, plus one for the terminating NULL.

Returns

  The length of the new string.

## 3.3.8. dbd_conn_quote_string

``size_t dbd_conn_quote_string`(dbi_conn_t *conn, const char *orig, char *dest);`

Given a string, wrap quotes around that string and escape any characters that the database server needs escaped.

> Note: The use of this function in user programs is preferred over dbd_quote_string. If the quoting and escaping does not depend on the connection parameters, it is perfectly legal to let your implementation of this function call dbd_quote_string. libdbi makes sure that both `orig` and `dest` are non-NULL before calling this function.

Arguments

  `conn`: A pointer to the current connection.

  `orig`: The string to quote and escape.

  `dest`: The destination for the new string, which is already allocated as (strlen(orig)*2)+4+1. In the worst case, each character will need to be escaped, with two quote characters at both the beginning and end of the string, plus one for the terminating NULL.

Returns

  The length of the new string.

## 3.3.9. dbd_quote_binary

``size_t dbd_quote_binary`(dbi_conn_t *conn, const char *orig, size_t from_length, char **dest);`

Given a binary string (which may contain NULL bytes and other non-printable characters), wrap quotes around that string and escape any characters that the database server needs escaped. If the function returns an error, *`dest` is not a valid pointer to a string.

Arguments

  `conn`: A pointer to the current connection.

  `orig`: The string to quote and escape.

  `from_length`: The length, in bytes, of the binary string.

  `dest`: A pointer to the destination of the new zero-terminated string. The function allocates the required memory as required and updates the pointer that `dest` points to accordingly.

Returns

  The length of the new string, or DBI_LENGTH_ERROR in case of an error.

## 3.3.10. dbd_query

``dbi_result_t *dbd_query`(dbi_conn_t *conn, const char *statement);`

Performs a query and keeps track of meta-information about the query. Also see the _dbd_result_create helper function.

Arguments

  `conn`: The target connection.

  `statement`: The zero-terminated query string to execute.

Returns

  A DBI result object, or NULL on error.

## 3.3.11. dbd_query_null

``dbi_result_t *dbd_query_null`(dbi_conn_t *conn, const unsigned char *statement, size_t st_length);`

Performs a query using a binary query string and keeps track of meta-information about the query. Also see the _dbd_result_create helper function.

Arguments

  `conn`: The target connection.

  `statement`: The query string to execute, which may contain NULL bytes and other non-printable characters.

  `st_length`: The length of the binary query string.

Returns

  A DBI result object, or NULL on error.

## 3.3.12. dbd_select_db

``const char *dbd_select_db`(dbi_conn_t *conn, const char* db);`

Selects a new database on the server.

Arguments

  `conn`: The target connection.

  `db`: The name of the database to switch to.

Returns

  The database name on success, NULL on error, or an empty string if the operation is not supported by the database server.

## 3.3.13. dbd_get_seq_last

``unsigned long long dbd_get_seq_last`(dbi_conn_t *conn, const char *sequence);`

Returns the row ID generated by the last INSERT command.

Arguments

  `conn`: The target connection.

  `sequence`: The name of the sequence if the database engine requires this, or NULL if it is not required.

Returns

  The row ID if successful, otherwise 0.

## 3.3.14. dbd_get_seq_next

``unsigned long long dbd_get_seq_next`(dbi_conn_t *conn, const char *sequence);`

Increments the sequence counter by the preset increment, and returns the resulting row ID.

Arguments

  `conn`: The target connection.

  `sequence`: The name of the sequence if the database engine requires this, or NULL if it is not required.

Returns

  The row ID if successful, otherwise 0. Also return 0 if the database engine does not implement this feature.

## 3.3.15. dbd_ping

``int dbd_ping`(dbi_conn_t *conn);`

Checks whether the database connection is still alive.

Arguments

  `conn`: The target connection.

Returns

  1 if the connection is alive, otherwise 0. This function may be implemented such that it automatically attempts to reconnect if the connection went down. If the reconnect is successful, the function should also return 1.

Prev | Home | Next
Internal Database Query Functions | Up | DBD Helper Functions