# libdbi API Reference

## Instance Infrastructure

### dbi_initialize_r

    	    int dbi_initialize_r
    	    const char *driverdir
    	    dbi_inst *pInst

Creates an instance of libdbi, locates all available database drivers and loads them into memory.

Arguments

- `driverdir`: The directory to search for drivers. If NULL, DBI_DRIVER_DIR (defined at compile time) will be used instead.

  `pInst`: A pointer to an instance handle. The function will fill in the new instance handle if successful, or set it to NULL if an error occurred.

Returns

- The number of drivers successfully loaded, or -1 if there was an error. The latter may be due to an incorrect driver directory or to a lack of permissions.

Availability

- 0.9.0

### dbi_initialize

    	    int dbi_initialize
    	    const char *driverdir

Locates all available database drivers and loads them into memory.

This function is deprecated. Use dbi-initialize-r instead. In contrast to that function, dbi_initialize allows only one (internally managed) libdbi instance per process.

Arguments

- `driverdir`: The directory to search for drivers. If NULL, DBI_DRIVER_DIR (defined at compile time) will be used instead.

Returns

- The number of drivers successfully loaded, or -1 if there was an error.

### dbi_shutdown_r

    	    void dbi_shutdown_r
    	    dbi_inst Inst

Frees all loaded drivers and terminates the libdbi instance. You should close each connection you opened before shutting down, but libdbi will clean up after you if you don't.

Arguments

- `Inst`: The instance handle.

Availability

- 0.9.0

### dbi_shutdown

    	    void dbi_shutdown

Frees all loaded drivers and terminates the DBI system. You should close each connection you opened before shutting down, but libdbi will clean up after you if you don't.

This function is deprecated. Use dbi-shutdown-r instead.

### dbi_set_verbosity_r

    	    int dbi_set_verbosity_r
    	    int verbosity
    	    dbi_inst Inst

Toggles internal error messages on or off in the given libdbi instance. This affects only those error messages which are directly sent to stderr, not those handled by the connection error API.

Arguments

- `verbosity`: A nonzero value causes error messages to be printed on stderr. 0 (zero) suppresses error messages.

  `Inst`: The instance handle.

Returns

- The previous setting of `verbosity`.

Availability

- 0.9.0

### dbi_set_verbosity

    	    int dbi_set_verbosity
    	    int verbosity

Toggles internal error messages on or off. This affects only those error messages which are directly sent to stderr, not those handled by the connection error API.

This function is deprecated. Use dbi-set-verbosity-r instead.

Arguments

- `verbosity`: A nonzero value causes error messages to be printed on stderr. 0 (zero) suppresses error messages.

Returns

- The previous setting of `verbosity`.

### dbi_version

    	    const char *dbi_version

Requests the version of libdbi as a read-only string. The calling program must not attempt to free the returned string.

Returns

- A string containing the library's name and version.

### dbi_version_numeric

    	    unsigned int dbi_version_numeric

Requests the version of libdbi as an integer.

Returns

- The version, computed as ((major * 10000) + (minor * 100) + patch).

Availability

- 0.9.0

## Driver Infrastructure

### dbi_driver_list_r

    	    dbi_driver dbi_driver_list_r
    	    dbi_driver Current
    	    dbi_inst Inst

Enumerates all loaded drivers of the given instance. If Current is NULL, the first available driver will be returned. If Current is a valid driver, the next available driver will be returned.

Arguments

- `Current`: The current driver in the list of drivers, or NULL to retrieve the first one.

  `Inst`: The instance handle.

Returns

- The next available driver, or NULL if there is an error or no more are available.

Availability

- 0.9.0

### dbi_driver_list

    	    dbi_driver dbi_driver_list
    	    dbi_driver Current

Enumerates all loaded drivers. If Current is NULL, the first available driver will be returned. If Current is a valid driver, the next available driver will be returned.

This function is deprecated. Use dbi-driver-list-r instead.

Arguments

- `Current`: The current driver in the list of drivers, or NULL to retrieve the first one.

Returns

- The next available driver, or NULL if there is an error or no more are available.

### dbi_driver_open_r

    	    dbi_driver dbi_driver_open_r
    	    const char *name
    	    dbi_inst Inst

Locate the driver with the specified name.

Arguments

- `name`: The name of the driver to open.

  `Inst`: The instance handle.

Returns

- The requested driver, or NULL if there is no such driver.

Availability

- 0.9.0

### dbi_driver_open

    	    dbi_driver dbi_driver_open
    	    const char *name

Locate the driver with the specified name.

This function is deprecated. Use dbi-driver-open-r instead.

Arguments

- `name`: The name of the driver to open.

Returns

- The requested driver, or NULL if there is no such driver.

### dbi_driver_get_instance

    	    int dbi_driver_get_instance
    	    dbi_driver Driver

Retrieves the handle of the instance that loaded the driver.

Arguments

- `Driver`: The target driver.

Returns

- The instance handle, or NULL in case of an error.

Availability

- 0.9.0

### dbi_driver_is_reserved_word

    	    int dbi_driver_is_reserved_word
    	    dbi_driver Driver
    	    const char *word

Looks for the specified word in the list of reserved words. The result of this function may vary between databases. Case does not matter.

Arguments

- `Driver`: The target driver.

  `word`: The word to check against the reserved word list.

Returns

- -1 if an error occurs, 0 if the word is not reserved, 1 otherwise.

### dbi_driver_specific_function

    	    void *dbi_driver_specific_function
    	    dbi_driver Driver
    	    const char *name

Returns a function pointer to the specifed custom function. This can be used to access database-specific functionality, but it will restrict your code to one particular database, lessening the benefits of using libdbi.

Arguments

- `Driver`: The target driver.

  `name`: The name of the custom function.

Returns

- If the custom function is found, a pointer to that function. If not, returns NULL.

Availability

- 0.9.0

### dbi_driver_quote_string

    	    int dbi_driver_quote_string
    	    dbi_driver Driver
    	    char **orig

Encloses the target string in the types of quotes that the database expects, and escapes any special characters. 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 not be freed.

This function is deprecated. Use dbi-conn-quote-string instead.

Arguments

- `Driver`: The target driver.

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

### dbi_driver_quote_string_copy

    	    int dbi_driver_quote_string_copy
    	    dbi_driver Driver
    	    char **orig
    	    char **newstr

Encloses the target string in the types of quotes that the database expects, and escapes any special characters. 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). In case of an error, `newstr` is an invalid pointer which you must not attempt to deallocate.

This function is deprecated. Use dbi-conn-quote-string-copy instead.

Arguments

- `Driver`: The target driver.

  `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 quoted 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.

### dbi_driver_encoding_from_iana

    	    const char *dbi_driver_encoding_from_iana
    	    dbi_driver Driver
    	    const char *iana_encoding

Requests the database engine specific name of the character encoding identified by its name as known to IANA. Use this function to pass the database engine specific encoding name to SQL queries , e.g. as part of a `CREATE DATABASE` command.

Arguments

- `Driver`: The target driver.

  `iana_encoding`: The IANA name of the character encoding.

Returns

- A string containing the database engine specific encoding name. If the encoding name cannot be translated, the IANA name is returned without translation.

Availability

- 0.8.0

### dbi_driver_encoding_to_iana

    	    const char *dbi_driver_encoding_to_iana
    	    dbi_driver Driver
    	    const char *db_encoding

Requests the IANA name of the character encoding identified by its database engine specific name. Use this function to convert the database engine specific name returned by SQL queries to the corresponding common name.

Arguments

- `Driver`: The target driver.

  `db_encoding`: The database engine specific name of the character encoding.

Returns

- A string containing the IANA encoding name. If the encoding name cannot be translated, the database engine specific name is returned without translation.

Availability

- 0.8.0

### Driver Information

#### dbi_driver_get_name

    	      const char *dbi_driver_get_name
    	      dbi_driver Driver

Requests the name of the specified driver. The calling program must not attempt to free the returned string.

Arguments

- `Driver`: The target driver.

Returns

- A string containing the driver's name.

#### dbi_driver_get_filename

    	      const char *dbi_driver_get_filename
    	      dbi_driver Driver

Requests the filename of the specified driver. The calling program must not attempt to free the returned string.

Arguments

- `Driver`: The target driver.

Returns

- A string containing the driver's full path and file name.

#### dbi_driver_get_description

    	      const char *dbi_driver_get_description
    	      dbi_driver Driver

Requests a description of the specified driver. The calling program must not attempt to free the returned string.

Arguments

- `Driver`: The target driver.

Returns

- A string containing the driver's description. It will be one or two short sentences with no newlines.

#### dbi_driver_get_maintainer

    	      const char *dbi_driver_get_maintainer
    	      dbi_driver Driver

Requests the maintainer of the specified driver. The calling program must not attempt to free the returned string.

Arguments

- `Driver`: The target driver.

Returns

- A string containing the driver maintainer's full name and email address.

#### dbi_driver_get_url

    	      const char *dbi_driver_get_url
    	      dbi_driver Driver

Requests the maintainer's URL for the specified driver. This is useful for drivers maintained by a third party. The calling program must not attempt to free the returned string.

Arguments

- `Driver`: The target driver.

#### dbi_driver_get_version

    	      const char *dbi_driver_get_version
    	      dbi_driver Driver

Requests the version of the specified driver. The calling program must not attempt to free the returned string.

Arguments

- `Driver`: The target driver.

Returns

- A string containing the driver's version.

#### dbi_driver_get_date_compiled

    	      const char *dbi_driver_get_date_compiled
    	      dbi_driver Driver

Requests the compilation date of the specified driver. The calling program must not attempt to free the returned string.

Arguments

- `Driver`: The target driver.

Returns

- A string containing the date the driver was compiled.

#### dbi_driver_cap_get

    	      int dbi_driver_cap_get
    	      dbi_driver Driver
    	      const char *capname

Requests the value of the driver capability which is specified as an argument.

Arguments

- `Driver`: The target driver.

  `capname`: A pointer to a string containing the name of the driver capability to be queried.

Returns

- The numeric value of the driver capability.

## Connection Infrastructure

### dbi_conn_new_r

    	    dbi_conn dbi_conn_new_r
    	    const char *name
    	    dbi_inst Inst

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.

Arguments

- `name`: The name of the desired driver.

  `Inst`: The instance handle.

Returns

- A connection instance of the specified driver, or NULL if there was an error.

### dbi_conn_new

    	    dbi_conn dbi_conn_new
    	    const char *name

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.

This function is deprecated. Use dbi-conn-new-r instead.

Arguments

- `name`: The name of the desired driver.

Returns

- A connection instance of the specified driver, or NULL if there was an error.

### dbi_conn_open

    	    dbi_conn dbi_conn_open
    	    dbi_driver Driver

Creates a connection instance of the specified driver. This connection can be used to perform queries and set options.

Arguments

- `Driver`: The target driver.

Returns

- A connection instance of the specified driver, or NULL if there was an error.

### dbi_conn_close

    	    void dbi_conn_close
    	    dbi_conn Conn

Disconnects the specified connection connection from the database and cleans up the connection session.

Arguments

- `Conn`: The target connection.

### dbi_conn_get_driver

    	    dbi_driver dbi_conn_get_driver
    	    dbi_conn Conn

Returns the driver type of the specified connection.

Arguments

- `Conn`: The target connection.

Returns

- The driver type of the target connection.

### dbi_conn_set_option

    	    int dbi_conn_set_option
    	    dbi_conn Conn
    	    const char *key
    	    char *value

Sets a specified connection option to a string value.

Arguments

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

Returns

- -1 on error, 0 on success. In case of an error, the error number is DBI_ERROR_NOMEM.

### dbi_conn_set_option_numeric

    	    int dbi_conn_set_option_numeric
    	    dbi_conn Conn
    	    const char *key
    	    int value

Sets a specified connection option to a numeric value.

Arguments

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

Returns

- -1 on error, 0 on success. In case of an error, the error number is DBI_ERROR_NOMEM.

### dbi_conn_get_option

    	    const char *dbi_conn_get_option
    	    dbi_conn Conn
    	    const char *key

Retrieves the string value of the specified option set for a connection if available.

Arguments

- `Conn`: The target connection.

  `key`: The name of the target setting.

Returns

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

### dbi_conn_require_option

    	    const char *dbi_conn_require_option
    	    dbi_conn Conn
    	    const char *key

Retrieves the string value of the specified option set for a connection and throws an error if the option was not set.

Arguments

- `Conn`: The target connection.

  `key`: The name of the target setting.

Returns

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

### dbi_conn_get_option_numeric

    	    int dbi_conn_get_option_numeric
    	    dbi_conn Conn
    	    const char *key

Retrieves the integer value of the specified option set for a connection if available.

Arguments

- `Conn`: The target connection.

  `key`: The name of the target setting.

Returns

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

### dbi_conn_require_option_numeric

    	    int dbi_conn_require_option_numeric
    	    dbi_conn Conn
    	    const char *key

Retrieves the integer value of the specified option set for a connection and throws an error if it is not available.

Arguments

- `Conn`: The target connection.

  `key`: The name of the target setting.

Returns

- The value of the setting, or -1 if it is not available. In the latter case, the error number is DBI_ERROR_BADNAME.

### dbi_conn_get_option_list

    	    const char *dbi_conn_get_option_list
    	    dbi_conn Conn
    	    const char *current

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.

Arguments

- `Conn`: The target connection.

  `current`: The key name of the target option.

Returns

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

### dbi_conn_clear_option

    	    void dbi_conn_clear_option
    	    dbi_conn Conn
    	    const char *key

Removes the target option setting from a connection. It is not considered an error if the requested option was not set before.

Arguments

- `Conn`: The target connection.

  `key`: The name of the target setting.

### dbi_conn_clear_options

    	    void dbi_conn_clear_options
    	    dbi_conn Conn

Removes all option settings from a connection.

Arguments

- `Conn`: The target connection.

### dbi_conn_cap_get

    	      int dbi_conn_cap_get
    	      dbi_conn Conn
    	      const char *capname

Requests the value of a driver capability associated with the current connection. The name of the capability is specified as an argument.

Arguments

- `Conn`: The target connection.

  `capname`: A pointer to a string containing the name of the driver capability to be queried.

Returns

- The numeric value of the driver capability.

### dbi_conn_get_socket

    	    int dbi_conn_get_socket
    	    dbi_conn Conn

Obtain the file descriptor number for the backend connection socket.

Arguments

- `Conn`: The target connection

Returns

- -1 on failure, the file descriptor number on success

### dbi_conn_get_encoding

    	    const char *dbi_conn_get_encoding
    	    dbi_conn Conn

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

Arguments

- `Conn`: The current encoding.

Returns

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

### dbi_conn_get_engine_version_string

    	    char *dbi_conn_get_engine_version_string
    	    dbi_conn Conn
    	    char *versionstring

Requests the version of the database engine that serves the current connection as a string.

Arguments

- `Conn`: The current connection.

  `versionstring`: A string buffer that can hold at least VERSIONSTRING_LENGTH bytes.

Returns

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

  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.

Availability

- 0.8.0

### dbi_conn_get_engine_version

    	    unsigned int dbi_conn_get_engine_version
    	    dbi_conn Conn

Requests the version of the database engine that serves the current connection in a numeric form.

Arguments

- `Conn`: The current connection.

Returns

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

Availability

- 0.8.0

### Error Handling

#### dbi_conn_error

    	      int dbi_conn_error
    	      dbi_conn Conn
    	      const char **errmsg_dest

Returns a formatted message with the error number and description resulting from the previous database operation.

Arguments

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

Returns

- The error number of the most recent database operation if it resulted in an error. If not, this will return DBI_ERROR_NONE. See errorhandling for further information.

#### dbi_conn_error_handler

    	      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.

Arguments

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

#### dbi_conn_error_flag

    	      dbi_error_flag dbi_conn_error_flag
    	      dbi_conn Conn

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.

Arguments

- `Conn`: The target connection.

Returns

- 0 means the previous query finished without errors. A value larger than zero means an error occurred.

This function is deprecated. Use dbi-conn-error instead. Both functions return the same error code to maintain backwards compatibility.

#### dbi_conn_set_error

    	      int dbi_conn_set_error
    	      dbi_conn Conn
    	      int errnum
    	      const char *formatstr
    	      ...

Applications may set an error status and an error message which are accessible through the libdbi error API function dbi_conn_error.

Arguments

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

Returns

- The length of the error message in bytes, or 0 if there was an error.

### Transactions and Savepoints

#### dbi_conn_transaction_begin

    	      int dbi_conn_transaction_begin
    	      dbi_conn Conn

Starts a transaction.

Arguments

- `Conn`: The target connection.

Returns

- 0 (zero) if successful, otherwise nonzero.

#### dbi_conn_transaction_commit

    	      int dbi_conn_transaction_commit
    	      dbi_conn Conn

Commits a transaction, i.e. writes all changes since the transaction was started to the database.

Arguments

- `Conn`: The target connection.

Returns

- 0 (zero) if successful, otherwise nonzero.

#### dbi_conn_transaction_rollback

    	      int dbi_conn_transaction_rollback
    	      dbi_conn Conn

Rolls back a transaction, i.e. reverts all changes since the transaction started.

Arguments

- `Conn`: The target connection.

Returns

- 0 (zero) if successful, otherwise nonzero.

#### dbi_conn_savepoint

    	      int dbi_conn_savepoint
    	      dbi_conn Conn
    	      const char *savepoint

Sets a savepoint named `savepoint` within the current transaction.

Arguments

- `Conn`: The target connection.

  `savepoint`: a pointer to a string containing the name of the savepoint.

Returns

- 0 (zero) if successful, otherwise nonzero.

#### dbi_conn_rollback_to_savepoint

    	      int dbi_conn_rollback_to_savepoint
    	      dbi_conn Conn
    	      const char *savepoint

Rolls back all changes since the savepoint named `savepoint` was established within the current transaction.

Arguments

- `Conn`: The target connection.

  `savepoint`: a pointer to a string containing the name of the savepoint.

Returns

- 0 (zero) if successful, otherwise nonzero.

#### dbi_conn_release_savepoint

    	      int dbi_conn_release_savepoint
    	      dbi_conn Conn
    	      const char *savepoint

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.

Arguments

- `Conn`: The target connection.

  `savepoint`: a pointer to a string containing the name of the savepoint.

Returns

- 0 (zero) if successful, otherwise nonzero.

## SQL and Database Infrastructure

### dbi_conn_connect

    	    int dbi_conn_connect
    	    dbi_conn Conn

Connects to the database using the options (host, username, password, port, (etc.) set with dbi_conn_set_option and related functions. See the documentation for each specific database driver for the options it recognizes and requires.

Arguments

- `Conn`: The target connection.

Returns

- 0 (zero) on success, less than zero on failure. In the latter case, the error number may be DBI_ERROR_NOMEM, DBI_ERROR_NOCONN, or one of the driver-specific values.

### dbi_conn_get_db_list

    	    dbi_result dbi_conn_get_db_list
    	    dbi_conn Conn
    	    const char *pattern

Queries the list of available databases on the server.

Arguments

- `Conn`: The target connection.

  `pattern`: A string pattern (SQL regular expression) that each name must match, or NULL to show all available databases.

Returns

- A query result object, which will contain database names in the first field (for use with the by-index field functions). In case of an error, the function returns NULL and sets the error number to a database engine-specific nonzero value.

### dbi_conn_get_table_list

    	    dbi_result dbi_conn_get_table_list
    	    dbi_conn Conn
    	      const char *db
    	      const char *pattern

Queries the list of available tables in a particular database.

Arguments

- `Conn`: The target connection.

  `db`: The target database name.

  `pattern`: A string pattern (SQL regular expression) that each name must match, or NULL to show all available tables.

Returns

- A query result object, which will contain table names in the first field (for use with the by-index field functions). In case of an error, the function returns NULL and sets the error number to a database engine-specific nonzero value.

### dbi_conn_select_db

    	    int dbi_conn_select_db
    	    dbi_conn Conn
    	    const char *db

Switches to a different database on the server.

Arguments

- `Conn`: The target connection.

  `db`: The target database name.

Returns

- -1 on failure, zero on success. In case of an error, the error number may be DBI_ERROR_UNSUPPORTED or a database engine-specific nonzero value.

## Managing Queries

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

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

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

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.

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

  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.

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

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.

  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

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

  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.

### 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

### 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

### 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

### 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

### 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

### 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

## Managing Results

### 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.If an error occurs, the return value is NULL, and the error number is set to DBI_ERROR_BADPTR.

### 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. If a failure was caused by the database client library, the error number is set to the database engine-specific nonzero error code.

### 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. In the latter case, the error number is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.

### 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. In the latter case, the error number is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.

### 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. In the latter case, the error number is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.

### 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. In the latter case, the error number is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.

### 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. In the latter case, the error number is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.

### 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. In case of an error, the error number is DBI_ERROR_BADPTR.

### 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. In that case, the error number is DBI_ERROR_BADPTR.

### 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. In case of an error, the error number is DBI_ERROR_BADPTR.

## Retrieving Field Meta-data

### dbi_result_get_field_length

    	    size_t dbi_result_get_field_length
    	    dbi_result Result
    	    const char *const char *fieldname

Returns the length of the value stored in the specified field which contains a string or a binary string.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the target field.

Returns

- The length in bytes of the target field data, excluding the terminating zero byte, or DBI_LENGTH_ERROR in case of an error. The return value is 0 for field types other than string or binary string. In case of an error the error number is one of DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, or DBI_ERROR_BADIDX.

### dbi_result_get_field_length_idx

    	    size_t dbi_result_get_field_length_idx
    	    dbi_result Result
    	    unsigned int idx

Returns the length of the value stored in the specified field which contains a string or a binary string.

Arguments

- `Result`: The target query result.

  `idx`: The index of the target field (starting at 1).

Returns

- The length in bytes of the target field data, excluding the terminating zero byte, or DBI_LENGTH_ERROR in case of an error. The return value is 0 for field types other than string or binary string. In case of an error the error number is one of DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, or DBI_ERROR_BADIDX.

### dbi_result_get_field_size

    	    size_t dbi_result_get_field_size
    	    dbi_result Result
    	    const char *fieldname

Returns the size in bytes of the value stored in the specified field.

This function is deprecated. Use dbi-result-get-field-length instead.

### dbi_result_get_field_size_idx

    	    size_t dbi_result_get_field_size_idx
    	    dbi_result Result
    	    unsigned long idx

Returns the size in bytes of the value stored in the specified field.

This function is deprecated. Use dbi-result-get-field-length-idx instead.

### dbi_result_get_field_idx

    	    unsigned int dbi_result_get_field_idx
    	    dbi_result Result
    	    const char *fieldname

Given a field's name, return that field's numeric index.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the target field.

Returns

- The index (starting at 1) of the target field, or 0 in case of an error. In that case, the error number is DBI_ERROR_BADPTR.

### dbi_result_get_field_name

    	    const char *dbi_result_get_field_name
    	    dbi_result Result
    	    unsigned int idx

Given a field's numeric index, return that field's name.

Arguments

- `Result`: The target query result.

  `idx`: The index of the target field (starting at 1).

Returns

- The target field's name, or NULL in case of an error. In that case the error number is one of DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, or DBI_ERROR_BADIDX.

### dbi_result_get_numfields

    	    unsigned int dbi_result_get_numfields
    	    dbi_result Result

Returns the number of fields in the query result.

Arguments

- `Result`: The target query result.

Returns

- The number of fields in the query result, or DBI_FIELD_ERROR in case of an error.

### dbi_result_get_field_type

    	    unsigned short dbi_result_get_field_type
    	    dbi_result Result
    	    const char *fieldname

Returns the target field's data type. The constants returned by this function are defined in dbi.h with the prefix "DBI_TYPE_".

Arguments

- `Result`: The target query result.

  `fieldname`: The target field's name.

Returns

- The target field's data type, or DBI_TYPE_ERROR in case of an error. In the latter case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_field_type_idx

    	    unsigned short dbi_result_get_field_type_idx
    	    dbi_result Result
    	    unsigned int idx

Returns the target field's data type. The constants returned by this function are defined in dbi.h with the prefix "DBI_TYPE_".

Arguments

- `Result`: The target query result.

  `idx`: The index of the target field (starting at 1).

Returns

- The target field's data type, or DBI_TYPE_ERROR in case of an error. In the latter case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_field_attrib

    	    unsigned int dbi_result_get_field_attrib
    	    dbi_result Result
    	    const char *fieldname
    	      unsigned int attribmin
    	      unsigned int attribmax

Returns the target field's data type attributes in the specified range. The constants returned by this function are defined in `include/dbi/dbi.h` with the prefix "DBI_", followed by the name of the field's datatype.

Arguments

- `Result`: The target query result.

  `fieldname`: The target field's name.

  `attribmin`: The first attribute value in the range of attributes to extract.

  `attribmax`: The last attribute value in the range of attributes to extract. This may be the same as attribmin if you are only trying to extract a single attribute value.

Returns

- The target field's requested attribute range, or DBI_ATTRIBUTE_ERROR in case of an error. In the latter case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_field_attrib_idx

    	    unsigned int dbi_result_get_field_attrib_idx
    	    dbi_result Result
    	    unsigned int idx
    	    unsigned int attribmin
    	    unsigned int attribmax

Returns the target field's data type attributes in the specified range. The constants returned by this function are defined in dbi.h with the prefix "DBI_", followed by the name of the field's datatype.

Arguments

- `Result`: The target query result.

  `idx`: The index of the target field (starting at 1).

  `attribmin`: The first attribute value in the range of attributes to extract.

  `attribmax`: The last attribute value in the range of attributes to extract. This may be the same as attribmin if you are only trying to extract a single attribute value.

Returns

- The target field's requested attribute range, or DBI_ATTRIBUTE_ERROR in case of an error. In the latter case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_field_attribs

    	    unsigned int dbi_result_get_field_attribs
    	    dbi_result Result
    	    const char *fieldname

Returns the target field's data type attributes. The constants returned by this function are defined in dbi.h with the prefix "DBI_", followed by the name of the field's datatype.

Arguments

- `Result`: The target query result.

  `fieldname`: The target field's name.

Returns

- The target field's attributes, or DBI_ATTRIBUTE_ERROR in case of an error. In case of an error the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_field_attribs_idx

    	    unsigned int dbi_result_get_field_attribs_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Returns the target field's data type attributes. The constants returned by this function are defined in dbi.h with the prefix "DBI_", followed by the name of the field's datatype.

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The target field's attributes, or DBI_ATTRIBUTE_ERROR in case of an error. In that case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_field_is_null

    	    int dbi_result_field_is_null
    	    dbi_result Result
    	    const char *fieldname

Determines whether the indicated field contains a NULL value.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the target field.

Returns

- 1 if the field contains a NULL value, otherwise 0, or DBI_FIELD_FLAG_ERROR in case of an error. In the latter case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_field_is_null_idx

    	    int dbi_result_field_is_null_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Determines whether the indicated field contains a NULL value.

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- 1 if the field contains a NULL value, otherwise 0, or DBI_FIELD_FLAG_ERROR in case of an error. In the latter case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

## Retrieving Field Data by Name

### dbi_result_get_fields

    	    unsigned int dbi_result_get_fields
    	    dbi_result Result
    	    const char *format
    	    ...

Fetch multiple fields from the current result set, using a printf-like syntax. The formatter string specified field names and types, and each field's associated destination variable is passed as an argument following the format string. Fields in the formatter string are separated by spaces, and follow the format `"a.%b"`, where "a" is the name of the field, and "b" is the field type specifier. Make sure you pass the destination variables' memory addresses by prepending the & operator to each variable's name.

Field type specifiers:

- `%c / %uc`: A signed/unsigned character (1-byte)

- `%h / %uh`: A signed/unsigned short integer (2-byte)

- `%l / %ul`: A signed/unsigned integer (4-byte)

- `%i / %ui`: A signed/unsigned integer (4-byte)

- `%L / %uL`: A signed/unsigned long long integer (8-byte)

- `%f`: A floating point number

- `%d`: A double-precision number

- `%s`: A read-only string

- `%S`: A local copy of a string (must be freed by program)

- `%b`: A read-only pointer to binary data

- `%B`: A local copy of binary data (must be freed by program)

- `%m`: A time_t value representing a DATE and/or TIME

Example usage: `dbi_result_get_fields(result, "idnum.%ul lastname.%s", &id_number, &name)`

Arguments

- `Result`: The target query result.

  `format`: The field format string as described above.

  `ARG`: (...) Pointers to the destination variables corresponding with each field in the format string.

Returns

- The number of fields fetched, or DBI_FIELD_ERROR if there was an error. If an invalid field name was specified it will not raise an error, and the other fetched fields will work as usual.

### dbi_result_bind_fields

    	    unsigned int dbi_result_bind_fields
    	    dbi_result Result
    	    const char *format
    	    ...

Bind multiple fields in the current result set, using a printf-like syntax. See dbi-result-get-fields for a detailed explanation of the syntax.

Arguments

- `Result`: The target query result.

  `format`: The field format string as described above.

  `ARG`: (...) Pointers to the destination variables corresponding with each field in the format string.

Returns

- The number of field binding set up, or DBI_FIELD_ERROR if there was an error.

### dbi_result_get_char

    	    signed char dbi_result_get_char
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains a character (a 1-byte signed integer). This is the default for the "char" type on the x86 platform, as well as on Mac OS X.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_uchar

    	    unsigned char dbi_result_get_uchar
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains an unsigned character (1-byte unsigned integer). This is the default for the "char" type on Linux for PowerPC.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_short

    	    short dbi_result_get_short
    	    dbi_result Result
    	    const char *const char *fieldname

Fetch the data stored in the speficied field, which contains a short integer (2-byte signed integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME..

### dbi_result_get_ushort

    	    unsigned short dbi_result_get_ushort
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains an unsigned short integer (2-byte unsigned integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME..

### dbi_result_get_int

    	    int dbi_result_get_int
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains an integer (4-byte signed integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME..

Availability

- 0.8.0

### dbi_result_get_uint

    	    unsigned int dbi_result_get_uint
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains an unsigned integer (4-byte unsigned integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME..

Availability

- 0.8.0

### dbi_result_get_long

    	    int dbi_result_get_long
    	    dbi_result Result
    	    const char *fieldname

This is the same as dbi-result-get-int. The use of this function is deprecated as the name implies the wrong return type on 64-bit platforms.

### dbi_result_get_ulong

    	    unsigned int dbi_result_get_ulong
    	    dbi_result Result
    	    const char *fieldname

This is the same as dbi-result-get-uint. The use of this function is deprecated as the name implies the wrong return type on 64-bit platforms.

### dbi_result_get_longlong

    	    long long dbi_result_get_longlong
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains a long long integer (8-byte signed integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME..

### dbi_result_get_ulonglong

    	    unsigned long long dbi_result_get_ulonglong
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains an unsigned long long integer (8-byte unsigned integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME..

### dbi_result_get_float

    	    float dbi_result_get_float
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains a floating-point number.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field, which contains a fractional number, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME..

### dbi_result_get_double

    	    double dbi_result_get_double
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains a double-precision fractional number.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME..

### dbi_result_get_string

    	    const char *dbi_result_get_string
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains a zero-terminated string.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field, which is a zero-terminated string. If the field contains a NULL value, the function returns a NULL pointer. The string may not be modified, and may not necessarily persist between row fetches. In case of an error, this function returns the string "ERROR". In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_string_copy

    	    char *dbi_result_get_string_copy
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains a zero-terminated string, and return it in an allocated buffer.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field as a zero-terminated allocated string. If the field contains a NULL value, the function returns a NULL pointer, and no memory is allocated. The newly allocated string may be modified by the host program, but the program is responsible for freeing the string. In case of an error, this function returns an allocated string reading "ERROR". In that case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_binary

    	    const unsigned char *dbi_result_get_binary
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains binary data.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field. The binary data may contain zero bytes and non-printable characters. Use dbi-result-get-field-length or dbi-result-get-field-length-idx to determine the number of bytes contained in the resulting binary string. The data may not be modified, and may not necessarily persist between row fetches. If the field contains a NULL value, the function returns a NULL pointer. In case of an error, this function returns the string "ERROR". In that case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_binary_copy

    	    unsigned char *dbi_result_get_binary_copy
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the speficied field, which contains binary data, and return it in an allocated buffer.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field. The binary data may contain zero bytes and non-printable characters. Use dbi-result-get-field-length or dbi-result-get-field-length-idx to determine the number of bytes contained in the resulting binary string. The newly allocated memory may be modified by the host program, but the program is responsible for freeing the data. If the field contains a NULL value, the function returns a NULL pointer. In case of an error, this function returns the string "ERROR". In that case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_datetime

    	    time_t dbi_result_get_datetime
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the specified field, which contains a DATE and/or TIME value.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field as a time_t value. To convert this into human-readable dates or times, use the C library functions gmtime (3) and localtime (3). In case of an error this function returns 0 (zero) which resolves to the Unix epoch when converted. In case of an error the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_as_longlong

    	    long long dbi_result_get_as_longlong
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the specified field. Return the contents as a long long integer value, using appropriate casts or conversions if applicable.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- The data stored in the specified field as a long long integer. Integer and floating point data as well as datetime data are cast to long long. Strings are converted using strtoll(). Empty strings, strings that do not translate into an integer, and binary strings are returned as 0 (zero) without raising an error. In case of an error this function returns 0 (zero) and the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

Availability

- 0.9.0

### dbi_result_get_as_string_copy

    	    char *dbi_result_get_as_string_copy
    	    dbi_result Result
    	    const char *fieldname

Fetch the data stored in the specified field. Return the contents as an allocated string, using appropriate conversions if applicable. The caller is responsible for freeing the returned buffer when done.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to fetch.

Returns

- A string representation of the data stored in the specified field. Integer, floating point and datetime data are pretty-printed using snprintf(). Strings are returned as such. Empty strings and binary strings are returned as empty strings without raising an error. In case of an error this function returns the string "ERROR" and the error number is DBI_ERROR_NOMEM, DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

Availability

- 0.9.0

### dbi_result_bind_char

    	    int dbi_result_bind_char
    	    dbi_result Result
    	    const char *fieldname
    	    char *bindto

Bind the specified variable to the specified field, which holds a character (a 1-byte signed integer). This is the default for the "char" type on the x86 platform, as well as on Mac OS X.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_uchar

    	    int dbi_result_bind_uchar
    	    dbi_result Result
    	    const char *fieldname
    	    unsigned char *bindto

Bind the specified variable to the specified field, which holds an unsigned character (1-byte unsigned integer). This is the default for the "char" type on Linux for PowerPC.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_short

    	    int dbi_result_bind_short
    	    dbi_result Result
    	    const char *fieldname
    	    short *bindto

Bind the specified variable to the specified field, which holds a short integer (2-byte signed integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_ushort

    	    int dbi_result_bind_ushort
    	    dbi_result Result
    	      const char *fieldname
    	      unsigned short *bindto

Bind the specified variable to the specified field, which holds an unsigned short integer (2-byte unsigned integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_int

    	    int dbi_result_bind_int
    	    dbi_result Result
    	    const char *fieldname
    	    long *bindto

Bind the specified variable to the specified field, which holds an integer (4-byte signed integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

Availability

- 0.8.0

### dbi_result_bind_uint

    	    int dbi_result_bind_uint
    	    dbi_result Result
    	     const char *fieldname
    	      unsigned long *bindto

Bind the specified variable to the specified field, which holds an unsigned long integer (4-byte unsigned integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

Availability

- 0.8.0

### dbi_result_bind_long

    	    int dbi_result_bind_long
    	    dbi_result Result
    	    const char *fieldname
    	    long *bindto

The same as dbi-result-bind-int. The use of this function is deprecated as the name implies the wrong return type on 64-bit platforms.

### dbi_result_bind_ulong

    	    int dbi_result_bind_ulong
    	    dbi_result Result
    	     const char *fieldname
    	      unsigned long *bindto

The same as dbi-result-bind-uint. The use of this function is deprecated as the name implies the wrong return type on 64-bit platforms.

### dbi_result_bind_longlong

    	    int dbi_result_bind_longlong
    	    dbi_result Result
    	    const char *fieldname
    	    long long *bindto

Bind the specified variable to the specified field, which holds a long long integer (8-byte signed integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_ulonglong

    	    int dbi_result_bind_ulonglong
    	    dbi_result Result
    	    const char *fieldname
    	    unsigned long long *bindto

Bind the specified variable to the specified field, which holds an unsigned long long integer (8-byte unsigned integer).

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_float

    	    int dbi_result_bind_float
    	    dbi_result Result
    	    const char *fieldname
    	    float *bindto

Bind the specified variable to the specified field, which holds a floating-point number.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_double

    	    int dbi_result_bind_double
    	    dbi_result Result
    	    const char *fieldname
    	    double *bindto

Bind the specified variable to the specified field, which holds a double-precision fractional number.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_string

    	    int dbi_result_bind_string
    	    dbi_result Result
    	    const char *fieldname
    	    const char **bindto

Bind the specified variable to the specified field, which holds a string. The string must not be modified.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_binary

    	    int dbi_result_bind_binary
    	    dbi_result Result
    	    const char *fieldname
    	    const unsigned char **bindto

Bind the specified variable to the specified field, which holds binary BLOB data. The data must not be modified.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_string_copy

    	    int dbi_result_bind_string_copy
    	    dbi_result Result
    	    const char *fieldname
    	    char **bindto

Bind the specified variable to the specified field, which holds a string. The newly allocated string may be modified by the host program, but the program is responsible for freeing the string.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_binary_copy

    	    int dbi_result_bind_binary_copy
    	    dbi_result Result
    	    const char *fieldname
    	    unsigned char **bindto

Bind the specified variable to the specified field, which holds binary BLOB data. The newly allocated data may be modified by the host program, but the program is responsible for freeing the data.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

### dbi_result_bind_datetime

    	    int dbi_result_bind_datetime
    	    dbi_result Result
    	    const char *fieldname
    	    time_t *bindto

Bind the specified variable to the specified field, which holds a DATE and/or TIME value.

Arguments

- `Result`: The target query result.

  `fieldname`: The name of the field to bind to.

  `bindto`: A pointer to the variable that will be updated with the specified field's value.

Returns

- 0 upon success, DBI_BIND_ERROR if there was an error. Possible error numbers are DBI_ERROR_BADPTR, DBI_ERROR_NOMEM, and DBI_ERROR_BADNAME.

## Retrieving Field Data by Index

### dbi_result_get_char_idx

    	    signed char dbi_result_get_char_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains a character (a 1-byte signed integer). This is the default for the "char" type on the x86 platform, as well as on Mac OS X.

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE or DBI_ERROR_BADIDX.

### dbi_result_get_uchar_idx

    	    unsigned char dbi_result_get_uchar_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains an unsigned character (1-byte unsigned integer). This is the default for the "char" type on Linux for PowerPC.

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE or DBI_ERROR_BADIDX.

### dbi_result_get_short_idx

    	    short dbi_result_get_short_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains a short integer (2-byte signed integer).

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE or DBI_ERROR_BADIDX.

### dbi_result_get_ushort_idx

    	    unsigned short dbi_result_get_ushort_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains an unsigned short integer (2-byte unsigned integer).

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE or DBI_ERROR_BADIDX.

### dbi_result_get_int_idx

    	    int dbi_result_get_int_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains an integer (4-byte signed integer).

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE or DBI_ERROR_BADIDX.

Availability

- 0.8.0

### dbi_result_get_uint_idx

    	    unsigned int dbi_result_get_uint_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains an unsigned integer (4-byte signed integer).

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE or DBI_ERROR_BADIDX.

Availability

- 0.8.0

### dbi_result_get_long_idx

    	    int dbi_result_get_long_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Same as dbi-result-get-int-idx. This function is deprecated as the name implies the wrong return type on 64bit platforms.

### dbi_result_get_ulong_idx

    	    unsigned int dbi_result_get_ulong_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Same as dbi-result-get-uint-idx. This function is deprecated as the name implies the wrong return type on 64bit platforms.

### dbi_result_get_longlong_idx

    	    long long dbi_result_get_longlong_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains a long long integer (8-byte signed integer).

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE or DBI_ERROR_BADIDX.

### dbi_result_get_ulonglong_idx

    	    unsigned long long dbi_result_get_ulonglong_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains an unsigned long long integer (8-byte unsigned integer).

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE or DBI_ERROR_BADIDX.

### dbi_result_get_float_idx

    	    float dbi_result_get_float_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains a floating-point number.

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE or DBI_ERROR_BADIDX.

### dbi_result_get_double_idx

    	    double dbi_result_get_double_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains a double-precision fractional number.

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field, or 0 (zero) if an error occurs. In the latter case the error number is DBI_ERROR_BADTYPE or DBI_ERROR_BADIDX.

### dbi_result_get_string_idx

    	    const char *dbi_result_get_string_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains a zero-terminated string.

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field. If the field contains a NULL value, the function returns a NULL pointer. The string may not be modified, and may not necessairly persist between row fetches. In case of an error, this function returns the string "ERROR". In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_string_copy_idx

    	    char *dbi_result_get_string_copy_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains a zero-terminated string, and return it in an allocated buffer.

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field. If the field contains a NULL value, the function returns a NULL pointer, and no memory is allocated. The newly allocated string may be modified by the host program, but the program is responsible for freeing the string. In case of an error, this function returns an allocated string reading "ERROR". In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_binary_idx

    	    const unsigned char *dbi_result_get_binary_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains binary data. The data may not be modified, and may not necessarily persist between row fetches. If the field contains a NULL value, the function returns a NULL pointer. In case of an error, this function returns the string "ERROR".

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field. The binary data may contain zero bytes and non-printable characters. Use dbi-result-get-field-length or dbi-result-get-field-length-idx to determine the number of bytes contained in the resulting binary string. The data may not be modified, and may not necessarily persist between row fetches. If the field contains a NULL value, the function returns a NULL pointer. In case of an error, this function returns the string "ERROR". In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_binary_copy_idx

    	    unsigned char *dbi_result_get_binary_copy_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the speficied field, which contains binary data, and return it in an allocated buffer. The newly allocated memory may be modified by the host program, but the program is responsible for freeing the data. If the field contains a NULL value, the function returns a NULL pointer. In case of an error, this function returns the string "ERROR".

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field. The newly allocated memory may be modified by the host program, but the program is responsible for freeing the data. If the field contains a NULL value, the function returns a NULL pointer. In case of an error, this function returns the string "ERROR". In the latter case the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_datetime_idx

    	    time_t dbi_result_get_datetime_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the specified field, which contains a DATE and/or TIME value.

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field as a time_t value. To convert this into human-readable dates or times, use the C library functions gmtime (3) and localtime (3). In case of an error this function returns 0 (zero) which resolves to the Unix epoch when converted. In case of an error the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

### dbi_result_get_as_longlong_idx

    	    long long dbi_result_get_as_longlong_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the specified field. Return the contents as a long long integer value, using appropriate casts or conversions if applicable.

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- The data stored in the specified field as a long long integer. Integer and floating point data as well as datetime data are cast to long long. Strings are converted using strtoll(). Empty strings, strings that do not translate into an integer, and binary strings are returned as 0 (zero) without raising an error. In case of an error this function returns 0 (zero) and the error number is DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

Availability

- 0.9.0

### dbi_result_get_as_string_copy_idx

    	    char *dbi_result_get_as_string_copy_idx
    	    dbi_result Result
    	    unsigned int fieldidx

Fetch the data stored in the specified field. Return the contents as an allocated string, using appropriate conversions if applicable. The caller is responsible for freeing the returned buffer when done.

Arguments

- `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

- A string representation of the data stored in the specified field. Integer, floating point and datetime data are pretty-printed using snprintf(). Strings are returned as such. Empty strings and binary strings are returned as empty strings without raising an error. In case of an error this function returns the string "ERROR" and the error number is DBI_ERROR_NOMEM, DBI_ERROR_BADTYPE, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

Availability

- 0.9.0