3.5. Managing Queries and Results

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

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

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

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

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

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

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

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

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

3.5.10. dbi_result_get_conn

dbi_conn dbi_result_get_conn(dbi_result Result);

Returns the connection belonging to the specified result object.

Arguments

Result: The target query result.

Returns

The connection belonging to the target query result.

3.5.11. dbi_result_free

int dbi_result_free(dbi_result Result);

Frees the result's query, disables all stored field bindings, and releases internally stored variables.

Arguments

Result: The target query result.

Returns

-1 on failure, zero on success.

3.5.12. dbi_result_seek_row

int dbi_result_seek_row(dbi_result Result, unsigned long long rowidx);

Jump to a specific row in a result set.

Arguments

Result: The target query result.

rowidx: The ordinal number of the row to seek to. The first row is at position 1, not zero.

Returns

1 if successful, or 0 if there was an error.

3.5.13. dbi_result_first_row

int dbi_result_first_row(dbi_result Result);

Jump to the first row in a result set.

Arguments

Result: The target query result.

Returns

1 if successful, or 0 if there was an error.

3.5.14. dbi_result_last_row

int dbi_result_last_row(dbi_result Result);

Jump to the last row in a result set.

Arguments

Result: The target query result.

Returns

1 if successful, or 0 if there was an error.

3.5.15. dbi_result_prev_row

int dbi_result_prev_row(dbi_result Result);

Jump to the previous row in a result set.

Arguments

Result: The target query result.

Returns

1 if successful, or 0 if there is an error.

3.5.16. dbi_result_next_row

int dbi_result_next_row(dbi_result Result);

Jump to the next row in a result set.

Arguments

Result: The target query result.

Returns

1 if successful, or 0 if there was an error.

3.5.17. dbi_result_get_currow

unsigned long long dbi_result_get_currow(dbi_result Result);

Returns the ordinal number of the current row in the specified result set.

Arguments

Result: The target query result.

Returns

The ordinal number of the row, or 0 if there was an error. The first row has the number 1.

3.5.18. dbi_result_get_numrows

unsigned long long dbi_result_get_numrows(dbi_result Result);

Returns the number of rows in the specified result set.

Arguments

Result: The target query result.

Returns

The number of rows in the result set, which may be 0 if the query did not return any datasets, or DBI_ROW_ERROR in case of an error.

3.5.19. dbi_result_get_numrows_affected

unsigned long long dbi_result_get_numrows_affected(dbi_result Result);

Returns the number of rows in the specified result set that were actually modified. Note that not all database servers support this, in which case it will always be zero. See the documentation for each specific driver for details.

Arguments

Result: The target query result.

Returns

The number of modified rows in the result set which may be 0 if no row was affected by the previous query. Also returns 0 if the database engine does not support this feature. The return value will be DBI_ROW_ERROR in case of an error.