Apache Portable Runtime Utility Library: DBD routines

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

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 *	pool,
		const char *	params,
		apr_dbd_t **	handle
	)

apr_dbd_open: open a connection to a backend

Parameters:

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

Remarks:

PostgreSQL: the params is passed directly to the PQconnectdb() function (check PostgreSQL documentation for more details on the syntax).

SQLite2: the params is split on a colon, with the first part used as the filename and second part converted to an integer and used as file mode.

SQLite3: the params is passed directly to the sqlite3_open() function as a filename to be opened (check SQLite3 documentation for more details).

MySQL: the params can have "host", "port", "user", "pass", "dbname", "sock", "flags" "fldsz" and "group" keys, each followed by an equal sign and a value. Such key/value pairs can be delimited by space, CR, LF, tab, semicolon, vertical bar or comma. For now, "flags" can only recognise CLIENT_FOUND_ROWS (check MySQL manual for details). The value associated with "fldsz" determines maximum amount of memory (in bytes) for each of the fields in the result set of prepared statements. By default, this value is 1 MB. The value associated with "group" determines which group from configuration file to use (see MYSQL_READ_DEFAULT_GROUP option of mysql_options() in MySQL manual).

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

Remarks:: To specify parameters of the prepared query, use s in place of database specific parameter syntax (e.g. for PostgreSQL, this would be $1, $2, for SQLite3 this would be ? etc.). For instance: "SELECT name FROM customers WHERE name=s" would be a query that this function understands. Some drivers may support different data types using printf-like format: for example d (e.g. PostgreSQL) or f for numeric data.

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
	trans	- 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
	trans	- ptr to a transaction. May be null on entry

Returns:: 0 for success or error code

Remarks:: If any of the query/select calls during a transaction return non-zero status code, the transaction will inherit this code and any further query/select calls will fail immediately.


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 pool, 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,...)

DBD routines
[APR Utility Functions]

Typedefs

Functions

Function Documentation

DBD routines [APR Utility Functions]

Typedefs

Functions

Function Documentation

DBD routines
[APR Utility Functions]