dtl

DB_iterator<DataObj, ParamObj>


Category: iterators	Component type: type

Description

DB_iterator<DataObj, ParamObj> is an abstract base class that manipulates objects of type DataObj with a particular DBView (and thus the database). The SQL query used by the iterator is generated automatically based on the DBView and postfix parameters specified by the BPA. Each of the subclasses of DB_iterator generates the type of SQL query as suggested by its name. There are six classes that inherit from DB_iterator:

DBView<DataObj, ParamObj>::select_iterator - reads DataObj's from the database - Input Iterator
DBView<DataObj, ParamObj>::insert_iterator - inserts DataObj's into the database - Output Iterator
DBView<DataObj, ParamObj>::update_iterator - updates DataObj's in the database - Output Iterator
DBView<DataObj, ParamObj>::delete_iterator - deletes DataObj's from the database - Output Iterator
DBView<DataObj, ParamObj>::sql_iterator - executes SQL statments such as stored procedures against the database - Input Iterator, Output Iterator

All of these subclasses inherit from the std::iterator template defined in the C++ standard library and thus support the public typedefs DB_iterator::iterator_category, DB_iterator::value_type, DB_iterator::distance_type, DB_iterator::pointer, and DB_iterator::reference.

Definition

Defined in the DB_iterator.h header file.

Example

Inapplicable - abstract base class.

Template parameters

Parameter	Description	Default
`DataObj`	The type of object that will be written to the DBView. This object will be bound through use of the BCA to the appropriate columns in the database. The set of value types of an `DBView::insert_iterator` consists of a single type, DataObj.
`ParamObj`	The type of object that will be used to specify the postfix parameters to the DBView.	DefaultParamObj<DataObj>

Model of

Trivial Iterator.

Type requirements

DataObj and ParamObj must each fulfill the following requirements:.

Be of a type that is not primitive or of type string.
Have a publicly accessible copy constructor (the default is OK).
Have a publicly accessible assignment operator (the default is OK).

Public base classes

dtl_ios_base.

Members

Member	Where defined	Description
`DB_iterator()`	`DB_iterator`	Default constructor.
`DB_iterator(DBView<DataObj, ParamObj> &view, bool bPrepare)`	`DB_iterator`	See below.
`DB_iterator(const DB_iterator&)`	Trivial Iterator	The copy constructor.
`DB_iterator& operator=(const DB_iterator<DataObj, ParamObj>&)`	Trivial Iterator	The assignment operator
`DataObj &operator()` or `const DataObj &operator() const`	Trivial Iterator	Dereferencing operator. Returns (a reference to) the DataObj pointed to in the DBView. See Note [2].
`DB_iterator& operator++()`	Trivial Iterator	Preincrement. See Note [1].
`const DB_iterator operator++(int)`	Trivial Iterator	Postincrement. See Note [1].
`CountedPtr<DataObj> *operator->()`	Trivial Iterator	Dereferencing operator. Returns a pointer to the DataObj pointed to by the DBView.. See Note [2].
ParamObj &Params()	DB_iterator	See below.
void Params(const ParamObj &params)	DB_iterator	See below.
const DBView<DataObj, ParamObj> &GetView()	DB_iterator	See below.
string GetQuery() const	DB_iterator	See below.
long GetCount() const	DB_iterator	See below.
long GetLastCount() const	DB_iterator	See below.
void set_io_handler(IOHandler<DataObj, ParamObj>)	DB_iterator	See below.
template<class UserHandler> const UserHandler & get_io_handler(UserHandler *dummy) const	DB_iterator	See below.
IOHandler<DataObj, ParamObj> &get_io_handler() const	DB_iterator	See below.
dtl_iostate rdstate() const	dtl_ios_base	See below.
void setstate(dtl_iostate state)	dtl_ios_base	See below.
void clear(dtl_iostate state = goodbit)	dtl_ios_base	See below.
bool good() const	dtl_ios_base	See below.
bool bad() const	dtl_ios_base	See below.
bool fail() const	dtl_ios_base	See below.
void swap(DB_iterator<DataObj, ParamObj> &other)	DB_iterator	See below.
void SetPrepare(bool bPrepare)	DB_iterator	See below.

New members

These members are not defined in the Trivial Iterator requirements, but are specific to DB_iterator.

Function	Description
`DB_iterator(DBView<DataObj, ParamObj> &view, bool bPrepare)`	Creates a DB_iterator which refers to view. If bPrepare is true, uses SQLPrepare() and SQLExecute() to ultimately run the query, otherwise the iterator will use SQLExecDirect().
ParamObj &Params()	Returns a reference to the ParamObj which is bound to the postfix parameters used in the query to the database based on the BPA.
void Params(const ParamObj &params)	Sets the ParamObj, which is bound to the postfix parameters used in the query to the database based on the BPA, to value params.
const DBView<DataObj, ParamObj> &GetView()	Returns a reference to the DBView referred to by this DB_iterator.
string GetQuery() const	Returns the SQL query string associated with this DB_iterator.
long GetCount() const	Returns the number of DataObj's processed from the database since this select_iterator or the one it was copied or assigned from was first opened. Think of this result as the total number of DataObj's processed in this conceptual iterator's lifetime.
long GetLastCount() const	Returns the number of DataObj's processed from the database in last operation. For non-bulk operations for select and insert, this will return 1 as the iterator is operating on a single row. For bulk operations, updates, and deletes, the count returned is the actual number of rows processed by the single operation.
void set_io_handler(IOHandler<DataObj, ParamObj>)	Sets the IOHandler for this iterator. The IOHandler will try to handle exceptions thrown by the iterator and tell the code which caught the exception whether to suppress the error or still throw.
template<class UserHandler> const UserHandler & get_io_handler(UserHandler *dummy)	Returns the current IOHandler for this object cast to the actual type of the handler based on the dummy pointer passed in. If the dynamic cast of the IOHandler object fails, an exception will be thrown.
IOHandler<DataObj, ParamObj> &get_io_handler() const	Returns the current IOHandler for this object as a raw IOHandler object. You must cast to the actual type of the handler to be able to access any of your handler's public members.
dtl_iostate rdstate() const	Returns the state of the iterator as a bit field (as in the facilities for iostreams): goodbit == 0, failbit = 0x01, badbit = 0x02, bad_and_fail_bit = 0x03.
void setstate(dtl_iostate state)	Sets the state of the iterator to rdstate() \| state using a bit field.
void clear(dtl_iostate state = goodbit)	Sets the state of the iterator to state using a bit field.
bool good() const	Is the iterator in an OK state? Equivalent to rdstate() == goodbit.
bool bad() const	Is the iterator in a completely irreconcilable (such as a lost database connection or bad underlying SQL query)? Equivalent to (rdstate() & badbit) != 0.
bool fail() const	Is the iterator in a temporary failure state? This means the iterator is still usable, but the last operation on it failed (such as a validation on an element just read or written). Equivalent to ((rdstate() & failbit) != 0) \|\| bad().
void swap(DB_iterator<DataObj, ParamObj> &other)	Swaps *this with other.
void SetPrepare(bool bPrepare)	If bPrepare is true, then the iterator will use SQLPrepare() and SQLExecute() to run the query. Otherwise, SQLExecDirect() will be used. Must be called before the iterator is opened to take effect.

Notes

[1] This is the operation that actually processes the DataObj with the database via the DBView. Each DB_iterator internally owns a DBStmt object which is allocated and prepared when the underlying ODBC statement handle is first needed and not before. The handle is not opened until absolutely needed in order to make copying and assigning these iterators an inexpensive operation. The DBStmt is executed on each call to operator++(), whether the prefix or postfix version. The iterator implicitly commits all updates upon destruction unless an exception is thrown.

[2] This is not an operation actually declared in DB_iteratordue to the fact that operator*() returns a reference to the iterator itself for insert_iterator, update_iterator, and delete_iterator, but it returns a const reference to the value for select_iterator's. This operator is listed here for completeness.