| Member Functions | |||
| acquire() connection() errorHandler() isReady() |
isValid() operator>>() operator<<() operator()() |
operator=() operator[]() release() setErrorHandler() |
status() table() |
#include <rw/db/reader.h> RWDBReader rdr = myTable.reader(); RWDBReader rdr = mySelector.reader(); RWDBReader rdr = myMemTable.reader();
Class RWDBReader provides row-by-row access to tabular data. RWDBReaders are produced by RWDBTables. 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 operator () is used to advance an RWDBReader one row. Within a row, the operators for indexing [] and extraction >> may be used to access data.
The RWDBReader extraction operator >> is used to transfer data from the current row into program variables. DBTools.h++ has defined operator>> variants for all native C++ types, as well as for RWCString, RWDBDateTime, RWDecimalPortable (money), 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:
rdr >> x; rdr[i] >> x; rdr["columnName"] >> x; rdr[table["columnName"]] >> x;
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.
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.
class Employee {
public:
friend RWDBReader& operator>>(RWDBReader&, Employee&);
Employee(const RWDBDatabase& db, int id);
// etc.
private:
int id_;
RWCString name_;
RWDBDateTime dateOfBirth_;
};
RWDBReader&
operator>>(RWDBReader& rdr, Employee& employee){
rdr >> employee.id_ >> employee.name_ >> employee.dateOfBirth_;
return rdr;
}
Employee::Employee(const RWDBDatabase& db, int id){
RWDBSelector select = db.selector;
RWDBTable employees = db.table("Employees");
select << employees["id"] << employees["name"]
<< employees["dateOfBirth"];
select.where(employees["id"] == id);
RWDBReader rdr = select.reader();
if (!rdr()) //advance to first row and check for valid id
throw("no such employee");
rdr >> *this;
}
DBTools.h++ stores the data from the database in RWDBValues. See RWDBValue for information about conversions from RWDBValue to C++ types. For information about the conversion from database-specific datatypes to RWDBValue, see the DBTools.h++ access library 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.
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 RWDBReaders. Usable RWDBReaders are obtained from RWDBSelectors or RWDBTables.
RWDBReader(const RWDBReader& reader);
Copy constructor. Self shares an implementation with reader.
RWDBReader& operator=(const RWDBReader& reader);
Assignment operator. Self shares an implementation with reader.
void* 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.
NOTE:In asynchronous mode, you must check the validity of the reader prior to shifting out values from the reader.
The following code snippet demonstrates checking the validity of the reader:
while(reader())
{
if (reader.isValid())
{
reader >> myint >> mychar;
cout << "MyInt:" << myint << MyChar:" << mychar << endl;
}
}
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& 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. Sets self's status to RWDBStatus::invalidPosition if there is no such column. Returns a reference to self.
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.
RWDBReader& operator>>(char& value); RWDBReader& operator>>(unsigned char& value); RWDBReader& operator>>(short& value); RWDBReader& operator>>(unsigned short& value); RWDBReader& operator>>(int& value); RWDBReader& operator>>(unsigned int& value); RWDBReader& operator>>(long& value); RWDBReader& operator>>(unsigned long& value); RWDBReader& operator>>(float& value); RWDBReader& operator>>(double& value); RWDBReader& operator>>(RWDecimalPortable& value); RWDBReader& operator>>(RWDate& value); RWDBReader& operator>>(RWTime& value); RWDBReader& operator>>(RWDBDateTime& value); RWDBReader& operator>>(RWDBDuration& value); RWDBReader& operator>>(RWCString& value); RWDBReader& operator>>(RWDBBlob& value); RWDBReader& operator>>(RWDBMBString& value); 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 datatype, changes self's status to RWDBStatus::typeConversion without changing value. If self is not valid, value is unchanged. Returns a reference to self.
RWDBReader& operator>>(RWDBNullIndicator& nullIndictator);
If self is valid, sets nullIndicator to TRUE if the data at the current row position represents a NULL value, or to FALSE otherwise. The current row position is unchanged. If self is not valid, nullIndicator is unchanged. Returns a reference to self.
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& 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.
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.
RWDBConnection connection() const;
Returns the database connection used by self. An RWDBReader holds an RWDBConnection until the RWDBReader is destroyed.
RWDBStatus::ErrorHandler errorHandler() const;
Returns the error handler attached to self.
RWBoolean isReady();
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.
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 errorHandler);
Installs errorHhandler as self's error handler. The supplied handler is inherited by all objects produced by self. By default an RWDBConnection error handler is inherited from the object that produced it. This method overwrites the default.
RWDBStatus status() const;
Returns the current status of self.
RWDBTable table() 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 result table returned.
RWDBInserter& operator<<(RWDBReader& rdr);
Adds the contents of the current row in rdr to ins.
©Copyright 1999, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.