include/qore/DBI.h File Reference

(4311)

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

Go to the source code of this file.

Classes
class	qore_dbi_method_list
	this is the data structure Qore DBI drivers will use to pass the supported DBI methods More...
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...
Typedefs
typedef int(*	q_dbi_open_t )(Datasource *ds, ExceptionSink *xsink)
	signature for the DBI "open" method - must be defined in each DBI driver
typedef int(*	q_dbi_close_t )(Datasource *ds)
	signature for the DBI "close" method - must be defined in each DBI driver
typedef AbstractQoreNode *(*	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
typedef AbstractQoreNode *(*	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
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
typedef AbstractQoreNode *(*	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
typedef AbstractQoreNode *(*	q_dbi_execraw_t )(Datasource *ds, const QoreString *str, ExceptionSink *xsink)
	signature for the DBI "execRawSQL" method - must be defined in each DBI driver
typedef int(*	q_dbi_commit_t )(Datasource *ds, ExceptionSink *xsink)
	signature for the DBI "commit" method - must be defined in each DBI driver
typedef int(*	q_dbi_rollback_t )(Datasource *ds, ExceptionSink *xsink)
	signature for the DBI "rollback" method - must be defined in each DBI driver
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
typedef int(*	q_dbi_abort_transaction_start_t )(Datasource *ds, ExceptionSink *xsink)
	signature for the rollback method to be executed when the first statement in an explicit transaction started implicitly with the DBI "begin_transaction" method fails
typedef AbstractQoreNode *(*	q_dbi_get_server_version_t )(Datasource *ds, ExceptionSink *xsink)
	signature for the "get_server_version" method
typedef AbstractQoreNode *(*	q_dbi_get_client_version_t )(const Datasource *ds, ExceptionSink *xsink)
	signature for the "get_client_version" method
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
typedef int(*	q_dbi_stmt_prepare_raw_t )(SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink)
	prepare statement with no bind parsing
typedef int(*	q_dbi_stmt_bind_t )(SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink)
	bind input values and optionally describe output parameters
typedef int(*	q_dbi_stmt_exec_t )(SQLStatement *stmt, ExceptionSink *xsink)
	execute statement
typedef int(*	q_dbi_stmt_affected_rows_t )(SQLStatement *stmt, ExceptionSink *xsink)
	get number of affected rows
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
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
Functions
DLLEXPORT QoreHashNode *	parseDatasource (const char *ds, ExceptionSink *xsink)
	parses a datasource string and returns a hash of the component parts
DLLEXPORT void	DBI_concat_numeric (QoreString *str, const AbstractQoreNode *v)
	concatenates a numeric value to the QoreString from the QoreNode
DLLEXPORT int	DBI_concat_string (QoreString *str, const AbstractQoreNode *v, ExceptionSink *xsink)
	concatenates a string value to the QoreString from the AbstractQoreNode
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

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

signature for the rollback method to be executed when the first statement in an explicit transaction started implicitly with the DBI "begin_transaction" method fails

this should just be a pointer to the rollback method for those drivers that need it (ex: pgsql)

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

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

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

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

typedef AbstractQoreNode*(* 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

typedef AbstractQoreNode*(* 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

typedef AbstractQoreNode*(* 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

typedef AbstractQoreNode*(* 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

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

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

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

typedef AbstractQoreNode*(* 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

typedef AbstractQoreNode*(* 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

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

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

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

execute statement

Returns:

-1 = an exception occurred, 0 = OK

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

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

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

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

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

concatenates a string value to the QoreString from the AbstractQoreNode

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