SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
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
 
RWDBResultoperator= (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();
Represents a sequence of zero or more RWDBTable instances.
Definition result.h:87
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
}
Represents an explicit database connection object that can be used in place of the implicit database ...
Definition connect.h:81
RWDBResult executeSql(const RWCString &sqlProgram) const
Provides row-by-row access to tabular data.
Definition reader.h:136
RWDBTable table()
Base class for a family of classes that represent the abstract notion of a database table in a number...
Definition table.h:89
bool isValid() const
RWDBReader reader(size_t cacheSize=0) const

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();
long rowCount() const

◆ 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();
long rowsAffected() const

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

Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.