Qore Programming Language - C/C++ Library  0.8.12.2
 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 (C) 2003 - 2015 David Nichols
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 
57 #define BN_PLACEHOLDER 0
58 #define BN_VALUE 1
59 
60 #define DBI_DEFAULT_STR_LEN 512
61 
62 // DBI method codes
63 #define QDBI_METHOD_OPEN 1
64 #define QDBI_METHOD_CLOSE 2
65 #define QDBI_METHOD_SELECT 3
66 #define QDBI_METHOD_SELECT_ROWS 4
67 #define QDBI_METHOD_EXEC 5
68 #define QDBI_METHOD_COMMIT 6
69 #define QDBI_METHOD_ROLLBACK 7
70 #define QDBI_METHOD_BEGIN_TRANSACTION 8
71 #define QDBI_METHOD_ABORT_TRANSACTION_START 9
72 #define QDBI_METHOD_GET_SERVER_VERSION 10
73 #define QDBI_METHOD_GET_CLIENT_VERSION 11
74 #define QDBI_METHOD_EXECRAW 12
75 #define QDBI_METHOD_STMT_PREPARE 13
76 #define QDBI_METHOD_STMT_PREPARE_RAW 14
77 #define QDBI_METHOD_STMT_BIND 15
78 #define QDBI_METHOD_STMT_BIND_PLACEHOLDERS 16
79 #define QDBI_METHOD_STMT_BIND_VALUES 17
80 #define QDBI_METHOD_STMT_EXEC 18
81 #define QDBI_METHOD_STMT_FETCH_ROW 19
82 #define QDBI_METHOD_STMT_FETCH_ROWS 20
83 #define QDBI_METHOD_STMT_FETCH_COLUMNS 21
84 #define QDBI_METHOD_STMT_NEXT 22
85 #define QDBI_METHOD_STMT_CLOSE 23
86 #define QDBI_METHOD_STMT_AFFECTED_ROWS 24
87 #define QDBI_METHOD_STMT_GET_OUTPUT 25
88 #define QDBI_METHOD_STMT_GET_OUTPUT_ROWS 26
89 #define QDBI_METHOD_STMT_DEFINE 27
90 #define QDBI_METHOD_SELECT_ROW 28
91 #define QDBI_METHOD_OPT_SET 29
92 #define QDBI_METHOD_OPT_GET 30
93 #define QDBI_METHOD_STMT_DESCRIBE 31
94 #define QDBI_METHOD_DESCRIBE 32
95 
96 #define QDBI_VALID_CODES 32
97 
98 /* DBI EVENT Types
99  all DBI events must have the following keys:
100  - user: db username (if available)
101  - db: db name (if available)
102  - eventtype: integer event code
103 */
104 // warning events have the following additional keys: warning, desc, [info]
105 #define QDBI_EVENT_WARNING 1
106 
107 class Datasource;
108 class ExceptionSink;
109 class QoreString;
110 class QoreListNode;
111 class AbstractQoreNode;
112 class QoreHashNode;
113 class QoreNamespace;
114 class SQLStatement;
115 
116 // DBI method signatures - note that only get_client_version uses a "const Datasource"
117 // the others do not so that automatic reconnects can be supported (which will normally
118 // require writing to the Datasource)
119 
121 
125 typedef int (*q_dbi_open_t)(Datasource* ds, ExceptionSink* xsink);
126 
128 
132 typedef int (*q_dbi_close_t)(Datasource* ds);
133 
135 
142 typedef AbstractQoreNode* (*q_dbi_select_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
143 
145 
152 typedef AbstractQoreNode* (*q_dbi_select_rows_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
153 
155 
163 typedef QoreHashNode* (*q_dbi_select_row_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
164 
166 
173 typedef AbstractQoreNode* (*q_dbi_exec_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
174 
176 
182 typedef AbstractQoreNode* (*q_dbi_execraw_t)(Datasource* ds, const QoreString* str, ExceptionSink* xsink);
183 
185 
190 typedef int (*q_dbi_commit_t)(Datasource* ds, ExceptionSink* xsink);
191 
193 
198 typedef int (*q_dbi_rollback_t)(Datasource* ds, ExceptionSink* xsink);
199 
201 
207 
209 
217 
219 
224 typedef AbstractQoreNode* (*q_dbi_get_server_version_t)(Datasource* ds, ExceptionSink* xsink);
225 
227 
232 typedef AbstractQoreNode* (*q_dbi_get_client_version_t)(const Datasource* ds, ExceptionSink* xsink);
233 
234 // FIXME: document
236 
238 typedef int (*q_dbi_stmt_prepare_t)(SQLStatement* stmt, const QoreString& str, const QoreListNode* args, ExceptionSink* xsink);
239 
241 
243 typedef int (*q_dbi_stmt_prepare_raw_t)(SQLStatement* stmt, const QoreString& str, ExceptionSink* xsink);
244 
246 
248 typedef int (*q_dbi_stmt_bind_t)(SQLStatement* stmt, const QoreListNode& l, ExceptionSink* xsink);
249 
251 
253 typedef int (*q_dbi_stmt_exec_t)(SQLStatement* stmt, ExceptionSink* xsink);
254 
256 
259 
261 
263 typedef QoreHashNode* (*q_dbi_stmt_get_output_t)(SQLStatement* stmt, ExceptionSink* xsink);
264 
266 
268 typedef QoreHashNode* (*q_dbi_stmt_get_output_rows_t)(SQLStatement* stmt, ExceptionSink* xsink);
269 
270 typedef int (*q_dbi_stmt_define_t)(SQLStatement* stmt, ExceptionSink* xsink);
271 typedef QoreHashNode* (*q_dbi_stmt_fetch_row_t)(SQLStatement* stmt, ExceptionSink* xsink);
272 typedef QoreHashNode* (*q_dbi_stmt_fetch_columns_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
273 typedef QoreListNode* (*q_dbi_stmt_fetch_rows_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
274 typedef bool (*q_dbi_stmt_next_t)(SQLStatement* stmt, ExceptionSink* xsink);
275 typedef int (*q_dbi_stmt_close_t)(SQLStatement* stmt, ExceptionSink* xsink);
276 
277 typedef int (*q_dbi_option_set_t)(Datasource* ds, const char* opt, const AbstractQoreNode* val, ExceptionSink* xsink);
278 typedef AbstractQoreNode* (*q_dbi_option_get_t)(const Datasource* ds, const char* opt);
279 
281 
288 typedef QoreHashNode* (*q_dbi_describe_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
289 
290 #define DBI_OPT_NUMBER_OPT "optimal-numbers"
291 #define DBI_OPT_NUMBER_STRING "string-numbers"
292 #define DBI_OPT_NUMBER_NUMERIC "numeric-numbers"
293 #define DBI_OPT_TIMEZONE "timezone"
294 
295 
299  friend struct qore_dbi_mlist_private;
300 
301 private:
302  struct qore_dbi_mlist_private* priv; // private implementation
303 
304  // not implemented
306  DLLLOCAL qore_dbi_method_list& operator=(const qore_dbi_method_list&);
307 
308 public:
309  DLLEXPORT qore_dbi_method_list();
310  DLLEXPORT ~qore_dbi_method_list();
311 
312  // covers open, commit, rollback, and begin transaction
313  DLLEXPORT void add(int code, q_dbi_open_t method);
314  // for close
315  DLLEXPORT void add(int code, q_dbi_close_t method);
316  // covers select, select_rows, select, and exec
317  DLLEXPORT void add(int code, q_dbi_select_t method);
318  // covers select_row
319  DLLEXPORT void add(int code, q_dbi_select_row_t method);
320  // covers execRaw
321  DLLEXPORT void add(int code, q_dbi_execraw_t method);
322  // covers get_server_version
323  DLLEXPORT void add(int code, q_dbi_get_server_version_t method);
324  // covers get_client_version
325  DLLEXPORT void add(int code, q_dbi_get_client_version_t method);
326 
327  // covers prepare
328  DLLEXPORT void add(int code, q_dbi_stmt_prepare_t method);
329  // covers prepare_raw
330  DLLEXPORT void add(int code, q_dbi_stmt_prepare_raw_t method);
331  // covers bind, bind_placeholders, bind_values
332  DLLEXPORT void add(int code, q_dbi_stmt_bind_t method);
333  // covers exec, close, affected_rows, and define
334  DLLEXPORT void add(int code, q_dbi_stmt_exec_t method);
335  // covers fetch_row, get_output, and get_output_rows
336  DLLEXPORT void add(int code, q_dbi_stmt_fetch_row_t method);
337  // covers fetch_columns
338  DLLEXPORT void add(int code, q_dbi_stmt_fetch_columns_t method);
339  // covers fetch_rows
340  DLLEXPORT void add(int code, q_dbi_stmt_fetch_rows_t method);
341  // covers next
342  DLLEXPORT void add(int code, q_dbi_stmt_next_t method);
343 
344  // covers set option
345  DLLEXPORT void add(int code, q_dbi_option_set_t method);
346  // covers get option
347  DLLEXPORT void add(int code, q_dbi_option_get_t method);
348 
349  // for registering valid options
350  DLLEXPORT void registerOption(const char* name, const char* desc, const QoreTypeInfo* type = 0);
351 };
352 
354 
359 class DBIDriver {
360  friend struct qore_dbi_private;
361 
362 private:
364  struct qore_dbi_private* priv;
365 
367  DLLLOCAL DBIDriver(const DBIDriver&);
369  DLLLOCAL DBIDriver& operator=(const DBIDriver&);
370 
371 public:
373 
376  DLLEXPORT const char* getName() const;
377 
379  DLLEXPORT bool hasStatementAPI() const;
380 
382 
388  DLLEXPORT QoreHashNode* getOptionHash() const;
389 
390  DLLLOCAL DBIDriver(struct qore_dbi_private* p);
391  DLLLOCAL ~DBIDriver();
392 };
393 
394 struct qore_dbi_dlist_private;
395 
397 
402 private:
404  struct qore_dbi_dlist_private *priv;
405 
406  DLLLOCAL DBIDriver* find_intern(const char* name) const;
407 
408 public:
410 
417  DLLEXPORT DBIDriver* registerDriver(const char* name, const qore_dbi_method_list &methods, int caps);
418 
420 
427  DLLEXPORT DBIDriver* find(const char* name) const;
428 
430 
438  DLLEXPORT DBIDriver* find(const char* name, ExceptionSink* xsink) const;
439 
440  DLLLOCAL DBIDriverList();
441  DLLLOCAL ~DBIDriverList();
442  DLLLOCAL QoreListNode* getDriverList() const;
443 };
444 
446 DLLEXPORT extern DBIDriverList DBI;
447 
449 DLLEXPORT QoreHashNode* parseDatasource(const char* ds, ExceptionSink* xsink);
450 
452 DLLEXPORT void DBI_concat_numeric(QoreString* str, const AbstractQoreNode* v);
453 
455 
458 DLLEXPORT int DBI_concat_string(QoreString* str, const AbstractQoreNode* v, ExceptionSink* xsink);
459 
460 #endif // _QORE_DBI_H
int(* q_dbi_open_t)(Datasource *ds, ExceptionSink *xsink)
signature for the DBI &quot;open&quot; method - must be defined in each DBI driver
Definition: DBI.h:125
AbstractQoreNode *(* q_dbi_get_client_version_t)(const Datasource *ds, ExceptionSink *xsink)
signature for the &quot;get_client_version&quot; method
Definition: DBI.h:232
This is the hash or associative list container type in Qore, dynamically allocated only...
Definition: QoreHashNode.h:49
The base class for all value and parse types in Qore expression trees.
Definition: AbstractQoreNode.h:55
QoreHashNode *(* q_dbi_select_row_t)(Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)
signature for the DBI &quot;selectRow&quot; method - must be defined in each DBI driver
Definition: DBI.h:163
contains constants, classes, and subnamespaces in QoreProgram objects
Definition: QoreNamespace.h:58
this class provides the internal link to the database driver for Qore&#39;s DBI layer ...
Definition: DBI.h:359
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:216
DLLEXPORT QoreHashNode * getOptionHash() const
returns the valid options for this driver with descriptions
Qore&#39;s string type supported by the QoreEncoding class.
Definition: QoreString.h:82
int(* q_dbi_rollback_t)(Datasource *ds, ExceptionSink *xsink)
signature for the DBI &quot;rollback&quot; method - must be defined in each DBI driver
Definition: DBI.h:198
AbstractQoreNode *(* q_dbi_execraw_t)(Datasource *ds, const QoreString *str, ExceptionSink *xsink)
signature for the DBI &quot;execRawSQL&quot; method - must be defined in each DBI driver
Definition: DBI.h:182
int(* q_dbi_stmt_bind_t)(SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink)
bind input values and optionally describe output parameters
Definition: DBI.h:248
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
int(* q_dbi_close_t)(Datasource *ds)
signature for the DBI &quot;close&quot; method - must be defined in each DBI driver
Definition: DBI.h:132
the base class for accessing databases in Qore through a Qore DBI driver
Definition: Datasource.h:54
AbstractQoreNode *(* q_dbi_get_server_version_t)(Datasource *ds, ExceptionSink *xsink)
signature for the &quot;get_server_version&quot; method
Definition: DBI.h:224
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:298
This is the public class for DBI drivers supporting Qore&#39;s new prepared statement API...
Definition: SQLStatement.h:40
int(* q_dbi_commit_t)(Datasource *ds, ExceptionSink *xsink)
signature for the DBI &quot;commit&quot; method - must be defined in each DBI driver
Definition: DBI.h:190
container for holding Qore-language exception information and also for registering a &quot;thread_exit&quot; ca...
Definition: ExceptionSink.h:43
AbstractQoreNode *(* q_dbi_select_t)(Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)
signature for the DBI &quot;select&quot; method - must be defined in each DBI driver
Definition: DBI.h:142
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 &quot;begin_transaction&quot; method, should only be defined for drivers needing this to ...
Definition: DBI.h:206
int(* q_dbi_stmt_exec_t)(SQLStatement *stmt, ExceptionSink *xsink)
execute statement
Definition: DBI.h:253
this class is used to register and find DBI drivers loaded in qore
Definition: DBI.h:401
int(* q_dbi_stmt_prepare_raw_t)(SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink)
prepare statement with no bind parsing
Definition: DBI.h:243
int(* q_dbi_stmt_affected_rows_t)(SQLStatement *stmt, ExceptionSink *xsink)
get number of affected rows
Definition: DBI.h:258
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:238
DLLEXPORT int DBI_concat_string(QoreString *str, const AbstractQoreNode *v, ExceptionSink *xsink)
concatenates a string value to the QoreString from the AbstractQoreNode