Rogue Wave banner
Previous fileTop of DocumentContentsIndexNext file

RWDBCursor



Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Synopsis

#include <rw/db/cursor.h>

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

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. DBTools.h++ makes no 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 the DBTools.h++ access library guide for details concerning RWDBCursor restrictions for a particular database.

RWDBCursor captures common features of database cursors.

Specifically:

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:

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.

Example

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 RWDBCursors 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.

Public Enums

enum CursorAccess { Read, Write };
enum CursorPosition { First, Last, Next, Previous, Absolute,
                      Relative };
enum CursorType { Sequential, Scrolling };

Related Objects

RWDBValueManip rwdbNull;

Public Constructors

RWDBCursor();
RWDBCursor(const RWDBCursor& csr);

Public Member Operators

RWDBCursor&
operator=(const RWDBCursor& csr);
RWDBCursor&
operator[](const RWDBColumn& column);
RWDBCursor&
operator[](const RWCString& colName);
RWDBCursor&
operator[](size_t index);
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<<(float* val);
RWDBCursor&      
operator<<(double* val);
RWDBCursor&      
operator<<(RWCString* val);
RWDBCursor&      
operator<<(RWDate* val);
RWDBCursor&      
operator<<(RWDBBlob* val);
RWDBCursor&      
operator<<(RWDBDateTime* val);
RWDBCursor&      
operator<<(RWDBDuration* val); 
RWDBCursor&      
operator<<(RWDecimalPortable* val); 
RWDBCursor& 
operator<<(RWDBMBString* val);
RWDBCursor& 
operator<<(RWWString* val);
RWDBCursor&
operator<<(RWDBValueManip);

NOTE:This function is deprecated, and may be removed from future versions of DBTools.h++. Please use the function setNull(size_t colPosition) instead.

Public Member Functions

RWDBCursor::CursorAccess
access() const;
void
acquire() const;
RWDBConnection
connection() const;
RWDBStatus
deleteRow(const RWCString& tablename);
RWDBStatus::ErrorHandler
errorHandler() const;
RWDBStatus
fetchRow(CursorPosition position = Next, int offset = 1);
RWDBStatus
insertRow(const RWCString& tableName);
RWBoolean
isNull(size_t index) const;
RWBoolean
isReady() const;
RWBoolean
isValid() const;
RWCString
name() const;
void
release() const;
RWDBSchema
schema() const;
void
setErrorHandler(RWDBStatus::ErrorHandler handler);
void
setNull(size_t colPosition);
RWDBStatus
status() const;
RWDBCursor::CursorType
type() const;
RWDBStatus
unbind();
RWDBStatus
updateRow(const RWCString& tableName);
void
unsetNull(size_t colPosition);


Previous fileTop of DocumentContentsIndexNext file

©Copyright 1999, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.