Loading...
Searching...
No Matches
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_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 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_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