| Qore Programming Language - C/C++ Library 1.0.8

Datasource.h
1 /* -*- mode: c++; indent-tabs-mode: nil -*- */
2 /*
3 Datasource.h
4
5 Qore Programming Language
6
7 Copyright (C) 2003 - 2020 Qore Technologies, s.r.o.
8
9 The Datasource class provides the low-level interface to Qore DBI drivers.
10
11 Permission is hereby granted, free of charge, to any person obtaining a
12 copy of this software and associated documentation files (the "Software"),
13 to deal in the Software without restriction, including without limitation
14 the rights to use, copy, modify, merge, publish, distribute, sublicense,
15 and/or sell copies of the Software, and to permit persons to whom the
16 Software is furnished to do so, subject to the following conditions:
17
18 The above copyright notice and this permission notice shall be included in
19 all copies or substantial portions of the Software.
20
21 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
26 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
27 DEALINGS IN THE SOFTWARE.
28
29 Note that the Qore library is released under a choice of three open-source
30 licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
31 information.
32 */
33
34 #ifndef _QORE_DATASOURCE_H
35
36 #define _QORE_DATASOURCE_H
37
38 #include <qore/QoreThreadLock.h>
39 #include <qore/QoreQueue.h>
40
41 #include <string>
42
43 class DBIDriver;
44 class DatasourceStatementHelper;
45
47
55 class Datasource {
56 friend class QoreSQLStatement;
57 friend struct qore_ds_private;
58
59 private:
60 struct qore_ds_private *priv; // private implementation
61
63 Datasource& operator=(const Datasource&) = delete;
64
66 DLLLOCAL QoreValue exec_internal(bool doBind, const QoreString* query_str, const QoreListNode* args, ExceptionSink* xsink);
67
68 protected:
70 DLLEXPORT void freeConnectionValues();
71
73 DLLEXPORT void setConnectionValues();
74
76 DLLEXPORT void setTransactionStatus(bool);
77
79 DLLEXPORT void setPendingConnectionValues(const Datasource* other);
80
82 DLLEXPORT int beginImplicitTransaction(ExceptionSink* xsink);
83
84 public:
86
92 DLLLOCAL Datasource(DBIDriver* driver, DatasourceStatementHelper* dsh);
93
95
101 DLLLOCAL Datasource(const Datasource& old, DatasourceStatementHelper* dsh);
102
104
109 DLLEXPORT Datasource(DBIDriver* driver);
110
112 /*
113 @deprecated do not use
114 */
115 DLLEXPORT Datasource(const Datasource& old);
116
118 DLLEXPORT virtual ~Datasource();
119
121
124 DLLEXPORT bool getAutoCommit() const;
125
127
130 DLLEXPORT const char* getUsername() const;
131
133
136 DLLEXPORT const char* getPassword() const;
137
139
142 DLLEXPORT const char* getDBName() const;
143
145
148 DLLEXPORT const char* getDBEncoding() const;
149
151
154 DLLEXPORT const char* getOSEncoding() const;
155
157
160 DLLEXPORT const char* getHostName() const;
161
163
166 DLLEXPORT int getPort() const;
167
169
172 DLLEXPORT const std::string& getUsernameStr() const;
173
175
178 DLLEXPORT const std::string& getPasswordStr() const;
179
181
184 DLLEXPORT const std::string& getDBNameStr() const;
185
187
190 DLLEXPORT const std::string& getDBEncodingStr() const;
191
193
196 DLLEXPORT const std::string& getHostNameStr() const;
197
199 DLLEXPORT void* getPrivateData() const;
200
202 template <typename T>
203 DLLLOCAL T* getPrivateData() const {
204 return reinterpret_cast<T*>(getPrivateData());
205 }
206
208 template <typename T>
209 DLLLOCAL T& getPrivateDataRef() const {
210 return *getPrivateData<T>();
211 }
212
214
217 DLLEXPORT void setPrivateData(void* data);
218
220
223 DLLEXPORT void setDBEncoding(const char* name);
224
226 DLLEXPORT const QoreEncoding* getQoreEncoding() const;
227
229
232 DLLEXPORT void setQoreEncoding(const QoreEncoding* enc);
233
235
238 DLLEXPORT void setQoreEncoding(const char* name);
239
241
244 DLLEXPORT void setPendingUsername(const char* u);
245
247
250 DLLEXPORT void setPendingPassword(const char* p);
251
253
256 DLLEXPORT void setPendingDBName(const char* d);
257
259
262 DLLEXPORT void setPendingDBEncoding(const char* c);
263
265
268 DLLEXPORT void setPendingHostName(const char* h);
269
271
274 DLLEXPORT void setPendingPort(int port);
275
276 DLLEXPORT void setAutoCommit(bool ac);
277
279
282 DLLEXPORT int open(ExceptionSink* xsink);
283
285
290 DLLEXPORT QoreValue select(const QoreString* query_str, const QoreListNode* args, ExceptionSink* xsink);
291
293
298 DLLEXPORT QoreValue selectRows(const QoreString* query_str, const QoreListNode* args, ExceptionSink* xsink);
299
301
308 DLLEXPORT QoreHashNode* selectRow(const QoreString* query_str, const QoreListNode* args, ExceptionSink* xsink);
309
311
318 DLLEXPORT QoreValue exec(const QoreString* query_str, const QoreListNode* args, ExceptionSink* xsink);
319
321
331 DLLEXPORT QoreValue execRaw(const QoreString* query_str, const QoreListNode* args, ExceptionSink* xsink);
332
334
341 DLLEXPORT QoreValue execRaw(const QoreString* query_str, ExceptionSink* xsink);
342
344
351 DLLEXPORT QoreHashNode* describe(const QoreString* query_str, const QoreListNode* args, ExceptionSink* xsink);
352
354
358 DLLEXPORT int commit(ExceptionSink* xsink);
359
361
365 DLLEXPORT int rollback(ExceptionSink* xsink);
366
368 DLLEXPORT int close();
369
371 DLLEXPORT void reset(ExceptionSink* xsink);
372
374
377 DLLEXPORT QoreListNode* getCapabilityList() const;
378
380
383 DLLEXPORT int getCapabilities() const;
384
386
388 DLLEXPORT QoreStringNode* getPendingUsername() const;
389
391
393 DLLEXPORT QoreStringNode* getPendingPassword() const;
394
396
398 DLLEXPORT QoreStringNode* getPendingDBName() const;
399
401
403 DLLEXPORT QoreStringNode* getPendingDBEncoding() const;
404
406
409 DLLEXPORT QoreStringNode* getPendingHostName() const;
410
412
415 DLLEXPORT int getPendingPort() const;
416
422 DLLEXPORT int beginTransaction(ExceptionSink* xsink);
423
425
428 DLLEXPORT bool isInTransaction() const;
429
431
435 DLLEXPORT bool activeTransaction() const;
436
438
441 DLLEXPORT bool isOpen() const;
442
444
447 DLLEXPORT Datasource* copy() const;
448
450 DLLEXPORT const char* getDriverName() const;
451
453
457 DLLEXPORT QoreValue getServerVersion(ExceptionSink* xsink);
458
460
464 DLLEXPORT QoreValue getClientVersion(ExceptionSink* xsink) const;
465
467
470 DLLEXPORT const DBIDriver* getDriver() const;
471
473
485 DLLEXPORT void connectionAborted();
486
488
503 DLLEXPORT void connectionAborted(ExceptionSink* xsink);
504
506
514 DLLEXPORT void connectionLost(ExceptionSink* xsink);
515
517
526 DLLEXPORT void connectionRecovered(ExceptionSink* xsink);
527
529
531 DLLEXPORT bool wasConnectionAborted() const;
532
534
538 DLLEXPORT int autoCommit(ExceptionSink* xsink);
539
541
548 DLLEXPORT QoreHashNode* getOptionHash() const;
549
551
557 DLLEXPORT QoreHashNode* getCurrentOptionHash() const;
558
560
568 DLLEXPORT int setOption(const char* opt, const QoreValue val, ExceptionSink* xsink);
569
571
578 DLLEXPORT QoreValue getOption(const char* opt, ExceptionSink* xsink);
579
581
589 DLLEXPORT const QoreHashNode* getConnectOptions() const;
590
592
595 DLLEXPORT QoreHashNode* getConfigHash() const;
596
598
602 DLLEXPORT QoreStringNode* getConfigString() const;
603
605
608 DLLEXPORT void setEventQueue(Queue* q, QoreValue arg, ExceptionSink* xsink);
609
611
613 DLLEXPORT QoreHashNode* getEventQueueHash(Queue*& q, int event_code) const;
614
616
622 DLLEXPORT QoreObject* getSQLStatementObjectForResultSet(void* stmt_private_data);
623 };
624
625 #endif // _QORE_DATASOURCE_H
Datasource::getPendingDBName
DLLEXPORT QoreStringNode * getPendingDBName() const
returns the pending database (or schema) name for the next connection
Datasource::setPendingConnectionValues
DLLEXPORT void setPendingConnectionValues(const Datasource *other)
copies all pending connection values to another Datasource
Datasource::getCurrentOptionHash
DLLEXPORT QoreHashNode * getCurrentOptionHash() const
returns the options currently set for this object
Datasource::select
DLLEXPORT QoreValue select(const QoreString *query_str, const QoreListNode *args, ExceptionSink *xsink)
executes SQL throught the "select" function of the DBI driver and returns the result, makes an implicit connection if necessary
Datasource::setPendingPort
DLLEXPORT void setPendingPort(int port)
sets the port number to be used for the next connection
Datasource::getDBNameStr
DLLEXPORT const std::string & getDBNameStr() const
returns the database (or schema) name used for the last connection
Datasource::copy
DLLEXPORT Datasource * copy() const
returns a copy of this object with the same DBIDriver and pending connection values ...
Datasource::getCapabilities
DLLEXPORT int getCapabilities() const
returns the capability mask of the current driver
Datasource::getDriverName
DLLEXPORT const char * getDriverName() const
returns the name of the current DBI driver
QoreEncoding
defines string encoding functions in Qore
Definition: QoreEncoding.h:83
Datasource::getPendingHostName
DLLEXPORT QoreStringNode * getPendingHostName() const
returns the pending host name for the next connection
Datasource::getSQLStatementObjectForResultSet
DLLEXPORT QoreObject * getSQLStatementObjectForResultSet(void *stmt_private_data)
returns an SQLStatement object representing a result set
Datasource::commit
DLLEXPORT int commit(ExceptionSink *xsink)
commits the current transaction to the database
Datasource::getPendingPort
DLLEXPORT int getPendingPort() const
returns the pending port number for the next connection
QoreHashNode
This is the hash or associative list container type in Qore, dynamically allocated only...
Definition: QoreHashNode.h:50
Datasource::~Datasource
virtual DLLEXPORT ~Datasource()
the Datasource is closed if it&#39;s still open and the object is destroyed
Datasource::setPendingUsername
DLLEXPORT void setPendingUsername(const char *u)
sets the username to be used for the next connection
Datasource::autoCommit
DLLEXPORT int autoCommit(ExceptionSink *xsink)
called from subclasses when releasing the transaction lock
Datasource::getOSEncoding
DLLEXPORT const char * getOSEncoding() const
returns the OS (or Qore) character encoding name used for the last connection
Datasource::getPort
DLLEXPORT int getPort() const
returns the port number used for the last connection
Datasource::isOpen
DLLEXPORT bool isOpen() const
returns true if the connection is currently open
Datasource::freeConnectionValues
DLLEXPORT void freeConnectionValues()
frees all connection values
Datasource::getPendingUsername
DLLEXPORT QoreStringNode * getPendingUsername() const
returns the pending username for the next connection
Datasource::selectRows
DLLEXPORT QoreValue selectRows(const QoreString *query_str, const QoreListNode *args, ExceptionSink *xsink)
executes SQL throught the "selectRows" function of the DBI driver and returns the result...
Datasource::setPendingHostName
DLLEXPORT void setPendingHostName(const char *h)
sets the hostname to be used for the next connection
Datasource::execRaw
DLLEXPORT QoreValue execRaw(const QoreString *query_str, const QoreListNode *args, ExceptionSink *xsink)
executes SQL throught the "execRaw" function of the DBI driver and returns the result, makes an implicit connection if necessary
Datasource::reset
DLLEXPORT void reset(ExceptionSink *xsink)
closes and opens the connection
Datasource::setEventQueue
DLLEXPORT void setEventQueue(Queue *q, QoreValue arg, ExceptionSink *xsink)
sets an event queue for datasource events
DBIDriver
this class provides the internal link to the database driver for Qore&#39;s DBI layer ...
Definition: DBI.h:353
Datasource::getClientVersion
DLLEXPORT QoreValue getClientVersion(ExceptionSink *xsink) const
executes the "get_client_version" function of the driver, if any, and returns the result ...
Datasource::getQoreEncoding
DLLEXPORT const QoreEncoding * getQoreEncoding() const
returns the QoreEncoding pointer used for this connection
Datasource::connectionRecovered
DLLEXPORT void connectionRecovered(ExceptionSink *xsink)
should be called be the DBI driver to signify that the connection to the server has been recovered ...
Datasource::setPendingDBName
DLLEXPORT void setPendingDBName(const char *d)
sets the database (or schema) name to be used for the next connection
Datasource::getDBEncoding
DLLEXPORT const char * getDBEncoding() const
returns the database-specific character encoding name used for the last connection ...
Datasource::getCapabilityList
DLLEXPORT QoreListNode * getCapabilityList() const
returns a QoreListNode object of all capability strings of the current driver, the caller owns the re...
Datasource::getHostNameStr
DLLEXPORT const std::string & getHostNameStr() const
returns the host name used for the last connection
Datasource::getDBEncodingStr
DLLEXPORT const std::string & getDBEncodingStr() const
returns the database-specific character encoding name used for the last connection ...
QoreString
Qore&#39;s string type supported by the QoreEncoding class.
Definition: QoreString.h:81
QoreStringNode
Qore&#39;s string value type, reference counted, dynamically-allocated only.
Definition: QoreStringNode.h:50
Datasource::exec
DLLEXPORT QoreValue exec(const QoreString *query_str, const QoreListNode *args, ExceptionSink *xsink)
executes SQL throught the "exec" function of the DBI driver and returns the result, makes an implicit connection if necessary
Datasource::beginTransaction
DLLEXPORT int beginTransaction(ExceptionSink *xsink)
Datasource::getPassword
DLLEXPORT const char * getPassword() const
returns the password used for the last connection
Datasource::getUsernameStr
DLLEXPORT const std::string & getUsernameStr() const
returns the username used for the last connection
Datasource::getConfigHash
DLLEXPORT QoreHashNode * getConfigHash() const
returns a hash representing the configuration of the current object
QoreListNode
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:52
Datasource::getPendingDBEncoding
DLLEXPORT QoreStringNode * getPendingDBEncoding() const
returns the pending database-specific character encoding name for the next connection ...
Datasource::activeTransaction
DLLEXPORT bool activeTransaction() const
returns true if a transaction is in progress and DB commands have been issued since the transaction w...
Datasource::setPendingPassword
DLLEXPORT void setPendingPassword(const char *p)
sets the password to be used for the next connection
Datasource::connectionAborted
DLLEXPORT void connectionAborted()
should be called by the DBIDriver if the connection to the server is lost
Datasource::getDriver
DLLEXPORT const DBIDriver * getDriver() const
returns the DBIDriver pointer used for this object
Datasource::getAutoCommit
DLLEXPORT bool getAutoCommit() const
returns the autocommit status
Datasource::rollback
DLLEXPORT int rollback(ExceptionSink *xsink)
rolls back the current transaction to the database
Datasource::describe
DLLEXPORT QoreHashNode * describe(const QoreString *query_str, const QoreListNode *args, ExceptionSink *xsink)
executes SQL that returns a result set and then returns a hash description of the result set ...
Datasource::setConnectionValues
DLLEXPORT void setConnectionValues()
copies pending values to current values
Datasource::setOption
DLLEXPORT int setOption(const char *opt, const QoreValue val, ExceptionSink *xsink)
sets an option for the datasource
Datasource::setQoreEncoding
DLLEXPORT void setQoreEncoding(const QoreEncoding *enc)
sets the QoreEncoding used for this connection
Datasource::getOptionHash
DLLEXPORT QoreHashNode * getOptionHash() const
returns the valid options for this driver with descriptions and current values for the current dataso...
Datasource
the base class for accessing databases in Qore through a Qore DBI driver
Definition: Datasource.h:55
Datasource::getPrivateData
DLLEXPORT void * getPrivateData() const
returns the private DBI-specific data structure for this object
Datasource::getPasswordStr
DLLEXPORT const std::string & getPasswordStr() const
returns the password used for the last connection
Datasource::connectionLost
DLLEXPORT void connectionLost(ExceptionSink *xsink)
should be called be the DBI driver to signify that the connection to the server has been lost ...
QoreValue
The main value class in Qore, designed to be passed by value.
Definition: QoreValue.h:267
QoreObject
the implementation of Qore&#39;s object data type, reference counted, dynamically-allocated only ...
Definition: QoreObject.h:60
ExceptionSink
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:48
Datasource::beginImplicitTransaction
DLLEXPORT int beginImplicitTransaction(ExceptionSink *xsink)
calls the "begin_implicit_transaction" DBI method if it exists
Datasource::wasConnectionAborted
DLLEXPORT bool wasConnectionAborted() const
returns the connection aborted status
Datasource::setPendingDBEncoding
DLLEXPORT void setPendingDBEncoding(const char *c)
sets the database-specific name of the character-encoding to be used for the next connection ...
Datasource::getConnectOptions
DLLEXPORT const QoreHashNode * getConnectOptions() const
returns the valid options for this driver with descriptions and current values for the current dataso...
Datasource::getConfigString
DLLEXPORT QoreStringNode * getConfigString() const
returns a string representing the configuration of the current object
Datasource::getUsername
DLLEXPORT const char * getUsername() const
returns the username used for the last connection
Datasource::getPendingPassword
DLLEXPORT QoreStringNode * getPendingPassword() const
returns the pending password for the next connection
Datasource::getPrivateDataRef
DLLLOCAL T & getPrivateDataRef() const
returns the private DBI-specific data structure for this object
Definition: Datasource.h:209
Datasource::selectRow
DLLEXPORT QoreHashNode * selectRow(const QoreString *query_str, const QoreListNode *args, ExceptionSink *xsink)
executes SQL throught the "selectRow" function of the DBI driver and returns the result, makes an implicit connection if necessary
Datasource::setTransactionStatus
DLLEXPORT void setTransactionStatus(bool)
sets the transaction status
Datasource::setPrivateData
DLLEXPORT void setPrivateData(void *data)
sets the private DBI-specific data structure for this object
Datasource::Datasource
DLLLOCAL Datasource(DBIDriver *driver, DatasourceStatementHelper *dsh)
creates the object; internal only
Datasource::open
DLLEXPORT int open(ExceptionSink *xsink)
opens a connection to the database
Datasource::getServerVersion
DLLEXPORT QoreValue getServerVersion(ExceptionSink *xsink)
executes the "get_server_version" function of the driver, if any, and returns the result...
Datasource::getEventQueueHash
DLLEXPORT QoreHashNode * getEventQueueHash(Queue *&q, int event_code) const
returns an event hash with only default information in it or 0 if no event queue is set ...
Datasource::setDBEncoding
DLLEXPORT void setDBEncoding(const char *name)
sets the database-specific character encoding name used for the current connection ...
Datasource::getDBName
DLLEXPORT const char * getDBName() const
returns the database (or schema) name used for the last connection
Datasource::getHostName
DLLEXPORT const char * getHostName() const
returns the host name used for the last connection
Datasource::getOption
DLLEXPORT QoreValue getOption(const char *opt, ExceptionSink *xsink)
Returns the current value for the given option.
Datasource::close
DLLEXPORT int close()
closes the connection
Datasource::isInTransaction
DLLEXPORT bool isInTransaction() const
returns the transaction status flag