SourcePro® 2024.1 |
SourcePro® API Reference Guide |
Encapsulates the SQL UPDATE
statement.
More...
#include <rw/db/updater.h>
Public Member Functions | |
RWDBUpdater () | |
RWDBUpdater (const RWDBUpdater &upd) | |
void | acquire (void) const |
RWCString | asString () const |
RWCString | asString (bool verbose) const |
RWCString | asString (const RWDBConnection &conn) const |
RWCString | asString (const RWDBConnection &conn, bool verbose) const |
RWDBStatus | clear () |
RWDBStatus::ErrorHandler | errorHandler () const |
RWDBResult | execute () |
RWDBResult | execute (const RWDBConnection &connection) |
bool | isReady () const |
bool | isValid () const |
RWDBUpdater & | operator= (const RWDBUpdater &upd) |
RWDBUpdater & | operator[] (size_t index) |
void | release (void) const |
RWDBUpdater & | set (const RWDBAssignment &assignment) |
void | setErrorHandler (RWDBStatus::ErrorHandler handler) |
RWDBStatus | status () const |
RWDBTable | table () const |
RWDBCriterion | where () const |
RWDBUpdater & | where (const RWDBCriterion &criterion) |
Related Symbols | |
(Note that these are not member symbols.) | |
RWDBUpdater & | operator<< (RWDBUpdater &upd, const RWDBAssignment &assignment) |
RWDBUpdater is an encapsulation of an SQL UPDATE
statement. Its methods provide an application with explicit control over the UPDATE
statement's SET
and WHERE
clauses.
The insertion operator operator<<() is used to add encapsulated SET
clauses to an RWDBUpdater; the where() method specifies a WHERE
clause. The items that are inserted into an RWDBUpdater are RWDBAssignment objects, created by the assign() method of RWDBColumn. The WHERE
clause is encapsulated by an RWDBCriterion, which is some number of RWDBExpr objects combined with logical operators.
An UPDATE
statement does not normally produce results. However, the DB Interface Module recognizes that some database vendors provide triggers, which can cause results to be generated by an UPDATE
statement. Consequently, the execute() method of RWDBUpdater returns an RWDBResult, which is a sequence of zero or more RWDBTable objects. Applications are not obliged to request any tables from the returned object.
RWDBUpdater is designed around the Interface/Implementation paradigm. An RWDBUpdater instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBUpdater implementation is a base class from which a family of database-specific updater implementations is derived.
The encapsulated WHERE
clause of an RWDBUpdater is an RWDBCriterion, which is composed of RWDBExpr objects. Each encapsulated SET
clause is an RWDBAssignment, produced by the assign() method of RWDBColumn. See RWDBAssignment, RWDBCriterion, RWDBExpr, and RWDBColumn for details.
The result of RWDBUpdater::execute() is an RWDBResult, which represents a sequence of zero or more RWDBTable objects. See RWDBResult and RWDBTable for details.
Example 1
This example uses an RWDBUpdater to increment the number
column of the Inventory
table by 50
wherever red
is found in the color
column.
Example 2
This example accomplishes the same task as Example 1, but provides bindings to an application variable. This allows the application to repeatedly execute the update with different values without reshifting in values.
RWDBUpdater::RWDBUpdater | ( | ) |
The default constructor creates an RWDBUpdater whose status is RWDBStatus::notInitialized. This constructor is provided as a convenience, for example, for declaring an array of RWDBUpdater objects. Usable RWDBUpdater instances are obtained from RWDBTable instances.
RWDBUpdater::RWDBUpdater | ( | const RWDBUpdater & | upd | ) |
Copy constructor. Self shares an implementation with upd.
void RWDBUpdater::acquire | ( | void | ) | const |
Attempts to acquire the internal mutex lock. If the mutex is already locked by another thread, the function blocks until the mutex is released. This function can be called from a const
object.
|
inline |
Returns the SQL equivalent of:
This method returns an SQL statement that would be produced by executing self with an implicit RWDBConnection object. An implicit RWDBConnection object inherits the time zone setting from the producer RWDBDatabase instance. Hence, the time zone setting of the producer RWDBDatabase object will be used for creating the string representations of any RWDateTime instances in self.
The behavior of this method depends upon the RWDBDatabase::verboseAsString() setting in the producer RWDBDatabase instance.
false
, the SQL returned is the same as that passed to the database for execution. This is the default.true
, any placeholders in the returned SQL are replaced with their bound values.true
, the SQL returned by this method may not be a valid SQL statement. However, this method's return value is not necessarily the same SQL that is sent to the database for execution. For example, if an RWDBBlob object is bound, calling this method with RWDBDatabase::verboseAsString() set to true
will result in a string with blob data returned as hex numbers, such as 0x0A32F5
.
|
inline |
Returns the SQL equivalent of:
This method returns an SQL statement that would be produced by executing self with an implicit RWDBConnection object. An implicit RWDBConnection object inherits the time zone setting from the producer RWDBDatabase instance. Hence, the time zone setting of the producer RWDBDatabase object will be used for creating the string representations of any RWDateTime instances in self.
The behavior of this method depends on the value of verbose, and is independent of the RWDBDatabase::verboseAsString() setting.
false
, the SQL returned is the same as that passed to the database for execution.true
, any placeholders in the returned SQL are replaced with their bound values although the SQL passed to the database for execution will not be affected.true
may not be a valid SQL statement. However, this is not necessarily the same SQL that is sent to the database for execution. For example, if an RWDBBlob object is bound, calling this method with verbose as true
will result in a string with blob data returned as hex numbers, such as 0x0A32F5
.
|
inline |
Returns the SQL equivalent of:
This method returns an SQL statement that would be produced by executing self with conn. The time zone setting of conn will be used for creating string representations of any RWDateTime instances in self.
The behavior of this method depends upon the RWDBDatabase::verboseAsString() setting in the producer RWDBDatabase instance.
false
, the SQL returned is the same as that passed to the database for execution. This is the default.true
, any placeholders in the returned SQL are replaced with their bound values.true
, the SQL returned by this method may not be a valid SQL statement. However, this method's return value is not necessarily the same SQL that is sent to the database for execution. For example, if an RWDBBlob object is bound, calling this method with RWDBDatabase::verboseAsString() set to true
will result in a string with blob data returned as hex numbers, such as 0x0A32F5
.
|
inline |
Returns the SQL equivalent of:
This method returns an SQL statement that would be produced by executing self with conn. The time zone setting of conn will be used for creating string representations of any RWDateTime instances in self.
The behavior of this method depends on the value of verbose, and is independent of the RWDBDatabase::verboseAsString() setting.
false
, the SQL returned is the same as that passed to the database for execution.true
, any placeholders in the returned SQL are replaced with their bound values although the SQL passed to the database for execution will not be affected.true
may not be a valid SQL statement. However, this is not necessarily the same SQL that is sent to the database for execution. For example, if an RWDBBlob object is bound, calling this method with verbose as true
will result in a string with blob data returned as hex numbers, such as 0x0A32F5
.RWDBStatus RWDBUpdater::clear | ( | ) |
Clears self's list of assignments, WHERE
clauses, and internal controls.
RWDBStatus::ErrorHandler RWDBUpdater::errorHandler | ( | ) | const |
Returns the error handler attached to self.
RWDBResult RWDBUpdater::execute | ( | ) |
Uses a default database connection to execute the SQL statement encapsulated by self.
RWDBResult RWDBUpdater::execute | ( | const RWDBConnection & | connection | ) |
Uses the supplied connection to execute the SQL statement encapsulated by self. This function can behave asynchronously if executed using an asynchronous connection.
bool RWDBUpdater::isReady | ( | ) | const |
Returns true
if the object is in ready state, indicating that accessing the object will not block. Accessing a nonready object may potentially block.
bool RWDBUpdater::isValid | ( | ) | const |
Returns true
if self's status is RWDBStatus::ok, otherwise returns false
. Does not return false
if the previously executed statement failed. In this case, you must check the status of the RWDBResult returned from execute() instead of the status of the RWDBUpdater object.
RWDBUpdater & RWDBUpdater::operator= | ( | const RWDBUpdater & | upd | ) |
Assignment operator. Self shared an implementation with upd.
RWDBUpdater & RWDBUpdater::operator[] | ( | size_t | index | ) |
Sets self's current position to index.
void RWDBUpdater::release | ( | void | ) | const |
Releases a previously acquired mutex. This function can be called from a const
object.
RWDBUpdater & RWDBUpdater::set | ( | const RWDBAssignment & | assignment | ) |
Adds the encapsulated SET
clause represented by assignment to self. Equivalent to inserting assignment into self. Returns a reference to self.
void RWDBUpdater::setErrorHandler | ( | RWDBStatus::ErrorHandler | handler | ) |
Installs handler as self's error handler. The supplied handler is inherited by all objects produced by self. By default, an RWDBStatus::ErrorHandler is inherited from the object that produced self; this method overrides the default.
RWDBStatus RWDBUpdater::status | ( | ) | const |
Returns the current status of self.
RWDBTable RWDBUpdater::table | ( | ) | const |
Returns the RWDBTable that produced self. Returns an RWDBTable whose status is RWDBStatus::notInitialized if self was created with the default constructor.
RWDBCriterion RWDBUpdater::where | ( | ) | const |
Returns a copy of self's RWDBCriterion, an encapsulated SQL WHERE
clause. Returns an empty RWDBCriterion if self has no WHERE
clause.
RWDBUpdater & RWDBUpdater::where | ( | const RWDBCriterion & | criterion | ) |
Specifies criterion as self's SQL WHERE
clause. If self already has a WHERE
clause, this method replaces it. Specifying an empty criterion clears self's WHERE
clause. Notice that an updater without a WHERE
clause updates all rows in its table. Returns a reference to self.
|
friend |
Appends assignment to the encapsulated SET
clause in upd. Returns a reference to upd.
Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved. |