SQL Database Interface
[State Utility Library]

Typedefs
typedef apr_int32_t	sul_key_t
typedef sul_dbc_t	sul_dbc_t
typedef sul_dbr_t	sul_dbr_t
Functions
	sul_dbc_create (sul_dbc_t **self, const char *dbname, const char *user, const char *passwd, apr_pool_t *pool)
	sul_dbc_close (sul_dbc_t *dbc)
	sul_dbc_update (sul_dbc_t *dbc, apr_pool_t *pool, const char *sql)
	sul_dbc_updatef (sul_dbc_t *dbc, apr_pool_t *pool, const char *f,...)
	sul_dbc_query (sul_dbr_t **resp, sul_dbc_t *dbc, apr_pool_t *pool, const char *sql)
	sul_dbc_queryf (sul_dbr_t **resp, sul_dbc_t *dbc, apr_pool_t *pool, const char *f,...)
	sul_dbc_refs_read (sul_dbc_t *dbc)
	sul_dbc_refs_inc (sul_dbc_t *dbc)
	sul_dbc_refs_dec (sul_dbc_t *dbc)
	sul_dbc_owner_set_thread (sul_dbc_t *dbc)
	sul_dbc_owner_set_none (sul_dbc_t *dbc)
	sul_dbc_begin (sul_dbc_t *dbc)
	sul_dbc_end (sul_dbc_t *dbc)
	sul_dbc_rollback (sul_dbc_t *dbc)
	sul_dbc_primary_key (sul_dbc_t *dbc, const char *serial, apr_pool_t *pool)
	sul_dbc_query_key (sul_dbc_t *dbc, const char *sql, apr_pool_t *pool)
	sul_dbr_number_rows (sul_dbr_t *res)
	sul_dbr_number_fields (sul_dbr_t *res)
	sul_dbr_field_value_by_index (sul_dbr_t *res, apr_ssize_t row, apr_ssize_t index)
	sul_dbr_field_value_by_name (sul_dbr_t *res, apr_ssize_t row, const char *name)
	sul_dbc_escape (const char *str, apr_pool_t *pool)

---

Typedef Documentation

typedef struct sul_dbc_t sul_dbc_t

Opaque database connection structure. Used to execute queries and communicate with the database.

typedef struct sul_dbr_t sul_dbr_t

Opaque database results structure for representing the data returned by a query of some kind.

typedef apr_int32_t sul_key_t

Unique identifier of a row/object in the database, our primary key type.

---

Function Documentation

sul_dbc_begin (  sul_dbc_t *  dbc  )

Begins a new transaction. Parameters: dbc  A database connection. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_dbc_close (  sul_dbc_t *  dbc  )

Closes and frees up an existing database connection. Parameters: dbc  A database connection. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_dbc_create (  sul_dbc_t **  self, const char *  dbname, const char *  user, const char *  passwd, apr_pool_t *  pool )

Create a new Database Connection. Parameters: self  The newly created database connection. dbname  Name of the database to open up. user  User name for authentication purposes. passwd  Password for authentication purposes. pool  Pool to serve the new database connection. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_dbc_end (  sul_dbc_t *  dbc  )

Ends the transaction and writes all the changes to the database. Parameters: dbc  A database connection. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_dbc_escape (  const char *  str, apr_pool_t *  pool )

Escapes a string suitable for use in an SQL query. Any character that requires escaping will be replaced with the proper sequence so that the resulting string can be used in SQL and not generate any errors. Parameters: str  String to be escaped. pool  Pool to allocate the returned string from, this is necessary because the string's length will have changed should any escaping need to be done. Returns: Newly escaped string.

sul_dbc_owner_set_none (  sul_dbc_t *  dbc  )

Assigns the owner of a connection to None, so it's orphaned. In order to use a thread there MUST be an owner. This is for threads that are in a pool waiting for owners. Parameters: dbc  A database connection.

sul_dbc_owner_set_thread (  sul_dbc_t *  dbc  )

Sets the connections owner to the active thread. Owners may only be changed on orphaned connections. Parameters: dbc  A database connection.

sul_dbc_primary_key (  sul_dbc_t *  dbc, const char *  serial, apr_pool_t *  pool )

Retrieves the value of a tables Primary Key, usually after a manipulation of some kind. Parameters: dbc  A database connection. serial  Identifying name of the serial who's primary key is being retrieved. pool  Pool to allocate overhead from. Returns: Latest primary key value requested.

sul_dbc_query (  sul_dbr_t **  resp, sul_dbc_t *  dbc, apr_pool_t *  pool, const char *  sql )

Executse an SQL query over a database connection and returns the resulting rows of that query. Parameters: resp  Where the results of the query will be stored. dbc  A database connection. pool  Pool to serve this queries memory requirements. sql  SQL with format specifiers and all that juicy stuff. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_dbc_query_key (  sul_dbc_t *  dbc, const char *  sql, apr_pool_t *  pool )

Queries for a key using the given SQL query. If no rows are returned then 0 is returned. Parameters: dbc  A database connection. sql  SQL to use to query. pool  Pool to allocate overhead from. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_dbc_queryf (  sul_dbr_t **  resp, sul_dbc_t *  dbc, apr_pool_t *  pool, const char *  f, ...  )

Executse an SQL query over a database connection and returns the resulting rows of that query. Parameters: resp  Where the results of the query will be stored. dbc  A database connection. pool  Pool to serve this queries memory requirements. f  SQL with format specifiers and all that juicy stuff. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_dbc_refs_dec (  sul_dbc_t *  dbc  )

Decrease the DBC's reference counter. Parameters: dbc  A database connection.

sul_dbc_refs_inc (  sul_dbc_t *  dbc  )

Increase the DBC's reference counter. Parameters: dbc  A database connection.

sul_dbc_refs_read (  sul_dbc_t *  dbc  )

Increase the DBC's reference counter. Parameters: dbc  A database connection.

sul_dbc_rollback (  sul_dbc_t *  dbc  )

Roll back the transaction currently being processed. Parameters: dbc  A database connection. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_dbc_update (  sul_dbc_t *  dbc, apr_pool_t *  pool, const char *  sql )

Executse an SQL query over a database connection and returns the resulting rows of that query. Parameters: dbc  A database connection. pool  Pool to serve this queries memory requirements. sql  SQL with format specifiers and all that juicy stuff. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_dbc_updatef (  sul_dbc_t *  dbc, apr_pool_t *  pool, const char *  f, ...  )

Executse an SQL query over a database connection and returns the resulting rows of that query. Parameters: dbc  A database connection. pool  Pool to serve this queries memory requirements. f  SQL with format specifiers and all that juicy stuff. Returns: An sul_error_t instance if an error occured and NULL otherwise.

sul_dbr_field_value_by_index (  sul_dbr_t *  res, apr_ssize_t  row, apr_ssize_t  index )

Returns the value of the field at the given index. Parameters: res  Database results object. row  Row to read the value from. index  Index of the column, starting at zero. Returns: Value of the field.

sul_dbr_field_value_by_name (  sul_dbr_t *  res, apr_ssize_t  row, const char *  name )

Returns the value of the field in the column with the given name. Parameters: res  Database results object. row  Row to read the value from. name  Name of the column. Returns: Value of the field.

sul_dbr_number_fields (  sul_dbr_t *  res  )

Returns the number of fields (columns) in returned by the database. Parameters: res  Database results object. Returns: Number of fields in RES.

sul_dbr_number_rows (  sul_dbr_t *  res  )

Returns the number of rows in returned by the database. Parameters: res  Database results object. Returns: Number of rows in RES.

---