All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Datasource Class Reference

the base class for accessing databases in Qore through a Qore DBI driver More...

`#include <Datasource.h>`

## Public Member Functions

DLLEXPORT | Datasource (DBIDriver *driver)
| creates the object and binds it to a particular DBIDriver
DLLEXPORT | Datasource (const Datasource &old)
| copy constructor
virtual DLLEXPORT | ~Datasource ()
| the Datasource is closed if it's still open and the object is destroyed
DLLEXPORT bool | getAutoCommit () const
| returns the autocommit status
DLLEXPORT const char * | getUsername () const
| returns the username used for the last connection
DLLEXPORT const char * | getPassword () const
| returns the password used for the last connection
DLLEXPORT const char * | getDBName () const
| returns the database (or schema) name used for the last connection
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 char * | getHostName () const
| returns the host name used for the last connection
DLLEXPORT int | getPort () const
| returns the port number used for the last connection
DLLEXPORT const std::string & | getUsernameStr () const
| returns the username used for the last connection
DLLEXPORT const std::string & | getPasswordStr () const
| returns the password used for the last connection
DLLEXPORT const std::string & | getDBNameStr () const
| returns the database (or schema) name used for the last connection
DLLEXPORT const std::string & | getDBEncodingStr () const
| returns the database-specific character encoding name used for the last connection
DLLEXPORT const std::string & | getHostNameStr () const
| returns the host name used for the last connection
DLLEXPORT void * | getPrivateData () const
| returns the private DBI-specific data structure for this object
template<typename T >
DLLLOCAL T * | getPrivateData () const
| returns the private DBI-specific data structure for this object
template<typename T >
DLLLOCAL T & | getPrivateDataRef () const
| returns the private DBI-specific data structure for this object
DLLEXPORT void | setPrivateData (void *data)
| sets the private DBI-specific data structure for this object
DLLEXPORT void | setDBEncoding (const char *name)
| sets the database-specific character encoding name used for the current connection
DLLEXPORT const QoreEncoding * | getQoreEncoding () const
| returns the QoreEncoding pointer used for this connection
DLLEXPORT void | setQoreEncoding (const QoreEncoding *enc)
| sets the QoreEncoding used for this connection
DLLEXPORT void | setQoreEncoding (const char *name)
| sets the name for the QoreEncoding used for this connection
DLLEXPORT void | setPendingUsername (const char *u)
| sets the username to be used for the next connection
DLLEXPORT void | setPendingPassword (const char *p)
| sets the password to be used for the next connection
DLLEXPORT void | setPendingDBName (const char *d)
| sets the database (or schema) name to be used for the next connection
DLLEXPORT void | setPendingDBEncoding (const char *c)
| sets the database-specific name of the character-encoding to be used for the next connection
DLLEXPORT void | setPendingHostName (const char *h)
| sets the hostname to be used for the next connection
DLLEXPORT void | setPendingPort (int port)
| sets the port number to be used for the next connection
DLLEXPORT int | open (ExceptionSink *xsink)
| opens a connection to the database
DLLEXPORT AbstractQoreNode * | 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
DLLEXPORT AbstractQoreNode * | selectRows (const QoreString *query_str, const QoreListNode *args, ExceptionSink *xsink)
| executes SQL throught the "selectRows" function of the DBI driver and returns the result, makes an implicit connection if necessary
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
DLLEXPORT AbstractQoreNode * | 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
DLLEXPORT AbstractQoreNode * | 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
DLLEXPORT AbstractQoreNode * | execRaw (const QoreString *query_str, ExceptionSink *xsink)
| executes SQL throught the "execRaw" function of the DBI driver and returns the result, makes an implicit connection if necessary
DLLEXPORT int | commit (ExceptionSink *xsink)
| commits the current transaction to the database
DLLEXPORT int | rollback (ExceptionSink *xsink)
| rolls back the current transaction to the database
DLLEXPORT int | close ()
| closes the connection
DLLEXPORT void | reset (ExceptionSink *xsink)
| closes and opens the connection
DLLEXPORT QoreListNode * | getCapabilityList () const
| returns a QoreListNode object of all capability strings of the current driver, the caller owns the reference count in the object returned
DLLEXPORT int | getCapabilities () const
| returns the capability mask of the current driver
DLLEXPORT QoreStringNode * | getPendingUsername () const
| returns the pending username for the next connection
DLLEXPORT QoreStringNode * | getPendingPassword () const
| returns the pending password for the next connection
DLLEXPORT QoreStringNode * | getPendingDBName () const
| returns the pending database (or schema) name for the next connection
DLLEXPORT QoreStringNode * | getPendingDBEncoding () const
| returns the pending database-specific character encoding name for the next connection
DLLEXPORT QoreStringNode * | getPendingHostName () const
| returns the pending host name for the next connection
DLLEXPORT int | getPendingPort () const
| returns the pending port number for the next connection
DLLEXPORT int | beginTransaction (ExceptionSink *xsink)
DLLEXPORT bool | isInTransaction () const
| returns the transaction status flag
DLLEXPORT bool | activeTransaction () const
| returns true if a transaction is in progress and DB commands have been issued since the transaction was started
DLLEXPORT bool | isOpen () const
| returns true if the connection is currently open
DLLEXPORT Datasource * | copy () const
| returns a copy of this object with the same DBIDriver and pending connection values
DLLEXPORT const char * | getDriverName () const
| returns the name of the current DBI driver
DLLEXPORT AbstractQoreNode * | getServerVersion (ExceptionSink *xsink)
| executes the "get_server_version" function of the driver, if any, and returns the result, makes an implicit connection if necessary
DLLEXPORT AbstractQoreNode * | getClientVersion (ExceptionSink *xsink) const
| executes the "get_client_version" function of the driver, if any, and returns the result
DLLEXPORT const DBIDriver * | getDriver () const
| returns the DBIDriver pointer used for this object
DLLEXPORT void | connectionAborted ()
| should be called by the DBIDriver if the connection to the server is lost
DLLEXPORT bool | wasConnectionAborted () const
| returns the connection aborted status
DLLEXPORT int | autoCommit (ExceptionSink *xsink)
| called from subclasses when releasing the transaction lock
DLLEXPORT QoreHashNode * | getOptionHash () const
| returns the valid options for this driver with descriptions and current values for the current datasource
DLLEXPORT int | setOption (const char *opt, const AbstractQoreNode *val, ExceptionSink *xsink)
| sets an option for the datasource
DLLEXPORT AbstractQoreNode * | getOption (const char *opt, ExceptionSink *xsink)
| Returns the current value for the given option.
DLLEXPORT const QoreHashNode * | getConnectOptions () const
| returns the valid options for this driver with descriptions and current values for the current datasource

## Protected Member Functions

DLLEXPORT void | freeConnectionValues ()
| frees all connection values
DLLEXPORT void | setConnectionValues ()
| copies pending values to current values
DLLEXPORT void | setTransactionStatus (bool)
| sets the transaction status
DLLEXPORT void | setPendingConnectionValues (const Datasource *other)
| copies all pending connection values to another Datasource
DLLEXPORT int | beginImplicitTransaction (ExceptionSink *xsink)
| calls the "begin_implicit_transaction" DBI method if it exists

## Detailed Description

the base class for accessing databases in Qore through a Qore DBI driver

This class is not thread-safe or even thread-aware. Thread safety and thread resource management is implemented in higher-level classes such as ManagedDatasource and DatasourcePool (classes are currently internal)

Two copies of connection values are kept in case the values are changed while a connection is in use.

See Also
  DBIDriver

## Constructor & Destructor Documentation

DLLEXPORT Datasource::Datasource | ( | DBIDriver * | driver | ) |

creates the object and binds it to a particular DBIDriver

Parameters

  driver | the DBIDriver object to use for the connection

## Member Function Documentation

DLLEXPORT bool Datasource::activeTransaction | ( |  | ) | const

returns true if a transaction is in progress and DB commands have been issued since the transaction was started

note that this function will return false if the transaction was started with beginTransaction() and no DB commands have been issued since then

Returns
  true if a transaction is in progress and DB commands have been issued since the transaction was started

DLLEXPORT int Datasource::autoCommit | ( | ExceptionSink * | xsink | ) |

called from subclasses when releasing the transaction lock

Calls the DBI driver's "commit" method if autocommit is enabled and the current connection was not lost and the driver requires a commit this function is not "const" to allow for implicit connections (and reconnections)

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here

DLLEXPORT int Datasource::beginTransaction | ( | ExceptionSink * | xsink | ) |

sets the "in_transaction" flag to true if autocommit is not set throws an exception if autocommit is true

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  -1 for error, 0 for OK

DLLEXPORT int Datasource::commit | ( | ExceptionSink * | xsink | ) |

commits the current transaction to the database

Calls the DBI driver's "commit" method. this function is not "const" to allow for implicit connections (and reconnections)

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here

DLLEXPORT void Datasource::connectionAborted | ( |  | ) |

should be called by the DBIDriver if the connection to the server is lost

The DBIDriver should raise its own exception when this call is made, as making this call will suppress further Qore exceptions from being raised in the Datasource destructor (at least for derived classes)

DLLEXPORT Datasource* Datasource::copy | ( |  | ) | const

returns a copy of this object with the same DBIDriver and pending connection values

return a copy of this object

DLLEXPORT AbstractQoreNode* Datasource::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

The "in_transaction" flag will be set to true if this method executes without throwing an exception and the object was not already in a transaction. this function is not "const" to allow for implicit connections (and reconnections)

Parameters

  query_str | the qurey to execute
  args | query arguments for s, n, d placeholders
  xsink | if an error occurs, the Qore-language exception information will be added here

DLLEXPORT AbstractQoreNode* Datasource::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

The "in_transaction" flag will be set to true if this method executes without throwing an exception and the object was not already in a transaction. this function is not "const" to allow for implicit connections (and reconnections)

Parameters

  query_str | the qurey to execute
  args | this argument is ignored
  xsink | if an error occurs, the Qore-language exception information will be added here

Deprecated:
  this function will be removed in the next major version of the Qore library due to the inclusion of the extraneous and ignored args parameter

DLLEXPORT AbstractQoreNode* Datasource::execRaw | ( | const QoreString * | query_str,
|  | ExceptionSink * | xsink
| ) |  |

executes SQL throught the "execRaw" function of the DBI driver and returns the result, makes an implicit connection if necessary

The "in_transaction" flag will be set to true if this method executes without throwing an exception and the object was not already in a transaction. this function is not "const" to allow for implicit connections (and reconnections)

Parameters

  query_str | the qurey to execute
  xsink | if an error occurs, the Qore-language exception information will be added here

DLLEXPORT bool Datasource::getAutoCommit | ( |  | ) | const

returns the autocommit status

Returns
  the autocommit status of the object

DLLEXPORT int Datasource::getCapabilities | ( |  | ) | const

returns the capability mask of the current driver

Returns
  the capability mask of the current driver

DLLEXPORT QoreListNode* Datasource::getCapabilityList | ( |  | ) | const

returns a QoreListNode object of all capability strings of the current driver, the caller owns the reference count in the object returned

Returns
  list of capability strings of the driver

DLLEXPORT AbstractQoreNode* Datasource::getClientVersion | ( | ExceptionSink * | xsink | ) | const

executes the "get_client_version" function of the driver, if any, and returns the result

the caller owns the AbstractQoreNode pointer's reference count returned (if the pointer is not 0)

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here

DLLEXPORT const QoreHashNode* Datasource::getConnectOptions | ( |  | ) | const

returns the valid options for this driver with descriptions and current values for the current datasource

Returns
  a hash where the keys are valid option names, and the values are hashes with the following keys:
  - `"desc"`: a string description of the option
  - `"type"`: a string giving the data type restriction for the option
  - `"value"`: the current value of the option

This function returns the same value as getOptionHash() but the caller should not modify the value returned, also this function is meant to be used during the open() call to read any options that may be relevant for opening a new connection

DLLEXPORT const char* Datasource::getDBEncoding | ( |  | ) | const

returns the database-specific character encoding name used for the last connection

Returns
  the database-specific character encoding name used for the last connection

DLLEXPORT const std::string& Datasource::getDBEncodingStr | ( |  | ) | const

returns the database-specific character encoding name used for the last connection

Returns
  the database-specific character encoding name used for the last connection

DLLEXPORT const char* Datasource::getDBName | ( |  | ) | const

returns the database (or schema) name used for the last connection

Returns
  the database (or schema) name used for the last connection (or 0 if none)

DLLEXPORT const std::string& Datasource::getDBNameStr | ( |  | ) | const

returns the database (or schema) name used for the last connection

Returns
  the database (or schema) name used for the last connection (or 0 if none)

DLLEXPORT const DBIDriver* Datasource::getDriver | ( |  | ) | const

returns the DBIDriver pointer used for this object

Returns
  the DBIDriver pointer used for this object

DLLEXPORT const char* Datasource::getHostName | ( |  | ) | const

returns the host name used for the last connection

Returns
  the host name used for the last connection (or 0 if none)

DLLEXPORT const std::string& Datasource::getHostNameStr | ( |  | ) | const

returns the host name used for the last connection

Returns
  the host name used for the last connection (or 0 if none)

DLLEXPORT AbstractQoreNode* Datasource::getOption | ( | const char * | opt,
|  | ExceptionSink * | xsink
| ) |  |

Returns the current value for the given option.

Parameters

  opt | the option to get
  xsink | if any errors are raised (invalid option, etc), the exception info is raised here

The caller owns the reference count for the value returned

Note
  this function is only safe to call when a connection is established

DLLEXPORT QoreHashNode* Datasource::getOptionHash | ( |  | ) | const

returns the valid options for this driver with descriptions and current values for the current datasource

Returns
  a hash where the keys are valid option names, and the values are hashes with the following keys:
  - `"desc"`: a string description of the option
  - `"type"`: a string giving the data type restriction for the option
  - `"value"`: the current value of the option

The caller owns the reference count for the hash returned

DLLEXPORT const char* Datasource::getOSEncoding | ( |  | ) | const

returns the OS (or Qore) character encoding name used for the last connection

Returns
  the OS (or Qore) character encoding name used for the last connection

DLLEXPORT const char* Datasource::getPassword | ( |  | ) | const

returns the password used for the last connection

Returns
  the password used for the last connection (or 0 if none)

DLLEXPORT const std::string& Datasource::getPasswordStr | ( |  | ) | const

returns the password used for the last connection

Returns
  the password used for the last connection (or 0 if none)

DLLEXPORT QoreStringNode* Datasource::getPendingDBEncoding | ( |  | ) | const

returns the pending database-specific character encoding name for the next connection

caller owns the AbstractQoreNode pointer's reference count returned

DLLEXPORT QoreStringNode* Datasource::getPendingDBName | ( |  | ) | const

returns the pending database (or schema) name for the next connection

caller owns the AbstractQoreNode pointer's reference count returned

DLLEXPORT QoreStringNode* Datasource::getPendingHostName | ( |  | ) | const

returns the pending host name for the next connection

caller owns the AbstractQoreNode pointer's reference count returned

Returns
  the pending host name for the next connection

DLLEXPORT QoreStringNode* Datasource::getPendingPassword | ( |  | ) | const

returns the pending password for the next connection

caller owns the AbstractQoreNode pointer's reference count returned

DLLEXPORT int Datasource::getPendingPort | ( |  | ) | const

returns the pending port number for the next connection

Returns
  the pending port number used for the next connection

DLLEXPORT QoreStringNode* Datasource::getPendingUsername | ( |  | ) | const

returns the pending username for the next connection

caller owns the AbstractQoreNode pointer's reference count returned

DLLEXPORT int Datasource::getPort | ( |  | ) | const

returns the port number used for the last connection

Returns
  the port number used for the last connection

DLLEXPORT AbstractQoreNode* Datasource::getServerVersion | ( | ExceptionSink * | xsink | ) |

executes the "get_server_version" function of the driver, if any, and returns the result, makes an implicit connection if necessary

the caller owns the AbstractQoreNode pointer's reference count returned (if the pointer is not 0) this function is not "const" to allow for implicit connections (and reconnections)

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here

DLLEXPORT const char* Datasource::getUsername | ( |  | ) | const

returns the username used for the last connection

Returns

DLLEXPORT const std::string& Datasource::getUsernameStr | ( |  | ) | const

returns the username used for the last connection

Returns

DLLEXPORT bool Datasource::isInTransaction | ( |  | ) | const

returns the transaction status flag

Returns
  the transaction status flag

DLLEXPORT bool Datasource::isOpen | ( |  | ) | const

returns true if the connection is currently open

Returns
  the connection status (true if open)

DLLEXPORT int Datasource::open | ( | ExceptionSink * | xsink | ) |

opens a connection to the database

calls the DBI driver's "open" method

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here

DLLEXPORT int Datasource::rollback | ( | ExceptionSink * | xsink | ) |

rolls back the current transaction to the database

Calls the DBI driver's "rollback" method. this function is not "const" to allow for implicit connections (and reconnections)

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here

DLLEXPORT AbstractQoreNode* Datasource::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

this function is not "const" to allow for implicit connections (and reconnections)

Parameters

  query_str | the qurey to execute
  args | query arguments for s, n, d placeholders
  xsink | if an error occurs, the Qore-language exception information will be added here

DLLEXPORT QoreHashNode* Datasource::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

This function is not "const" to allow for implicit connections (and reconnections). An exception will be thrown by the DBI driver if the query returns more than 1 row of data.

Parameters

  query_str | the qurey to execute
  args | query arguments for s, n, d placeholders
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  the row data returned or 0

DLLEXPORT AbstractQoreNode* Datasource::selectRows | ( | const QoreString * | query_str,
|  | const QoreListNode * | args,
|  | ExceptionSink * | xsink
| ) |  |

executes SQL throught the "selectRows" function of the DBI driver and returns the result, makes an implicit connection if necessary

this function is not "const" to allow for implicit connections (and reconnections)

Parameters

  query_str | the qurey to execute
  args | query arguments for s, n, d placeholders
  xsink | if an error occurs, the Qore-language exception information will be added here

DLLEXPORT void Datasource::setDBEncoding | ( | const char * | name | ) |

sets the database-specific character encoding name used for the current connection

this function should only be called by the DBI driver when a connection is established

Parameters

  name | the database-specific character encoding name used for the current connection

DLLEXPORT int Datasource::setOption | ( | const char * | opt,
|  | const AbstractQoreNode * | val,
|  | ExceptionSink * | xsink
| ) |  |

sets an option for the datasource

Parameters

  opt | the option to set
  val | the value to set
  xsink | if any errors are raised (invalid option, etc), the exception info is raised here

Returns
  -1 for error (exception raised), 0 for OK

DLLEXPORT void Datasource::setPendingDBEncoding | ( | const char * | c | ) |

sets the database-specific name of the character-encoding to be used for the next connection

Parameters

  c | the database-specific name of the character-encoding to be used for the next connection

DLLEXPORT void Datasource::setPendingDBName | ( | const char * | d | ) |

sets the database (or schema) name to be used for the next connection

Parameters

  d | the database (or schema) name to be used for the next connection

DLLEXPORT void Datasource::setPendingHostName | ( | const char * | h | ) |

sets the hostname to be used for the next connection

Parameters

  h | the hostname to be used for the next connection

DLLEXPORT void Datasource::setPendingPassword | ( | const char * | p | ) |

sets the password to be used for the next connection

Parameters

  p | the password to be used for the next connection

DLLEXPORT void Datasource::setPendingPort | ( | int | port | ) |

sets the port number to be used for the next connection

Parameters

  port | the port number to be used for the next connection

DLLEXPORT void Datasource::setPendingUsername | ( | const char * | u | ) |

sets the username to be used for the next connection

Parameters

  u | the username to be used for the next connection

DLLEXPORT void Datasource::setPrivateData | ( | void * | data | ) |

sets the private DBI-specific data structure for this object

this should only be called once in the actual DBI driver code

Parameters

  data | the data for the DBI driver that holds the driver-specific state of the connection

DLLEXPORT void Datasource::setQoreEncoding | ( | const QoreEncoding * | enc | ) |

sets the QoreEncoding used for this connection

this function should only be called by the DBI driver when a connection is established

Parameters

  enc | the QoreEncoding used for the current connection

DLLEXPORT void Datasource::setQoreEncoding | ( | const char * | name | ) |

sets the name for the QoreEncoding used for this connection

this function should only be called by the DBI driver when a connection is established

Parameters

  name | the name for the QoreEncoding used for the current connection

DLLEXPORT bool Datasource::wasConnectionAborted | ( |  | ) | const

returns the connection aborted status

Returns
  the connection aborted status

The documentation for this class was generated from the following file:

- include/qore/Datasource.h (5431)