 SourcePro® 2023.1 |
SourcePro® API Reference Guide |
Encapsulates an SQL INSERT statement.
More...
#include <rw/db/inserter.h>
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 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 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.
RWDBInserter instances 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 operator[]() 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 RWDBTable instances. 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.
Example 2
This is how to insert a single row, using an encapsulated VALUES clause:
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:
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:
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:
The result of RWDBInserter::execute() is an RWDBResult, which represents a sequence of zero or more RWDBTable instances. For details, see RWDBResult and RWDBTable.
| RWDBInserter::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 RWDBInserter instances. A usable RWDBInserter is obtained from an RWDBDatabase and RWDBTable.
| RWDBInserter::RWDBInserter | ( | const RWDBInserter & | ins | ) |
Copy constructor. Self shares an implementation with ins.
| void RWDBInserter::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.
| RWDBInserter& 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& 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.
|
inline |
Returns the SQL equivalent of:
or:
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:
or:
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:
or:
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 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 verbose as true will result in a string with blob data returned as hex numbers, such as 0x0A32F5.
|
inline |
Returns the SQL equivalent of:
or:
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 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 verbose as true will result in a string with blob data returned as hex numbers, such as 0x0A32F5.| RWDBStatus RWDBInserter::clear | ( | ) |
Clears self's list of scalar values and all internal controls.
| RWDBStatus::ErrorHandler RWDBInserter::errorHandler | ( | ) | const |
Returns the error handler attached to self.
| RWDBResult RWDBInserter::execute | ( | ) |
Uses a default database connection to cause the SQL statement encapsulated by self to be executed.
| RWDBResult RWDBInserter::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 RWDBInserter::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:
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.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.
| bool RWDBInserter::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 RWDBInserter::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.
| RWDBInserter& 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& 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& 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.
| RWDBInserter& RWDBInserter::operator<< | ( | const RWDBValue & | 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& RWDBInserter::operator<< | ( | char | 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& RWDBInserter::operator<< | ( | unsigned char | 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& RWDBInserter::operator<< | ( | short | 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& RWDBInserter::operator<< | ( | unsigned short | 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& RWDBInserter::operator<< | ( | int | 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& RWDBInserter::operator<< | ( | unsigned int | 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& RWDBInserter::operator<< | ( | long | 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& RWDBInserter::operator<< | ( | unsigned long | 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& RWDBInserter::operator<< | ( | long long | 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& RWDBInserter::operator<< | ( | unsigned long long | 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& RWDBInserter::operator<< | ( | float | 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& RWDBInserter::operator<< | ( | double | 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& RWDBInserter::operator<< | ( | long double | 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& RWDBInserter::operator<< | ( | const char * | 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& RWDBInserter::operator<< | ( | const RWDecimalPortable & | 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& RWDBInserter::operator<< | ( | const RWDate & | 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& RWDBInserter::operator<< | ( | const RWDateTime & | 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& RWDBInserter::operator<< | ( | const RWDBDateTime & | 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& RWDBInserter::operator<< | ( | const RWDBDuration & | 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& RWDBInserter::operator<< | ( | const RWCString & | 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& RWDBInserter::operator<< | ( | const RWDBMBString & | 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& 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.
| RWDBInserter& RWDBInserter::operator<< | ( | const RWWString & | 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& 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& 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& RWDBInserter::operator= | ( | const RWDBInserter & | ins | ) |
Assignment operator. Self shares an implementation with ins.
| RWDBInserter& 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& 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.
| size_t RWDBInserter::position | ( | ) | const |
| void RWDBInserter::release | ( | void | ) | const |
Releases a previously acquired mutex. This function can be called from a const object.
| void RWDBInserter::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 RWDBInserter::status | ( | ) | const |
Returns the current status of self.
| RWDBTable RWDBInserter::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 © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved. |