Datasource Class Reference

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

#include <Datasource.h>

List of all members.

Public Member Functions

DLLEXPORT Datasource (DBIDriver *driver)
 creates the object and binds it to a particular DBIDriver
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
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 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 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
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

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

Returns:
the transaction status

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

doxygen