# Exception Handler Class

Topics
Overview | Functions
Exceptions Codes | Exception Classes

Overview

The Exception Handler class is used to catch program exceptions that occur at run time. This implementation can be used with or without C++ built-in exception handling. If C++ exception handling is turned off, then the Exception Handler class can be used to display program errors, exit the program, or trap a program error with a user defined action function. In order to handle errors within an application without using C++ exception handling, a global Exception Handler object pointer, named Error, is used to signal an exception and terminate the program if the exception is considered to be fatal. To enable C++ exception handling within the VBD class library define the CPP_EXCEPTIONS macro at compile time.

The Exception Handler class is designed to display exceptions and terminate the program using several different Application Programming Interfaces (API.) In this release of Variable Block Database, the Exception Handler classes are designed to display exceptions in console applications, curses (independent terminal type) applications, and wxWindows (portable GUI interface) applications. To enable the console display, define the __CONSOLE__ macro at compile time. To enable the curses display, enable the __CURSES__ macro at compile time. To enable the wxWindows display, define the __wxWINDOWS__ macro at compile time.

The display and terminate functions in the Exception Handler class are all virtual and designed to be overridden in a derived class. This allows the Exception Handler class to act as base class and still preserve the interface presented here. All the classes used for C++ exceptions handling, within the VBD class library, inherit the Exception Handler class without overriding any of the virtual functions. They have all the functionality of the Exception Handler class and use the display and terminate functions defined in the Exception Handler class.

Functions

EHandler::EHandler()

- Default class constructor.

virtual EHandler::~EHandler()

- Virtual class destructor provided for virtuality.

virtual void EHandler::DisplayException()

- Virtual public member function used to display the current exception code.

virtual void EHandler::DisplayException(int ECode)

- Virtual public member function used to display a specific exception code.

virtual void EHandler::SignalException(int ECode, int Level = FATAL, int DisplayError = DisplayOn)

- Virtual public member function used to display the exception, exit the program, or do nothing. The exception codes and error levels are defined within the EHandler class by an anonymous enumeration.

virtual void EHandler::Message(const char *mesg1=" ", const char *mesg2=" ", const char *mesg3=" ")

- Virtual public member function used to display a program message containing up to three individual strings. This function is not used in the curses port.

void EHandler::TrapException(AF ActionFunction)

- Public member function used to handle a user defined routine to trap a program exception. ActionFunction is a function pointer to a function defined within the application.

void EHandler::SetException(int ECode)

- Public member function used to set the exception code.

int EHandler::Exception()

- Public member function that returns the current exception code.

void EHandler::ClearException()

- Public member function used to clear the current exception code by setting it to None.

virtual void EHandler::Terminate()

- Virtual protected member function used to terminate the program. The routine used to terminate the program is dependent on the Application Programming Interface (API) used.

Exceptions Codes and Error Levels

All of the EHandler exception codes are defined within the EHandler class by an anonymous enumeration. Use any of the tagged integer constants listed here to identify the exception that occurred at run time. The following is an example of a call to the Ehandler::SignalException() function using the global exception handler to signal the user that an exception has occurred, display the exception and terminate the program in accordance with the API.

Error->SignalException(EHandler::AccessViolation);

None

- No exception, used to clear the current exception code.
FileNotReady - File not ready, using failed or closed file.
FileNotWriteable - Could not write to the file open for read/write access.
ReadOnlyFile - Trying to write to read-only file.
FileNotOpenError - Trying to use a closed file.
FileCreationError - Error creating a file.
FileOpenError - Error opening a file.
FileCloseError - Error closing a file.
FileSeekError - Error seeking in file during a read or write sequence.
FileReadError - Error reading file during a read sequence.
FileWriteError - Error writing to file during a write sequence.
EOFError - Unexpected end of file occurred during a read or write sequence.
WrongFileType - Wrong file type was opened or could not read file header.
FileCorrupt - File is corrupted, verified by testing the check word sequence.
FileExists - File already exists, cannot overwrite or create.
NoFileExists - No such file exists, cannot read from or open.
PathError - Invalid path was specified within the application.
DanglingPtr - Dangling reference counted pointer, cannot destroy or modify this object.
NullPtr - Accessing a null pointer, program will crash if allowed to continue.
CacheFull - Cache is full and cannot be flushed to disk.
StkFull - Stack is full, cannot push any more entries.
StkEmpty - Stack is empty, cannot pop any entries.
AssertError - Assumptions made do not meet the conditions specified, entry not processed.
NoDatabaseOpen - No database open, cannot process any entries.
ObjectExists - Object already exists.
BadObjectAddress - Bad object address passed within the application.
BadReference - Bad reference, program will crash if allowed to continue.
DivideByZero - Divide by zero Error, program will crash if allowed to continue.
OverFlow - Math overflow caused by signed-unsigned mismatch.
UnderFlow - Math under-flow caused by signed-unsigned mismatch.
ParseError - Parse error occurred during a parse operation.
NoObjectsExist - No such objects exists.
BadClassID - Wrong object type specified within the application.
SyncError - Synchronization error occurred when reading/writing from disk/memory.
AccessViolation - Access violation occurred when reading/writing from disk/memory.
ChecksumError - Bit error occurred when writing to disk.

The exception handler error levels are defined within the EHandler class by an anonymous enumeration. Use any of the tagged integer constants listed here to display the exception that occurred at run time and terminate or continue processing the program. The following is an example of a call to the Ehandler::SignalException() function using the global exception handler to signal the user that an exception has occurred, display the exception, and continue processing. NOTE: The Ehandler::SignalException() function defaults to a "FATAL" exception.

Error->SignalException(EHandler::AccessViolation, EHandler::DISPLAY);

FATAL

- Fatal error, terminate program immediately in accordance with the API.
DISPLAY - Dummy handler that does nothing except display the exception.

Exceptions Classes

The following class declarations are used for exceptions representing program errors encountered at run time. This implementation is provided for use with the C++ built-in exception handling routines (try, catch, and throw) within the VBD class library. To enable C++ exception handling within the VBD class library define the CPP_EXCEPTIONS macro at compile time.

class CNone : public EHandler { }

- No exception.
class CFileNotReady : public EHandler { } - File not ready.
class CFileNotWriteable : public EHandler { } - Could not write to file.
class CReadOnlyFile : public EHandler { } - Writing to read-only file.
class CFileNotOpenError : public EHandler { } - Using a closed file.
class CFileCreationError : public EHandler { } - Error creating file.
class CFileOpenError : public EHandler { } - Error opening file.
class CFileCloseError : public EHandler { } - Error closing file.
class CFileSeekError : public EHandler { } - Error seeking in file.
class CFileReadError : public EHandler { } - Error reading from file.
class CFileWriteError : public EHandler { } - Error writing to file.
class CEOFError : public EHandler { } - Unexpected end of file.
class CWrongFileType : public EHandler { } - Wrong file type.
class CFileCorrupt : public EHandler { } - File corrupted.
class CFileExists : public EHandler { } - File already exists.
class CNoFileExists : public EHandler { } - No such file exists.
class CPathError : public EHandler { } - Invalid path specified.
class CDanglingPtr : public EHandler { } - Dangling reference counted pointer.
class CNullPtr : public EHandler { } - Accessing a Null pointer.
class CCacheFull : public EHandler { } - Cache is full.
class CStkFull : public EHandler { } - Stack is full.
class CStkEmpty : public EHandler { } - Stack is empty.
class CAssertError : public EHandler { } - Assertion failed, entry not processed.
class CNoDatabaseOpen : public EHandler { } - No database is open.
class CObjectExists : public EHandler { } - Object already exists.
class CBadObjectAddress : public EHandler { } - Bad object address.
class CBadReference : public EHandler { } - Bad Reference.
class CDivideByZero : public EHandler { } - Divide By Zero Error.
class COverFlow : public EHandler { } - Math overflow.
class CUnderFlow : public EHandler { } - Math under-flow.
class CParseError : public EHandler { } - Parse error.
class CNoObjectsExist : public EHandler { } - No objects exist.
class CBadClassID : public EHandler { } - Wrong object type.
class CSyncError : public EHandler { } - Synchronization error.
class CAccessViolation : public EHandler { } - Access violation.
class CChecksumError : public EHandler { } - CRC Checksum error.

End Of Document