Qore Programming Language - C/C++ Library  0.8.13.6
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 (C) 2003 - 2018 Qore Technologies, s.r.o.
8 
9  Permission is hereby granted, free of charge, to any person obtaining a
10  copy of this software and associated documentation files (the "Software"),
11  to deal in the Software without restriction, including without limitation
12  the rights to use, copy, modify, merge, publish, distribute, sublicense,
13  and/or sell copies of the Software, and to permit persons to whom the
14  Software is furnished to do so, subject to the following conditions:
15 
16  The above copyright notice and this permission notice shall be included in
17  all copies or substantial portions of the Software.
18 
19  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
25  DEALINGS IN THE SOFTWARE.
26 
27  Note that the Qore library is released under a choice of three open-source
28  licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
29  information.
30 */
31 
32 #ifndef _QORE_DBI_H
33 #define _QORE_DBI_H
34 
36 
37 // DBI Driver capabilities
38 #define DBI_CAP_NONE 0
39 #define DBI_CAP_TIME_ZONE_SUPPORT (1 << 0)
40 #define DBI_CAP_CHARSET_SUPPORT (1 << 1)
41 #define DBI_CAP_TRANSACTION_MANAGEMENT (1 << 2)
42 #define DBI_CAP_STORED_PROCEDURES (1 << 3)
43 #define DBI_CAP_LOB_SUPPORT (1 << 4)
44 #define DBI_CAP_BIND_BY_VALUE (1 << 5)
45 #define DBI_CAP_BIND_BY_PLACEHOLDER (1 << 6)
46 #define DBI_CAP_HAS_EXECRAW (1 << 7)
47 #define DBI_CAP_HAS_STATEMENT (1 << 8)
48 #define DBI_CAP_HAS_SELECT_ROW (1 << 9)
49 #define DBI_CAP_HAS_NUMBER_SUPPORT (1 << 10)
50 #define DBI_CAP_HAS_OPTION_SUPPORT (1 << 11)
51 #define DBI_CAP_SERVER_TIME_ZONE (1 << 12)
52 #define DBI_CAP_AUTORECONNECT (1 << 13)
53 #define DBI_CAP_EVENTS (1 << 14)
54 #define DBI_CAP_HAS_DESCRIBE (1 << 15)
55 #define DBI_CAP_HAS_ARRAY_BIND (1 << 16)
56 #define DBI_CAP_HAS_RESULTSET_OUTPUT (1 << 17)
57 
58 #define BN_PLACEHOLDER 0
59 #define BN_VALUE 1
60 
61 #define DBI_DEFAULT_STR_LEN 512
62 
63 // DBI method codes
64 #define QDBI_METHOD_OPEN 1
65 #define QDBI_METHOD_CLOSE 2
66 #define QDBI_METHOD_SELECT 3
67 #define QDBI_METHOD_SELECT_ROWS 4
68 #define QDBI_METHOD_EXEC 5
69 #define QDBI_METHOD_COMMIT 6
70 #define QDBI_METHOD_ROLLBACK 7
71 #define QDBI_METHOD_BEGIN_TRANSACTION 8
72 #define QDBI_METHOD_ABORT_TRANSACTION_START 9
73 #define QDBI_METHOD_GET_SERVER_VERSION 10
74 #define QDBI_METHOD_GET_CLIENT_VERSION 11
75 #define QDBI_METHOD_EXECRAW 12
76 #define QDBI_METHOD_STMT_PREPARE 13
77 #define QDBI_METHOD_STMT_PREPARE_RAW 14
78 #define QDBI_METHOD_STMT_BIND 15
79 #define QDBI_METHOD_STMT_BIND_PLACEHOLDERS 16
80 #define QDBI_METHOD_STMT_BIND_VALUES 17
81 #define QDBI_METHOD_STMT_EXEC 18
82 #define QDBI_METHOD_STMT_FETCH_ROW 19
83 #define QDBI_METHOD_STMT_FETCH_ROWS 20
84 #define QDBI_METHOD_STMT_FETCH_COLUMNS 21
85 #define QDBI_METHOD_STMT_NEXT 22
86 #define QDBI_METHOD_STMT_CLOSE 23
87 #define QDBI_METHOD_STMT_AFFECTED_ROWS 24
88 #define QDBI_METHOD_STMT_GET_OUTPUT 25
89 #define QDBI_METHOD_STMT_GET_OUTPUT_ROWS 26
90 #define QDBI_METHOD_STMT_DEFINE 27
91 #define QDBI_METHOD_SELECT_ROW 28
92 #define QDBI_METHOD_OPT_SET 29
93 #define QDBI_METHOD_OPT_GET 30
94 #define QDBI_METHOD_STMT_DESCRIBE 31
95 #define QDBI_METHOD_DESCRIBE 32
96 #define QDBI_METHOD_STMT_FREE 33
97 #define QDBI_METHOD_STMT_EXEC_DESCRIBE 34
98 
99 #define QDBI_VALID_CODES 34
100 
101 /* DBI EVENT Types
102  all DBI events must have the following keys:
103  - user: db username (if available)
104  - db: db name (if available)
105  - eventtype: integer event code
106 */
107 // warning events have the following additional keys: warning, desc, [info]
108 #define QDBI_EVENT_WARNING 1
109 
110 class Datasource;
111 class ExceptionSink;
112 class QoreString;
113 class QoreListNode;
114 class AbstractQoreNode;
115 class QoreHashNode;
116 class QoreNamespace;
117 class SQLStatement;
118 
119 // DBI method signatures - note that only get_client_version uses a "const Datasource"
120 // the others do not so that automatic reconnects can be supported (which will normally
121 // require writing to the Datasource)
122 
124 
128 typedef int (*q_dbi_open_t)(Datasource* ds, ExceptionSink* xsink);
129 
131 
135 typedef int (*q_dbi_close_t)(Datasource* ds);
136 
138 
145 typedef AbstractQoreNode* (*q_dbi_select_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
146 
148 
155 typedef AbstractQoreNode* (*q_dbi_select_rows_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
156 
158 
166 typedef QoreHashNode* (*q_dbi_select_row_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
167 
169 
176 typedef AbstractQoreNode* (*q_dbi_exec_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
177 
179 
185 typedef AbstractQoreNode* (*q_dbi_execraw_t)(Datasource* ds, const QoreString* str, ExceptionSink* xsink);
186 
188 
193 typedef int (*q_dbi_commit_t)(Datasource* ds, ExceptionSink* xsink);
194 
196 
201 typedef int (*q_dbi_rollback_t)(Datasource* ds, ExceptionSink* xsink);
202 
204 
210 
212 
220 
222 
227 typedef AbstractQoreNode* (*q_dbi_get_server_version_t)(Datasource* ds, ExceptionSink* xsink);
228 
230 
235 typedef AbstractQoreNode* (*q_dbi_get_client_version_t)(const Datasource* ds, ExceptionSink* xsink);
236 
237 // FIXME: document
239 
241 typedef int (*q_dbi_stmt_prepare_t)(SQLStatement* stmt, const QoreString& str, const QoreListNode* args, ExceptionSink* xsink);
242 
244 
246 typedef int (*q_dbi_stmt_prepare_raw_t)(SQLStatement* stmt, const QoreString& str, ExceptionSink* xsink);
247 
249 
251 typedef int (*q_dbi_stmt_bind_t)(SQLStatement* stmt, const QoreListNode& l, ExceptionSink* xsink);
252 
254 
256 typedef int (*q_dbi_stmt_exec_t)(SQLStatement* stmt, ExceptionSink* xsink);
257 
259 
262 
264 
266 typedef QoreHashNode* (*q_dbi_stmt_get_output_t)(SQLStatement* stmt, ExceptionSink* xsink);
267 
269 
271 typedef QoreHashNode* (*q_dbi_stmt_get_output_rows_t)(SQLStatement* stmt, ExceptionSink* xsink);
272 
273 typedef int (*q_dbi_stmt_define_t)(SQLStatement* stmt, ExceptionSink* xsink);
274 typedef QoreHashNode* (*q_dbi_stmt_fetch_row_t)(SQLStatement* stmt, ExceptionSink* xsink);
275 typedef QoreHashNode* (*q_dbi_stmt_fetch_columns_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
276 typedef QoreListNode* (*q_dbi_stmt_fetch_rows_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
277 typedef bool (*q_dbi_stmt_next_t)(SQLStatement* stmt, ExceptionSink* xsink);
278 typedef int (*q_dbi_stmt_close_t)(SQLStatement* stmt, ExceptionSink* xsink);
279 
280 typedef int (*q_dbi_option_set_t)(Datasource* ds, const char* opt, const AbstractQoreNode* val, ExceptionSink* xsink);
281 typedef AbstractQoreNode* (*q_dbi_option_get_t)(const Datasource* ds, const char* opt);
282 
284 
291 typedef QoreHashNode* (*q_dbi_describe_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
292 
293 #define DBI_OPT_NUMBER_OPT "optimal-numbers"
294 #define DBI_OPT_NUMBER_STRING "string-numbers"
295 #define DBI_OPT_NUMBER_NUMERIC "numeric-numbers"
296 #define DBI_OPT_TIMEZONE "timezone"
297 
298 
302  friend struct qore_dbi_mlist_private;
303 
304 private:
305  struct qore_dbi_mlist_private* priv; // private implementation
306 
307  // not implemented
309  DLLLOCAL qore_dbi_method_list& operator=(const qore_dbi_method_list&);
310 
311 public:
312  DLLEXPORT qore_dbi_method_list();
313  DLLEXPORT ~qore_dbi_method_list();
314 
315  // covers open, commit, rollback, and begin transaction
316  DLLEXPORT void add(int code, q_dbi_open_t method);
317  // for close
318  DLLEXPORT void add(int code, q_dbi_close_t method);
319  // covers select, select_rows, select, and exec
320  DLLEXPORT void add(int code, q_dbi_select_t method);
321  // covers select_row
322  DLLEXPORT void add(int code, q_dbi_select_row_t method);
323  // covers execRaw
324  DLLEXPORT void add(int code, q_dbi_execraw_t method);
325  // covers get_server_version
326  DLLEXPORT void add(int code, q_dbi_get_server_version_t method);
327  // covers get_client_version
328  DLLEXPORT void add(int code, q_dbi_get_client_version_t method);
329 
330  // covers prepare
331  DLLEXPORT void add(int code, q_dbi_stmt_prepare_t method);
332  // covers prepare_raw
333  DLLEXPORT void add(int code, q_dbi_stmt_prepare_raw_t method);
334  // covers bind, bind_placeholders, bind_values
335  DLLEXPORT void add(int code, q_dbi_stmt_bind_t method);
336  // covers exec, close, affected_rows, define, and exec_describe
337  DLLEXPORT void add(int code, q_dbi_stmt_exec_t method);
338  // covers fetch_row, get_output, and get_output_rows
339  DLLEXPORT void add(int code, q_dbi_stmt_fetch_row_t method);
340  // covers fetch_columns
341  DLLEXPORT void add(int code, q_dbi_stmt_fetch_columns_t method);
342  // covers fetch_rows
343  DLLEXPORT void add(int code, q_dbi_stmt_fetch_rows_t method);
344  // covers next
345  DLLEXPORT void add(int code, q_dbi_stmt_next_t method);
346 
347  // covers set option
348  DLLEXPORT void add(int code, q_dbi_option_set_t method);
349  // covers get option
350  DLLEXPORT void add(int code, q_dbi_option_get_t method);
351 
352  // for registering valid options
353  DLLEXPORT void registerOption(const char* name, const char* desc, const QoreTypeInfo* type = 0);
354 };
355 
357 
362 class DBIDriver {
363  friend struct qore_dbi_private;
364 
365 private:
367  struct qore_dbi_private* priv;
368 
370  DLLLOCAL DBIDriver(const DBIDriver&);
372  DLLLOCAL DBIDriver& operator=(const DBIDriver&);
373 
374 public:
376 
379  DLLEXPORT const char* getName() const;
380 
382  DLLEXPORT bool hasStatementAPI() const;
383 
385 
391  DLLEXPORT QoreHashNode* getOptionHash() const;
392 
393  DLLLOCAL DBIDriver(struct qore_dbi_private* p);
394  DLLLOCAL ~DBIDriver();
395 };
396 
397 struct qore_dbi_dlist_private;
398 
400 
405 private:
407  struct qore_dbi_dlist_private *priv;
408 
409  DLLLOCAL DBIDriver* find_intern(const char* name) const;
410 
411 public:
413 
420  DLLEXPORT DBIDriver* registerDriver(const char* name, const qore_dbi_method_list &methods, int caps);
421 
423 
430  DLLEXPORT DBIDriver* find(const char* name) const;
431 
433 
441  DLLEXPORT DBIDriver* find(const char* name, ExceptionSink* xsink) const;
442 
443  DLLLOCAL DBIDriverList();
444  DLLLOCAL ~DBIDriverList();
445  DLLLOCAL QoreListNode* getDriverList() const;
446 };
447 
449 DLLEXPORT extern DBIDriverList DBI;
450 
452 DLLEXPORT QoreHashNode* parseDatasource(const char* ds, ExceptionSink* xsink);
453 
455 DLLEXPORT void DBI_concat_numeric(QoreString* str, const AbstractQoreNode* v);
456 
458 
461 DLLEXPORT int DBI_concat_string(QoreString* str, const AbstractQoreNode* v, ExceptionSink* xsink);
462 
463 #endif // _QORE_DBI_H
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:185
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:219
int(* q_dbi_close_t)(Datasource *ds)
signature for the DBI "close" method - must be defined in each DBI driver
Definition: DBI.h:135
This is the hash or associative list container type in Qore, dynamically allocated only...
Definition: QoreHashNode.h:50
int(* q_dbi_stmt_bind_t)(SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink)
bind input values and optionally describe output parameters
Definition: DBI.h:251
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:166
AbstractQoreNode *(* q_dbi_get_client_version_t)(const Datasource *ds, ExceptionSink *xsink)
signature for the "get_client_version" method
Definition: DBI.h:235
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:209
int(* q_dbi_stmt_prepare_raw_t)(SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink)
prepare statement with no bind parsing
Definition: DBI.h:246
The base class for all value and parse types in Qore expression trees.
Definition: AbstractQoreNode.h:54
contains constants, classes, and subnamespaces in QoreProgram objects
Definition: QoreNamespace.h:63
this class provides the internal link to the database driver for Qore&#39;s DBI layer ...
Definition: DBI.h:362
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:128
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:145
Qore&#39;s string type supported by the QoreEncoding class.
Definition: QoreString.h:82
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:52
DLLEXPORT DBIDriverList DBI
list of DBI drivers currently reigsted by the Qore library
the base class for accessing databases in Qore through a Qore DBI driver
Definition: Datasource.h:55
this is the data structure Qore DBI drivers will use to pass the supported DBI methods ...
Definition: DBI.h:301
This is the public class for DBI drivers supporting Qore&#39;s new prepared statement API...
Definition: SQLStatement.h:38
int(* q_dbi_stmt_exec_t)(SQLStatement *stmt, ExceptionSink *xsink)
execute statement
Definition: DBI.h:256
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:47
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:201
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:241
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:193
this class is used to register and find DBI drivers loaded in qore
Definition: DBI.h:404
AbstractQoreNode *(* q_dbi_get_server_version_t)(Datasource *ds, ExceptionSink *xsink)
signature for the "get_server_version" method
Definition: DBI.h:227
int(* q_dbi_stmt_affected_rows_t)(SQLStatement *stmt, ExceptionSink *xsink)
get number of affected rows
Definition: DBI.h:261
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