Qore Programming Language 0.8.8

- Main Page
- Related Pages
- Modules
- Classes
- Files

- File List
- File Members

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
184 typedef int (*q_dbi_begin_transaction_t)(Datasource* ds, ExceptionSink* xsink);
185
187
192 typedef int (*q_dbi_abort_transaction_start_t)(Datasource* ds, ExceptionSink* xsink);
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
234 typedef int (*q_dbi_stmt_affected_rows_t)(SQLStatement* stmt, ExceptionSink* xsink);
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
264 class qore_dbi_method_list {
265 friend struct qore_dbi_mlist_private;
266
267 private:
268 struct qore_dbi_mlist_private* priv; // private implementation
269
270 // not implemented
271 DLLLOCAL qore_dbi_method_list(const qore_dbi_method_list&);
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
367 class DBIDriverList {
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
q_dbi_open_t
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:103
q_dbi_get_client_version_t
AbstractQoreNode *(* q_dbi_get_client_version_t)(const Datasource *ds, ExceptionSink *xsink)
signature for the &quot;get_client_version&quot; method
Definition: DBI.h:208
QoreHashNode
This is the hash or associative list container type in Qore, dynamically allocated only...
Definition: QoreHashNode.h:41
AbstractQoreNode
The base class for all value and parse types in Qore expression trees.
Definition: AbstractQoreNode.h:47
q_dbi_select_row_t
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:141
QoreNamespace
contains constants, classes, and subnamespaces in QoreProgram objects
Definition: QoreNamespace.h:50
DBIDriver
this class provides the internal link to the database driver for Qore&#39;s DBI layer ...
Definition: DBI.h:325
DBIDriver::hasStatementAPI
DLLEXPORT bool hasStatementAPI() const
returns true if the driver supports the statement API
q_dbi_abort_transaction_start_t
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:192
DBIDriver::getOptionHash
DLLEXPORT QoreHashNode * getOptionHash() const
returns the valid options for this driver with descriptions
QoreString
Qore&#39;s string type supported by the QoreEncoding class.
Definition: QoreString.h:42
q_dbi_rollback_t
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:176
q_dbi_execraw_t
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:160
q_dbi_stmt_bind_t
int(* q_dbi_stmt_bind_t)(SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink)
bind input values and optionally describe output parameters
Definition: DBI.h:224
QoreListNode
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:44
DBI
DLLEXPORT DBIDriverList DBI
list of DBI drivers currently reigsted by the Qore library
q_dbi_close_t
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:110
Datasource
the base class for accessing databases in Qore through a Qore DBI driver
Definition: Datasource.h:45
q_dbi_get_server_version_t
AbstractQoreNode *(* q_dbi_get_server_version_t)(Datasource *ds, ExceptionSink *xsink)
signature for the &quot;get_server_version&quot; method
Definition: DBI.h:200
DBIDriver::getName
DLLEXPORT const char * getName() const
this is the only public exported function available in this class
qore_dbi_method_list
this is the data structure Qore DBI drivers will use to pass the supported DBI methods ...
Definition: DBI.h:264
SQLStatement
This is the public class for DBI drivers supporting Qore&#39;s new prepared statement API...
Definition: SQLStatement.h:32
q_dbi_commit_t
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:168
ExceptionSink
container for holding Qore-language exception information and also for registering a &quot;thread_exit&quot; ca...
Definition: ExceptionSink.h:35
q_dbi_select_t
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:120
DBIDriverList::registerDriver
DLLEXPORT DBIDriver * registerDriver(const char *name, const qore_dbi_method_list &methods, int caps)
registers a new DBI driver
q_dbi_begin_transaction_t
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:184
q_dbi_stmt_exec_t
int(* q_dbi_stmt_exec_t)(SQLStatement *stmt, ExceptionSink *xsink)
execute statement
Definition: DBI.h:229
DBIDriverList
this class is used to register and find DBI drivers loaded in qore
Definition: DBI.h:367
q_dbi_stmt_prepare_raw_t
int(* q_dbi_stmt_prepare_raw_t)(SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink)
prepare statement with no bind parsing
Definition: DBI.h:219
q_dbi_stmt_affected_rows_t
int(* q_dbi_stmt_affected_rows_t)(SQLStatement *stmt, ExceptionSink *xsink)
get number of affected rows
Definition: DBI.h:234
parseDatasource
DLLEXPORT QoreHashNode * parseDatasource(const char *ds, ExceptionSink *xsink)
parses a datasource string and returns a hash of the component parts
DBI_concat_numeric
DLLEXPORT void DBI_concat_numeric(QoreString *str, const AbstractQoreNode *v)
concatenates a numeric value to the QoreString from the QoreNode
DBIDriverList::find
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...
q_dbi_stmt_prepare_t
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:214
DBI_concat_string
DLLEXPORT int DBI_concat_string(QoreString *str, const AbstractQoreNode *v, ExceptionSink *xsink)
concatenates a string value to the QoreString from the AbstractQoreNode