Qore Programming Language  0.8.11
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
DBI.h
Go to the documentation of this file.
1 /* -*- mode: c++; indent-tabs-mode: nil -*- */
2 /*
3  DBI.h
4 
5  Qore Programming Language
6 
7  Copyright 2003 - 2014 David Nichols
8 
9  This library is free software; you can redistribute it and/or
10  modify it under the terms of the GNU Lesser General Public
11  License as published by the Free Software Foundation; either
12  version 2.1 of the License, or (at your option) any later version.
13 
14  This library is distributed in the hope that it will be useful,
15  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17  Lesser General Public License for more details.
18 
19  You should have received a copy of the GNU Lesser General Public
20  License along with this library; if not, write to the Free Software
21  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23 
24 #ifndef _QORE_DBI_H
25 #define _QORE_DBI_H
26 
28 
29 // DBI Driver capabilities
30 #define DBI_CAP_NONE 0
31 #define DBI_CAP_TIME_ZONE_SUPPORT (1 << 0)
32 #define DBI_CAP_CHARSET_SUPPORT (1 << 1)
33 #define DBI_CAP_TRANSACTION_MANAGEMENT (1 << 2)
34 #define DBI_CAP_STORED_PROCEDURES (1 << 3)
35 #define DBI_CAP_LOB_SUPPORT (1 << 4)
36 #define DBI_CAP_BIND_BY_VALUE (1 << 5)
37 #define DBI_CAP_BIND_BY_PLACEHOLDER (1 << 6)
38 #define DBI_CAP_HAS_EXECRAW (1 << 7)
39 #define DBI_CAP_HAS_STATEMENT (1 << 8)
40 #define DBI_CAP_HAS_SELECT_ROW (1 << 9)
41 #define DBI_CAP_HAS_NUMBER_SUPPORT (1 << 10)
42 #define DBI_CAP_HAS_OPTION_SUPPORT (1 << 11)
43 #define DBI_CAP_SERVER_TIME_ZONE (1 << 12)
44 #define DBI_CAP_AUTORECONNECT (1 << 13)
45 #define DBI_CAP_EVENTS (1 << 14)
46 #define DBI_CAP_HAS_DESCRIBE (1 << 15)
47 
48 #define BN_PLACEHOLDER 0
49 #define BN_VALUE 1
50 
51 #define DBI_DEFAULT_STR_LEN 512
52 
53 // DBI method codes
54 #define QDBI_METHOD_OPEN 1
55 #define QDBI_METHOD_CLOSE 2
56 #define QDBI_METHOD_SELECT 3
57 #define QDBI_METHOD_SELECT_ROWS 4
58 #define QDBI_METHOD_EXEC 5
59 #define QDBI_METHOD_COMMIT 6
60 #define QDBI_METHOD_ROLLBACK 7
61 #define QDBI_METHOD_BEGIN_TRANSACTION 8
62 #define QDBI_METHOD_ABORT_TRANSACTION_START 9
63 #define QDBI_METHOD_GET_SERVER_VERSION 10
64 #define QDBI_METHOD_GET_CLIENT_VERSION 11
65 #define QDBI_METHOD_EXECRAW 12
66 #define QDBI_METHOD_STMT_PREPARE 13
67 #define QDBI_METHOD_STMT_PREPARE_RAW 14
68 #define QDBI_METHOD_STMT_BIND 15
69 #define QDBI_METHOD_STMT_BIND_PLACEHOLDERS 16
70 #define QDBI_METHOD_STMT_BIND_VALUES 17
71 #define QDBI_METHOD_STMT_EXEC 18
72 #define QDBI_METHOD_STMT_FETCH_ROW 19
73 #define QDBI_METHOD_STMT_FETCH_ROWS 20
74 #define QDBI_METHOD_STMT_FETCH_COLUMNS 21
75 #define QDBI_METHOD_STMT_NEXT 22
76 #define QDBI_METHOD_STMT_CLOSE 23
77 #define QDBI_METHOD_STMT_AFFECTED_ROWS 24
78 #define QDBI_METHOD_STMT_GET_OUTPUT 25
79 #define QDBI_METHOD_STMT_GET_OUTPUT_ROWS 26
80 #define QDBI_METHOD_STMT_DEFINE 27
81 #define QDBI_METHOD_SELECT_ROW 28
82 #define QDBI_METHOD_OPT_SET 29
83 #define QDBI_METHOD_OPT_GET 30
84 #define QDBI_METHOD_STMT_DESCRIBE 31
85 #define QDBI_METHOD_DESCRIBE 32
86 
87 #define QDBI_VALID_CODES 32
88 
89 /* DBI EVENT Types
90  all DBI events must have the following keys:
91  - user: db username (if available)
92  - db: db name (if available)
93  - eventtype: integer event code
94 */
95 // warning events have the following additional keys: warning, desc, [info]
96 #define QDBI_EVENT_WARNING 1
97 
98 class Datasource;
99 class ExceptionSink;
100 class QoreString;
101 class QoreListNode;
102 class AbstractQoreNode;
103 class QoreHashNode;
104 class QoreNamespace;
105 class SQLStatement;
106 
107 // DBI method signatures - note that only get_client_version uses a "const Datasource"
108 // the others do not so that automatic reconnects can be supported (which will normally
109 // require writing to the Datasource)
110 
112 
116 typedef int (*q_dbi_open_t)(Datasource* ds, ExceptionSink* xsink);
117 
119 
123 typedef int (*q_dbi_close_t)(Datasource* ds);
124 
126 
133 typedef AbstractQoreNode* (*q_dbi_select_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
134 
136 
143 typedef AbstractQoreNode* (*q_dbi_select_rows_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
144 
146 
154 typedef QoreHashNode* (*q_dbi_select_row_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
155 
157 
164 typedef AbstractQoreNode* (*q_dbi_exec_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
165 
167 
173 typedef AbstractQoreNode* (*q_dbi_execraw_t)(Datasource* ds, const QoreString* str, ExceptionSink* xsink);
174 
176 
181 typedef int (*q_dbi_commit_t)(Datasource* ds, ExceptionSink* xsink);
182 
184 
189 typedef int (*q_dbi_rollback_t)(Datasource* ds, ExceptionSink* xsink);
190 
192 
198 
200 
206 
208 
213 typedef AbstractQoreNode* (*q_dbi_get_server_version_t)(Datasource* ds, ExceptionSink* xsink);
214 
216 
221 typedef AbstractQoreNode* (*q_dbi_get_client_version_t)(const Datasource* ds, ExceptionSink* xsink);
222 
223 // FIXME: document
225 
227 typedef int (*q_dbi_stmt_prepare_t)(SQLStatement* stmt, const QoreString& str, const QoreListNode* args, ExceptionSink* xsink);
228 
230 
232 typedef int (*q_dbi_stmt_prepare_raw_t)(SQLStatement* stmt, const QoreString& str, ExceptionSink* xsink);
233 
235 
237 typedef int (*q_dbi_stmt_bind_t)(SQLStatement* stmt, const QoreListNode& l, ExceptionSink* xsink);
238 
240 
242 typedef int (*q_dbi_stmt_exec_t)(SQLStatement* stmt, ExceptionSink* xsink);
243 
245 
248 
250 
252 typedef QoreHashNode* (*q_dbi_stmt_get_output_t)(SQLStatement* stmt, ExceptionSink* xsink);
253 
255 
257 typedef QoreHashNode* (*q_dbi_stmt_get_output_rows_t)(SQLStatement* stmt, ExceptionSink* xsink);
258 
259 typedef int (*q_dbi_stmt_define_t)(SQLStatement* stmt, ExceptionSink* xsink);
260 typedef QoreHashNode* (*q_dbi_stmt_fetch_row_t)(SQLStatement* stmt, ExceptionSink* xsink);
261 typedef QoreHashNode* (*q_dbi_stmt_fetch_columns_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
262 typedef QoreListNode* (*q_dbi_stmt_fetch_rows_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
263 typedef bool (*q_dbi_stmt_next_t)(SQLStatement* stmt, ExceptionSink* xsink);
264 typedef int (*q_dbi_stmt_close_t)(SQLStatement* stmt, ExceptionSink* xsink);
265 
266 typedef int (*q_dbi_option_set_t)(Datasource* ds, const char* opt, const AbstractQoreNode* val, ExceptionSink* xsink);
267 typedef AbstractQoreNode* (*q_dbi_option_get_t)(const Datasource* ds, const char* opt);
268 
270 
277 typedef QoreHashNode* (*q_dbi_describe_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
278 
279 #define DBI_OPT_NUMBER_OPT "optimal-numbers"
280 #define DBI_OPT_NUMBER_STRING "string-numbers"
281 #define DBI_OPT_NUMBER_NUMERIC "numeric-numbers"
282 #define DBI_OPT_TIMEZONE "timezone"
283 
284 
288  friend struct qore_dbi_mlist_private;
289 
290 private:
291  struct qore_dbi_mlist_private* priv; // private implementation
292 
293  // not implemented
295  DLLLOCAL qore_dbi_method_list& operator=(const qore_dbi_method_list&);
296 
297 public:
298  DLLEXPORT qore_dbi_method_list();
299  DLLEXPORT ~qore_dbi_method_list();
300 
301  // covers open, commit, rollback, and begin transaction
302  DLLEXPORT void add(int code, q_dbi_open_t method);
303  // for close
304  DLLEXPORT void add(int code, q_dbi_close_t method);
305  // covers select, select_rows, select, and exec
306  DLLEXPORT void add(int code, q_dbi_select_t method);
307  // covers select_row
308  DLLEXPORT void add(int code, q_dbi_select_row_t method);
309  // covers execRaw
310  DLLEXPORT void add(int code, q_dbi_execraw_t method);
311  // covers get_server_version
312  DLLEXPORT void add(int code, q_dbi_get_server_version_t method);
313  // covers get_client_version
314  DLLEXPORT void add(int code, q_dbi_get_client_version_t method);
315 
316  // covers prepare
317  DLLEXPORT void add(int code, q_dbi_stmt_prepare_t method);
318  // covers prepare_raw
319  DLLEXPORT void add(int code, q_dbi_stmt_prepare_raw_t method);
320  // covers bind, bind_placeholders, bind_values
321  DLLEXPORT void add(int code, q_dbi_stmt_bind_t method);
322  // covers exec, close, affected_rows, and define
323  DLLEXPORT void add(int code, q_dbi_stmt_exec_t method);
324  // covers fetch_row, get_output, and get_output_rows
325  DLLEXPORT void add(int code, q_dbi_stmt_fetch_row_t method);
326  // covers fetch_columns
327  DLLEXPORT void add(int code, q_dbi_stmt_fetch_columns_t method);
328  // covers fetch_rows
329  DLLEXPORT void add(int code, q_dbi_stmt_fetch_rows_t method);
330  // covers next
331  DLLEXPORT void add(int code, q_dbi_stmt_next_t method);
332 
333  // covers set option
334  DLLEXPORT void add(int code, q_dbi_option_set_t method);
335  // covers get option
336  DLLEXPORT void add(int code, q_dbi_option_get_t method);
337 
338  // for registering valid options
339  DLLEXPORT void registerOption(const char* name, const char* desc, const QoreTypeInfo* type = 0);
340 };
341 
343 
348 class DBIDriver {
349  friend struct qore_dbi_private;
350 
351 private:
353  struct qore_dbi_private* priv;
354 
356  DLLLOCAL DBIDriver(const DBIDriver&);
358  DLLLOCAL DBIDriver& operator=(const DBIDriver&);
359 
360 public:
362 
365  DLLEXPORT const char* getName() const;
366 
368  DLLEXPORT bool hasStatementAPI() const;
369 
371 
377  DLLEXPORT QoreHashNode* getOptionHash() const;
378 
379  DLLLOCAL DBIDriver(struct qore_dbi_private* p);
380  DLLLOCAL ~DBIDriver();
381 };
382 
383 struct qore_dbi_dlist_private;
384 
386 
391 private:
393  struct qore_dbi_dlist_private *priv;
394 
395  DLLLOCAL DBIDriver* find_intern(const char* name) const;
396 
397 public:
399 
406  DLLEXPORT DBIDriver* registerDriver(const char* name, const qore_dbi_method_list &methods, int caps);
407 
409 
416  DLLEXPORT DBIDriver* find(const char* name) const;
417 
419 
427  DLLEXPORT DBIDriver* find(const char* name, ExceptionSink* xsink) const;
428 
429  DLLLOCAL DBIDriverList();
430  DLLLOCAL ~DBIDriverList();
431  DLLLOCAL QoreListNode* getDriverList() const;
432 };
433 
435 DLLEXPORT extern DBIDriverList DBI;
436 
438 DLLEXPORT QoreHashNode* parseDatasource(const char* ds, ExceptionSink* xsink);
439 
441 DLLEXPORT void DBI_concat_numeric(QoreString* str, const AbstractQoreNode* v);
442 
444 
447 DLLEXPORT int DBI_concat_string(QoreString* str, const AbstractQoreNode* v, ExceptionSink* xsink);
448 
449 #endif // _QORE_DBI_H
int(* q_dbi_open_t)(Datasource *ds, ExceptionSink *xsink)
signature for the DBI "open" method - must be defined in each DBI driver
Definition: DBI.h:116
AbstractQoreNode *(* q_dbi_get_client_version_t)(const Datasource *ds, ExceptionSink *xsink)
signature for the "get_client_version" method
Definition: DBI.h:221
This is the hash or associative list container type in Qore, dynamically allocated only...
Definition: QoreHashNode.h:41
The base class for all value and parse types in Qore expression trees.
Definition: AbstractQoreNode.h:47
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
Definition: DBI.h:154
contains constants, classes, and subnamespaces in QoreProgram objects
Definition: QoreNamespace.h:50
this class provides the internal link to the database driver for Qore's DBI layer ...
Definition: DBI.h:348
DLLEXPORT bool hasStatementAPI() const
returns true if the driver supports the statement API
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 ...
Definition: DBI.h:205
DLLEXPORT QoreHashNode * getOptionHash() const
returns the valid options for this driver with descriptions
Qore's string type supported by the QoreEncoding class.
Definition: QoreString.h:42
int(* q_dbi_rollback_t)(Datasource *ds, ExceptionSink *xsink)
signature for the DBI "rollback" method - must be defined in each DBI driver
Definition: DBI.h:189
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
Definition: DBI.h:173
int(* q_dbi_stmt_bind_t)(SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink)
bind input values and optionally describe output parameters
Definition: DBI.h:237
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:44
DLLEXPORT DBIDriverList DBI
list of DBI drivers currently reigsted by the Qore library
int(* q_dbi_close_t)(Datasource *ds)
signature for the DBI "close" method - must be defined in each DBI driver
Definition: DBI.h:123
the base class for accessing databases in Qore through a Qore DBI driver
Definition: Datasource.h:46
AbstractQoreNode *(* q_dbi_get_server_version_t)(Datasource *ds, ExceptionSink *xsink)
signature for the "get_server_version" method
Definition: DBI.h:213
DLLEXPORT const char * getName() const
this is the only public exported function available in this class
this is the data structure Qore DBI drivers will use to pass the supported DBI methods ...
Definition: DBI.h:287
This is the public class for DBI drivers supporting Qore's new prepared statement API...
Definition: SQLStatement.h:32
int(* q_dbi_commit_t)(Datasource *ds, ExceptionSink *xsink)
signature for the DBI "commit" method - must be defined in each DBI driver
Definition: DBI.h:181
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:35
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
Definition: DBI.h:133
DLLEXPORT DBIDriver * registerDriver(const char *name, const qore_dbi_method_list &methods, int caps)
registers a new DBI driver
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 ...
Definition: DBI.h:197
int(* q_dbi_stmt_exec_t)(SQLStatement *stmt, ExceptionSink *xsink)
execute statement
Definition: DBI.h:242
this class is used to register and find DBI drivers loaded in qore
Definition: DBI.h:390
int(* q_dbi_stmt_prepare_raw_t)(SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink)
prepare statement with no bind parsing
Definition: DBI.h:232
int(* q_dbi_stmt_affected_rows_t)(SQLStatement *stmt, ExceptionSink *xsink)
get number of affected rows
Definition: DBI.h:247
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 DBIDriver * find(const char *name) const
finds a driver, will try to load the driver using the ModuleManager if no such driver is already pres...
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
Definition: DBI.h:227
DLLEXPORT int DBI_concat_string(QoreString *str, const AbstractQoreNode *v, ExceptionSink *xsink)
concatenates a string value to the QoreString from the AbstractQoreNode