DBI.h File Reference

describes Qore's DBI interface for writing database drivers More...

#include <string>

Include dependency graph for DBI.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	DBIDriver
	this class provides the internal link to the database driver for Qore's DBI layer More...
class	DBIDriverList
	this class is used to register and find DBI drivers loaded in qore More...
class	qore_dbi_method_list
	this is the data structure Qore DBI drivers will use to pass the supported DBI methods More...

Macros
#define	DBI_CAP_AUTORECONNECT   (1 << 13)
	supports automatically/transparently reconnecting to the server if the connection is lost while not in a transaction
#define	DBI_CAP_BIND_BY_PLACEHOLDER   (1 << 6)
	supports or requires placeholder buffer specifications for output variables
#define	DBI_CAP_BIND_BY_VALUE   (1 << 5)
	supports bind by value
#define	DBI_CAP_CHARSET_SUPPORT   (1 << 1)
	support tagging/converting character encoding in strings
#define	DBI_CAP_EVENTS   (1 << 14)
	supports DBI events
#define	DBI_CAP_HAS_ARRAY_BIND   (1 << 16)
	supports binding arrays by value for bulk DML operations
#define	DBI_CAP_HAS_DESCRIBE   (1 << 15)
	supports the describe API
#define	DBI_CAP_HAS_EXECRAW   (1 << 7)
	provides the Datasource::execRaw() method (set automatically by the Qore library)
#define	DBI_CAP_HAS_NUMBER_SUPPORT   (1 << 10)
	supports arbitrary-precision numeric support for binding and retrieving values; if this is not true then any QoreNumberNode bind arguments will be converted to floats before binding
#define	DBI_CAP_HAS_OPTION_SUPPORT   (1 << 11)
	supports the new driver option API (set automatically by the Qore library)
#define	DBI_CAP_HAS_RESULTSET_OUTPUT   (1 << 17)
	supports the "resultset" placeholder buffer specification
#define	DBI_CAP_HAS_SELECT_ROW   (1 << 9)
	provides a native selectRow() method (set automatically by the Qore library)
#define	DBI_CAP_HAS_STATEMENT   (1 << 8)
	supports the SQLStatement class (set automatically by the Qore library)
#define	DBI_CAP_LOB_SUPPORT   (1 << 4)
	supports large objects in binding and retrieving
#define	DBI_CAP_NONE   0
	no capabilities
#define	DBI_CAP_OPTION_PASSTHRU   (1 << 18)
	supports all options; all options are passed through to the driver
#define	DBI_CAP_SERVER_TIME_ZONE   (1 << 12)
	supports automatically converting date/time values to the server's presumed time zone (can be set with options) and tagging date/time values with the same; this is independent from the client's current time zone setting
#define	DBI_CAP_STORED_PROCEDURES   (1 << 3)
	supports calling stored procedures/functions
#define	DBI_CAP_TIME_ZONE_SUPPORT   (1 << 0)
	supports time zones in date/time values
#define	DBI_CAP_TRANSACTION_MANAGEMENT   (1 << 2)
	supports transaction management (commit/rollback)
#define	DBI_OPT_NUMBER_NUMERIC   "numeric-numbers"
	numeric/decimal/number values converted to arbitrary-precision number values
#define	DBI_OPT_NUMBER_OPT   "optimal-numbers"
	numeric/decimal/number values converted to optimal Qore type (either int or number)
#define	DBI_OPT_NUMBER_STRING   "string-numbers"
	numeric/decimal/number values converted to Qore strings (original solution)
#define	DBI_OPT_TIMEZONE   "timezone"
	set server=side timezone rules for automatic conversions/date-time value tagging

Typedefs
typedef int(*	q_dbi_begin_transaction_t) (Datasource *ds, ExceptionSink *xsink)
	signature for the DBI "begin_transaction" method, should only be defined for drivers needing this to explicitly start a transaction More...
typedef int(*	q_dbi_close_t) (Datasource *ds)
	signature for the DBI "close" method - must be defined in each DBI driver More...
typedef int(*	q_dbi_commit_t) (Datasource *ds, ExceptionSink *xsink)
	signature for the DBI "commit" method - must be defined in each DBI driver More...
typedef QoreHashNode *(*	q_dbi_describe_t) (Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)
	signature for the DBI "describe" method More...
typedef QoreValue(*	q_dbi_exec_t) (Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)
	signature for the DBI "execSQL" method - must be defined in each DBI driver More...
typedef QoreValue(*	q_dbi_execraw_t) (Datasource *ds, const QoreString *str, ExceptionSink *xsink)
	signature for the DBI "execRawSQL" method - must be defined in each DBI driver More...
typedef QoreValue(*	q_dbi_get_client_version_t) (const Datasource *ds, ExceptionSink *xsink)
	signature for the "get_client_version" method More...
typedef QoreStringNode *(*	q_dbi_get_driver_real_name_t) (Datasource *ds, ExceptionSink *xsink)
	signature for the "get_driver_real_name" method More...
typedef QoreValue(*	q_dbi_get_server_version_t) (Datasource *ds, ExceptionSink *xsink)
	signature for the "get_server_version" method More...
typedef int(*	q_dbi_open_t) (Datasource *ds, ExceptionSink *xsink)
	signature for the DBI "open" method - must be defined in each DBI driver More...
typedef int(*	q_dbi_rollback_t) (Datasource *ds, ExceptionSink *xsink)
	signature for the DBI "rollback" method - must be defined in each DBI driver More...
typedef QoreHashNode *(*	q_dbi_select_row_t) (Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)
	signature for the DBI "selectRow" method - must be defined in each DBI driver More...
typedef QoreValue(*	q_dbi_select_rows_t) (Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)
	signature for the DBI "selectRows" method - must be defined in each DBI driver More...
typedef QoreValue(*	q_dbi_select_t) (Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)
	signature for the DBI "select" method - must be defined in each DBI driver More...
typedef int(*	q_dbi_stmt_affected_rows_t) (SQLStatement *stmt, ExceptionSink *xsink)
	get number of affected rows More...
typedef int(*	q_dbi_stmt_bind_t) (SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink)
	bind input values and optionally describe output parameters More...
typedef int(*	q_dbi_stmt_exec_t) (SQLStatement *stmt, ExceptionSink *xsink)
	execute statement More...
typedef QoreHashNode *(*	q_dbi_stmt_get_output_rows_t) (SQLStatement *stmt, ExceptionSink *xsink)
	get output values, any row sets are returned as a list of hashes More...
typedef QoreHashNode *(*	q_dbi_stmt_get_output_t) (SQLStatement *stmt, ExceptionSink *xsink)
	get output values, any row sets are returned as a hash of lists More...
typedef int(*	q_dbi_stmt_prepare_raw_t) (SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink)
	prepare statement with no bind parsing More...
typedef int(*	q_dbi_stmt_prepare_t) (SQLStatement *stmt, const QoreString &str, const QoreListNode *args, ExceptionSink *xsink)
	prepare statement and process placeholder specifications and bind parameters More...

Functions
DLLEXPORT void	DBI_concat_numeric (QoreString *str, QoreValue v)
	concatenates a numeric value to the QoreString from the value
DLLEXPORT int	DBI_concat_string (QoreString *str, QoreValue v, ExceptionSink *xsink)
	concatenates a string value to the QoreString from the value More...
DLLEXPORT QoreHashNode *	parseDatasource (const char *ds, ExceptionSink *xsink)
	parses a datasource string and returns a hash of the component parts

Variables
DLLEXPORT DBIDriverList	DBI
	list of DBI drivers currently reigsted by the Qore library

Detailed Description

describes Qore's DBI interface for writing database drivers

Typedef Documentation

q_dbi_begin_transaction_t

typedef int(* q_dbi_begin_transaction_t) (Datasource *ds, ExceptionSink *xsink)

signature for the DBI "begin_transaction" method, should only be defined for drivers needing this to explicitly start a transaction

Parameters

ds	the Datasource for the connection
xsink	if any errors occur, error information should be added to this object

Returns

0 for OK, non-zero for error

q_dbi_close_t

typedef int(* q_dbi_close_t) (Datasource *ds)

signature for the DBI "close" method - must be defined in each DBI driver

this function cannot throw an exception and currently any return error code is ignored

Parameters

ds	the Datasource for the connection to close

Returns

0 for OK, non-zero for error

q_dbi_commit_t

typedef int(* q_dbi_commit_t) (Datasource *ds, ExceptionSink *xsink)

signature for the DBI "commit" method - must be defined in each DBI driver

Parameters

ds	the Datasource for the connection
xsink	if any errors occur, error information should be added to this object

Returns

0 for OK, non-zero for error

q_dbi_describe_t

typedef QoreHashNode *(* q_dbi_describe_t) (Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)

signature for the DBI "describe" method

Parameters

ds	the Datasource for the connection
str	the SQL string to execute, may not be in the encoding of the Datasource, must return a result set to be described
args	arguments for placeholders or DBI formatting codes in the SQL string
xsink	if any errors occur, error information should be added to this object

Returns

the data returned by executing the SQL or 0

q_dbi_exec_t

typedef QoreValue(* q_dbi_exec_t) (Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)

signature for the DBI "execSQL" method - must be defined in each DBI driver

Parameters

ds	the Datasource for the connection
str	the SQL string to execute, may not be in the encoding of the Datasource
args	arguments for placeholders or DBI formatting codes in the SQL string
xsink	if any errors occur, error information should be added to this object

Returns

the data returned by executing the SQL or 0

q_dbi_execraw_t

typedef QoreValue(* q_dbi_execraw_t) (Datasource *ds, const QoreString *str, ExceptionSink *xsink)

signature for the DBI "execRawSQL" method - must be defined in each DBI driver

Parameters

ds	the Datasource for the connection
str	the SQL string to execute, may not be in the encoding of the Datasource
xsink	if any errors occur, error information should be added to this object

Returns

the data returned by executing the SQL or 0

q_dbi_get_client_version_t

typedef QoreValue(* q_dbi_get_client_version_t) (const Datasource *ds, ExceptionSink *xsink)

signature for the "get_client_version" method

Parameters

ds	the Datasource for the connection
xsink	if any errors occur, error information should be added to this object

Returns

a value describing the client's version

q_dbi_get_driver_real_name_t

typedef QoreStringNode *(* q_dbi_get_driver_real_name_t) (Datasource *ds, ExceptionSink *xsink)

signature for the "get_driver_real_name" method

Parameters

ds	the Datasource for the connection
xsink	if any errors occur, error information should be added to this object

Returns

a value describing the database name

q_dbi_get_server_version_t

typedef QoreValue(* q_dbi_get_server_version_t) (Datasource *ds, ExceptionSink *xsink)

signature for the "get_server_version" method

Parameters

ds	the Datasource for the connection
xsink	if any errors occur, error information should be added to this object

Returns

a value describing the server's version

q_dbi_open_t

typedef int(* q_dbi_open_t) (Datasource *ds, ExceptionSink *xsink)

signature for the DBI "open" method - must be defined in each DBI driver

Parameters

ds	the Datasource for the connection
xsink	if any errors occur, error information should be added to this object

Returns

0 for OK, non-zero for error

q_dbi_rollback_t

typedef int(* q_dbi_rollback_t) (Datasource *ds, ExceptionSink *xsink)

signature for the DBI "rollback" method - must be defined in each DBI driver

Parameters

ds	the Datasource for the connection
xsink	if any errors occur, error information should be added to this object

Returns

0 for OK, non-zero for error

q_dbi_select_row_t

typedef QoreHashNode *(* q_dbi_select_row_t) (Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)

signature for the DBI "selectRow" method - must be defined in each DBI driver

if the SQL causes more than 1 row to be returned, then the driver must raise an exception

Parameters

ds	the Datasource for the connection
str	the SQL string to execute, may not be in the encoding of the Datasource; must cause at most one row to be returned
args	arguments for placeholders or DBI formatting codes in the SQL string
xsink	if any errors occur, error information should be added to this object

Returns

the row data returned by executing the SQL or 0

Since

qore 0.8.2

q_dbi_select_rows_t

typedef QoreValue(* q_dbi_select_rows_t) (Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)

signature for the DBI "selectRows" method - must be defined in each DBI driver

Parameters

ds	the Datasource for the connection
str	the SQL string to execute, may not be in the encoding of the Datasource
args	arguments for placeholders or DBI formatting codes in the SQL string
xsink	if any errors occur, error information should be added to this object

Returns

the data returned by executing the SQL or 0

q_dbi_select_t

typedef QoreValue(* q_dbi_select_t) (Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)

signature for the DBI "select" method - must be defined in each DBI driver

Parameters

ds	the Datasource for the connection
str	the SQL string to execute, may not be in the encoding of the Datasource
args	arguments for placeholders or DBI formatting codes in the SQL string
xsink	if any errors occur, error information should be added to this object

Returns

the data returned by executing the SQL or 0

q_dbi_stmt_affected_rows_t

typedef int(* q_dbi_stmt_affected_rows_t) (SQLStatement *stmt, ExceptionSink *xsink)

get number of affected rows

Returns

number of rows affected by last query

q_dbi_stmt_bind_t

typedef int(* q_dbi_stmt_bind_t) (SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink)

bind input values and optionally describe output parameters

Returns

-1 = an exception occurred, 0 = OK

q_dbi_stmt_exec_t

typedef int(* q_dbi_stmt_exec_t) (SQLStatement *stmt, ExceptionSink *xsink)

execute statement

Returns

-1 = an exception occurred, 0 = OK

q_dbi_stmt_get_output_rows_t

typedef QoreHashNode *(* q_dbi_stmt_get_output_rows_t) (SQLStatement *stmt, ExceptionSink *xsink)

get output values, any row sets are returned as a list of hashes

Returns

a hash of output values, any row sets are returned as a list of hashes

q_dbi_stmt_get_output_t

typedef QoreHashNode *(* q_dbi_stmt_get_output_t) (SQLStatement *stmt, ExceptionSink *xsink)

get output values, any row sets are returned as a hash of lists

Returns

a hash of output values, any row sets are returned as a hash of lists

q_dbi_stmt_prepare_raw_t

typedef int(* q_dbi_stmt_prepare_raw_t) (SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink)

prepare statement with no bind parsing

Returns

-1 = an exception occurred, 0 = OK

q_dbi_stmt_prepare_t

typedef int(* q_dbi_stmt_prepare_t) (SQLStatement *stmt, const QoreString &str, const QoreListNode *args, ExceptionSink *xsink)

prepare statement and process placeholder specifications and bind parameters

Returns

-1 = an exception occurred, 0 = OK

Function Documentation

DBI_concat_string()

DLLEXPORT int DBI_concat_string	(	QoreString *	str,
		QoreValue	v,
		ExceptionSink *	xsink
	)

concatenates a string value to the QoreString from the value

NOTE: no escaping is done here this function is most useful for table prefixes, etc in queries