Qore Programming Language  0.8.7
 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 - 2013 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 
46 #define BN_PLACEHOLDER 0
47 #define BN_VALUE 1
48 
49 #define DBI_DEFAULT_STR_LEN 512
50 
51 // DBI method codes
52 #define QDBI_METHOD_OPEN 1
53 #define QDBI_METHOD_CLOSE 2
54 #define QDBI_METHOD_SELECT 3
55 #define QDBI_METHOD_SELECT_ROWS 4
56 #define QDBI_METHOD_EXEC 5
57 #define QDBI_METHOD_COMMIT 6
58 #define QDBI_METHOD_ROLLBACK 7
59 #define QDBI_METHOD_BEGIN_TRANSACTION 8
60 #define QDBI_METHOD_ABORT_TRANSACTION_START 9
61 #define QDBI_METHOD_GET_SERVER_VERSION 10
62 #define QDBI_METHOD_GET_CLIENT_VERSION 11
63 #define QDBI_METHOD_EXECRAW 12
64 #define QDBI_METHOD_STMT_PREPARE 13
65 #define QDBI_METHOD_STMT_PREPARE_RAW 14
66 #define QDBI_METHOD_STMT_BIND 15
67 #define QDBI_METHOD_STMT_BIND_PLACEHOLDERS 16
68 #define QDBI_METHOD_STMT_BIND_VALUES 17
69 #define QDBI_METHOD_STMT_EXEC 18
70 #define QDBI_METHOD_STMT_FETCH_ROW 19
71 #define QDBI_METHOD_STMT_FETCH_ROWS 20
72 #define QDBI_METHOD_STMT_FETCH_COLUMNS 21
73 #define QDBI_METHOD_STMT_NEXT 22
74 #define QDBI_METHOD_STMT_CLOSE 23
75 #define QDBI_METHOD_STMT_AFFECTED_ROWS 24
76 #define QDBI_METHOD_STMT_GET_OUTPUT 25
77 #define QDBI_METHOD_STMT_GET_OUTPUT_ROWS 26
78 #define QDBI_METHOD_STMT_DEFINE 27
79 #define QDBI_METHOD_SELECT_ROW 28
80 #define QDBI_METHOD_OPT_SET 29
81 #define QDBI_METHOD_OPT_GET 30
82 
83 #define QDBI_VALID_CODES 30
84 
85 class Datasource;
86 class ExceptionSink;
87 class QoreString;
88 class QoreListNode;
89 class AbstractQoreNode;
90 class QoreHashNode;
91 class QoreNamespace;
92 class SQLStatement;
93 
94 // DBI method signatures - note that only get_client_version uses a "const Datasource"
95 // the others do not so that automatic reconnects can be supported (which will normally
96 // require writing to the Datasource)
97 
99 
103 typedef int (*q_dbi_open_t)(Datasource* ds, ExceptionSink* xsink);
104 
106 
110 typedef int (*q_dbi_close_t)(Datasource* ds);
111 
113 
120 typedef AbstractQoreNode* (*q_dbi_select_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
121 
123 
130 typedef AbstractQoreNode* (*q_dbi_select_rows_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
131 
133 
141 typedef QoreHashNode* (*q_dbi_select_row_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
142 
144 
151 typedef AbstractQoreNode* (*q_dbi_exec_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
152 
154 
160 typedef AbstractQoreNode* (*q_dbi_execraw_t)(Datasource* ds, const QoreString* str, ExceptionSink* xsink);
161 
163 
168 typedef int (*q_dbi_commit_t)(Datasource* ds, ExceptionSink* xsink);
169 
171 
176 typedef int (*q_dbi_rollback_t)(Datasource* ds, ExceptionSink* xsink);
177 
179 
185 
187 
193 
195 
200 typedef AbstractQoreNode* (*q_dbi_get_server_version_t)(Datasource* ds, ExceptionSink* xsink);
201 
203 
208 typedef AbstractQoreNode* (*q_dbi_get_client_version_t)(const Datasource* ds, ExceptionSink* xsink);
209 
210 // FIXME: document
212 
214 typedef int (*q_dbi_stmt_prepare_t)(SQLStatement* stmt, const QoreString& str, const QoreListNode* args, ExceptionSink* xsink);
215 
217 
219 typedef int (*q_dbi_stmt_prepare_raw_t)(SQLStatement* stmt, const QoreString& str, ExceptionSink* xsink);
220 
222 
224 typedef int (*q_dbi_stmt_bind_t)(SQLStatement* stmt, const QoreListNode& l, ExceptionSink* xsink);
225 
227 
229 typedef int (*q_dbi_stmt_exec_t)(SQLStatement* stmt, ExceptionSink* xsink);
230 
232 
235 
237 
239 typedef QoreHashNode* (*q_dbi_stmt_get_output_t)(SQLStatement* stmt, ExceptionSink* xsink);
240 
242 
244 typedef QoreHashNode* (*q_dbi_stmt_get_output_rows_t)(SQLStatement* stmt, ExceptionSink* xsink);
245 
246 typedef int (*q_dbi_stmt_define_t)(SQLStatement* stmt, ExceptionSink* xsink);
247 typedef QoreHashNode* (*q_dbi_stmt_fetch_row_t)(SQLStatement* stmt, ExceptionSink* xsink);
248 typedef QoreHashNode* (*q_dbi_stmt_fetch_columns_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
249 typedef QoreListNode* (*q_dbi_stmt_fetch_rows_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
250 typedef bool (*q_dbi_stmt_next_t)(SQLStatement* stmt, ExceptionSink* xsink);
251 typedef int (*q_dbi_stmt_close_t)(SQLStatement* stmt, ExceptionSink* xsink);
252 
253 typedef int (*q_dbi_option_set_t)(Datasource* ds, const char* opt, const AbstractQoreNode* val, ExceptionSink* xsink);
254 typedef AbstractQoreNode* (*q_dbi_option_get_t)(const Datasource* ds, const char* opt);
255 
256 #define DBI_OPT_NUMBER_OPT "optimal-numbers"
257 #define DBI_OPT_NUMBER_STRING "string-numbers"
258 #define DBI_OPT_NUMBER_NUMERIC "numeric-numbers"
259 #define DBI_OPT_TIMEZONE "timezone"
260 
261 
262 
265  friend struct qore_dbi_mlist_private;
266 
267 private:
268  struct qore_dbi_mlist_private* priv; // private implementation
269 
270  // not implemented
272  DLLLOCAL qore_dbi_method_list& operator=(const qore_dbi_method_list&);
273 
274 public:
275  DLLEXPORT qore_dbi_method_list();
276  DLLEXPORT ~qore_dbi_method_list();
277 
278  // covers open, commit, rollback, and begin transaction
279  DLLEXPORT void add(int code, q_dbi_open_t method);
280  // for close
281  DLLEXPORT void add(int code, q_dbi_close_t method);
282  // covers select, select_rows, and exec
283  DLLEXPORT void add(int code, q_dbi_select_t method);
284  // covers select_row
285  DLLEXPORT void add(int code, q_dbi_select_row_t method);
286  // covers execRaw
287  DLLEXPORT void add(int code, q_dbi_execraw_t method);
288  // covers get_server_version
289  DLLEXPORT void add(int code, q_dbi_get_server_version_t method);
290  // covers get_client_version
291  DLLEXPORT void add(int code, q_dbi_get_client_version_t method);
292 
293  // covers prepare
294  DLLEXPORT void add(int code, q_dbi_stmt_prepare_t method);
295  // covers prepare_raw
296  DLLEXPORT void add(int code, q_dbi_stmt_prepare_raw_t method);
297  // covers bind, bind_placeholders, bind_values
298  DLLEXPORT void add(int code, q_dbi_stmt_bind_t method);
299  // covers exec, close, affected_rows, and define
300  DLLEXPORT void add(int code, q_dbi_stmt_exec_t method);
301  // covers fetch_row, get_output, and get_output_rows
302  DLLEXPORT void add(int code, q_dbi_stmt_fetch_row_t method);
303  // covers fetch_columns
304  DLLEXPORT void add(int code, q_dbi_stmt_fetch_columns_t method);
305  // covers fetch_rows
306  DLLEXPORT void add(int code, q_dbi_stmt_fetch_rows_t method);
307  // covers next
308  DLLEXPORT void add(int code, q_dbi_stmt_next_t method);
309 
310  // covers set option
311  DLLEXPORT void add(int code, q_dbi_option_set_t method);
312  // covers get option
313  DLLEXPORT void add(int code, q_dbi_option_get_t method);
314 
315  // for registering valid options
316  DLLEXPORT void registerOption(const char* name, const char* desc, const QoreTypeInfo* type = 0);
317 };
318 
320 
325 class DBIDriver {
326  friend struct qore_dbi_private;
327 
328 private:
330  struct qore_dbi_private* priv;
331 
333  DLLLOCAL DBIDriver(const DBIDriver&);
335  DLLLOCAL DBIDriver& operator=(const DBIDriver&);
336 
337 public:
339 
342  DLLEXPORT const char* getName() const;
343 
345  DLLEXPORT bool hasStatementAPI() const;
346 
348 
354  DLLEXPORT QoreHashNode* getOptionHash() const;
355 
356  DLLLOCAL DBIDriver(struct qore_dbi_private* p);
357  DLLLOCAL ~DBIDriver();
358 };
359 
360 struct qore_dbi_dlist_private;
361 
363 
368 private:
370  struct qore_dbi_dlist_private *priv;
371 
372  DLLLOCAL DBIDriver* find_intern(const char* name) const;
373 
374 public:
376 
383  DLLEXPORT DBIDriver* registerDriver(const char* name, const qore_dbi_method_list &methods, int caps);
384 
386 
393  DLLEXPORT DBIDriver* find(const char* name) const;
394 
396 
404  DLLEXPORT DBIDriver* find(const char* name, ExceptionSink* xsink) const;
405 
406  DLLLOCAL DBIDriverList();
407  DLLLOCAL ~DBIDriverList();
408  DLLLOCAL QoreListNode* getDriverList() const;
409 };
410 
412 DLLEXPORT extern DBIDriverList DBI;
413 
415 DLLEXPORT QoreHashNode* parseDatasource(const char* ds, ExceptionSink* xsink);
416 
418 DLLEXPORT void DBI_concat_numeric(QoreString* str, const AbstractQoreNode* v);
419 
421 
424 DLLEXPORT int DBI_concat_string(QoreString* str, const AbstractQoreNode* v, ExceptionSink* xsink);
425 
426 #endif // _QORE_DBI_H