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

Public Member Functions | Protected Member Functions | List of all members
Datasource Class Reference

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

`#include <Datasource.h>`

## Public Member Functions
DLLLOCAL | Datasource (DBIDriver *driver, DatasourceStatementHelper *dsh)
| creates the object; internal only More...
DLLLOCAL | Datasource (const Datasource &old, DatasourceStatementHelper *dsh)
| copy constructor; internal only More...
DLLEXPORT | Datasource (DBIDriver *driver)
| creates the object and binds it to a particular DBIDriver More...
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 | activeTransaction () const
| returns true if a transaction is in progress and DB commands have been issued since the transaction was started More...
DLLEXPORT int | autoCommit (ExceptionSink *xsink)
| called from subclasses when releasing the transaction lock More...
DLLEXPORT int | beginTransaction (ExceptionSink *xsink)
DLLEXPORT int | close ()
| closes the connection
DLLEXPORT int | commit (ExceptionSink *xsink)
| commits the current transaction to the database More...
DLLEXPORT void | connectionAborted ()
| should be called by the DBIDriver if the connection to the server is lost More...
DLLEXPORT void | connectionAborted (ExceptionSink *xsink)
| should be called by the DBI driver if the connection to the server has been lost More...
DLLEXPORT void | connectionLost (ExceptionSink *xsink)
| should be called be the DBI driver to signify that the connection to the server has been lost More...
DLLEXPORT void | connectionRecovered (ExceptionSink *xsink)
| should be called be the DBI driver to signify that the connection to the server has been recovered More...
DLLEXPORT Datasource * | copy () const
| returns a copy of this object with the same DBIDriver and pending connection values More...
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 More...
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 More...
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 More...
DLLEXPORT QoreValue | 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 More...
DLLEXPORT bool | getAutoCommit () const
| returns the autocommit status More...
DLLEXPORT int | getCapabilities () const
| returns the capability mask of the current driver More...
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 More...
DLLEXPORT QoreValue | getClientVersion (ExceptionSink *xsink) const
| executes the "get_client_version" function of the driver, if any, and returns the result More...
DLLEXPORT QoreHashNode * | getConfigHash () const
| returns a hash representing the configuration of the current object More...
DLLEXPORT QoreStringNode * | getConfigString () const
| returns a string representing the configuration of the current object More...
DLLEXPORT const QoreHashNode * | getConnectOptions () const
| returns the valid options for this driver with descriptions and current values for the current datasource More...
DLLEXPORT QoreHashNode * | getCurrentOptionHash () const
| returns the options currently set for this object More...
DLLEXPORT const char * | getDBEncoding () const
| returns the database-specific character encoding name used for the last connection More...
DLLEXPORT const std::string & | getDBEncodingStr () const
| returns the database-specific character encoding name used for the last connection More...
DLLEXPORT const char * | getDBName () const
| returns the database (or schema) name used for the last connection More...
DLLEXPORT const std::string & | getDBNameStr () const
| returns the database (or schema) name used for the last connection More...
DLLEXPORT const DBIDriver * | getDriver () const
| returns the DBIDriver pointer used for this object More...
DLLEXPORT const char * | getDriverName () const
| returns the name of the current DBI 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 More...
DLLEXPORT const char * | getHostName () const
| returns the host name used for the last connection More...
DLLEXPORT const std::string & | getHostNameStr () const
| returns the host name used for the last connection More...
DLLEXPORT QoreValue | getOption (const char *opt, ExceptionSink *xsink)
| Returns the current value for the given option. More...
DLLEXPORT QoreHashNode * | getOptionHash () const
| returns the valid options for this driver with descriptions and current values for the current datasource More...
DLLEXPORT const char * | getOSEncoding () const
| returns the OS (or Qore) character encoding name used for the last connection More...
DLLEXPORT const char * | getPassword () const
| returns the password used for the last connection More...
DLLEXPORT const std::string & | getPasswordStr () const
| returns the password used for the last connection More...
DLLEXPORT QoreStringNode * | getPendingDBEncoding () const
| returns the pending database-specific character encoding name for the next connection More...
DLLEXPORT QoreStringNode * | getPendingDBName () const
| returns the pending database (or schema) name for the next connection More...
DLLEXPORT QoreStringNode * | getPendingHostName () const
| returns the pending host name for the next connection More...
DLLEXPORT QoreStringNode * | getPendingPassword () const
| returns the pending password for the next connection More...
DLLEXPORT int | getPendingPort () const
| returns the pending port number for the next connection More...
DLLEXPORT QoreStringNode * | getPendingUsername () const
| returns the pending username for the next connection More...
DLLEXPORT int | getPort () const
| returns the port number used for the last connection More...
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 const QoreEncoding * | getQoreEncoding () const
| returns the QoreEncoding pointer used for this connection
DLLEXPORT QoreValue | getServerVersion (ExceptionSink *xsink)
| executes the "get_server_version" function of the driver, if any, and returns the result, makes an implicit connection if necessary More...
DLLEXPORT QoreObject * | getSQLStatementObjectForResultSet (void *stmt_private_data)
| returns an SQLStatement object representing a result set More...
DLLEXPORT const char * | getUsername () const
| returns the username used for the last connection More...
DLLEXPORT const std::string & | getUsernameStr () const
| returns the username used for the last connection More...
DLLEXPORT bool | isInTransaction () const
| returns the transaction status flag More...
DLLEXPORT bool | isOpen () const
| returns true if the connection is currently open More...
DLLEXPORT int | open (ExceptionSink *xsink)
| opens a connection to the database More...
DLLEXPORT void | reset (ExceptionSink *xsink)
| closes and opens the connection
DLLEXPORT int | rollback (ExceptionSink *xsink)
| rolls back the current transaction to the database More...
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 More...
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 More...
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, makes an implicit connection if necessary More...
DLLEXPORT void | setDBEncoding (const char *name)
| sets the database-specific character encoding name used for the current connection More...
DLLEXPORT void | setEventQueue (Queue *q, QoreValue arg, ExceptionSink *xsink)
| sets an event queue for datasource events More...
DLLEXPORT int | setOption (const char *opt, const QoreValue val, ExceptionSink *xsink)
| sets an option for the datasource More...
DLLEXPORT void | setPendingDBEncoding (const char *c)
| sets the database-specific name of the character-encoding to be used for the next connection More...
DLLEXPORT void | setPendingDBName (const char *d)
| sets the database (or schema) name to be used for the next connection More...
DLLEXPORT void | setPendingHostName (const char *h)
| sets the hostname to be used for the next connection More...
DLLEXPORT void | setPendingPassword (const char *p)
| sets the password to be used for the next connection More...
DLLEXPORT void | setPendingPort (int port)
| sets the port number to be used for the next connection More...
DLLEXPORT void | setPendingUsername (const char *u)
| sets the username to be used for the next connection More...
DLLEXPORT void | setPrivateData (void *data)
| sets the private DBI-specific data structure for this object More...
DLLEXPORT void | setQoreEncoding (const QoreEncoding *enc)
| sets the QoreEncoding used for this connection More...
DLLEXPORT void | setQoreEncoding (const char *name)
| sets the name for the QoreEncoding used for this connection More...
DLLEXPORT bool | wasConnectionAborted () const
| returns the connection aborted status More...

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

## 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

## ◆ Datasource() [1/3]

DLLLOCAL Datasource::Datasource | ( | DBIDriver * | driver,
|  | DatasourceStatementHelper * | dsh
| ) |  |

creates the object; internal only

Parameters

  driver | the DBIDriver object to use for the connection
  dsh | the interface of the real C++ parent object

Since
  Qore 0.8.13

## ◆ Datasource() [2/3]

DLLLOCAL Datasource::Datasource | ( | const Datasource & | old,
|  | DatasourceStatementHelper * | dsh
| ) |  |

copy constructor; internal only

Parameters

  old | the old object to copy
  dsh | the interface of the real C++ parent object

Since
  Qore 0.8.13

## ◆ Datasource() [3/3]

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

Deprecated:
  do not use

## Member Function Documentation

## ◆ activeTransaction()

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

## ◆ autoCommit()

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

## ◆ beginTransaction()

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

## ◆ commit()

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

## ◆ connectionAborted() [1/2]

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)

Note
  This call results in all open statements being closed and then the Datasource itself is closed, resulting in the deletion of the driver-specific Datasource local data; if the driver needs to free memory before the Datasource is closed, then the driver should call connectionLost() instead, free its memory, and then call the variant of function taking an ExceptionSink pointer argument.

Deprecated:
  use connectionAborted(ExceptionSink*) instead

## ◆ connectionAborted() [2/2]

DLLEXPORT void Datasource::connectionAborted | ( | ExceptionSink * | xsink | ) |

should be called by the DBI driver if the connection to the server has been 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)

This function should be called after a connectionLost() call if the connection is not able to be reopened.

Note
  This call results in all open statements being closed and then the Datasource itself is closed, resulting in the deletion of the driver-specific Datasource local data; if the driver needs to free memory before the Datasource is closed, then the driver should call connectionLost() instead, free its memory, and then call this function.

Since
  Qore 0.8.12.10

## ◆ connectionLost()

DLLEXPORT void Datasource::connectionLost | ( | ExceptionSink * | xsink | ) |

should be called be the DBI driver to signify that the connection to the server has been lost

This call does not result in the Datasource being closed, but rather ensures that all open statements are closed while the driver-specific Datasource local data remains in place.

This flag does not result in the connection aborted flag being set.

Since
  Qore 0.8.12.10

## ◆ connectionRecovered()

DLLEXPORT void Datasource::connectionRecovered | ( | ExceptionSink * | xsink | ) |

should be called be the DBI driver to signify that the connection to the server has been recovered

This call does not result in the Datasource being closed, but rather ensures that all open statements are closed and also that driver-specific Datasource local data is deleted.

This function should be called after a connectionLost() call if the connection is then reopened.

Since
  Qore 0.8.12.10

## ◆ copy()

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

## ◆ describe()

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

Parameters

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

Since
  Qore 0.8.9

## ◆ exec()

DLLEXPORT QoreValue 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 query to execute
  args | query arguments for s, n, d placeholders
  xsink | if an error occurs, the Qore-language exception information will be added here

## ◆ execRaw() [1/2]

DLLEXPORT QoreValue 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 query 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

## ◆ execRaw() [2/2]

DLLEXPORT QoreValue 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 query to execute
  xsink | if an error occurs, the Qore-language exception information will be added here

## ◆ getAutoCommit()

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

returns the autocommit status

Returns
  the autocommit status of the object

## ◆ getCapabilities()

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

returns the capability mask of the current driver

Returns
  the capability mask of the current driver

## ◆ getCapabilityList()

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

## ◆ getClientVersion()

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

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

the caller owns the pointer's reference count returned (if the QoreValue returned holds a pointer)

Parameters

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

## ◆ getConfigHash()

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

returns a hash representing the configuration of the current object

Since
  Qore 0.8.8

## ◆ getConfigString()

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

returns a string representing the configuration of the current object

Note
  must be connected before calling or a crash could result

Since
  Qore 0.8.8

## ◆ getConnectOptions()

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

## ◆ getCurrentOptionHash()

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

returns the options currently set for this object

Returns
  a hash where the keys and values are option names and option values

The caller owns the reference count for the hash returned; returns 0 if no options are set on the current object or if the driver does not support options

Since
  0.8.9

## ◆ getDBEncoding()

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

## ◆ getDBEncodingStr()

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

## ◆ getDBName()

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)

## ◆ getDBNameStr()

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)

## ◆ getDriver()

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

returns the DBIDriver pointer used for this object

Returns
  the DBIDriver pointer used for this object

## ◆ getEventQueueHash()

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

meant to be called from drivers while a transaction or action lock is held

## ◆ getHostName()

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)

## ◆ getHostNameStr()

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)

## ◆ getOption()

DLLEXPORT QoreValue 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

## ◆ getOptionHash()

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

## ◆ getOSEncoding()

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

## ◆ getPassword()

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)

## ◆ getPasswordStr()

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)

## ◆ getPendingDBEncoding()

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

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

caller owns the pointer's reference count returned

## ◆ getPendingDBName()

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

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

caller owns the pointer's reference count returned

## ◆ getPendingHostName()

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

returns the pending host name for the next connection

caller owns the pointer's reference count returned

Returns
  the pending host name for the next connection

## ◆ getPendingPassword()

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

returns the pending password for the next connection

caller owns the pointer's reference count returned

## ◆ getPendingPort()

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

returns the pending port number for the next connection

Returns
  the pending port number used for the next connection

## ◆ getPendingUsername()

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

returns the pending username for the next connection

caller owns the pointer's reference count returned

## ◆ getPort()

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

returns the port number used for the last connection

Returns
  the port number used for the last connection

## ◆ getServerVersion()

DLLEXPORT QoreValue 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 pointer's reference count returned (if the QoreValue returned holds a pointer) 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

## ◆ getSQLStatementObjectForResultSet()

DLLEXPORT QoreObject* Datasource::getSQLStatementObjectForResultSet | ( | void * | stmt_private_data | ) |

returns an SQLStatement object representing a result set

Parameters

  stmt_private_data | private data for the QoreSQLStatement object

Returns
  an SQLStatement object representing a result set

Since
  Qore 0.8.13

## ◆ getUsername()

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

returns the username used for the last connection

Returns

## ◆ getUsernameStr()

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

returns the username used for the last connection

Returns
  the username used for the last connection

## ◆ isInTransaction()

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

returns the transaction status flag

Returns
  the transaction status flag

## ◆ isOpen()

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

returns true if the connection is currently open

Returns
  the connection status (true if open)

## ◆ 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

## ◆ rollback()

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

## ◆ select()

DLLEXPORT QoreValue 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 query to execute
  args | query arguments for s, n, d placeholders
  xsink | if an error occurs, the Qore-language exception information will be added here

## ◆ selectRow()

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 query 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

## ◆ selectRows()

DLLEXPORT QoreValue 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 query to execute
  args | query arguments for s, n, d placeholders
  xsink | if an error occurs, the Qore-language exception information will be added here

## ◆ setDBEncoding()

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

## ◆ setEventQueue()

DLLEXPORT void Datasource::setEventQueue | ( | Queue * | q,
|  | QoreValue | arg,
|  | ExceptionSink * | xsink
| ) |  |

sets an event queue for datasource events

Since
  Qore 0.8.9

## ◆ setOption()

DLLEXPORT int Datasource::setOption | ( | const char * | opt,
|  | const QoreValue | 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

Deprecated:
  use setOption(const char*, const QoreValue, ExceptionSink*);

## ◆ setPendingDBEncoding()

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

## ◆ setPendingDBName()

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

## ◆ setPendingHostName()

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

## ◆ setPendingPassword()

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

## ◆ setPendingPort()

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

## ◆ setPendingUsername()

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

## ◆ setPrivateData()

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

## ◆ setQoreEncoding() [1/2]

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

## ◆ setQoreEncoding() [2/2]

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

## ◆ wasConnectionAborted()

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