| Member Functions | |||
| acquire() addValue() asString() clear() |
errorHandler() execute() flush() isReady() |
isValid() operator<<() operator=() operator[]() |
release() setErrorHandler() status() table() |
#include <rw/db/inserter.h> RWDBInserter inserter = myTable.inserter(); RWDBInserter inserter = myTable.inserter(mySelector);
RWDBInserter is an encapsulation of the SQL INSERT statement. In SQL, the INSERT statement may be based either on a VALUES clause or on a SELECT statement. RWDBInserter supports either variant. Use the insertion operator << to add items to an RWDBInserter encapsulated VALUES clause, or supply an RWDBSelector when the RWDBInserter is produced. It is an error to use the insertion operator << with an RWDBInserter that was produced with an RWDBSelector.
An RWDBInserter can be produced with an optional RWDBSchema, which is used to generate a list of column names. If the list of column names is given, the values are inserted one for one into the specified columns. Otherwise the values are inserted into the table columns in the order they were created.
RWDBInserters that use the indexing operator, operator[], with colName derive a list of column names if all columns are provided. This allows values to be shifted into the inserter in any order, without requiring a schema and an additional database access.
RWDBInserter has a notion of the current position in itself. This position is set to zero when the RWDBInserter is produced, and reset to zero whenever execute() is called. Each insertion operation adds a value at the current position and increments the position by one. If the RWDBInserter was created with an optional RWDBSchema, then the indexing operators [] can set the position to a specified column or column name, and return a reference to self. DBTools.h++ does not check to see if the inserted values match the table's schema in type or in number; such errors are reported by the database when execute() is invoked.
An INSERT 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 INSERT statement. Consequently, the RWDBInserter 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.
RWDBInserter is designed around the Interface/Implementation paradigm. An RWDBInserter instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBInserter implementation is a base class from which a family of database-specific inserter implementations is derived.
For this example, assume an AutoParts table in the database, with text column name and integer column id. Here is a way to populate it with data selected from another table, AllParts, which is also assumed to have a name and an id column.
RWDBTable allParts = myDbase.table("AllParts");
RWDBConnection connection = myDbase.connection();
RWDBSelector select = myDbase.selector();
select << allParts["name"] << allParts["id"];
select.where(allParts["type"] == "Auto");
RWDBTable autoParts = myDbase.table("AutoParts");
RWDBInserter inserter = autoParts.inserter(select);
inserter.execute(connection);
This is how to insert a single row, using an encapsulated VALUES clause:
RWDBInserter inserter = autoParts.inserter(); inserter << "steering wheel" << 1001; inserter.execute(connection);
This is how to insert a single row, using a column list and an encapsulated VALUES clause. The correct order of insertions depends on the supplied RWDBSchema, not on the order of columns in the autoParts table:
RWDBSchema schema;
schema.appendColumn("id");
schema.appendColumn("name");
RWDBInserter inserter = autoParts.inserter(schema);
inserter << 1001; // associate with schema's 0
// with column "id"
inserter << "steering wheel"; // associate with schema's 0
// with column "name"
inserter.execute(connection);
This is how to insert a single row, using a column list, but supplying bindings to application variables. The advantage here is that the same insertion can be made several times without reshifting variables:
RWDBSchema schema;
schema.appendColumn("id");
schema.appendColumn("name");
RWDBInserter inserter = autoParts.inserter(schema);
int id = 1001;
RWCString name = "steering wheel";
inserter << RWDBBoundExpr( &id );
inserter << RWDBBoundExpr( &name );
inserter.execute();
id = 2001;
name = "gear shift";
inserter.execute(connection);
RWDBValueManip rwdbNull;
rwdbNull is used to represent a literal NULL value. A NULL value can be inserted through an RWDBInserter by inserting rwdbNull into the inserter like this:
inserter << rwdbNull;
RWDBValueManip is a typedef:
typedef void (*RWDBValueManip)(RWDBValue&);
The result of RWDBInserter::execute() is an RWDBResult, which represents a sequence of zero or more RWDBTables. For details, see RWDBResult and RWDBTable.
RWDBInserter();
The default constructor creates an RWDBInserter whose status is RWDBStatus::notInitialized. This constructor is provided as a convenience, for example, to declare an array of RWDBInserters. Usable RWDBInserters are obtained from RWDBDatabases and RWDBTables.
RWDBInserter(const RWDBInserter& ins);
Copy constructor. Self shares an implementation with ins.
RWDBInserter & operator[](const RWCString& colName);
Sets self's current position to the index associated with the column in the column list whose name matches colName. If there is no such column, colName is appended to the column list and the current position is set to the index of that new entry. The next insertion into self will associate the inserted value with the current position. Returns a reference to self.
RWDBInserter & operator[](const RWDBColumn& column);
Sets self's current position to the index associated with the column in the column list whose name matches column.name(). If there is no such column, column.name() is appended to the column list and the current position is set to the index of that new entry. The next insertion into self will associate the inserted value with the current position. Returns a reference to self.
RWDBInserter& operator=(const RWDBInserter& ins);
Assignment operator. Self shares an implementation with ins.
RWDBInserter& operator<<(const RWDBValue& value); RWDBInserter& operator<<(char value); RWDBInserter& operator<<(unsigned char value); RWDBInserter& operator<<(short value); RWDBInserter& operator<<(unsigned short value); RWDBInserter& operator<<(int value); RWDBInserter& operator<<(unsigned int value); RWDBInserter& operator<<(long value); RWDBInserter& operator<<(unsigned long value); RWDBInserter& operator<<(float value); RWDBInserter& operator<<(double value); RWDBInserter& operator<<(const char* value); RWDBInserter& operator<<(const RWDecimalPortable& value); RWDBInserter& operator<<(const RWDate& value); RWDBInserter& operator<<(const RWDBDateTime& value); RWDBInserter& operator<<(const RWDBDuration& value); RWDBInserter& operator<<(const RWCString& value); RWDBInserter& operator<<(const RWDBMBString& value); RWDBInserter& operator<<(const RWWString& value); RWDBInserter& operator<<(const RWDBBlob& value);
Adds the provided value as a literal in the encapsulated VALUES clause in self. The position that value holds is associated with the current position within self. The current position is incremented after adding the value. If self was produced with an RWDBSelector, sets self's status to RWDBStatus::invalidUsage. Returns a reference to self.
RWDBInserter& operator<<(const RWDBExpr& value);
Adds a scalar expression to the encapsulated VALUES clause in self, allowing values or scalar expressions to be inserted into a table. The position that value holds is associated with the current position within self. The current position is incremented after adding the expression. If self was produced with an RWDBSelector, sets self's status to RWDBStatus::invalidUsage. Returns a reference to self.
RWDBInserter& operator<<(const RWDBBoundExpr& value);
Adds a variable expression to the encapsulated VALUES clause in self, where supported, thus allowing values or scalar expressions to be inserted into a table. The position that value holds is associated with the current position within self. The current position is incremented after adding the expression. If self was produced with an RWDBSelector, sets self's status to RWDBStatus::invalidUsage. Returns a reference to self.
RWDBInserter& operator<<(RWDBReader& reader);
A row of data can be inserted directly from an RWDBReader into an RWDBInserter. This method is equivalent to using a loop to extract each value out of reader into inserter. Returns a reference to self.
RWDBInserter& operator<<(RWDBValueManip& manip);
Adds an RWDBValueManip to the encapsulated VALUES clause in self. RWDBValueManip is a typedef and is typically used to insert a literal NULL into the inserter. The position that manip holds is associated with the current position within self. The current position is incremented after adding the expression.
Use rwdbNull to insert a literal NULL into an inserter.
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.
RWDBInserter& addValue(const RWDBExpr& value);
Adds value to self's encapsulated VALUES clause. If self was produced with an RWDBSelector, sets self's status to RWDBStatus::invalidUsage. Equivalent to inserting value into self. Returns reference to self.
RWDBInserter& addValue(const RWDBBoundExpr& value);
Adds value to self's encapsulated VALUES clause. If self was produced with an RWDBSelector, sets self's status to RWDBStatus::invalidUsage. Equivalent to inserting value into self. Returns reference to self.
RWCString asString() const;
Returns the SQL equivalent of:
INSERT INTO table ... VALUES ( ... )
or:
INSERT INTO table ... SELECT ...
RWDBStatus clear();
Clears self's list of scalar values and all 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.
RWDBResult flush();
Sends all cached data, if any, to the server. Depending on the size of the cache parameter used to create the inserter, can work one of two ways:
When the cache parameter is less than or equal to 1, sends cached data to the server immediately on invocation of ::execute(). Ignores any direct invocations of flush(), like a no-op.
When the cache parameter is greater than 1, sends cached data to the server, and is called automatically when the cache is full.
When the connection between executions changes, flush() is called before executing on the new connection. However, new data since the last execute on the old connection is saved for the new execute on the new 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 RWDBInserter 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.
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, an RWDBInserter error handler 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.
©Copyright 1999, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.