Qore Programming Language  0.9.0
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_GET_SERVER_VERSION 9
73 #define QDBI_METHOD_GET_CLIENT_VERSION 10
74 #define QDBI_METHOD_EXECRAW 11
75 #define QDBI_METHOD_STMT_PREPARE 12
76 #define QDBI_METHOD_STMT_PREPARE_RAW 13
77 #define QDBI_METHOD_STMT_BIND 14
78 #define QDBI_METHOD_STMT_BIND_PLACEHOLDERS 15
79 #define QDBI_METHOD_STMT_BIND_VALUES 16
80 #define QDBI_METHOD_STMT_EXEC 17
81 #define QDBI_METHOD_STMT_FETCH_ROW 18
82 #define QDBI_METHOD_STMT_FETCH_ROWS 19
83 #define QDBI_METHOD_STMT_FETCH_COLUMNS 20
84 #define QDBI_METHOD_STMT_NEXT 21
85 #define QDBI_METHOD_STMT_CLOSE 22
86 #define QDBI_METHOD_STMT_AFFECTED_ROWS 23
87 #define QDBI_METHOD_STMT_GET_OUTPUT 24
88 #define QDBI_METHOD_STMT_GET_OUTPUT_ROWS 25
89 #define QDBI_METHOD_STMT_DEFINE 26
90 #define QDBI_METHOD_SELECT_ROW 27
91 #define QDBI_METHOD_OPT_SET 28
92 #define QDBI_METHOD_OPT_GET 29
93 #define QDBI_METHOD_STMT_DESCRIBE 30
94 #define QDBI_METHOD_DESCRIBE 31
95 #define QDBI_METHOD_STMT_FREE 32
96 #define QDBI_METHOD_STMT_EXEC_DESCRIBE 33
97 
98 #define QDBI_VALID_CODES 33
99 
100 /* DBI EVENT Types
101  all DBI events must have the following keys:
102  - user: db username (if available)
103  - db: db name (if available)
104  - eventtype: integer event code
105 */
106 // warning events have the following additional keys: warning, desc, [info]
107 #define QDBI_EVENT_WARNING 1
108 
109 class Datasource;
110 class ExceptionSink;
111 class QoreString;
112 class QoreListNode;
113 class QoreHashNode;
114 class QoreNamespace;
115 class SQLStatement;
116 
117 // DBI method signatures - note that only get_client_version uses a "const Datasource"
118 // the others do not so that automatic reconnects can be supported (which will normally
119 // require writing to the Datasource)
120 
122 
126 typedef int (*q_dbi_open_t)(Datasource* ds, ExceptionSink* xsink);
127 
129 
133 typedef int (*q_dbi_close_t)(Datasource* ds);
134 
136 
143 typedef QoreValue (*q_dbi_select_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
144 
146 
153 typedef QoreValue (*q_dbi_select_rows_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
154 
156 
164 typedef QoreHashNode* (*q_dbi_select_row_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
165 
167 
174 typedef QoreValue (*q_dbi_exec_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
175 
177 
183 typedef QoreValue (*q_dbi_execraw_t)(Datasource* ds, const QoreString* str, ExceptionSink* xsink);
184 
186 
191 typedef int (*q_dbi_commit_t)(Datasource* ds, ExceptionSink* xsink);
192 
194 
199 typedef int (*q_dbi_rollback_t)(Datasource* ds, ExceptionSink* xsink);
200 
202 
208 
210 
216 
218 
224 
225 // FIXME: document
227 
229 typedef int (*q_dbi_stmt_prepare_t)(SQLStatement* stmt, const QoreString& str, const QoreListNode* args, ExceptionSink* xsink);
230 
232 
234 typedef int (*q_dbi_stmt_prepare_raw_t)(SQLStatement* stmt, const QoreString& str, ExceptionSink* xsink);
235 
237 
239 typedef int (*q_dbi_stmt_bind_t)(SQLStatement* stmt, const QoreListNode& l, ExceptionSink* xsink);
240 
242 
244 typedef int (*q_dbi_stmt_exec_t)(SQLStatement* stmt, ExceptionSink* xsink);
245 
247 
250 
252 
254 typedef QoreHashNode* (*q_dbi_stmt_get_output_t)(SQLStatement* stmt, ExceptionSink* xsink);
255 
257 
259 typedef QoreHashNode* (*q_dbi_stmt_get_output_rows_t)(SQLStatement* stmt, ExceptionSink* xsink);
260 
261 typedef int (*q_dbi_stmt_define_t)(SQLStatement* stmt, ExceptionSink* xsink);
262 typedef QoreHashNode* (*q_dbi_stmt_fetch_row_t)(SQLStatement* stmt, ExceptionSink* xsink);
263 typedef QoreHashNode* (*q_dbi_stmt_fetch_columns_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
264 typedef QoreListNode* (*q_dbi_stmt_fetch_rows_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
265 typedef bool (*q_dbi_stmt_next_t)(SQLStatement* stmt, ExceptionSink* xsink);
266 typedef int (*q_dbi_stmt_close_t)(SQLStatement* stmt, ExceptionSink* xsink);
267 
268 typedef int (*q_dbi_option_set_t)(Datasource* ds, const char* opt, const QoreValue val, ExceptionSink* xsink);
269 typedef QoreValue (*q_dbi_option_get_t)(const Datasource* ds, const char* opt);
270 
272 
279 typedef QoreHashNode* (*q_dbi_describe_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
280 
281 #define DBI_OPT_NUMBER_OPT "optimal-numbers"
282 #define DBI_OPT_NUMBER_STRING "string-numbers"
283 #define DBI_OPT_NUMBER_NUMERIC "numeric-numbers"
284 #define DBI_OPT_TIMEZONE "timezone"
285 
286 
290  friend hashdecl qore_dbi_mlist_private;
291 
292 private:
293  hashdecl qore_dbi_mlist_private* priv; // private implementation
294 
295  // not implemented
297  DLLLOCAL qore_dbi_method_list& operator=(const qore_dbi_method_list&);
298 
299 public:
300  DLLEXPORT qore_dbi_method_list();
301  DLLEXPORT ~qore_dbi_method_list();
302 
303  // covers open, commit, rollback, and begin transaction
304  DLLEXPORT void add(int code, q_dbi_open_t method);
305  // for close
306  DLLEXPORT void add(int code, q_dbi_close_t method);
307  // covers select, select_rows, select, and exec
308  DLLEXPORT void add(int code, q_dbi_select_t method);
309  // covers select_row
310  DLLEXPORT void add(int code, q_dbi_select_row_t method);
311  // covers execRaw
312  DLLEXPORT void add(int code, q_dbi_execraw_t method);
313  // covers get_server_version
314  DLLEXPORT void add(int code, q_dbi_get_server_version_t method);
315  // covers get_client_version
316  DLLEXPORT void add(int code, q_dbi_get_client_version_t method);
317 
318  // covers prepare
319  DLLEXPORT void add(int code, q_dbi_stmt_prepare_t method);
320  // covers prepare_raw
321  DLLEXPORT void add(int code, q_dbi_stmt_prepare_raw_t method);
322  // covers bind, bind_placeholders, bind_values
323  DLLEXPORT void add(int code, q_dbi_stmt_bind_t method);
324  // covers exec, close, affected_rows, define, and exec_describe
325  DLLEXPORT void add(int code, q_dbi_stmt_exec_t method);
326  // covers fetch_row, get_output, and get_output_rows
327  DLLEXPORT void add(int code, q_dbi_stmt_fetch_row_t method);
328  // covers fetch_columns
329  DLLEXPORT void add(int code, q_dbi_stmt_fetch_columns_t method);
330  // covers fetch_rows
331  DLLEXPORT void add(int code, q_dbi_stmt_fetch_rows_t method);
332  // covers next
333  DLLEXPORT void add(int code, q_dbi_stmt_next_t method);
334 
335  // covers set option
336  DLLEXPORT void add(int code, q_dbi_option_set_t method);
337  // covers get option
338  DLLEXPORT void add(int code, q_dbi_option_get_t method);
339 
340  // for registering valid options
341  DLLEXPORT void registerOption(const char* name, const char* desc, const QoreTypeInfo* type = 0);
342 };
343 
345 
350 class DBIDriver {
351  friend hashdecl qore_dbi_private;
352 
353 private:
355  hashdecl qore_dbi_private* priv;
356 
358  DLLLOCAL DBIDriver(const DBIDriver&);
360  DLLLOCAL DBIDriver& operator=(const DBIDriver&);
361 
362 public:
364 
367  DLLEXPORT const char* getName() const;
368 
370  DLLEXPORT bool hasStatementAPI() const;
371 
373 
379  DLLEXPORT QoreHashNode* getOptionHash() const;
380 
381  DLLLOCAL DBIDriver(struct qore_dbi_private* p);
382  DLLLOCAL ~DBIDriver();
383 };
384 
385 hashdecl qore_dbi_dlist_private;
386 
388 
393 private:
395  hashdecl qore_dbi_dlist_private *priv;
396 
397  DLLLOCAL DBIDriver* find_intern(const char* name) const;
398 
399 public:
401 
408  DLLEXPORT DBIDriver* registerDriver(const char* name, const qore_dbi_method_list &methods, int caps);
409 
411 
418  DLLEXPORT DBIDriver* find(const char* name) const;
419 
421 
429  DLLEXPORT DBIDriver* find(const char* name, ExceptionSink* xsink) const;
430 
431  DLLLOCAL DBIDriverList();
432  DLLLOCAL ~DBIDriverList();
433  DLLLOCAL QoreListNode* getDriverList() const;
434 };
435 
437 DLLEXPORT extern DBIDriverList DBI;
438 
440 DLLEXPORT QoreHashNode* parseDatasource(const char* ds, ExceptionSink* xsink);
441 
443 DLLEXPORT void DBI_concat_numeric(QoreString* str, QoreValue v);
444 
446 
449 DLLEXPORT int DBI_concat_string(QoreString* str, QoreValue v, ExceptionSink* xsink);
450 
451 #endif // _QORE_DBI_H
int(* q_dbi_close_t)(Datasource *ds)
signature for the DBI "close" method - must be defined in each DBI driver
Definition: DBI.h:133
DLLEXPORT void DBI_concat_numeric(QoreString *str, QoreValue v)
concatenates a numeric value to the QoreString from the value
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:239
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:164
QoreValue(* q_dbi_get_server_version_t)(Datasource *ds, ExceptionSink *xsink)
signature for the "get_server_version" method
Definition: DBI.h:215
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:207
int(* q_dbi_stmt_prepare_raw_t)(SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink)
prepare statement with no bind parsing
Definition: DBI.h:234
contains constants, classes, and subnamespaces in QoreProgram objects
Definition: QoreNamespace.h:65
this class provides the internal link to the database driver for Qore&#39;s DBI layer ...
Definition: DBI.h:350
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
Definition: DBI.h:143
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:126
DLLEXPORT QoreHashNode * getOptionHash() const
returns the valid options for this driver with descriptions
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...
Qore&#39;s string type supported by the QoreEncoding class.
Definition: QoreString.h:81
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
QoreValue(* q_dbi_get_client_version_t)(const Datasource *ds, ExceptionSink *xsink)
signature for the "get_client_version" method
Definition: DBI.h:223
DLLEXPORT int DBI_concat_string(QoreString *str, QoreValue v, ExceptionSink *xsink)
concatenates a string value to the QoreString from the value
the base class for accessing databases in Qore through a Qore DBI driver
Definition: Datasource.h:55
The main value class in Qore, designed to be passed by value.
Definition: QoreValue.h:262
this is the data structure Qore DBI drivers will use to pass the supported DBI methods ...
Definition: DBI.h:289
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:244
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:46
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:199
DLLEXPORT const char * getName() const
this is the only public exported function available in this class
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:229
DLLEXPORT DBIDriver * registerDriver(const char *name, const qore_dbi_method_list &methods, int caps)
registers a new DBI driver
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:191
DLLEXPORT bool hasStatementAPI() const
returns true if the driver supports the statement API
this class is used to register and find DBI drivers loaded in qore
Definition: DBI.h:392
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
Definition: DBI.h:153
int(* q_dbi_stmt_affected_rows_t)(SQLStatement *stmt, ExceptionSink *xsink)
get number of affected rows
Definition: DBI.h:249
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
Definition: DBI.h:174
DLLEXPORT QoreHashNode * parseDatasource(const char *ds, ExceptionSink *xsink)
parses a datasource string and returns a hash of the component parts
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
Definition: DBI.h:183