Qore Programming Language  0.9.0
DBI.h File Reference

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

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_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 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 QoreHashNodeparseDatasource (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
dsthe Datasource for the connection
xsinkif 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
dsthe 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
dsthe Datasource for the connection
xsinkif 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
dsthe Datasource for the connection
strthe SQL string to execute, may not be in the encoding of the Datasource, must return a result set to be described
argsarguments for placeholders or DBI formatting codes in the SQL string
xsinkif 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
dsthe Datasource for the connection
strthe SQL string to execute, may not be in the encoding of the Datasource
argsarguments for placeholders or DBI formatting codes in the SQL string
xsinkif 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
dsthe Datasource for the connection
strthe SQL string to execute, may not be in the encoding of the Datasource
xsinkif 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
dsthe Datasource for the connection
xsinkif any errors occur, error information should be added to this object
Returns
a value describing the client's version

◆ 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
dsthe Datasource for the connection
xsinkif 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
dsthe Datasource for the connection
xsinkif 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
dsthe Datasource for the connection
xsinkif 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
dsthe Datasource for the connection
strthe SQL string to execute, may not be in the encoding of the Datasource; must cause at most one row to be returned
argsarguments for placeholders or DBI formatting codes in the SQL string
xsinkif 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
dsthe Datasource for the connection
strthe SQL string to execute, may not be in the encoding of the Datasource
argsarguments for placeholders or DBI formatting codes in the SQL string
xsinkif 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
dsthe Datasource for the connection
strthe SQL string to execute, may not be in the encoding of the Datasource
argsarguments for placeholders or DBI formatting codes in the SQL string
xsinkif 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