RWDBResult

Module:  DB Interface Module   Group:  Data Manipulation Classes

Does not inherit

• Local Index
• Synopsis
• Description
• Example
• Public Constructors
• Public Member Operator
• Public Member Functions

Members

connection() errorHandler() isReady()

isValid() operator=() rowCount()

rowsAffected() RWDBResult() setErrorHandler()

status() table()

#include <rw/db/result.h>

RWDBResult result = myConn.executeSql("someSql");
RWDBResult result = mySelector.execute();
RWDBResult result = myInserter.execute();
RWDBResult result = myDeleter.execute();
RWDBResult result = myUpdater.execute();
RWDBResult result = myStoredProcedure.execute();

RWDBResult represents a sequence of zero or more RWDBTables. An RWDBResult instance is returned whenever a database operation may potentially produce multiple SQL table expressions. This is obviously the case when using the RWDBDatabase::executeSql() method to submit arbitrary SQL for execution. However, the DB Interface Module recognizes that some database vendors provide:

• Stored procedures that can execute more than one SELECT statement.

• Triggers that can cause results to be generated as a result of an INSERT, DELETE, or UPDATE statement.

For this reason, each of the above execute() methods returns an RWDBResult instance. An application that knows that its database does not provide these capabilities is not obliged to check for multiple results.

Every RWDBResult instance has an RWDBConnection. Passing an RWDBConnection to an execute() method causes the RWDBResult to acquire the passed connection. Calling execute() without an RWDBConnection causes the RWDBResult to acquire a default connection from the caller's RWDBDatabase. In each case, the connection is held by the RWDBResult until the RWDBResult is destroyed.

The RWDBTables produced by RWDBResult must be processed in order. Each call to RWDBResult::table() causes unprocessed rows from any previous table to be flushed.

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

Here is a way to process an SQL query that may return more than one table expression. The example assumes that the SQL is contained in the variable sqlString.

RWDBConnection dbConn = myDBase.connection();
RWDBResult result = dbConn.executeSql(sqlString);
RWDBTable resultTable = result.table();
while (resultTable.isValid())  
{
RWDBReader reader = resultTable.reader();
 while (reader()) 
 {
   // process a row from table
 }
 resultTable = result.table(); // get the next table
}

RWDBResult();

The default constructor creates an RWDBResult whose status is RWDBStatus::notInitialized. This constructor is provided as a convenience, for example, for declaring an array of RWDBResults. Usable RWDBResults are obtained from execute() methods.

RWDBResult(const RWDBResult& result);

Copy constructor. Self shares an implementation with result.

RWDBResult&
operator=(const RWDBResult& result);

Assignment operator. Self shares an implementation with result.

RWDBConnection
connection() const;

Returns self's database connection.

RWDBStatus::ErrorHandler
errorHandler() const;

Returns the error handler attached to self.

bool
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
isValid() const;

Returns true if the status of self is RWDBStatus::ok, otherwise returns false.

long
rowCount() const;

---

NOTE -- This method is deprecated. Please use the method rowsAffected().

---

long
rowsAffected() const;

Returns the number of rows in the database affected by the most recent activity through self's connection. Even if the recent activity has failed, this method would attempt to fetch the number of rows affected in spite of the failure. Returns -1 if this information cannot be fetched. Typically, this method returns a valid value only after updating, inserting, or deleting rows.

The following code determines the number of rows updated through an RWDBUpdater.

RWDBResult myResult = myUpdater.execute();
long rowsAffected = myresult.rowsAffected();

void
setErrorHandler(RWDBStatus::ErrorHandler handler);

Installs handler as self's error handler. The supplied handler is inherited by all objects produced by self. By default, an RWDBResult error handler is inherited from the object which produced it; this method overrides the default. ErrorHandler is declared as a typedef within the scope of RWDBStatus:

typedef void (*ErrorHandler)(const RWDBStatus&);

RWDBStatus
status() const;

Returns the current status of self.

RWDBTable
table();

Returns the next RWDBTable in the sequence of tables represented by self. When there are no more tables, the status of the RWDBResult becomes RWDBStatus::endOfFetch. This function can behave asynchronously if executed using an asynchronous connection, or if self uses an asynchronous connection.

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.