| Member Functions | |||
| acquire() asString() clear() errorHandler() |
execute() isReady() isValid() operator<<() |
operator=() operator[]() release() set() |
setErrorHandler() status() table() where() |
#include <rw/db/updater.h> RWDBUpdater updater = myTable.updater();
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 << is used to add encapsulated SET clauses to an RWDBUpdater; the where() method is used to specify a WHERE clause. The items which are inserted into an RWDBUpdater are RWDBAssignments, which are created by the assign() method of RWDBColumn. The WHERE clause is encapsulated by an RWDBCriterion, which is some number of RWDBExprs combined with logical operators.
An UPDATE statement does not normally produce results. However, DBTools.h++ recognizes that some database vendors provide triggers, which can cause results to be generated by an UPDATE statement. Consequently, RWDBUpdater's execute() method returns an RWDBResult, which is a sequence of zero or more RWDBTables. 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's implementation is a base class from which a family of database-specific updater implementations is derived.
This example uses an RWDBUpdater to increment the number column of the Inventory table by 50 wherever red is found in the color column.
RWDBTable inventory = myDbase.table("Inventory");
RWDBConnection connection = myDbase.connection();
RWDBUpdater update = table.updater();
RWDBColumn number = inventory["number"];
update << number.assign(number + 50);
update.where(inventory["color"] == "red");
update.execute(connection);
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.
RWDBTable inventory = myDbase.table("Inventory");
RWDBConnection connection = myDbase.connection();
RWDBUpdater update = table.updater();
RWDBColumn number = inventory["number"];
int increment = 50;
RWCString color = "red";
update << number.assign( number + RWDBBoundExpr( &increment) );
update.where( inventory["color"] == RWDBBoundExpr(&color) );
update.execute(connection);
increment = 100;
color = "gold";
update.execute(connection);
The encapsulated WHERE clause of an RWDBUpdater is an RWDBCriterion, which is composed of RWDBExprs. 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 RWDBTables. See RWDBResult and RWDBTable for details.
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 RWDBUpdaters. Usable RWDBUpdaters are obtained from RWDBTables.
RWDBUpdater(const RWDBUpdater& upd);
Copy constructor. Self shares an implementation with upd.
RWDBUpdater& operator=(const RWDBUpdater& upd);
Assignment operator. Self shared an implementation with upd.
void acquire() 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. Note: in nonmultithreaded builds, this function evaluates to a no-op.
RWCString asString() const;
Returns the SQL equivalent of:
UPDATE table SET ... [ WHERE ...]
RWDBStatus clear();
Clears self's list of assignments, WHERE clauses, and internal controls.
RWDBStatus::ErrorHandler errorHandler() const;
Returns the error handler attached to self.
RWDBResult execute();
Uses a default database connection to cause the SQL statement encapsulated by self to be executed. The connection is held by the RWDBResult until the RWDBResult is destroyed.
RWDBResult execute(const RWDBConnection& connection);
Uses the supplied connection to cause the SQL statement encapsulated by self to be executed. The connection is held by the RWDBResult until the RWDBResult is destroyed. This function can behave asynchronously if executed using an asynchronous connection.
RWBoolean isReady() const;
This function returns TRUE if the object is in ready state, indicating that accessing the object will not block. Accessing a nonready object may potentially block.
RWBoolean isValid() const;
Returns TRUE if self's status is RWDBStatus::ok, otherwise returns FALSE. Does not return FALSE if the previous executed statement failed. You must check the status of the RWDBResult returned from execute() instead of the status of the RWDBUpdater object.
void release() const;
Releases a previously acquired mutex. This function can be called from a const object. Note: in nonmultithreaded builds, this function evaluates to a no-op.
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 setErrorHandler(RWDBStatus::ErrorHandler handler);
Installs handler as self's error handler. The supplied handler is inherited by all objects produced by self. By default, the error handler of an RWDBUpdater is inherited from the object that produced it; this method overrides the default. ErrorHandler is declared as a typedef within the scope of RWDBStatus:
typedef void (*ErrorHandler)(const RWDBStatus&);
RWDBStatus status() const;
Returns the current status of self.
RWDBTable 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 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& 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.
RWDBUpdater&
operator<<(RWDBUpdater& updater,
const RWDBAssignment assignment);
Appends assignment to the encapsulated SET clause in self. Returns a reference to self.
RWDBUpdater& operator[](size_t index);
Sets self's current position to index.
©Copyright 1999, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.