RWDBStatusRWDBFuture
| Data Types | |
| enum ErrorCode |
| Member Functions | |||
| errorCode() errorHandler() isTerminal() |
isValid() message() operator=() |
raise() 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 DBTools.h++ error model, 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 DBTools.h++ objects 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 DBTools.h++ object 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.
RWBoolean isTerminal() const;
Returns TRUE if the error that occurred will terminate the application.
RWBoolean 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 Tools.h++ macro RW_NO_EXCEPTIONS, aborts via a call to exit(ok). Otherwise raises an exception via an invocation of the Tools.h++ 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 DBTools.h++ access library 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 1999, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.