DBD routines
[APR Utility Functions]

Typedefs
typedef apr_dbd_driver_t	apr_dbd_driver_t
typedef apr_dbd_t	apr_dbd_t
typedef apr_dbd_transaction_t	apr_dbd_transaction_t
typedef apr_dbd_results_t	apr_dbd_results_t
typedef apr_dbd_row_t	apr_dbd_row_t
typedef apr_dbd_prepared_t	apr_dbd_prepared_t
Functions
apr_status_t	apr_dbd_init (apr_pool_t *pool)
apr_status_t	apr_dbd_get_driver (apr_pool_t *pool, const char *name, const apr_dbd_driver_t **driver)
apr_status_t	apr_dbd_open (const apr_dbd_driver_t *driver, apr_pool_t *ptmp, const char *params, apr_dbd_t **handle)
apr_status_t	apr_dbd_close (const apr_dbd_driver_t *driver, apr_dbd_t *handle)
const char *	apr_dbd_name (const apr_dbd_driver_t *driver)
void *	apr_dbd_native_handle (const apr_dbd_driver_t *driver, apr_dbd_t *handle)
int	apr_dbd_check_conn (const apr_dbd_driver_t *driver, apr_pool_t *pool, apr_dbd_t *handle)
int	apr_dbd_set_dbname (const apr_dbd_driver_t *driver, apr_pool_t *pool, apr_dbd_t *handle, const char *name)
int	apr_dbd_transaction_start (const apr_dbd_driver_t *driver, apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_transaction_t **trans)
int	apr_dbd_transaction_end (const apr_dbd_driver_t *driver, apr_pool_t *pool, apr_dbd_transaction_t *trans)
int	apr_dbd_query (const apr_dbd_driver_t *driver, apr_dbd_t *handle, int *nrows, const char *statement)
int	apr_dbd_select (const apr_dbd_driver_t *driver, apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res, const char *statement, int random)
int	apr_dbd_num_cols (const apr_dbd_driver_t *driver, apr_dbd_results_t *res)
int	apr_dbd_num_tuples (const apr_dbd_driver_t *driver, apr_dbd_results_t *res)
int	apr_dbd_get_row (const apr_dbd_driver_t *driver, apr_pool_t *pool, apr_dbd_results_t *res, apr_dbd_row_t **row, int rownum)
const char *	apr_dbd_get_entry (const apr_dbd_driver_t *driver, apr_dbd_row_t *row, int col)
const char *	apr_dbd_error (const apr_dbd_driver_t *driver, apr_dbd_t *handle, int errnum)
const char *	apr_dbd_escape (const apr_dbd_driver_t *driver, apr_pool_t *pool, const char *string, apr_dbd_t *handle)
int	apr_dbd_prepare (const apr_dbd_driver_t *driver, apr_pool_t *pool, apr_dbd_t *handle, const char *query, const char *label, apr_dbd_prepared_t **statement)
int	apr_dbd_pquery (const apr_dbd_driver_t *driver, apr_pool_t *pool, apr_dbd_t *handle, int *nrows, apr_dbd_prepared_t *statement, int nargs, const char **args)
int	apr_dbd_pselect (const apr_dbd_driver_t *driver, apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res, apr_dbd_prepared_t *statement, int random, int nargs, const char **args)
int	apr_dbd_pvquery (const apr_dbd_driver_t *driver, apr_pool_t *pool, apr_dbd_t *handle, int *nrows, apr_dbd_prepared_t *statement,...)
int	apr_dbd_pvselect (const apr_dbd_driver_t *driver, apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res, apr_dbd_prepared_t *statement, int random,...)

---

Function Documentation

int apr_dbd_check_conn	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		apr_dbd_t *	handle
	)

check_conn: check status of a database connection

Parameters:

	driver	- the driver
	pool	- working pool
	handle	- the connection to check

Returns:

APR_SUCCESS or error

apr_status_t apr_dbd_close	(	const apr_dbd_driver_t *	driver,
		apr_dbd_t *	handle
	)

apr_dbd_close: close a connection to a backend. Only required for explicit close or

Parameters:

	handle	- handle to close
	driver	- driver struct.

Returns:

APR_SUCCESS for success or error status

const char* apr_dbd_error	(	const apr_dbd_driver_t *	driver,
		apr_dbd_t *	handle,
		int	errnum
	)

apr_dbd_error: get current error message (if any)

Parameters:

	driver	- the driver
	handle	- the connection
	errnum	- error code from operation that returned an error

Returns:

the database current error message, or message for errnum (implementation-dependent whether errnum is ignored)

const char* apr_dbd_escape	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		const char *	string,
		apr_dbd_t *	handle
	)

apr_dbd_escape: escape a string so it is safe for use in query/select

Parameters:

	driver	- the driver
	pool	- pool to alloc the result from
	string	- the string to escape
	handle	- the connection

Returns:

the escaped, safe string

apr_status_t apr_dbd_get_driver	(	apr_pool_t *	pool,
		const char *	name,
		const apr_dbd_driver_t **	driver
	)

apr_dbd_get_driver: get the driver struct for a name

Parameters:

	pool	- (process) pool to register cleanup
	name	- driver name
	driver	- pointer to driver struct.

Returns:

APR_SUCCESS for success

APR_ENOTIMPL for no driver (when DSO not enabled)

APR_EDSOOPEN if DSO driver file can't be opened

APR_ESYMNOTFOUND if the driver file doesn't contain a driver

const char* apr_dbd_get_entry	(	const apr_dbd_driver_t *	driver,
		apr_dbd_row_t *	row,
		int	col
	)

apr_dbd_get_entry: get an entry from a row

Parameters:

	driver	- the driver
	row	- row pointer
	col	- entry number

Returns:

value from the row, or NULL if col is out of bounds.

int apr_dbd_get_row	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		apr_dbd_results_t *	res,
		apr_dbd_row_t **	row,
		int	rownum
	)

apr_dbd_get_row: get a row from a result set

Parameters:

	driver	- the driver
	pool	- pool to allocate the row
	res	- result set pointer
	row	- pointer to row pointer. May point to NULL on entry
	rownum	- row number, or -1 for "next row". Ignored if random access is not supported.

Returns:

0 for success, -1 for rownum out of range or data finished

apr_status_t apr_dbd_init

(

apr_pool_t *

pool

)

apr_dbd_init: perform once-only initialisation. Call once only.

Parameters:

pool

- pool to register any shutdown cleanups, etc

const char* apr_dbd_name

(

const apr_dbd_driver_t *

driver

)

apr_dbd_name: get the name of the driver

Parameters:

driver

- the driver

Returns:

- name

void* apr_dbd_native_handle	(	const apr_dbd_driver_t *	driver,
		apr_dbd_t *	handle
	)

apr_dbd_native_handle: get native database handle of the underlying db

Parameters:

	driver	- the driver
	handle	- apr_dbd handle

Returns:

- native handle

int apr_dbd_num_cols	(	const apr_dbd_driver_t *	driver,
		apr_dbd_results_t *	res
	)

apr_dbd_num_cols: get the number of columns in a results set

Parameters:

	driver	- the driver
	res	- result set.

Returns:

number of columns

int apr_dbd_num_tuples	(	const apr_dbd_driver_t *	driver,
		apr_dbd_results_t *	res
	)

apr_dbd_num_tuples: get the number of rows in a results set of a synchronous select

Parameters:

	driver	- the driver
	res	- result set.

Returns:

number of rows, or -1 if the results are asynchronous

apr_status_t apr_dbd_open	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	ptmp,
		const char *	params,
		apr_dbd_t **	handle
	)

apr_dbd_open: open a connection to a backend

Parameters:

	ptmp	- working pool
	params	- arguments to driver (implementation-dependent)
	handle	- pointer to handle to return
	driver	- driver struct.

Returns:

APR_SUCCESS for success

APR_EGENERAL if driver exists but connection failed

int apr_dbd_pquery	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		apr_dbd_t *	handle,
		int *	nrows,
		apr_dbd_prepared_t *	statement,
		int	nargs,
		const char **	args
	)

apr_dbd_pquery: query using a prepared statement + args

Parameters:

	driver	- the driver
	pool	- working pool
	handle	- the connection
	nrows	- number of rows affected.
	statement	- the prepared statement to execute
	nargs	- number of args to prepared statement
	args	- args to prepared statement

Returns:

0 for success or error code

int apr_dbd_prepare	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		apr_dbd_t *	handle,
		const char *	query,
		const char *	label,
		apr_dbd_prepared_t **	statement
	)

apr_dbd_prepare: prepare a statement

Parameters:

	driver	- the driver
	pool	- pool to alloc the result from
	handle	- the connection
	query	- the SQL query
	label	- A label for the prepared statement. use NULL for temporary prepared statements (eg within a Request in httpd)
	statement	- statement to prepare. May point to null on entry.

Returns:

0 for success or error code

int apr_dbd_pselect	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		apr_dbd_t *	handle,
		apr_dbd_results_t **	res,
		apr_dbd_prepared_t *	statement,
		int	random,
		int	nargs,
		const char **	args
	)

apr_dbd_pselect: select using a prepared statement + args

Parameters:

	driver	- the driver
	pool	- working pool
	handle	- the connection
	res	- pointer to query results. May point to NULL on entry
	statement	- the prepared statement to execute
	random	- Whether to support random-access to results
	nargs	- number of args to prepared statement
	args	- args to prepared statement

Returns:

0 for success or error code

int apr_dbd_pvquery	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		apr_dbd_t *	handle,
		int *	nrows,
		apr_dbd_prepared_t *	statement,
			...
	)

apr_dbd_pvquery: query using a prepared statement + args

Parameters:

	driver	- the driver
	pool	- working pool
	handle	- the connection
	nrows	- number of rows affected.
	statement	- the prepared statement to execute
	...	- varargs list

Returns:

0 for success or error code

int apr_dbd_pvselect	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		apr_dbd_t *	handle,
		apr_dbd_results_t **	res,
		apr_dbd_prepared_t *	statement,
		int	random,
			...
	)

apr_dbd_pvselect: select using a prepared statement + args

Parameters:

	driver	- the driver
	pool	- working pool
	handle	- the connection
	res	- pointer to query results. May point to NULL on entry
	statement	- the prepared statement to execute
	random	- Whether to support random-access to results
	...	- varargs list

Returns:

0 for success or error code

int apr_dbd_query	(	const apr_dbd_driver_t *	driver,
		apr_dbd_t *	handle,
		int *	nrows,
		const char *	statement
	)

apr_dbd_query: execute an SQL query that doesn't return a result set

Parameters:

	driver	- the driver
	handle	- the connection
	nrows	- number of rows affected.
	statement	- the SQL statement to execute

Returns:

0 for success or error code

int apr_dbd_select	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		apr_dbd_t *	handle,
		apr_dbd_results_t **	res,
		const char *	statement,
		int	random
	)

apr_dbd_select: execute an SQL query that returns a result set

Parameters:

	driver	- the driver
	pool	- pool to allocate the result set
	handle	- the connection
	res	- pointer to result set pointer. May point to NULL on entry
	statement	- the SQL statement to execute
	random	- 1 to support random access to results (seek any row); 0 to support only looping through results in order (async access - faster)

Returns:

0 for success or error code

int apr_dbd_set_dbname	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		apr_dbd_t *	handle,
		const char *	name
	)

apr_dbd_set_dbname: select database name. May be a no-op if not supported.

Parameters:

	driver	- the driver
	pool	- working pool
	handle	- the connection
	name	- the database to select

Returns:

0 for success or error code

int apr_dbd_transaction_end	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		apr_dbd_transaction_t *	trans
	)

apr_dbd_transaction_end: end a transaction (commit on success, rollback on error). May be a no-op.

Parameters:

	driver	- the driver
	handle	- the db connection
	transaction	- the transaction.

Returns:

0 for success or error code

int apr_dbd_transaction_start	(	const apr_dbd_driver_t *	driver,
		apr_pool_t *	pool,
		apr_dbd_t *	handle,
		apr_dbd_transaction_t **	trans
	)

apr_dbd_transaction_start: start a transaction. May be a no-op.

Parameters:

	driver	- the driver
	pool	- a pool to use for error messages (if any).
	handle	- the db connection
	transaction	- ptr to a transaction. May be null on entry

Returns:

0 for success or error code

---