RWDBInserter
Module: DB Interface Module Group: Data Manipulation Classes
Does not inherit
- Local Index
- Synopsis
- Description
- Example 1
- Example 2
- Example 3
- Example 4
- Related Objects
- Public Constructors
- Public Member Operators
- Public Member Functions
Local Index
Members
|
acquire() addValue() asString() clear() errorHandler() |
execute() flush() isReady() isValid() operator<<() |
operator=() operator[]() release() RWDBInserter() setErrorHandler() |
status() table() |
Non-Members
Synopsis
#include <rw/db/inserter.h> RWDBInserter inserter = myTable.inserter(); RWDBInserter inserter = myTable.inserter(mySelector);
Description
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. The DB Interface Module does not check whether 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, the DB Interface Module 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.
Example 1
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);
Example 2
This is how to insert a single row, using an encapsulated VALUES clause:
RWDBInserter inserter = autoParts.inserter(); inserter << "steering wheel" << 1001; inserter.execute(connection);
Example 3
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);
Example 4
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);
Related Objects
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.
Public Constructors
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.
Public Member Operators
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<<(long long value); RWDBInserter& operator<<(unsigned long long value); RWDBInserter& operator<<(float value); RWDBInserter& operator<<(double value); RWDBInserter& operator<<(long double value); RWDBInserter& operator<<(const char* value); RWDBInserter& operator<<(const RWDecimalPortable& value); RWDBInserter& operator<<(const RWDate& value); RWDBInserter& operator<<(const RWDateTime& 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); RWDBInserter& operator<<(const RWBasicUString& 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.
NOTE -- This function accepts Unicode strings. For more information, see the entry for RWBasicUString in the Essential Tools Module Reference Guide. For more information on internationalization, see Chapter 13 of the DB Interface Module User's Guide.
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.
Public Member Functions
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 ...
This method returns an SQL statement that would be produced by executing self with an implicit connection. This method however does not produce an implicit connection. It uses the time zone setting of the producer RWDBDatabase instance.
The behavior of this asString() method depends upon the RWDBDatabase::verboseAsString() setting in the producer RWDBDatabase instance.
If verboseAsString() is false, the SQL returned is the same as that passed to the database for execution. This is the default.
If verboseAsString() is true, any placeholders in the returned SQL are replaced with their bound values.
NOTE -- When the RWDBDatabase::verboseAsString() option is set to 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 asString() with RWDBDatabase::verboseAsString() set to true will result in a string with blob data returned as hex numbers, such as 0x0A32F5.
RWCString asString(bool verbose) const;
Returns the SQL equivalent of:
INSERT INTO table ... VALUES ( ... )
or:
INSERT INTO table ... SELECT ...
This method returns an SQL statement that would be produced by executing self with an implicit connection. This method however does not produce an implicit connection. It uses the time zone setting of the producer RWDBDatabase instance.
The behavior of this method depends on the value of verbose, and is independent of the RWDBDatabase::verboseAsString() setting.
If verbose is false, the SQL returned is the same as that passed to the database for execution.
If verbose is 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.
NOTE -- The SQL returned by this method when verbose is true may not be a valid SQL statement. However, this is not necessarily the same SQL sent to the database for execution. For example, if an RWDBBlob object is bound, calling asString(true) will result in a string with blob data returned as hex numbers, such as 0x0A32F5.
RWCString asString(const RWDBConnection& conn) const;
Returns the SQL equivalent of:
INSERT INTO table ... VALUES ( ... )
or:
INSERT INTO table ... SELECT ...
This method returns an SQL statement that would be produced by executing self with conn. It uses the time zone setting of the RWDBConnection instance conn, which can be set programmatically with RWDBConnection::timeZone().
The behavior of this asString() method depends upon the RWDBDatabase::verboseAsString() setting in the producer RWDBDatabase instance.
If verboseAsString() is false, the SQL returned is the same as that passed to the database for execution. This is the default.
If verboseAsString() is true, any placeholders in the returned SQL are replaced with their bound values.
NOTE -- When the RWDBDatabase::verboseAsString() option is set to 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 asString() with RWDBDatabase::verboseAsString() set to true will result in a string with blob data returned as hex numbers, such as 0x0A32F5.
RWCString asString(const RWDBConnection& conn, bool verbose) const;
Returns the SQL equivalent of:
INSERT INTO table ... VALUES ( ... )
or:
INSERT INTO table ... SELECT ...
This method returns an SQL statement that would be produced by executing self with conn. It uses the time zone setting of the RWDBConnection instance conn, which can be set programmatically with RWDBConnection::timeZone().
The behavior of this method depends on the value of verbose, and is independent of the RWDBDatabase::verboseAsString() setting.
If verbose is false, the SQL returned is the same as that passed to the database for execution.
If verbose is 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.
NOTE -- The SQL returned by this method when verbose is true may not be a valid SQL statement. However, this is not necessarily the same SQL sent to the database for execution. For example, if an RWDBBlob object is bound, calling asString(true) will result in a string with blob data returned as hex numbers, such as 0x0A32F5.
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.
RWDBResult execute(const RWDBConnection& connection);
Uses the supplied connection to cause the SQL statement encapsulated by self to be executed. This function can behave asynchronously if executed using an asynchronous connection.
RWDBResult flush();
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.
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 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.
bool 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.
bool 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 Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.