Provides row-by-row access to tabular data. More...

#include <rw/db/reader.h>

Public Member Functions
	RWDBReader ()

	RWDBReader (const RWDBReader &reader)

void	acquire () const

RWDBConnection	connection () const

RWDBStatus::ErrorHandler	errorHandler () const

bool	isReady () const

bool	isValid () const

void *	operator() ()

RWDBReader &	operator= (const RWDBReader &reader)

RWDBReader &	operator>> (RWDBNullIndicator &nullIndicator)

RWDBReader &	operator>> (RWDBRow &row)

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>> (long double &value)

RWDBReader &	operator>> (RWDecimalPortable &value)

RWDBReader &	operator>> (RWDate &value)

RWDBReader &	operator>> (RWTime &value)

RWDBReader &	operator>> (RWDateTime &value)

RWDBReader &	operator>> (RWTimeTuple &value)

RWDBReader &	operator>> (RWTimeTupleOffset &value)

RWDBReader &	operator>> (RWDBDateTime &value)

RWDBReader &	operator>> (RWDBDuration &value)

RWDBReader &	operator>> (RWCString &value)

RWDBReader &	operator>> (RWDBBlob &value)

RWDBReader &	operator>> (RWDBMBString &value)

RWDBReader &	operator>> (RWBasicUString &value)

RWDBReader &	operator>> (RWWString &value)

RWDBReader &	operator>> (RWDBValue &value)

RWDBReader &	operator[] (size_t index)

RWDBReader &	operator[] (const RWCString &colName)

RWDBReader &	operator[] (const RWDBColumn &column)

size_t	position () const

void	release () const

void	setErrorHandler (RWDBStatus::ErrorHandler errorHandler)

RWDBStatus	status () const

RWDBTable	table () const

Friends
RWDBInserter &	RWDBInserter::operator<< (RWDBReader &rdr)

Detailed Description

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:

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.

Synopsis: #include <rw/db/reader.h>

RWDBReader rdr = myTable.reader();

RWDBReader rdr = mySelector.reader();

RWDBReader rdr = myMemTable.reader();

See also

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.

Example: 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_;

RWDateTime 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;

}

Constructor & Destructor Documentation

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.

Member Function Documentation

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.

Note: In single-threaded builds, this function evaluates to a no-op.

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.

Note: In asynchronous mode, you must check the validity of the reader prior to shifting out values from the reader.

For example:

while (reader()) {
    if (reader.isValid()) {
        reader >> myint >> mychar;
        cout << "MyInt: " << myint
             << "; MyChar: " << mychar << endl;
    }
}

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 )

Deprecated:: As of SourcePro 12.5, use operator>>(RWDateTime&) instead.

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

Returns the current position, at which the next value will be shifted in using the extraction operator. Returns RW_NPOS if isValid() returns false.

void RWDBReader::release ( ) const

Releases a previously acquired mutex. This function can be called from a const object.

Note: In single-threaded builds, this function evaluates to a no-op.

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.

Friends And Related Function Documentation

RWDBInserter& RWDBInserter::operator<< ( RWDBReader & rdr )

friend

Adds the contents of the current row in rdr to inserter.

SourcePro® API Reference Guide

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation