Basic OpenDBX API - Version 1.1

Table of Content

Detailed API description

odbx_bind

int odbx_bind( odbx_t* handle, const char* database, const char* who, const char* cred, int method )
Description:
Opens the database located on the database server specified in odbx_init(). The authentification is done with "who" and "cred". If any options should be set by odbx_set_option(), it must be done before calling this function.
Rebinding with other parameter and options can be performed by calling this function again after invoking odbx_unbind() before.
Parameters:
  • handle: Connection object created by odbx_init()
  • database: Name of the database
  • who: User to connect to the database
  • cred: Password string for authentication
  • method: Authentication method used for login (currently only ODBX_BIND_SIMPLE)
Return values:
  • Zero on success
  • Non-zero if an error occured
Errors:
  • -ODBX_ERR_BACKEND: Any error retured by the backend
  • -ODBX_ERR_PARAM: One of the parameters is invalid
  • -ODBX_ERR_NOMEM: Allocating new memory failed
  • -ODBX_ERR_TOOLONG: The length of a string exceeded the buffer size

odbx_capabilities

int odbx_capabilities( odbx_t* handle, unsigned int cap )
Description:
Queries the backend if a extended capability is implemented. Currently defined capabilites are ODBX_CAP_LO for large object support and ODBX_CAP_PREP for support of prepared statements. This function can be called after odbx_init() returns successfully.
Parameters:
  • handle: Connection object created by odbx_init()
  • cap: Capability defined in odbx.h
Return values:
  • One if capability is supported
  • Zero if capability is not supported
  • Less than zero if an error occured
Errors:
  • -ODBX_ERR_PARAM: Parameter is NULL or an unknown capability

odbx_error

const char* odbx_error( odbx_t* handle, int errno )
Description:
Returns the error string represented by the error number or the error string generated by the backend. Error strings caused by the backend are overwritten when the next odbx_*() function is called. All error strings are static and must not be changed or freed.
Parameters:
  • handle: Connection object created by odbx_init()
  • errno: Error number returned by odbx_*() functions
Return values:
  • Error string in case of an error
  • NULL if no error occured
Errors:
  • None

odbx_error_type

int odbx_error_type( odbx_t* handle, int errno )
Description:
Returns an indicator for the severity of the error returned by the last function call. Errors returned by the backends are overwritten when the next odbx_*() function is called.
Parameters:
  • handle: Connection object created by odbx_init()
  • errno: Error number returned by odbx_*() functions
Return values:
  • Negative values for severe errors
  • Zero on success
  • Positive values for recoverable errors
Errors:
  • None

odbx_escape

int odbx_escape( odbx_t* handle, const char* from, unsigned long fromlen, char* to, unsigned long* tolen )
Description:
Escapes a string so it can be used in a statement. For security reasons each user input have to be passed to odbx_escape() to avoid code injection attacks! Most backends require the buffer to be more than twice as long as the input string. After successfully escaping the string in "from" the length of the new string is written into the value/result parameter "tolen".
Parameters:
  • handle: Connection object created by odbx_init()
  • from: String to escape
  • fromlen: Length of the string in "from" without terminating \0 character
  • to: Buffer for storing escaped string
  • tolen: Length of the buffer
Return values:
  • Zero on success
  • Non-zero if an error occured
Errors:
  • -ODBX_ERR_TOOLONG: The length of a string exceeded the buffer size
  • -ODBX_ERR_PARAM: One of the parameters or its content is invalid

odbx_column_count

unsigned long odbx_column_count( odbx_result_t* result )
Description:
Returns the number of fields in the current result set.
Parameters:
  • result: Object created by odbx_result()
Return values:
  • Number of fields returned by the last query
Errors:
  • None

odbx_column_name

char* odbx_column_name( odbx_result_t* result, unsigned long pos )
Description:
Returns the name of the field specified by "pos" in the current result set. The value of "pos" must be in the range from 0 to odbx_column_count()-1. In case of an error no error message is returned by odbx_error().
Parameters:
  • result: Object created by odbx_result()
  • pos: Column number in the current result set
Return values:
  • Name of the column on success
  • NULL if an error occured
Errors:
  • None

odbx_column_type

int odbx_column_type( odbx_result_t* result, unsigned long pos )
Description:
Returns the type of the column specified by "pos" in the current result set. The value of "pos" must be in the range from 0 to odbx_column_count()-1. Valid types can be found in odbx.h which are defined according to the SQL2003 standard.
Parameters:
  • result: Object created by odbx_result()
  • pos: Column number in the current result set
Return values:
  • Values of zero and more indicate types defined in odbx.h
  • Less than zero if an error occured
Errors:
  • -ODBX_ERR_BACKEND: Any error retured by the backend
  • -ODBX_ERR_PARAM: Parameter or its content is invalid

odbx_field_length

unsigned long odbx_field_length( odbx_result_t* result, unsigned long pos )
Description:
Returns the length of the field value specified by "pos" of the current row. The value of "pos" must be in the range from 0 to odbx_column_count()-1.
Parameters:
  • result: Object created by odbx_result()
  • pos: Column number in the current result set
Return values:
  • Length of the value in the specified column of the current row
Errors:
  • None

odbx_field_value

char* odbx_field_value( odbx_result_t* result, unsigned long pos )
Description:
Returns the value of the field specified by "pos" in the current row. All values except binary objects are returned as strings. Numbers have to be converted to their binary representation before arithmetic operations are allowed. The value of "pos" must be in the range from 0 to odbx_column_count()-1. A value of NULL is both, a valid field value and the return value in case of an error, but errors only occur if "pos" is outside the valid range or "handle" is invalid.
Parameters:
  • result: Object created by odbx_result()
  • pos: Column number in the current result set
Return values:
  • String value or binary object of the specified field
Errors:
  • None

odbx_finish

int odbx_finish( odbx_t* handle )
Description:
Frees all resources allocated by odbx_init()
Parameters:
  • handle: Connection object created by odbx_init()
Return values:
  • Zero on success
  • Non-zero if an error occured
Errors:
  • -ODBX_ERR_PARAM: Parameter or its content is invalid

odbx_get_option

int odbx_get_option( odbx_t* handle, unsigned int option, void* value )
Description:
Queries the backend for supported options. Look in odbx.h for available options.
Parameters:
  • handle: Connection object created by odbx_init()
  • option: Options defined in odbx.h
  • value: Pointer to the variable where the option value should be stored
Return values:
  • Zero on success
  • Less than zero if an error occured
Errors:
  • -ODBX_ERR_PARAM: One of the parameters or its content is invalid
  • -ODBX_ERR_OPTION: Unknown option

odbx_init

int odbx_init( odbx_t** handle, const char* backend, const char* host, const char* port )
Description:
Allocates and initializes the opaque object for connecting to the database server. The pointer to the newly created object is stored in handle and it have to be used in all further OpenDBX functions.
Parameters:
  • handle: Pointer where the connection object pointer should be stored
  • backend: Name of the used backend, e.g. mysql, pgsql or sqlite (depends on the installed libraries)
  • host: Host name or ip address of the database server
  • port: Port number the database server is listening
Return values:
  • Zero on success
  • Non-zero if an error occured
Errors:
  • -ODBX_ERR_BACKEND: Any error retured by the backend
  • -ODBX_ERR_PARAM: One of the parameters or its content is invalid
  • -ODBX_ERR_NOMEM: Allocating new memory failed
  • -ODBX_ERR_TOOLONG: The length of a string exceeded the buffer size
  • -ODBX_ERR_NOEXIST: Backend library was not found
  • -ODBX_ERR_NOOP: The function does not exist in the backend

odbx_query

int odbx_query( odbx_t* handle, const char* query, unsigned long length )
Description:
Sends a query statement to the database server. Some backends support multiple statement queries, which can be requested by odbx_get_option(). Each statement must be terminated by a semicolon and the complete query by a \0 character.
Parameters:
  • handle: Connection object created by odbx_init()
  • query: Statement string
  • length: Length of the query string without the terminating \0 character
Return values:
  • Zero on success
  • Non-zero if an error occured
Errors:
  • -ODBX_ERR_BACKEND: Any error retured by the backend
  • -ODBX_ERR_PARAM: One of the parameters or its content is invalid
  • -ODBX_ERR_NOMEM: Allocating new memory failed

odbx_result

int odbx_result( odbx_t* handle, odbx_result_t** result, struct timeval* timeout, unsigned long chunk )
Description:
Retrieves the result of a query statement from the database server. On success, an dynamically allocated object representing the result ist stored in "result". The third parameter may be NULL to wait until a result arrives or any number of seconds and microseconds in struct timeval to wait for. Dependent on the backend, it may be possible to retrieve all results at once (if "chunk" is zero), one by one or more at once.
Parameters:
  • handle: Connection object created by odbx_init()
  • result: Pointer to a result pointer
  • timeout: Amount of time before waiting for a result is canceled
  • chunk: Number of rows to fetch at once
Return values:
  • Three on success
  • Two if the query was empty or not SELECT-like
  • One in case a timeout occured
  • Zero if no more results are available
  • Less than zero if an error occured
Errors:
  • -ODBX_ERR_BACKEND: Any error retured by the backend
  • -ODBX_ERR_PARAM: One of the parameters or its content is invalid
  • -ODBX_ERR_NOMEM: Allocating new memory failed
  • -ODBX_ERR_RESULT: Waiting of result failed

odbx_result_free

void odbx_result_free( odbx_result_t* result )
Description:
Deletes all resources allocated by odbx_result(). You must not free "result" by yourself because this will create memory leaks. But you have to call odbx_result_free() if the statement returned no result (indicated by return value "3"), e.g for not SELECT-like queries.
Parameters:
  • result: Object created by odbx_result()
Return values:
  • None
Errors:
  • None

odbx_rows_affected

uint64_t odbx_rows_affected( odbx_result_t* result )
Description:
Returns the number of rows changed by the last non SELECT-like query. Zero is returned if nothing was changed, either due to the statement or due to an error.
Parameters:
  • result: Object created by odbx_result()
Return values:
  • Number of rows affected by the last query
Errors:
  • None

odbx_row_fetch

int odbx_row_fetch( odbx_result_t* result )
Description:
Retrieves the next row of a result set returned by odbx_result(). You must fetch all rows from a result set. Otherwise - depending on the backend - an error may occur after calling odbx_result() the next time.
Parameters:
  • result: Object created by odbx_result()
Return values:
  • One on success
  • Zero if no more rows are available
  • Less than zero if an error occured
Errors:
  • -ODBX_ERR_PARAM: Parameter or its content is invalid

odbx_set_option

int odbx_set_option( odbx_t* handle, unsigned int option, void* value )
Description:
Sets the specified options in the backend. Look in odbx.h for available options.
Parameters:
  • handle: Connection object created by odbx_init()
  • option: Options defined in odbx.h
  • value: Pointer of the variable where the option value (mostly zero or one) is stored
Return values:
  • Zero on success
  • Less than zero if an error occured
Errors:
  • -ODBX_ERR_PARAM: One of the parameters or its content is invalid
  • -ODBX_ERR_OPTION: Unknown option
  • -ODBX_ERR_OPTRO: Option is read-only
  • -ODBX_ERR_OPTWR: Setting option failed

odbx_unbind

int odbx_unbind( odbx_t* handle )
Description:
Releases the binding of a database and a user to a connection. This is useful for switching to another database or binding to the database as a different user. It is also possible to set new connection related options before rebinding to the database server.
Parameters:
  • handle: Connection object created by odbx_init()
Return values:
  • Zero on success
  • Non-zero if an error occured
Errors:
  • -ODBX_ERR_PARAM: Parameter or its content is invalid