SourcePro® 2023.1 |
SourcePro® API Reference Guide |
Provides row-by-row access to tabular data. More...
#include <rw/db/reader.h>
Friends | |
RWDBInserter & | RWDBInserter::operator<< (RWDBReader &rdr) |
Class RWDBReader provides row-by-row access to tabular data. RWDBReader objects are produced by RWDBTable objects. When instantiated, an RWDBReader is positioned before the first row of the table that produced it. Subsequently, it can repeatedly advance to the next row, but can never retreat. The contents of each row, however, may be accessed at random. The function call operator is used to advance an RWDBReader one row. Within a row, the indexing or extraction operators may be used to access data.
The RWDBReader extraction operator is used to transfer data from the current row into program variables. The DB Interface Module has defined extraction operator variants for all native C++ types, as well as for RWCString, RWDateTime, RWDecimalPortable, and RWDBBlob. Programmers are encouraged to define variants for classes in their application domain.
RWDBReader has a notion of the current position within the current row. Each time the reader is advanced to a new row, the position is set to 0
. Each extraction increments the position by 1
. The indexing operators set the position to a specified index, column, or column name; they return a reference to self, so that any of the following notations may be used:
RWDBReader is designed around the Interface/Implementation paradigm. An RWDBReader instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBReader implementation is a base class from which a family of database-specific reader implementations is derived.
The DB Interface Module stores the data from the database in RWDBValue objects. See RWDBValue for information about conversions from table to C++ types. For information about the conversion from database-specific data types to RWDBValue, see The DB Access Module User's Guide for each database.
Applications that need to detect NULL
values explicitly can use an RWDBNullIndicator to test whether or not the next data item to be extracted is NULL
. Extracting into an RWDBNullIndicator sets the indicator to true
if the data item at the current row position is NULL
, otherwise sets it to false
. The current row position is left unchanged.
In this example, assume that there is a database table Employees
, with a unique integer key field id
, text field name
, and date field dateOfBirth
. We define an employee class, along with an operator to extract an employee record from an RWDBReader, and include a constructor to retrieve an employee record given an id
.
RWDBReader::RWDBReader | ( | ) |
The default constructor creates an RWDBReader whose status is RWDBStatus::notInitialized. This constructor is provided as a convenience, for example, for declaring an array of RWDBReader instances. Usable RWDBReader instances are obtained from a RWDBSelector or RWDBTable.
RWDBReader::RWDBReader | ( | const RWDBReader & | reader | ) |
Copy constructor. Self shares an implementation with reader.
void RWDBReader::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.
RWDBConnection RWDBReader::connection | ( | ) | const |
Returns the database connection used by self. An RWDBReader holds an RWDBConnection until the RWDBReader is destroyed.
RWDBStatus::ErrorHandler RWDBReader::errorHandler | ( | ) | const |
Returns the error handler attached to self.
bool RWDBReader::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 RWDBReader::isValid | ( | ) | const |
Returns true
if self's status is RWDBStatus::ok, otherwise returns false
.
void* RWDBReader::operator() | ( | ) |
Advances self to next row. Returns 0
if already at the last row, otherwise returns nonzero. This function must be called once to advance to the first entry in the result set. This function can behave asynchronously if self is using an asynchronous connection.
For example:
RWDBReader& RWDBReader::operator= | ( | const RWDBReader & | reader | ) |
Assignment operator. Self shares an implementation with reader.
RWDBReader& RWDBReader::operator>> | ( | RWDBNullIndicator & | nullIndicator | ) |
If self is valid, sets nullIndicator to true
if the data at the current row position represents a NULL
value, or false
otherwise. The current row position is unchanged. If self is not valid, nullIndicator is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWDBRow & | row | ) |
If self is valid and self's current row position is zero, copies each value in self to the corresponding position in row. If self is not valid, row is unchanged. If self's position is not zero, self's status is set to RWDBStatus::invalidUsage and row is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | char & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | unsigned char & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | short & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | unsigned short & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | int & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | unsigned int & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | long & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | unsigned long & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | float & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | double & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | long double & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWDecimalPortable & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWDate & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWTime & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWDateTime & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWTimeTuple & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWTimeTupleOffset & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWDBDateTime & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWDBDuration & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWCString & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWDBBlob & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWDBMBString & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWBasicUString & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWWString & | value | ) |
If self is valid, deposits data from the current row position into value and increments the current row position by one. If the data at the current row position cannot be converted to the given value's data type, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& RWDBReader::operator>> | ( | RWDBValue & | value | ) |
If self is valid, copies data from the current row position into value and increments the current row position by one. Otherwise does not change value. Returns a reference to self.
RWDBReader& RWDBReader::operator[] | ( | size_t | index | ) |
Changes the current row position to index. If index is out of range, self's status is set to RWDBStatus::invalidPosition. Returns a reference to self.
RWDBReader& RWDBReader::operator[] | ( | const RWCString & | colName | ) |
Interrogates self's table() for the index of the first column with given colName, and changes the current row position to the result. If there is no such column, sets self's status to RWDBStatus::invalidPosition. Returns a reference to self.
RWDBReader& RWDBReader::operator[] | ( | const RWDBColumn & | column | ) |
Interrogates self's table() for the index of the first column whose name matches the name of the given column, and changes the current row position to the result. If there is no such column, sets self's status to RWDBStatus::invalidPosition. Returns a reference to self.
size_t RWDBReader::position | ( | ) | const |
void RWDBReader::release | ( | ) | const |
Releases a previously acquired mutex. This function can be called from a const
object.
void RWDBReader::setErrorHandler | ( | RWDBStatus::ErrorHandler | errorHandler | ) |
Installs errorHandler as self's error handler. The supplied handler is inherited by all objects produced by self. By default an RWDBReader object inherits error handler from the object that produced it. This method overwrites the default.
RWDBStatus RWDBReader::status | ( | ) | const |
Returns the current status of self.
RWDBTable RWDBReader::table | ( | ) | const |
Returns the result table that produced self. See RWDBResult. Each result table is associated with a single reader, so multiple readers cannot be obtained from the returned result table.
|
friend |
Adds the contents of the current row in rdr to inserter.
Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved. |