Qore Programming Language  1.7.0
Datasource.h
1 /* -*- mode: c++; indent-tabs-mode: nil -*- */
2 /*
3  Datasource.h
4 
5  Qore Programming Language
6 
7  Copyright (C) 2003 - 2022 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 hashdecl qore_ds_private;
58 
59 private:
60  hashdecl 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 
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 
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
this class provides the internal link to the database driver for Qore's DBI layer
Definition: DBI.h:353
the base class for accessing databases in Qore through a Qore DBI driver
Definition: Datasource.h:55
DLLLOCAL T & getPrivateDataRef() const
returns the private DBI-specific data structure for this object
Definition: Datasource.h:209
DLLEXPORT void setDBEncoding(const char *name)
sets the database-specific character encoding name used for the current connection
DLLEXPORT QoreStringNode * getPendingDBEncoding() const
returns the pending database-specific character encoding name for the next connection
DLLEXPORT void connectionRecovered(ExceptionSink *xsink)
should be called be the DBI driver to signify that the connection to the server has been recovered
DLLEXPORT void setEventQueue(Queue *q, QoreValue arg, ExceptionSink *xsink)
sets an event queue for datasource events
DLLEXPORT int setOption(const char *opt, const QoreValue val, ExceptionSink *xsink)
sets an option for the datasource
DLLEXPORT const std::string & getPasswordStr() const
returns the password used for the last connection
DLLEXPORT int open(ExceptionSink *xsink)
opens a connection to the database
DLLEXPORT bool isInTransaction() const
returns the transaction status flag
DLLEXPORT QoreStringNode * getConfigString() const
returns a string representing the configuration of the current object
DLLEXPORT void setPendingDBEncoding(const char *c)
sets the database-specific name of the character-encoding to be used for the next connection
DLLEXPORT QoreStringNode * getPendingDBName() const
returns the pending database (or schema) name for the next connection
DLLEXPORT int beginTransaction(ExceptionSink *xsink)
DLLLOCAL Datasource(DBIDriver *driver, DatasourceStatementHelper *dsh)
creates the object; internal only
DLLEXPORT void setPendingPassword(const char *p)
sets the password to be used for the next connection
DLLEXPORT void setTransactionStatus(bool)
sets the transaction status
DLLEXPORT Datasource * copy() const
returns a copy of this object with the same DBIDriver and pending connection values
DLLEXPORT QoreValue getOption(const char *opt, ExceptionSink *xsink)
Returns the current value for the given option.
DLLEXPORT void setPrivateData(void *data)
sets the private DBI-specific data structure for this object
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,...
DLLEXPORT const std::string & getUsernameStr() const
returns the username used for the last connection
DLLEXPORT QoreValue getClientVersion(ExceptionSink *xsink) const
executes the "get_client_version" function of the driver, if any, and returns the result
DLLEXPORT const char * getUsername() const
returns the username used for the last connection
DLLEXPORT const QoreEncoding * getQoreEncoding() const
returns the QoreEncoding pointer used for this connection
DLLEXPORT int beginImplicitTransaction(ExceptionSink *xsink)
calls the "begin_implicit_transaction" DBI method if it exists
DLLEXPORT void * getPrivateData() const
returns the private DBI-specific data structure for this object
DLLEXPORT const char * getPassword() const
returns the password used for the last connection
DLLEXPORT void reset(ExceptionSink *xsink)
closes and opens the connection
DLLEXPORT void setPendingUsername(const char *u)
sets the username to be used for the next connection
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,...
DLLEXPORT bool wasConnectionAborted() const
returns the connection aborted status
DLLEXPORT const std::string & getDBEncodingStr() const
returns the database-specific character encoding name used for the last connection
DLLEXPORT void setPendingHostName(const char *h)
sets the hostname to be used for the next connection
DLLEXPORT int autoCommit(ExceptionSink *xsink)
called from subclasses when releasing the transaction lock
DLLEXPORT void connectionLost(ExceptionSink *xsink)
should be called be the DBI driver to signify that the connection to the server has been lost
DLLEXPORT const char * getDBName() const
returns the database (or schema) name used for the last connection
DLLEXPORT const char * getDriverName() const
returns the name of the current DBI driver
DLLEXPORT int rollback(ExceptionSink *xsink)
rolls back the current transaction to the database
DLLEXPORT int getPort() const
returns the port number used for the last connection
DLLEXPORT void freeConnectionValues()
frees all connection values
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,...
DLLEXPORT QoreValue getServerVersion(ExceptionSink *xsink)
executes the "get_server_version" function of the driver, if any, and returns the result,...
DLLEXPORT void setPendingConnectionValues(const Datasource *other)
copies all pending connection values to another Datasource
DLLEXPORT const char * getDBEncoding() const
returns the database-specific character encoding name used for the last connection
DLLEXPORT const char * getOSEncoding() const
returns the OS (or Qore) character encoding name used for the last connection
DLLEXPORT const QoreHashNode * getConnectOptions() const
returns the valid options for this driver with descriptions and current values for the current dataso...
DLLEXPORT QoreHashNode * getOptionHash() const
returns the valid options for this driver with descriptions and current values for the current dataso...
DLLEXPORT QoreStringNode * getPendingPassword() const
returns the pending password for the next connection
DLLEXPORT bool activeTransaction() const
returns true if a transaction is in progress and DB commands have been issued since the transaction w...
DLLEXPORT const char * getHostName() const
returns the host name used for the last connection
DLLEXPORT int getCapabilities() const
returns the capability mask of the current driver
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
DLLEXPORT bool isOpen() const
returns true if the connection is currently open
DLLEXPORT int close()
closes the connection
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,...
DLLEXPORT const DBIDriver * getDriver() const
returns the DBIDriver pointer used for this object
DLLEXPORT QoreHashNode * getCurrentOptionHash() const
returns the options currently set for this object
DLLEXPORT void connectionAborted()
should be called by the DBIDriver if the connection to the server is lost
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,...
virtual DLLEXPORT ~Datasource()
the Datasource is closed if it's still open and the object is destroyed
DLLEXPORT QoreStringNode * getPendingUsername() const
returns the pending username for the next connection
DLLEXPORT void setPendingPort(int port)
sets the port number to be used for the next connection
DLLEXPORT const std::string & getHostNameStr() const
returns the host name used for the last connection
DLLEXPORT QoreListNode * getCapabilityList() const
returns a QoreListNode object of all capability strings of the current driver, the caller owns the re...
DLLEXPORT bool getAutoCommit() const
returns the autocommit status
DLLEXPORT void setConnectionValues()
copies pending values to current values
DLLEXPORT int commit(ExceptionSink *xsink)
commits the current transaction to the database
DLLEXPORT QoreObject * getSQLStatementObjectForResultSet(void *stmt_private_data)
returns an SQLStatement object representing a result set
DLLEXPORT int getPendingPort() const
returns the pending port number for the next connection
DLLEXPORT void setQoreEncoding(const QoreEncoding *enc)
sets the QoreEncoding used for this connection
DLLEXPORT void setPendingDBName(const char *d)
sets the database (or schema) name to be used for the next connection
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
DLLEXPORT QoreHashNode * getConfigHash() const
returns a hash representing the configuration of the current object
DLLEXPORT const std::string & getDBNameStr() const
returns the database (or schema) name used for the last connection
DLLEXPORT QoreStringNode * getPendingHostName() const
returns the pending host name for the next connection
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:48
defines string encoding functions in Qore
Definition: QoreEncoding.h:83
This is the hash or associative list container type in Qore, dynamically allocated only,...
Definition: QoreHashNode.h:50
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:52
the implementation of Qore's object data type, reference counted, dynamically-allocated only
Definition: QoreObject.h:60
Qore's string type supported by the QoreEncoding class.
Definition: QoreString.h:93
Qore's string value type, reference counted, dynamically-allocated only.
Definition: QoreStringNode.h:50
The main value class in Qore, designed to be passed by value.
Definition: QoreValue.h:275