Qore Programming Language Reference Manual 2.0.0
|
This class provides the Qore interface to databases. More...
#include <QC_Datasource.dox.h>
Public Member Methods | |
nothing | beginTransaction () |
Manually grabs the transaction lock. | |
nothing | clearEventQueue () |
Clears the queue object for DBI events on the datasource. | |
nothing | close () |
Closes the connection to the database; if any actions are in progress on the database, the close call will block until the actions complete. If any errors are encountered, an exception is raised. | |
nothing | commit () |
Commits the current transaction and releases the transaction lock. | |
constructor (string driver, __7_ string user, __7_ string pass, __7_ string db, __7_ string encoding, __7_ string host, __7_ softint port, __7_ hash< auto > options, __7_ Qore::Thread::Queue queue, auto arg) | |
Creates the Datasource object; attempts to load a DBI driver if the driver is not already present in Qore. | |
constructor (string desc, __7_ Qore::Thread::Queue queue, auto arg) | |
Creates a Datasource object from a single string giving all parameters that can be parsed by parse_datasource() | |
constructor (hash< auto > opts, __7_ Qore::Thread::Queue queue, auto arg) | |
Creates a Datasource object from a hash argument giving parameters for the constructor. | |
copy () | |
Creates a new Datasource object with the same driver as the original and copies of all the connection parameters. | |
bool | currentThreadInTransaction () |
Returns True if the current thread is in a transaction (i.e. holds the transaction lock), False if not. | |
__7_ hash< auto > | describe (string sql,...) |
Executes an SQL select statement on the server and returns a description of the result set as a hash. | |
destructor () | |
Closes the datasource if it's open (if any operations are in progress, will block until the operations complete) and destroys the object. | |
auto | exec (string sql,...) |
Grabs the transaction lock (if autocommit is disabled) and 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). | |
auto | execRaw (string sql) |
Grabs the transaction lock (if autocommit is disabled) and 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) | |
bool | getAutoCommit () |
Returns the autocommit status for the object. | |
int | getCapabilities () |
Returns an integer bitfield of DBI driver capabilities. | |
list< auto > | getCapabilityList () |
Returns a list of strings giving the capabilities of the current DBI driver. | |
auto | getClientVersion () |
Retrieves the driver-specific client library version information; this method may not be implemented for all drivers. | |
hash< auto > | getConfigHash () |
Returns a datasource hash describing the configuration of the current object. | |
string | getConfigString () |
Returns a string giving the configuration of the current object in a format that can be parsed by parse_datasource() | |
__7_ string | getDBCharset () |
Retrieves the database-specific charset set encoding for the current connection. | |
__7_ string | getDBEncoding () |
Retrieves the database-specific charset set encoding for the current connection. | |
__7_ string | getDBName () |
Returns the database name parameter as a string or NOTHING if none is set. | |
string | getDriverName () |
Returns the name of the driver used for the object. | |
string | getDriverRealName () |
Returns the real DB driver name if supported by the driver, otherwise the Qore driver name. | |
__7_ string | getHostName () |
Returns the hostname parameter as a string or NOTHING if none is set. | |
string | getOSCharset () |
Returns the Qore character encoding name for the current connection as a string or "(unknown)" if none is set. | |
__7_ string | getOSEncoding () |
Returns the Qore character encoding name for the current connection as a string or NOTHING if none is set. | |
auto | getOption (string opt) |
Returns the current value for the given option. | |
hash< auto > | getOptionHash () |
returns the valid options for the driver associated with the Datasource with descriptions and current values for the current Datasource object | |
__7_ string | getPassword () |
Returns the password parameter as a string or NOTHING if none is set. | |
__7_ int | getPort () |
Gets the port number that will be used for the next connection to the server. | |
AbstractSQLStatement | getSQLStatement () |
Returns an AbstractSQLStatement object based on the current database connection object. | |
auto | getServerVersion () |
Returns the driver-specific server version data for the current connection. | |
int | getTransactionLockTimeout () |
Retrieves the transaction lock timeout value as an integer in milliseconds. | |
__7_ string | getUserName () |
Returns the username parameter as a string or NOTHING if none is set. | |
bool | inTransaction () |
Returns True if a transaction is currently in progress, False if not. | |
nothing | open () |
Opens a connection to the datasouce, using the connection parameters already set; an exception is thrown if any errors occur. | |
nothing | reset () |
Closes and reopens the Datasource. | |
nothing | rollback () |
Rolls the current transaction back and releases the transaction lock. | |
auto | select (string sql,...) |
Executes an SQL select statement on the server and returns the result as a hash (column names) of lists (column values per row) | |
__7_ hash< auto > | selectRow (string sql,...) |
Executes an SQL select statement on the server and returns the first row as a hash (the column values) | |
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) | |
nothing | setAutoCommit (bool ac=True) |
Turns autocommit on or off for this object. | |
nothing | setDBCharset (string encoding) |
Sets the database-specific character encoding name for the next connection to the server. | |
nothing | setDBEncoding (string encoding) |
Sets the database-specific character encoding name for the next connection to the server. | |
nothing | setDBName (string db) |
Sets the database name parameter for the time a connection to the server is established. | |
nothing | setEventQueue (Qore::Thread::Queue queue, auto arg) |
Sets a queue object for DBI events on the datasource. | |
nothing | setHostName (string host) |
Sets the hostname to use for the next connection to the server. | |
setOption (string opt, auto val) | |
sets an option for the datasource | |
nothing | setPassword (string pass) |
Sets the password parameter for the time a connection to the server is established. | |
nothing | setPort (softint port=0) |
Sets the port number to use for the connection. | |
nothing | setTransactionLockTimeout (timeout timeout_ms=0) |
Sets the transaction lock timeout value in milliseconds; set to 0 for no timeout. | |
nothing | setUserName (string user) |
Sets the username parameter for the time a connection to the server is established. | |
int | transactionTid () |
Returns the TID of the thread holding the transaction lock or -1 if it's not currently held. | |
auto | vexec (string sql, __7_ softlist< auto > vargs) |
Grabs the transaction lock (if autocommit is disabled) and executes SQL code on the DB connection, taking a list for all bind arguments. | |
auto | vselect (string sql, __7_ 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. | |
__7_ hash< auto > | vselectRow (string sql, __7_ 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. | |
auto | vselectRows (string sql, __7_ 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. | |
Public Member Methods inherited from Qore::SQL::AbstractDatasource | |
abstract nothing | beginTransaction () |
Manually signals the start of transaction management on the AbstractDatasource. | |
abstract nothing | commit () |
Commits the current transaction and releases any thread resources associated with the transaction. | |
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. | |
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) | |
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) | |
abstract auto | getClientVersion () |
Retrieves the driver-specific client library version information. | |
abstract hash< auto > | getConfigHash () |
Returns a datasource hash describing the configuration of the current object. | |
abstract string | getConfigString () |
Returns a string giving the configuration of the current object in a format that can be parsed by parse_datasource() | |
abstract __7_ string | getDBEncoding () |
Retrieves the database-specific charset set encoding for the object. | |
abstract __7_ string | getDBName () |
Returns the database name parameter as a string or NOTHING if none is set. | |
abstract string | getDriverName () |
Returns the name of the driver used for the object. | |
string | getDriverRealName () |
Returns the real DB driver name if supported by the driver, otherwise the Qore driver name. | |
abstract __7_ string | getHostName () |
Returns the hostname parameter as a string or NOTHING if none is set. | |
abstract __7_ string | getOSEncoding () |
Returns the Qore character encoding name for the object as a string or NOTHING if none is set. | |
auto | getOption (string opt) |
Returns the current value for the given option. | |
hash< auto > | getOptionHash () |
Returns the valid options for the driver associated with the AbstractDatasource with descriptions and current values for the current AbstractDatasource object. | |
abstract __7_ string | getPassword () |
Returns the password parameter as a string or NOTHING if none is set. | |
abstract __7_ int | getPort () |
Gets the port number that will be used for the next connection to the server. | |
AbstractSQLStatement | getSQLStatement () |
Returns an AbstractSQLStatement object based on the current database connection object. | |
abstract auto | getServerVersion () |
Returns the driver-specific server version data for the current connection. | |
abstract __7_ string | getUserName () |
Returns the username parameter as a string or NOTHING if none is set. | |
abstract bool | inTransaction () |
Returns True if a transaction is currently in progress. | |
abstract nothing | rollback () |
Rolls the current transaction back and releases any thread resources associated with the transaction. | |
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) | |
abstract auto | selectRow (string sql,...) |
Executes an SQL select statement on the server and returns the first row as a hash (the column values) | |
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) | |
abstract auto | vexec (string sql, __7_ 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. | |
abstract auto | vselect (string sql, __7_ 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. | |
abstract auto | vselectRow (string sql, __7_ 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. | |
abstract auto | vselectRows (string sql, __7_ 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. | |
Public Member Methods inherited from Qore::Serializable | |
constructor () | |
The constructor does not perform any action; this class is just used to mark a class as serializable by inheriting this class. | |
copy () | |
The copy constructor does not perform any action; this class is just used to mark a class as serializable by inheriting this class. | |
serialize (OutputStream stream, __7_ int flags) | |
converts the object to binary data representing the object | |
binary | serialize (__7_ int flags) |
converts the object to binary data representing the object | |
hash< SerializationInfo > | serializeToData (__7_ int flags) |
converts the object to a serialization hash representing the object | |
Additional Inherited Members | |
Static Public Member Methods inherited from Qore::Serializable | |
static auto | deserialize (InputStream stream, __7_ int flags) |
Deserializes data produced with serialize() and returns the value represented by the data. | |
static auto | deserialize (binary bin, __7_ int flags) |
Deserializes data produced with serialize() and returns the value represented by the data. | |
static auto | deserialize (string bin, __7_ int flags) |
Deserializes data produced with serialize() and returns the value represented by the data. | |
static auto | deserialize (hash< SerializationInfo > data, __7_ int flags) |
Deserializes data produced with serializeToData() and returns the value represented by the data. | |
static hash< SerializationInfo > | deserializeToData (InputStream stream, __7_ int flags) |
Deserializes data produced with serialize() and returns the value represented by the data. | |
static hash< SerializationInfo > | deserializeToData (binary bin, __7_ int flags) |
Deserializes data produced with serialize() and returns the value represented by the data. | |
static | serialize (auto val, OutputStream stream, __7_ int flags) |
serializes the data and writes the serialized data to the given output stream | |
static binary | serialize (auto val, __7_ int flags) |
serializes the data and returns the serialized data as a binary object | |
static hash< SerializationInfo > | serializeToData (auto val, __7_ int flags) |
converts the value to a serialization hash representing the value | |
This class provides the Qore interface to databases.
"read committed"
.%d
numeric specifier is supported equally in all Qore DBI drivers.Format Specification | Description |
%d | If any value other than NOTHING or NULL is given, then the value is converted to an integer and this value is substituted in the string at this position; if the value is NOTHING or NULL, then a literal "null" is substituted instead. |
%s | The argument is converted to a string and the string is inserted literally without any conversion or escape sequences in the string; this is useful for table or schema prefixes, etc |
%v | The argument is bound by value according to the DBI driver's implementation. |
%v
in the command string, and include the value as an argument after the string. Binding by value allows the DBI driver to take care of formatting the data properly for use in the query with the database server. When binding by value, strings do not need to be quoted, date/time values do not need special formatting, binary objects (with BLOB columns, for example) can be used directly in queries, etc."null"
in a query, use %d
in the command string, and include the value as an argument after the string. If the value is NOTHING or NULL, a literal "null"
will be written to the string; otherwise the argument is converted to an arbitrary-precision number or integer value if necessary and written to the string. This is useful for working with DECIMAL
(NUMERIC
, NUMBER
) types in a database-independent way; for example PostgreSQL servers do not do type conversions to DECIMAL
types when a string, integer, or float is bound by value, therefore to ensure that integral decimal values can be used in a database-independent way (with "null"
substitution when no value is bound), a valid approach is to use the %d
code in the command string instead of %v
. However please note that %v
is normally preferred to keep the server-side statement cache a manageable size, in the previous example using the int(), float(), or number() functions to convert string values before binding with %v
may be better.":code"
). In this case the method will return a hash of the output variables using the placeholder names as keys, but without the colon prefix. By default, a string type will be bound to the position. To bind other variable types to placeholder positions, include the type constant (see SQL Constants) as an argument after the command string. For BLOBs, use Binary, for CLOBs, use the string "clob" (constants will be provided in a future release). Not all DBI drivers require placeholder buffer specifications; see the documentation for the DBI driver in question for more information and examples regarding placeholder buffer specifications.When using RESULTSET, the SQLStatement object created acquires the transaction lock even when used with a method that normally doesn't indicate that a transaction will be started such as select() or selectRows(), therefore the transaction lock must be released manually in such cases (just as with the normal usage of SQLStatement objects); see the following example for details.
DATASOURCE-TRANSACTION-EXCEPTION
exception is raised describing the situation.When deserializing, any datasource event queue is lost; only the connection information is propagated in the deserialized copy.
nothing Qore::SQL::Datasource::beginTransaction | ( | ) |
Manually grabs the transaction lock.
This method should be called when the Datasource object will be shared between more than 1 thread, and a transaction will be started with a Datasource::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.
It is an error to call this method when autocommit is enabled for the Datasource.
AUTOCOMMIT-ERROR | Cannot start a transaction when autocommit is enabled |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
nothing Qore::SQL::Datasource::clearEventQueue | ( | ) |
Clears the queue object for DBI events on the datasource.
nothing Qore::SQL::Datasource::close | ( | ) |
Closes the connection to the database; if any actions are in progress on the database, the close call will block until the actions complete. If any errors are encountered, an exception is raised.
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
nothing Qore::SQL::Datasource::commit | ( | ) |
Commits the current transaction and releases the transaction lock.
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
Qore::SQL::Datasource::constructor | ( | hash< auto > | opts, |
__7_ Qore::Thread::Queue | queue, | ||
auto | arg | ||
) |
Creates a Datasource object from a hash argument giving parameters for the constructor.
opts | a hash giving parameters for the new datasource with the following possible keys (the "type" key is mandatory, also usable with the output of the parse_datasource() function):
|
queue | An optional Queue object to receive datasource events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown; passing NOTHING will clear any event queue |
arg | an optional argument to be included in the arg key of datasource events |
DATASOURCE-UNSUPPORTED-DATABASE | DBI driver cannot be loaded |
DATASOURCE-CONSTRUCTOR-ERROR | missing or invalid "driver" key, other key name not assigned to a string; port value is <= 0 |
DBI-OPTION-ERROR | unknown or unsupported option passed to driver |
Qore::SQL::Datasource::constructor | ( | string | desc, |
__7_ Qore::Thread::Queue | queue, | ||
auto | arg | ||
) |
Creates a Datasource object from a single string giving all parameters that can be parsed by parse_datasource()
desc | a datasource description string in the format that can be parsed by parse_datasource() |
queue | An optional Queue object to receive datasource events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown; passing NOTHING will clear any event queue |
arg | an optional argument to be included in the arg key of datasource events |
DATASOURCE-UNSUPPORTED-DATABASE | DBI driver cannot be loaded |
DATASOURCE-CONSTRUCTOR-ERRO | missing required parameter for connection; port value is <= 0 |
DBI-OPTION-ERROR | unknown or unsupported option passed to driver |
Qore::SQL::Datasource::constructor | ( | string | driver, |
__7_ string | user, | ||
__7_ string | pass, | ||
__7_ string | db, | ||
__7_ string | encoding, | ||
__7_ string | host, | ||
__7_ softint | port, | ||
__7_ hash< auto > | options, | ||
__7_ Qore::Thread::Queue | queue, | ||
auto | arg | ||
) |
Creates the Datasource object; attempts to load a DBI driver if the driver is not already present in Qore.
driver | The name of the DBI driver for the Datasource. See SQL Constants for builtin constants for DBI drivers shipped with Qore, or see the DBI driver documentation to use an add-on driver (this string should be the name of the driver to be loaded) |
user | The user name for the new connection. Also see Datasource::setUserName() for a method that allows this parameter to be set after the constructor. |
pass | The password for the new connection. Also see Datasource::setPassword() for a method that allows this parameter to be set after the constructor. |
db | The database name for the new connection. Also see Datasource::setDBName() for a method that allows this parameter to be set after the constructor. |
encoding | The database-specific name of the character encoding to use for the new connection. Also see Datasource::setDBCharset() for a method that allows this parameter to be set after the constructor. If no value is passed for this parameter, then the database character encoding corresponding to the default character encoding will be used instead. |
host | The host name for the new connection. Also see Datasource::setHostName() for a method that allows this parameter to be set after the constructor. |
port | The port number for the new connection. Also see Datasource::setPort() for a method that allows this parameter to be set after the constructor. |
options | Any options for the database driver for the new connection |
queue | An optional Queue object to receive datasource events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown; passing NOTHING will clear any event queue |
arg | an optional argument to be included in the arg key of datasource events |
DATASOURCE-UNSUPPORTED-DATABASE | DBI driver cannot be loaded |
DATASOURCE-CONSTRUCTOR-ERROR | port value is <= 0 |
DBI-OPTION-ERROR | unknown or unsupported option passed to driver |
Qore::SQL::Datasource::copy | ( | ) |
Creates a new Datasource object with the same driver as the original and copies of all the connection parameters.
bool Qore::SQL::Datasource::currentThreadInTransaction | ( | ) |
Returns True if the current thread is in a transaction (i.e. holds the transaction lock), False if not.
Executes an SQL select statement on the server and returns a description of the result set as a hash.
This method also accepts all bind parameters (%d
, %v
, %s
, etc) as documented in Binding by Value and Placeholder
This method does not retain the transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"
), execute Datasource::beginTransaction() first to ensure that the transaction lock is dedicated to the calling 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 |
name:
the name of the columntype:
a string giving the type of the columnmaxsize:
an integer giving the column sizenative_type:
a string giving the native column typeinternal_id:
an integer giving the native column type codeTRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
Qore::SQL::Datasource::destructor | ( | ) |
Closes the datasource if it's open (if any operations are in progress, will block until the operations complete) and destroys the object.
DATASOURCE-TRANSACTION-EXCEPTION | The Datasource was destroyed while a transaction was still in progress; the transaction will be automatically rolled back |
Grabs the transaction lock (if autocommit is disabled) and 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).
This method also accepts all bind parameters (%d
, %v
, %s
, etc) as documented in Binding by Value and Placeholder
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 |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
Grabs the transaction lock (if autocommit is disabled) and 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 |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
bool Qore::SQL::Datasource::getAutoCommit | ( | ) |
Returns the autocommit status for the object.
int Qore::SQL::Datasource::getCapabilities | ( | ) |
Returns an integer bitfield of DBI driver capabilities.
Returns a list of strings giving the capabilities of the current DBI driver.
auto Qore::SQL::Datasource::getClientVersion | ( | ) |
Retrieves the driver-specific client library version information; this method may not be implemented for all drivers.
Returns a datasource hash describing the configuration of the current object.
This method does not require a connection to the server. The return value may differ for connected and unconnected objects, as the DB driver may set default option values when the datasource is connected.
string Qore::SQL::Datasource::getConfigString | ( | ) |
Returns a string giving the configuration of the current object in a format that can be parsed by parse_datasource()
This method does not require a connection to the server. The return value may differ for connected and unconnected objects, as the DB driver may set default option values when the datasource is connected.
Retrieves the database-specific charset set encoding for the current connection.
A method synonym for Datasource::getDBEncoding() kept for backwards-compatibility.
Retrieves the database-specific charset set encoding for the current connection.
string Qore::SQL::Datasource::getDriverName | ( | ) |
Returns the name of the driver used for the object.
string Qore::SQL::Datasource::getDriverRealName | ( | ) |
Returns the real DB driver name if supported by the driver, otherwise the Qore driver name.
The return value will differ from getDriverName() in the case of "wrapper" drivers such as odbc
or jdbc
, where the generic Qore driver name is insufficient to identify the database server type.
In other cases, this method will return the same value as getDriverName()
Returns the current value for the given option.
opt | the option to get |
DBI-OPTION-ERROR | unknown or unsupported option passed to driver |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
returns the valid options for the driver associated with the Datasource with descriptions and current values for the current Datasource 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 optionTRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
string Qore::SQL::Datasource::getOSCharset | ( | ) |
Returns the Qore character encoding name for the current connection as a string or "(unknown)"
if none is set.
"(unknown)"
if none is setGets 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
auto Qore::SQL::Datasource::getServerVersion | ( | ) |
Returns the driver-specific server version data for the current connection.
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
AbstractSQLStatement Qore::SQL::Datasource::getSQLStatement | ( | ) |
Returns an AbstractSQLStatement object based on the current database connection object.
SQLSTATEMENT-ERROR | the DBI driver for the given object does not support the prepared statement API |
int Qore::SQL::Datasource::getTransactionLockTimeout | ( | ) |
Retrieves the transaction lock timeout value as an integer in milliseconds.
bool Qore::SQL::Datasource::inTransaction | ( | ) |
nothing Qore::SQL::Datasource::open | ( | ) |
Opens a connection to the datasouce, using the connection parameters already set; an exception is thrown if any errors occur.
If the connection is already open, then no action is taken.
nothing Qore::SQL::Datasource::reset | ( | ) |
Closes and reopens the Datasource.
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
nothing Qore::SQL::Datasource::rollback | ( | ) |
Rolls the current transaction back and releases the transaction lock.
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
Executes an SQL select statement on the server and returns the result as a hash (column names) of lists (column values per row)
The 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 Datasource::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 Datasource::selectRows().
This method also accepts all bind parameters (%d
, %v
, %s
, etc) as documented in Binding by Value and Placeholder
This method does not retain the transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"
), execute Datasource::beginTransaction() first to ensure that the transaction lock is dedicated to the calling 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 |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
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 Datasource::vselectRow().
This method also accepts all bind parameters (%d
, %v
, %s
, etc) as documented in Binding by Value and Placeholder
This method does not retain the transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"
), execute Datasource::beginTransaction() first to ensure that the transaction lock is dedicated to the calling 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 |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
DBI-SELECT-ROW-ERROR | more than 1 row retrieved from the server |
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 Datasource::select() method, therefore for larger amounts of data, it is recommended to use Datasource::select().
The usual return value of this method can be iterated with the ListHashIterator class.
This method also accepts all bind parameters (%d
, %v
, %s
, etc) as documented in Binding by Value and Placeholder
This method does not retain the transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"
), execute Datasource::beginTransaction() first to ensure that the transaction lock is dedicated to the calling 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 |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
Sets the database-specific character encoding name for the next connection to the server.
This is a method synonym for the Datasource::setDBEncoding() method, kept for backwards-compatibility.
Invalid character encoding names will cause an exception to be thrown when the connection is opened.
encoding | the database-specific character encoding name for the next connection to the server |
Sets the database-specific character encoding name for the next connection to the server.
Invalid character encoding names will cause an exception to be thrown when the connection is opened.
encoding | the database-specific character encoding name for the next connection to the server |
Sets the database name parameter for the time a connection to the server is established.
Invalid database names will cause an exception to be thrown when the connection is opened
db | the database name parameter for the time a connection to the server is established |
nothing Qore::SQL::Datasource::setEventQueue | ( | Qore::Thread::Queue | queue, |
auto | arg | ||
) |
Sets a queue object for DBI events on the datasource.
queue | the Queue object to receive datasource events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown; passing NOTHING will clear any event queue |
arg | an argument to be included in the arg key of datasource events |
QUEUE-ERROR | the Queue passed has a maximum size set |
Sets the hostname to use for the next connection to the server.
Invalid hostnames will cause an exception to be thrown when the connection is opened.
host | the hostname to use for the next connection to the server |
sets an option for the datasource
opt | the option to set |
val | the value to set |
DBI-OPTION-ERROR | unknown or unsupported option passed to driver |
DATASOURCE-ERROR | the datasource must be open for this call |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
Sets the password parameter for the time a connection to the server is established.
Invalid passwords will cause an exception to be thrown when the connection is opened
pass | the password parameter for the time a connection to the server is established |
Sets the port number to use for the connection.
Invalid port numbers will cause an exception to be thrown when the connection is opened
port | the port number to use for the connection |
Sets the transaction lock timeout value in milliseconds; set to 0 for no timeout.
timeout_ms | the transaction lock timeout value in milliseconds; set to 0 for no timeout. Like all Qore functions and methods taking timeout values, a relative date/time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms for 2.5 seconds). |
Sets the username parameter for the time a connection to the server is established.
Invalid usernames will cause an exception to be thrown when the connection is opened
user | the username parameter for the time a connection to the server is established |
int Qore::SQL::Datasource::transactionTid | ( | ) |
Returns the TID of the thread holding the transaction lock or -1 if it's not currently held.
If the Datasource object is used in a multithreaded context and if the transaction lock is not held by the current thread, then the transaction lock status could change at any time.
Grabs the transaction lock (if autocommit is disabled) and executes SQL code on the DB connection, taking a list for all bind arguments.
Same as Datasource::exec() except takes an explicit list for bind arguments
This method also accepts all bind parameters (%d
, %v
, %s
, etc) as documented in Binding by Value and Placeholder
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 |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
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 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
, %s
, etc) as documented in Binding by Value and Placeholder
This method does not retain the transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"
), execute Datasource::beginTransaction() first to ensure that the transaction lock is dedicated to the calling 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 |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
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 Datasource::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
, %s
, etc) as documented in Binding by Value and Placeholder
This method does not retain the transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"
), execute Datasource::beginTransaction() first to ensure that the transaction lock is dedicated to the calling 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 |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |
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 Datasource::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 Datasource::select() method, therefore for larger amounts of data, it is recommended to use Datasource::select().
This method also accepts all bind parameters (%d
, %v
, %s
, etc) as documented in Binding by Value and Placeholder
This method does not retain the transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"
), execute Datasource::beginTransaction() first to ensure that the transaction lock is dedicated to the calling 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 |
TRANSACTION-LOCK-TIMEOUT | Timeout trying to acquire the transaction lock |