Qore Programming Language Reference Manual 1.19.5
|
This class defines an abstract interface for database access, inherited by both the Datasource and DatasourcePool classes. More...
#include <QC_AbstractDatasource.dox.h>
Public Member Methods | |
abstract nothing | beginTransaction () |
Manually signals the start of transaction management on the AbstractDatasource. More... | |
abstract nothing | commit () |
Commits the current transaction and releases any thread resources associated with the transaction. More... | |
bool | currentThreadInTransaction () |
Should return True if the current thread is in a transaction with this object, must be re-implemented in subclasses to provide the desired functionality. More... | |
abstract auto | exec (string sql,...) |
Executes an SQL command on the server and returns either the integer row count (for example, for updates, inserts, and deletes) or the data retrieved (for example, if a stored procedure is executed that returns values) More... | |
abstract auto | execRaw (string sql) |
Executes an SQL command on the server and returns either the row count (for example, for updates and inserts) or the data retrieved (for example, if a stored procedure is executed that returns values) More... | |
abstract auto | getClientVersion () |
Retrieves the driver-specific client library version information. More... | |
abstract hash< auto > | getConfigHash () |
Returns a datasource hash describing the configuration of the current object. More... | |
abstract string | getConfigString () |
Returns a string giving the configuration of the current object in a format that can be parsed by parse_datasource() More... | |
abstract *string | getDBEncoding () |
Retrieves the database-specific charset set encoding for the object. More... | |
abstract *string | getDBName () |
Returns the database name parameter as a string or NOTHING if none is set. More... | |
abstract string | getDriverName () |
Returns the name of the driver used for the object. More... | |
string | getDriverRealName () |
Returns the real DB driver name if supported by the driver, otherwise the Qore driver name. More... | |
abstract *string | getHostName () |
Returns the hostname parameter as a string or NOTHING if none is set. More... | |
abstract *string | getOSEncoding () |
Returns the Qore character encoding name for the object as a string or NOTHING if none is set. More... | |
auto | getOption (string opt) |
Returns the current value for the given option. More... | |
hash< auto > | getOptionHash () |
Returns the valid options for the driver associated with the AbstractDatasource with descriptions and current values for the current AbstractDatasource object. More... | |
abstract *string | getPassword () |
Returns the password parameter as a string or NOTHING if none is set. More... | |
abstract *int | getPort () |
Gets the port number that will be used for the next connection to the server. More... | |
AbstractSQLStatement | getSQLStatement () |
Returns an AbstractSQLStatement object based on the current database connection object. More... | |
abstract auto | getServerVersion () |
Returns the driver-specific server version data for the current connection. More... | |
abstract *string | getUserName () |
Returns the username parameter as a string or NOTHING if none is set. More... | |
abstract bool | inTransaction () |
Returns True if a transaction is currently in progress. More... | |
abstract nothing | rollback () |
Rolls the current transaction back and releases any thread resources associated with the transaction. More... | |
abstract auto | select (string sql,...) |
Executes an SQL select statement on the server and (normally) returns the result as a hash (column names) of lists (column values per row) More... | |
abstract auto | selectRow (string sql,...) |
Executes an SQL select statement on the server and returns the first row as a hash (the column values) More... | |
abstract auto | selectRows (string sql,...) |
Executes an SQL select statement on the server and returns the result as a list (rows) of hashes (the column values) More... | |
abstract auto | vexec (string sql, *softlist< auto > vargs) |
Executes an SQL command on the server and returns either the integer row count (for example, for updates, inserts, and deletes) or the data retrieved (for example, if a stored procedure is executed that returns values), taking a list for all bind arguments. More... | |
abstract auto | vselect (string sql, *softlist< auto > vargs) |
Executes a select statement on the server and returns the results in a hash (column names) of lists (column values per row), taking a list for all bind arguments. More... | |
abstract auto | vselectRow (string sql, *softlist< auto > vargs) |
Executes a select statement on the server and returns the first row as a hash (column names and values), taking a list for all bind arguments. More... | |
abstract auto | vselectRows (string sql, *softlist< auto > vargs) |
Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values), taking a list for all bind arguments. More... | |
This class defines an abstract interface for database access, inherited by both the Datasource and DatasourcePool classes.
|
pure virtual |
Manually signals the start of transaction management on the AbstractDatasource.
This method should be called when the AbstractDatasource object will be shared between more than 1 thread, and a transaction will be started with a AbstractDatasource::select() method or the like.
This method does not make any communication with the server to start a transaction; it only allocates the transaction lock to the current thread in Qore.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Commits the current transaction and releases any thread resources associated with the transaction.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
bool Qore::SQL::AbstractDatasource::currentThreadInTransaction | ( | ) |
Should return True if the current thread is in a transaction with this object, must be re-implemented in subclasses to provide the desired functionality.
|
pure virtual |
Executes an SQL command on the server and returns either the integer row count (for example, for updates, inserts, and deletes) or the data retrieved (for example, if a stored procedure is executed that returns values)
sql | The SQL command to execute on the server |
... | Include any values to be bound (using v in the command string) or placeholder specifications (using : key_name in the command string) in order after the command string |
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Executes an SQL command on the server and returns either the row count (for example, for updates and inserts) or the data retrieved (for example, if a stored procedure is executed that returns values)
This method does not do any variable binding, so it's useful for example for DDL statements etc
sql | The SQL command to execute on the server; this string will not be subjected to any transformations for variable binding |
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Retrieves the driver-specific client library version information.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Returns a datasource hash describing the configuration of the current object.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Returns a string giving the configuration of the current object in a format that can be parsed by parse_datasource()
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Retrieves the database-specific charset set encoding for the object.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Returns the database name parameter as a string or NOTHING if none is set.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Returns the name of the driver used for the object.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
string Qore::SQL::AbstractDatasource::getDriverRealName | ( | ) |
Returns the real DB driver name if supported by the driver, otherwise the Qore driver name.
By default this base class method returns getDriverName(); override in subclasses to modify this behavior
|
pure virtual |
Returns the hostname parameter as a string or NOTHING if none is set.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
auto Qore::SQL::AbstractDatasource::getOption | ( | string | opt | ) |
Returns the current value for the given option.
opt | the option to get |
hash< auto > Qore::SQL::AbstractDatasource::getOptionHash | ( | ) |
Returns the valid options for the driver associated with the AbstractDatasource with descriptions and current values for the current AbstractDatasource object.
"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
|
pure virtual |
Returns the Qore character encoding name for the object as a string or NOTHING if none is set.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Returns the password parameter as a string or NOTHING if none is set.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Gets the port number that will be used for the next connection to the server.
Invalid port numbers will cause an exception to be thrown when the connection is opened
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Returns the driver-specific server version data for the current connection.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
AbstractSQLStatement Qore::SQL::AbstractDatasource::getSQLStatement | ( | ) |
Returns an AbstractSQLStatement object based on the current database connection object.
|
pure virtual |
Returns the username parameter as a string or NOTHING if none is set.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Returns True if a transaction is currently in progress.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Rolls the current transaction back and releases any thread resources associated with the transaction.
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Executes an SQL select statement on the server and (normally) returns the result as a hash (column names) of lists (column values per row)
The usual return format of this method is suitable for use with context statements, for easy iteration and processing of query results. Alternatively, the HashListIterator class can be used to iterate the return value of this method.
Additionally, this format is a more efficient format than that returned by the AbstractDatasource::selectRows() method, because the column names are not repeated for each row returned. Therefore, for retrieving anything greater than small amounts of data, it is recommended to use this method instead of AbstractDatasource::selectRows().
To execute select statements that begin a transaction (such as "select for update"
), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one thread.
sql | The SQL command to execute on the server |
... | Include any values to be bound (using v in the command string) or placeholder specifications (using : key_name in the command string) in order after the command string |
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Executes an SQL select statement on the server and returns the first row as a hash (the column values)
If more than one row is returned, then it is treated as an error and a DBI-SELECT-ROW-ERROR
is returned (however the DBI driver should raise its own exception here to avoid retrieving more than one row from the server). For a similar method taking a list for all bind arguments, see AbstractDatasource::vselectRow().
This method also accepts all bind parameters (%d
, %v
, etc) as documented in Binding by Value and Placeholder
To execute select statements that begin a transaction (such as "select for update"
), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one thread.
sql | The SQL command to execute on the server |
... | Include any values to be bound (using v in the command string) or placeholder specifications (using : key_name in the command string) in order after the command string |
DBI-SELECT-ROW-ERROR | more than 1 row retrieved from the server |
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Executes an SQL select statement on the server and returns the result as a list (rows) of hashes (the column values)
The return format of this method is not as memory efficient as that returned by the AbstractDatasource::select() method, therefore for larger amounts of data, it is recommended to use AbstractDatasource::select(). The usual return value of this method can be iterated with the ListHashIterator class.
This method also accepts all bind parameters (%d
, %v
, etc) as documented in Binding by Value and Placeholder
To execute select statements that begin a transaction (such as "select for update"
), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one thread.
sql | The SQL command to execute on the server |
... | Include any values to be bound (using v in the command string) or placeholder specifications (using : key_name in the command string) in order after the command string |
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Executes an SQL command on the server and returns either the integer row count (for example, for updates, inserts, and deletes) or the data retrieved (for example, if a stored procedure is executed that returns values), taking a list for all bind arguments.
Same as AbstractDatasource::exec() except takes an explicit list for bind arguments
sql | The SQL command to execute on the server |
vargs | Include any values to be bound (using v in the command string) or placeholder specifications (using : key_name in the command string) in order after the command string |
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Executes a select statement on the server and returns the results in a hash (column names) of lists (column values per row), taking a list for all bind arguments.
The usual return format of this method is suitable for use with context statements, for easy iteration and processing of query results. Alternatively, the HashListIterator class can be used to iterate the return value of this method.
This method also accepts all bind parameters (%d
, %v
, etc) as documented in Binding by Value and Placeholder
To execute select statements that begin a transaction (such as "select for update"
), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one thread.
sql | The SQL command to execute on the server |
vargs | Include any values to be bound (using v in the command string) or placeholder specifications (using : key_name in the command string) in order after the command string |
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Executes a select statement on the server and returns the first row as a hash (column names and values), taking a list for all bind arguments.
This method is the same as the AbstractDatasource::selectRow() method, except this method takes a single argument after the SQL command giving the list of bind value parameters
This method also accepts all bind parameters (%d
, %v
, etc) as documented in Binding by Value and Placeholder
To execute select statements that begin a transaction (such as "select for update"
), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one thread.
sql | The SQL command to execute on the server |
vargs | Include any values to be bound (using v in the command string) or placeholder specifications (using : key_name in the command string) in order after the command string |
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.
|
pure virtual |
Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values), taking a list for all bind arguments.
Same as the AbstractDatasource::selectRows() method, except this method takes a single argument after the SQL command giving the list of bind value parameters.
The usual return value of this method can be iterated with the ListHashIterator class.
The return format of this method is not as memory efficient as that returned by the AbstractDatasource::select() method, therefore for larger amounts of data, it is recommended to use AbstractDatasource::select().
This method also accepts all bind parameters (%d
, %v
, etc) as documented in Binding by Value and Placeholder
To execute select statements that begin a transaction (such as "select for update"
), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one thread.
sql | The SQL command to execute |
vargs | Include any values to be bound (using v in the command string) or placeholder specifications (using : key_name in the command string) in order after the command string |
Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.