RWDBResult Class Reference

Represents a sequence of zero or more RWDBTable instances. More...

#include <rw/db/result.h>

Public Member Functions
	RWDBResult ()
	RWDBResult (const RWDBResult &result)
RWDBConnection	connection () const
RWDBStatus::ErrorHandler	errorHandler () const
bool	isReady () const
bool	isValid () const
RWDBResult &	operator= (const RWDBResult &result)
long	rowCount () const
long	rowsAffected () const
void	setErrorHandler (RWDBStatus::ErrorHandler handler)
RWDBStatus	status () const
RWDBTable	table ()

Detailed Description

RWDBResult represents a sequence of zero or more RWDBTable instances. An RWDBResult instance is returned whenever a database operation may potentially produce multiple SQL table expressions. This is obviously the case when using the RWDBConnection::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, execute() methods of each of the above operation returns an RWDBResult instance. An application using a database that 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 RWDBTable instances 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.

Synopsis

#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();

Example

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
}

Constructor & Destructor Documentation

RWDBResult() [1/2]

RWDBResult::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 RWDBResult instances. Usable RWDBResult instances are obtained from execute() methods.

RWDBResult() [2/2]

RWDBResult::RWDBResult

(

const RWDBResult &

result

)

Copy constructor. Self shares an implementation with result.

Member Function Documentation

connection()

RWDBConnection RWDBResult::connection

(

)

const

Returns self's database connection.

errorHandler()

RWDBStatus::ErrorHandler RWDBResult::errorHandler

(

)

const

Returns the error handler attached to self.

isReady()

bool RWDBResult::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.

isValid()

bool RWDBResult::isValid

(

)

const

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

operator=()

RWDBResult & RWDBResult::operator=

(

const RWDBResult &

result

)

Assignment operator. Self shares an implementation with result.

rowCount()

long RWDBResult::rowCount

(

)

const

Deprecated

As of SourcePro 7, use rowsAffected() instead.

Returns the number of rows in the database affected by the most recent activity through self's connection. This method makes a direct call to the implementation. Implementations without such a call return -1. Typically, this method returns a valid value only after updating, inserting, or deleting rows. Errors always return -1.

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

RWDBResult myResult = myUpdater.execute();
long rowsUpdated = myresult.rowCount();

rowsAffected()

long RWDBResult::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();

setErrorHandler()

void RWDBResult::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 RWDBStatus::ErrorHandler is inherited from the object which produced self; this method overrides the default.

status()

RWDBStatus RWDBResult::status

(

)

const

Returns the current status of self.

table()

RWDBTable RWDBResult::table

(

)

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