All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
DBI.h File Reference

### (5431)

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

## Macros

#define | DBI_CAP_NONE 0
| no capabilities
#define | DBI_CAP_TIME_ZONE_SUPPORT (1 << 0)
| supports time zones in date/time values
#define | DBI_CAP_CHARSET_SUPPORT (1 << 1)
| support tagging/converting character encoding in strings
#define | DBI_CAP_TRANSACTION_MANAGEMENT (1 << 2)
| supports transaction management (commit/rollback)
#define | DBI_CAP_STORED_PROCEDURES (1 << 3)
| supports calling stored procedures/functions
#define | DBI_CAP_LOB_SUPPORT (1 << 4)
| supports large objects in binding and retrieving
#define | DBI_CAP_BIND_BY_VALUE (1 << 5)
| supports bind by value
#define | DBI_CAP_BIND_BY_PLACEHOLDER (1 << 6)
| supports or requires placeholder buffer specifications for output variables
#define | DBI_CAP_HAS_EXECRAW (1 << 7)
| provides the Datasource*::execRaw() 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_HAS_SELECT_ROW (1 << 9)
| provides a native selectRow() 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 QoreFloatNode 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_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_AUTORECONNECT (1 << 13)
| supports automatically/transparently reconnecting to the server if the connection is lost while not in a transaction
#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_NUMBER_NUMERIC "numeric-numbers"
| numeric/decimal/number values converted to arbitrary-precision number values
#define | DBI_OPT_TIMEZONE "timezone"
| set server=side timezone rules for automatic conversions/date-time value tagging

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