SourcePro® API Reference Guide

 
List of all members | Public Types | Public Member Functions

Encapsulates the error state of an object or operation. More...

#include <rw/db/status.h>

Inherits RWDBFuture.

Public Types

enum  ErrorCode {
  ok, noMem, notInitialized, typeConversion,
  dbNotFound, serverError, serverMessage, vendorLib,
  notConnected, endOfFetch, invalidUsage, columnNotFound,
  invalidPosition, notSupported, nullReference, notFound,
  missing, noMultiReaders, noDeleter, noInserter,
  noUpdater, noReader, noIndex, noDrop,
  wrongConnection, noPrivilege, noCursor, cantOpen,
  applicationError, notReady, internalError, cacheWriteError,
  cacheReadError
}
 
typedef void(* ErrorHandler) (const RWDBStatus &status)
 

Public Member Functions

 RWDBStatus ()
 
 RWDBStatus (const RWDBStatus &status)
 
ErrorCode errorCode () const
 
ErrorHandler errorHandler () const
 
bool isTerminal () const
 
bool isValid () const
 
RWCString message () const
 
RWDBStatusoperator= (const RWDBStatus &status)
 
void raise () const
 
void setErrorHandler (ErrorHandler handler)
 
long vendorError1 () const
 
long vendorError2 () const
 
RWCString vendorMessage1 () const
 
RWCString vendorMessage2 () const
 

Detailed Description

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.

Synopsis
#include <rw/db/status.h>
RWDBStatus status = myDbase.status(); //status of object
RWDBStatus status = myDbase.createTable("tableName",myschema);
//status of function
Example

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

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

Member Typedef Documentation

typedef void(* RWDBStatus::ErrorHandler) (const RWDBStatus &status)

A typedef for the error handling function.

Member Enumeration Documentation

Possible RWDBStatus error codes.

Enumerator
ok 

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 in 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 readers

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 

For errors produced at the application level

notReady 

For future use

internalError 

Error in the SourcePro library

cacheWriteError 

Error writing to the cache.

cacheReadError 

Error reading from the cache.

Constructor & Destructor Documentation

RWDBStatus::RWDBStatus ( )

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

RWDBStatus::RWDBStatus ( const RWDBStatus status)

Copy constructor. The created RWDBStatus shares an implementation with status.

Member Function Documentation

ErrorCode RWDBStatus::errorCode ( ) const

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

ErrorHandler RWDBStatus::errorHandler ( ) const

Returns self's installed error handler, if any.

bool RWDBStatus::isTerminal ( ) const

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

bool RWDBStatus::isValid ( ) const

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

RWCString RWDBStatus::message ( ) const

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

RWDBStatus& RWDBStatus::operator= ( const RWDBStatus status)

Assignment operator. Self shares an implementation with status. Returns a reference to self.

void RWDBStatus::raise ( ) const

Throws an exception that contains the error message associated with self.

void RWDBStatus::setErrorHandler ( 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 that produced it; this method overrides the default.

long RWDBStatus::vendorError1 ( ) const

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

long RWDBStatus::vendorError2 ( ) const

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

RWCString RWDBStatus::vendorMessage1 ( ) const

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

RWCString RWDBStatus::vendorMessage2 ( ) const

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

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