| Member Functions | |||
| connection() errorHandler() isReady() |
isValid() operator=() rowCount() |
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 most obviously the case when using the RWDBDatabase::executeSql() method to submit arbitrary SQL for execution. However, DBTools.h++ 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.
RWDBResult result = myDBase.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.
RWBoolean 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.
RWBoolean isValid() const;
Returns TRUE if the status of self is RWDBStatus::ok, otherwise returns FALSE.
long rowCount() const;
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 only returns a valid value 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 rowsAffected = myresult.rowCount();
NOTE:Because of differences in implementations, it may be necessary to call the table() method before determining the row count.
The following example demonstrates the technique mentioned in the note:
RWDBResult myResult = myUpdater.execute(); RWDBTable myTable = myResult.table(); long rowsAffected = myresult.rowCount();
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, returns a table whose status is RWDBStatus::endOfFetch. This function can behave asynchronously if executed using an asynchronous connection, or if self uses an asynchronous connection.
©Copyright 1999, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.