7.5. Managing Queries

7.5.1. dbi_conn_query

dbi_result dbi_conn_query(dbi_conn Conn, const char *statement);

Execute the specified SQL query statement.

Arguments

Conn: The target connection.

statement: A string containing the SQL statement.

Returns

A query result object, or NULL if there was an error. In the latter case the error number is a database engine-specific nonzero value.

7.5.2. dbi_conn_queryf

dbi_result dbi_conn_queryf(dbi_conn Conn, const char *formatstr, ...);

Execute the specified SQL query statement.

Arguments

Conn: The target connection.

formatstr: The format string for the SQL statement. It uses the same format as printf().

ARG: (...) Any variables that correspond to the printf-like format string.

Returns

A query result object, or NULL if there was an error. In the latter case the error number is a database engine-specific nonzero value.

7.5.3. dbi_conn_query_null

dbi_result dbi_conn_query_null(dbi_conn Conn, const unsigned char *statement, unsigned long st_length);

Execute the specified SQL query statement, which may contain valid NULL characters.

Note: This function is not implemented by all database drivers. For a portable way of including binary strings into SQL queries, see the function dbi_conn_quote_binary_copy.

Arguments

Conn: The target connection.

statement: The SQL statement, which may contain binary data.

st_length: The number of characters in the non-null-terminated statement string.

Returns

A query result object, or NULL if there was an error. In the latter case the error number is a database engine-specific nonzero value.

7.5.4. dbi_conn_sequence_last

unsigned long long dbi_conn_sequence_last(dbi_conn Conn, const char *name);

Requests the row ID generated by the last INSERT command. The row ID is most commonly generated by an auto-incrementing column in the table. Use the return value to address the dataset that was last inserted.

Arguments

Conn: The current database connection.

name: The name of the sequence, or NULL if the database engine does not use explicit sequences.

Note: You may have noted that this function does not sufficiently encapsulate the peculiarities of the underlying database engines. You must keep track of sequence names yourself if your target database engine does use sequences.

Returns

An integer value corresponding to the ID that was created by the last INSERT command. If the database engine does not support sequences, the function returns 0 (zero) and sets the error number to DBI_ERROR_UNSUPPORTED.

7.5.5. dbi_conn_sequence_next

unsigned long long dbi_conn_sequence_next(dbi_conn Conn, const char *name);

Requests the row ID that would be generated by the next INSERT command. The row ID is most commonly generated by an auto-incrementing column in the table.

Note: Not all database engines support this feature. Portable code should use dbi_conn_sequence_last instead.

Arguments

Conn: The current database connection.

name: The name of the sequence, or NULL if the database engine does not use explicit sequences.

Note: You may have noted that this function does not sufficiently encapsulate the peculiarities of the underlying database engines. You must keep track of sequence names yourself if your target database engine does use sequences.

Returns

An integer value corresponding to the ID that was created by the last INSERT command, or 0 if the database engine does not support this feature. In the latter case, the error number is DBI_ERROR_UNSUPPORTED

7.5.6. dbi_conn_ping

int dbi_conn_ping(dbi_conn Conn);

Checks whether the current connection is still alive. Use this function to decide whether you must reconnect before running a query if your program is designed to keep connections open over prolonged periods of time.

Arguments

Conn: The current database connection.

Returns

1 if the connection is alive. Otherwise the function returns 0.

Note: Database drivers may attempt to reconnect automatically if this function is called. If the reconnect is successful, this function will also return 1, as if the connection never had gone down.

7.5.7. dbi_conn_quote_string

size_t dbi_conn_quote_string(dbi_conn Conn, char **orig);

Escapes any special characters in a string and places the string itself in quotes so the string can be sent to the database engine as a query string, using either dbi_conn_query or dbi_conn_queryf. The original string will be freed and orig will point to a newly allocated one (which you still must free on your own). If an error occurs, the original string will be left alone. This function is preferred over dbi_driver_quote_string because it takes the character encoding of the current connection into account when performing the escaping.

Arguments

Conn: The current database connection.

orig: A pointer to the string to quote and escape.

Returns

The new string's length in bytes, excluding the terminating zero byte, or 0 in case of an error. The length of a quoted empty string is 2 bytes. In case of an error the error number is DBI_ERROR_BADPTR or DBI_ERROR_NOMEM.

Availability

0.8.0

7.5.8. dbi_conn_quote_string_copy

size_t dbi_conn_quote_string_copy(dbi_conn Conn, char *orig, char **newstr);

Escapes any special characters in a string and places the string itself in quotes so the string can be sent to the database engine as a query string, using either dbi_conn_query or dbi_conn_queryf. The original string will be left alone, and newstr will point to a newly allocated string containing the quoted string (which you still must free on your own). If the function fails, newstr is an invalid pointer that must not be freed. This function is preferred over dbi_driver_quote_string_copy because it takes the character encoding of the current connection into account when performing the escaping.

Arguments

Conn: The current database connection.

orig: A pointer to the string to quote and escape.

newstr: After the function returns, this pointer will point to the quoted and escaped string.

Returns

The new string's length in bytes, excluding the terminating zero byte, or 0 in case of an error. Possible error numbers are DBI_ERROR_BADPTR and DBI_ERROR_NOMEM.

Availability

0.8.0

7.5.9. dbi_conn_quote_binary_copy

size_t dbi_conn_quote_binary_copy(dbi_conn Conn, char *orig, size_t from_length, char **newstr);

Escapes any special characters, including null bytes, in a binary string and places the resulting string in quotes so it can be used in an SQL query. The original string will be left alone, and newstr will point to a newly allocated string containing the quoted string (which you still must free on your own). If an error occurs, newstr is an invalid pointer which must not be freed.

Arguments

Conn: The current database connection.

orig: A pointer to the string to quote and escape.

from_length: The length of the binary string in bytes.

newstr: After the function returns, this pointer will point to the quoted and escaped string.

Returns

The new string's length in bytes, excluding the terminating zero byte, or 0 in case of an error. Possible error numbers are DBI_ERROR_BADPTR and DBI_ERROR_NOMEM.

Availability

0.8.0

7.5.10. dbi_conn_escape_string

size_t dbi_conn_escape_string(dbi_conn Conn, char **orig);

Works like dbi_conn_quote_string but does not surround the resulting string with quotes.

Arguments

Conn: The current database connection.

orig: A pointer to the string to quote and escape.

Returns

The new string's length in bytes, excluding the terminating zero byte, or 0 in case of an error. The length of a quoted empty string is 2 bytes. In case of an error the error number is DBI_ERROR_BADPTR or DBI_ERROR_NOMEM.

Availability

0.8.3

7.5.11. dbi_conn_escape_string_copy

size_t dbi_conn_escape_string_copy(dbi_conn Conn, char *orig, char **newstr);

Works like dbi_conn_quote_string_copy but does not surround the resulting string with quotes.

Arguments

Conn: The current database connection.

orig: A pointer to the string to quote and escape.

newstr: After the function returns, this pointer will point to the quoted and escaped string.

Returns

The new string's length in bytes, excluding the terminating zero byte, or 0 in case of an error. Possible error numbers are DBI_ERROR_BADPTR and DBI_ERROR_NOMEM.

Availability

0.8.3

7.5.12. dbi_conn_escape_binary_copy

size_t dbi_conn_escape_binary_copy(dbi_conn Conn, char *orig, size_t from_length, char **newstr);

Works like dbi_conn_quote_binary_copy but does not surround the resulting string with quotes.

Arguments

Conn: The current database connection.

orig: A pointer to the string to quote and escape.

from_length: The length of the binary string in bytes.

newstr: After the function returns, this pointer will point to the quoted and escaped string.

Returns

The new string's length in bytes, excluding the terminating zero byte, or 0 in case of an error. Possible error numbers are DBI_ERROR_BADPTR and DBI_ERROR_NOMEM.

Availability

0.8.3