Qore Programming Language  0.8.7
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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

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 QoreEncodinggetQoreEncoding () 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 AbstractQoreNodeselect (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 AbstractQoreNodeselectRows (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 QoreHashNodeselectRow (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 AbstractQoreNodeexec (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 AbstractQoreNodeexecRaw (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 AbstractQoreNodeexecRaw (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 QoreListNodegetCapabilityList () 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 QoreStringNodegetPendingUsername () const
 returns the pending username for the next connection
 
DLLEXPORT QoreStringNodegetPendingPassword () const
 returns the pending password for the next connection
 
DLLEXPORT QoreStringNodegetPendingDBName () const
 returns the pending database (or schema) name for the next connection
 
DLLEXPORT QoreStringNodegetPendingDBEncoding () const
 returns the pending database-specific character encoding name for the next connection
 
DLLEXPORT QoreStringNodegetPendingHostName () 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 Datasourcecopy () 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 AbstractQoreNodegetServerVersion (ExceptionSink *xsink)
 executes the "get_server_version" function of the driver, if any, and returns the result, makes an implicit connection if necessary
 
DLLEXPORT AbstractQoreNodegetClientVersion (ExceptionSink *xsink) const
 executes the "get_client_version" function of the driver, if any, and returns the result
 
DLLEXPORT const DBIDrivergetDriver () 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 QoreHashNodegetOptionHash () 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 AbstractQoreNodegetOption (const char *opt, ExceptionSink *xsink)
 Returns the current value for the given option.
 
DLLEXPORT const QoreHashNodegetConnectOptions () 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
driverthe 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
xsinkif 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
xsinkif 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
xsinkif 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_strthe qurey to execute
argsquery arguments for s, n, d placeholders
xsinkif 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_strthe qurey to execute
argsthis argument is ignored
xsinkif 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_strthe qurey to execute
xsinkif 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
xsinkif 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
optthe option to get
xsinkif 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
xsinkif 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
xsinkif 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
xsinkif 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_strthe qurey to execute
argsquery arguments for s, n, d placeholders
xsinkif 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_strthe qurey to execute
argsquery arguments for s, n, d placeholders
xsinkif 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_strthe qurey to execute
argsquery arguments for s, n, d placeholders
xsinkif 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
namethe 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
optthe option to set
valthe value to set
xsinkif 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
cthe 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
dthe 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
hthe 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
pthe 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
portthe 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
uthe 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
datathe 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
encthe 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
namethe 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: