RWDBCursor Class Reference
[Data Manipulation]

Encapsulates a database cursor. More...

#include <rw/db/cursor.h>

List of all members.

Public Types
enum	CursorType { Sequential, Scrolling }
enum	CursorAccess { Read, Write }
enum	CursorPosition {   First, Last, Next, Previous,   Absolute, Relative }
Public Member Functions
	RWDBCursor ()
	RWDBCursor (const RWDBCursor &csr)
RWCString	name () const
CursorType	type () const
CursorAccess	access () const
RWDBConnection	connection () const
RWDBSchema	schema () const
void	setErrorHandler (RWDBStatus::ErrorHandler handler)
RWDBStatus::ErrorHandler	errorHandler () const
RWDBStatus	status () const
bool	isValid () const
bool	isReady () const
void	acquire () const
void	release () const
RWDBStatus	fetchRow (CursorPosition position=Next, int offset=1)
RWDBStatus	updateRow (const RWCString &tableName)
RWDBStatus	deleteRow (const RWCString &tableName)
RWDBStatus	insertRow (const RWCString &tableName)
RWDBStatus	unbind ()
bool	isNull (size_t index) const
void	setNull (size_t colPosition)
void	unsetNull (size_t colPosition)
RWDBCursor &	operator<< (short *val)
RWDBCursor &	operator<< (unsigned short *val)
RWDBCursor &	operator<< (int *val)
RWDBCursor &	operator<< (unsigned int *val)
RWDBCursor &	operator<< (long *val)
RWDBCursor &	operator<< (unsigned long *val)
RWDBCursor &	operator<< (long long *val)
RWDBCursor &	operator<< (unsigned long long *val)
RWDBCursor &	operator<< (float *val)
RWDBCursor &	operator<< (double *val)
RWDBCursor &	operator<< (long double *val)
RWDBCursor &	operator<< (RWDecimalPortable *val)
RWDBCursor &	operator<< (RWDate *val)
RWDBCursor &	operator<< (RWDateTime *val)
RWDBCursor &	operator<< (RWDBDateTime *val)
RWDBCursor &	operator<< (RWDBDuration *val)
RWDBCursor &	operator<< (RWCString *val)
RWDBCursor &	operator<< (RWDBMBString *val)
RWDBCursor &	operator<< (RWWString *val)
RWDBCursor &	operator<< (RWDBBlob *val)
RWDBCursor &	operator<< (RWBasicUString *val)
RWDBCursor &	operator<< (RWDBValueManip)
RWDBCursor &	operator[] (size_t index)
RWDBCursor &	operator[] (const RWCString &colName)
RWDBCursor &	operator[] (const RWDBColumn &column)
RWDBCursor &	operator= (const RWDBCursor &csr)

---

Detailed Description

RWDBCursor is an encapsulation of a database cursor. It is a relatively low-level construct that maps directly onto a database cursor.

Despite the efforts of various standards bodies, cursor capabilities vary widely among database vendors. The DB Interface Module does not attempt to emulate functionality that is not supported by the underlying database engine. For example, if a database vendor's implementation does not support scrollable cursors, an application requesting a scrollable RWDBCursor from that RWDBDatabase receives an RWDBCursor with a status of RWDBStatus::notSupported. The remainder of this section assumes that all features are supported. See your DB Access Module guide for details concerning RWDBCursor restrictions for a particular database.

RWDBCursor captures common features of database cursors.

Specifically:

• There can be multiple RWDBCursor instances open on a single connection.
• RWDBCursor provides row-by-row access to data.
• RWDBCursor supports index entry and positioned deletes.
• RWDBCursor may be read-only or read-write.
• RWDBCursor may be scrollable or sequential.
• RWDBCursor operates on application-supplied buffers. It is pointer-based rather than value-based.

The insertion operator is used to supply an RWDBCursor with pointers to application variables. When possible, RWDBCursor performs a cursor bind operation directly on the pointer provided. This is always possible for pointers to primitive C++ types. Otherwise, the RWDBCursor allocates enough space internally to do the required type conversion, binds to its internal buffers, and arranges for results to be copied into the buffers supplied by the application.

An application continues to own the memory supplied to an RWDBCursor, and it is the application's responsibility to ensure that a pointer remains valid for as long as the RWDBCursor requires it. The unbind() method can be used to dissociate program memory from the RWDBCursor.

RWDBCursor has a notion of the current column position within the current row. Each time the cursor is advanced to a new row, the column position is set to 0. Each insertion increments the column 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:

 cursor  <<  &x;
 cursor[i]  <<  &x;
 cursor["columnName"]  <<  &x;
 cursor[table["columnName"]]  <<  &x;

RWDBCursor is designed around the Interface/Implementation paradigm. An RWDBCursor instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. RWDBCursor implementations are base classes from which a family of database-specific cursor implementations are derived.

Synopsis

 #include <rw/db/cursor.h>

 RWDBCursor cursor = myDbase.cursor(mySelector);
 RWDBCursor cursor = myDbase.cursor("SQL String");
 RWDBCursor cursor = myTable.cursor();

Examples

Assume there are database tables Inventory and Suppliers. The Inventory table has partNumber, Supplier, and onHand columns; the Suppliers table has Supplier and toOrder columns. This example uses two RWDBCursor instances to examine the Inventory table for any parts that have fewer than 10 on hand, and increment the order column in the Suppliers table for each such part.

 RWDBConnection session = myDbase.connection();
 RWDBTable inventory = myDbase.table("Inventory");
 RWDBTable suppliers = myDbase.table("Suppliers");
 RWDBSelector shortage = myDbase.selector();
 shortage << inventory;
 RWDBSelector order = myDbase.selector();
 order << suppliers;
 shortage.where(inventory["onHand"] < 10);
 RWDBCursor invCsr = shortage.cursor(session);

 int partNumber;
 RWCString supplier;
 int onHand;
 int toOrder;
 invCsr << &partNumber << &supplier << &onHand;
 while (invCsr.fetchRow().isValid()) {
    order.where(suppliers["Supplier"] == supplier);
    session.beginTransaction();
    RWDBCursor ordCsr = order.cursor(session,
       RWDBCursor::Sequential, RWDBCursor::Write);
    ordCsr << &supplier << &toOrder;
    while (ordCsr.fetchRow().isValid()) {
       ++toOrder;
       ordCsr.updateRow(suppliers.name());
    }
    session.commitTransaction();
 }

Assume a database table Parts. The Parts table has columns id, partName, cost with the types int, varchar, and int respectively. Assume an entry in the table with an id number and a partName, but the cost was inserted as NULL. This example uses one RWDBCursor to demonstrate how to update a row with a NULL value in a column and set a value for that column. Note that the column being updated must be UNSET from NULL for the new value to be updated in the table.

 int newCost = 0;
 RWDBSelector select = aDB.selector();
 select << parts["cost"];
 select.where(parts["partName"] == "Steering Wheel");
 select.fetchSchema(conn);
 RWDBSchema schema = select.schema();
 RWDBCursor cursor = select.cursor(schema, conn, RWDBCursor::Sequential, RWDBCursor::Write);
 cursor["cost"] << &newCost;
 if (cursor.fetchRow().isValid())
 {
   newCost = 30;
   if(cursor.isNull(0)) {
     cursor.unsetNull(0);
   }
   RWDBStatus status = cursor.updateRow(parts.name());
 }

---

Member Enumeration Documentation

enum RWDBCursor::CursorAccess

This enum holds values for cursor access.

Enumerator:

Read	A Read cursor can only be used to select data.
Write	A Write cursor can also be used for updates, inserts, and deletes.

enum RWDBCursor::CursorPosition

The CursorPosition is used by the fetchRow() method to identify the row to be fetched. A Scrolling cursor can fetch any row in a set of result rows. A Sequential cursor can fetch only the Next row.

Enumerator:

First	Fetches first row.
Last	Fetches last row.
Next	Fetches next row.
Previous	Fetches previous row.
Absolute	Fetches absolute row.
Relative	Fetches relative row.

enum RWDBCursor::CursorType

This enum holds values for cursor type.

Enumerator:

Sequential	A Sequential cursor can only advance to the Next row.
Scrolling	A Scrolling cursor can move to the First, Last, Next, or Previous row; to a row number Relative to the current row; or to an Absolute row number.

---

Constructor & Destructor Documentation

RWDBCursor::RWDBCursor

(

)

The default constructor creates an RWDBCursor whose status is RWDBStatus::notInitialized. This constructor is provided as a convenience, for example, for declaring an array of RWDBCursor objects. Usable RWDBCursor objects are obtained from instances of RWDBDatabase, RWDBTable, and RWDBSelector.

RWDBCursor::RWDBCursor

(

const RWDBCursor &

csr

)

Copy constructor. Self shares an implementation with csr.

---

Member Function Documentation

CursorAccess RWDBCursor::access

(

)

const

Returns self's cursor access. The cursor access is specified when an RWDBCursor is first obtained. The default is RWDBCursor::Read.

void RWDBCursor::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 RWDBCursor::connection

(

)

const

Returns the database connection used by self. An RWDBCursor holds an RWDBConnection until the RWDBCursor is destroyed. There may be more than one RWDBCursor opened using the same RWDBConnection.

RWDBStatus RWDBCursor::deleteRow

(

const RWCString &

tableName

)

Encapsulates the database-specific equivalent of the SQL statement:

DELETE tableName WHERE CURRENT OF CURSOR

You can check the return value's isValid() method to see if the operation succeeded. If the cursor is associated with an asynchronous connection, this function behaves asynchronously.

RWDBStatus::ErrorHandler RWDBCursor::errorHandler

(

)

const

Returns the error handler attached to self.

RWDBStatus RWDBCursor::fetchRow	(	CursorPosition	position = Next,
		int	offset = 1
	)

Fetches a row into self. Returns RWDBStatus::endOfFetch if there are no more rows. If the cursor is associated with an asynchronous connection, this function behaves asynchronously.

If self is a Sequential cursor, the only allowable value for position is Next; offset is ignored and the next row is fetched. Returns a status of RWDBStatus::invalidUsage if position is not Next.

If self is a Scrolling cursor and position is First, Last, Next, or Previous, offset is ignored and the specified row is fetched. If self is a Scrolling cursor and position is Relative, the row at the current position + offset is fetched. If self is a Scrolling cursor and position is Absolute, the row number identified by offset is fetched. Returns a database-specific error if the specified row does not exist.

RWDBStatus RWDBCursor::insertRow

(

const RWCString &

tableName

)

Encapsulates the database-specific equivalent of the SQL statement:

INSERT tableName WHERE CURRENT OF CURSOR

You can check the return value's isValid() method to see if the operation succeeded. If the cursor is associated with an asynchronous connection, this function behaves asynchronously.

bool RWDBCursor::isNull

(

size_t

index

)

const

Returns true if the last value fetched into self at column position index was NULL, otherwise returns false.

bool RWDBCursor::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 RWDBCursor::isValid

(

)

const

Returns true if self's status is RWDBStatus::ok, otherwise returns false.

RWCString RWDBCursor::name

(

)

const

Returns self's name. The DB Interface Module generates a unique name for every RWDBCursor. The name is used if the underlying database requires cursors to be named.

RWDBCursor& RWDBCursor::operator<<

(

RWDBValueManip

)

Deprecated:

Please use the function setNull(size_t colPosition) instead.

Uses the RWDBValueManip rwdbNull to insert a NULL value into a database table. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

RWBasicUString *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

Note:

This function accepts Unicode strings. For more information, see the entry for RWBasicUString in The Essential Tools Module Reference Guide. For more information on internationalization, see Chapter "Internationalization" in the The DB Interface Module User's Guide.

RWDBCursor& RWDBCursor::operator<<

(

RWDBBlob *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

RWWString *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

RWDBMBString *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

RWCString *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

RWDBDuration *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

RWDBDateTime *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

RWDateTime *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

RWDate *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

RWDecimalPortable *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

long double *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

double *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

float *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

unsigned long long *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

long long *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

unsigned long *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

long *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

unsigned int *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

int *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

unsigned short *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator<<

(

short *

val

)

The insertion operator is used to bind application variables to an RWDBCursor. Each call to fetchRow() populates the application variables with data from the fetch. Each call to insertRow() inserts the current contents of the relevant application variables into a database table. Each call to updateRow() updates a database table with the current contents of the relevant application variables. Returns a reference to self.

RWDBCursor& RWDBCursor::operator=

(

const RWDBCursor &

csr

)

Assignment operator. Self shares an implementation with csr.

RWDBCursor& RWDBCursor::operator[]

(

const RWDBColumn &

column

)

Changes the current row position to the index of the first column in self's result set whose name matches the name of the given column. If there is no such column, sets self's status to RWDBStatus::invalidPosition. Returns a reference to self.

RWDBCursor& RWDBCursor::operator[]

(

const RWCString &

colName

)

Changes the current row position to the index of the first column in self's result set whose name matches colName. If there is no such column, sets self's status to RWDBStatus::invalidPosition. Returns a reference to self.

RWDBCursor& RWDBCursor::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.

void RWDBCursor::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.

RWDBSchema RWDBCursor::schema

(

)

const

Returns a deep copy of self's RWDBSchema containing all column information. The copy is made so that an application can modify the returned RWDBSchema without changing self's schema.

void RWDBCursor::setErrorHandler

(

RWDBStatus::ErrorHandler

handler

)

Installs handler as self's error handler. The supplied handler is inherited by all objects produced by self. By default, the RWDBStatus::ErrorHandler is inherited from the object which produced self; this method overrides the default.

void RWDBCursor::setNull

(

size_t

colPosition

)

Sets the value at column colPosition to NULL, so that the next update or insert will make the corresponding field NULL.

RWDBStatus RWDBCursor::status

(

)

const

Returns the current status of self.

CursorType RWDBCursor::type

(

)

const

Returns self's cursor type. The cursor type is specified when an RWDBCursor is first obtained. The default is RWDBCursor::Sequential.

RWDBStatus RWDBCursor::unbind

(

)

Releases all pointers to external buffers that self holds. If the cursor is associated with an asynchronous connection, this function behaves asynchronously.

void RWDBCursor::unsetNull

(

size_t

colPosition

)

Unsets NULL from the value at column colPosition, so that the bound-in value for this column is used on the next update or insert.

RWDBStatus RWDBCursor::updateRow

(

const RWCString &

tableName

)

Encapsulates the database-specific equivalent of:

UPDATE tableName SET <set-clause> WHERE CURRENT OF CURSOR

where <set-clause> refers to the values in self that belong to tableName. You can check the return value's isValid() method to see if the operation succeeded. If the cursor is associated with an asynchronous connection, this function behaves asynchronously.