RWDBStatus

Module:  DB Interface Module   Group:  Utility and Diagnostics Classes

RWDBStatus  RWDBFuture

• Local Index
• Synopsis
• Description
• Example
• Public Typedefs and Enums
• Public Constructors
• Public Member Operator
• Public Member Functions
• Public Member Functions: Vendor-Specific

Members

enum ErrorCode errorCode() errorHandler() isTerminal()

isValid() message() operator=() raise()

RWDBStatus() setErrorHandler() vendorError1() vendorError2()

vendorMessage1() vendorMessage2()

#include <rw/db/status.h>

RWDBStatus status = myDbase.status();    //status of object
RWDBStatus status = myDbase.createTable("tableName",myschema);
                                         //status of function

RWDBStatus encapsulates the error state of an object or operation. A valid object or a successful operation is represented by RWDBStatus::ok. An RWDBStatus that is not valid contains an error code, an error message, and often some supplemental information provided by a database vendor's API.

Each RWDBStatus object contains a callback routine that can be changed by an application. If an RWDBStatus changes state to anything but RWDBStatus::ok, the installed handler is called with self as an argument.

In the error model of the DB Interface Module, the use of exceptions is optional, and is under the application's control. The raise() method of RWDBStatus throws an exception of type RWExternalErr. Thus, an application may choose to enforce a terminating or nonterminating model of error handling by installing an appropriate error handler.

When objects of the DB Interface Module are produced by other objects, the produced object's status is copied from the producer. Consequently, an application can control error handling at any level it chooses. A handler installed in the RWDBManager is propagated to every object of the DB Interface Module in the application; one installed in an RWDBDatabase is propagated to each object produced by that RWDBDatabase, and so on down to the level of individual objects.

RWDBStatus is designed around the Interface/Implementation paradigm. An RWDBStatus instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation.

An application that requires C++ exceptions throughout would proceed this way:

void throwStatus(const RWDBStatus& status)
{
 status.raise();
}
RWDBManager::setErrorHandler(throwStatus);

This is the signature of an RWDBStatus error handling routine:

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

At this writing, these are the possible RWDBStatus error codes:

enum ErrorCode 
{
   ok = 0,           // No error
   noMem,            // Out of memory
   notInitialized,   // Object never initialized
   typeConversion,   // Type conversion error
   dbNotFound,       // Database not registered
   serverError,      // Error reported by server
   serverMessage,    // Message from server
   vendorLib,        // Error from vendor's library
   notConnected,     // Lost connection
   endOfFetch,       // End of fetch
   invalidUsage,     // Invalid usage of object
   columnNotFound,   // Column does not exist
   invalidPosition,  // Invalid positioning within object,
                     //  i.e., bounds error
   notSupported,     // Unsupported feature
   nullReference,    // Null reference parameter
   notFound,         // Database object not found
   missing,          // Required piece of information is 
                     // missing
   noMultiReaders,   // This object cannot support multiple
                     //  readers
   noDeleter,        // This object cannot support deletions
   noInserter,       // This object cannot support insertions
   noUpdater,        // This object cannot support updates
   noReader,         // This object cannot support updates
   noIndex,          // This object cannot support indices
   noDrop,           // This object cannot be dropped
   wrongConnection,  // Incorrect connection was supplied
   noPrivilege,      // This object cannot support privileges
   noCursor,         // This object cannot support cursors
   cantOpen          // Unable to open
   applicationError  // Errors produced at the application 
                     // level
   notReady          // For future use
}

RWDBStatus();

The default constructor creates an RWDBStatus of notInitialized. Data members are supplied default values of 0 or the empty string, and the error handler is set to nil.

RWDBStatus(const RWDBStatus& status);

Copy constructor. RWDBStatus instances are always copied by value.

RWDBStatus& 
operator=(const RWDBStatus& status);

Assignment operator; status is copied onto self. Returns a reference to self.

ErrorCode
errorCode() const;

Returns self's error code. The code errorCode() != ok can be interpreted as an abnormal condition.

ErrorHandler
errorHandler() const;

Returns self's installed error handler, if any.

bool
isTerminal() const;

Returns true if the error that occurred will terminate the application.

bool
isValid() const;

Returns true if errorCode() == ok, otherwise returns false.

RWCString
message() const;

Returns the error message associated with the current error code. Returns an empty string if the current error code is ok.

void
raise() const;

If exceptions are not supported according to the Essential Tools Module macro RW_NO_EXCEPTIONS, aborts via a call to exit(ok). Otherwise raises an exception via an invocation of the Essential Tools Module macro RWTHROW(), passing the error message associated with self.

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 RWDBStatus error handler is inherited from the object that produced it; this method overrides the default. ErrorHandler is declared as a typedef within the scope of RWDBStatus:

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

The following methods return database-specific error information. If a status object has an error code of serverError, serverMessage, or vendorLib, these methods may provide additional information, as documented in the DB Access Module guides. Otherwise, these methods return 0 or the empty string, as appropriate.

long
vendorError1() const;

Returns a code supplied by the database vendor, or 0 if not relevant.

long
vendorError2() const;

Returns a code supplied by the database vendor, or 0 if not relevant.

RWCString
vendorMessage1() const;

Returns a string supplied by the database vendor, or an empty string if not relevant.

RWCString
vendorMessage2() const;

Returns a string supplied by the database vendor, or an empty string if not relevant.

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