home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
cset21v1.zip
/
IBMCPP
/
IBMCLASS
/
IEXCBASE.HPP
< prev
next >
Wrap
Text File
|
1993-09-22
|
29KB
|
486 lines
#ifndef _IEXCBASE_
#define _IEXCBASE_
/*******************************************************************************
* FILE NAME: iexcbase.hpp *
* *
* DESCRIPTION: *
* Declaration of the class(es): *
* IExceptionLocation - Holds location information for thrown exceptions. *
* IException - Base class for all exceptions in the library. *
* IAccessError - For logical errors, e.g. "resource not found". *
* IAssertionFailure - Generated by the IASSERT macro for assertions. *
* IDeviceError - Used for hardware related errors. *
* IInvalidParameter - For null pointer, invalid value type errors. *
* IInvalidRequest - For invalid requests for an object's state. *
* IResourceExhausted - Generic out-of-resource class. *
* IOutOfMemory - Generated by our new_handler for heap exhaustion. *
* IOutOfSystemResource - For operating system resource exhaustion. *
* IOutOfWindowResource - For windowing system resource exhaustion. *
* *
* This file also contains many of the macros used to implement the *
* library exception handling mechanism. This includes the IASSERT, ITHROW, *
* IRETHROW, IEXCEPTION_LOCATION, IEXCLASSDECLARE, IEXCLASSIMPLEMENT, and *
* and INO_EXCEPTIONS_SUPPORT macros. *
* *
* COPYRIGHT: *
* IBM C/C++ Tools Version 2.01 - Collection Class Library *
* Licensed Materials - Property of IBM *
* (C) Copyright IBM Corporation 1992, 1993 *
* All Rights Reserved *
* US Government Users Restricted Rights - Use, duplication, or disclosure *
* restricted by GSA ADP Schedule Contract with IBM Corp. *
* *
*******************************************************************************/
#ifndef _IMSGTEXT_
#include <imsgtext.hpp>
#endif
// Forward declarations for other classes:
class IExcText;
class IExceptionLocation {
/*******************************************************************************
* *
* The IExceptionLocation class saves the location information when *
* an exception is thrown or re-thrown. No exceptions are thrown by *
* any function in this class, because an exception probably has *
* been thrown already, or is about to be thrown. *
* *
* Typically, an instance of the IExceptionLocation class is created *
* by either the ITHROW or IRETHROW macro when an exception is going *
* to be thrown or re-thrown. However, you can create your own instance *
* of IExceptionLocation by constructing it yourself or by using the *
* IEXCEPTION_LOCATION macro. *
* *
* Example: *
* *
* The following example shows how you could use this class if you decided *
* to use the IEXCEPTION_LOCATION macro instead of the ITHROW and *
* IRETHROW macros: *
* *
* IInvalidRequest exc = IInvalidRequest("Func B invalid before Func A"); *
* exc.addLocation(IEXCEPTION_LOCATION()); *
* exc.logExceptionData(); // to log the exception information *
* throw exc; *
* *
*******************************************************************************/
public:
/*------------------------ Constructors/Destructors ----------------------------
| There is one way to construct instances of this class: |
| |
| The constructor takes three arguments: |
| |
| - The filename where the function creating this instance is |
| located |
| - The name of the function in which the instance is being |
| created |
| - The line number in the file in which the instance is being |
| created. |
| |
| The easiest way to construct an IExceptionLocation instance |
| is by using the IEXCEPTION_LOCATION macro, which captures |
| current location information using constants that are |
| provided by the compiler for all of the arguments. Default |
| values are provided for all arguments to support environments |
| in which all constants or alternative means for getting |
| location information are not provided. |
| |
| You can also use the ITHROW or IRETHROW macros to create an |
| instance, as they will invoke the IEXCEPTION_LOCATION macro. |
------------------------------------------------------------------------------*/
IExceptionLocation ( const char* fileName = 0,
const char* functionName = 0,
unsigned long lineNumber = 0 );
/*-------------------------------- Accessors -----------------------------------
| The following functions provide a means of getting and setting |
| the accessible attributes of instances of this class: |
| fileName - Returns the path-qualified source file name where an |
| exception has been thrown or re-thrown. |
| functionName - Returns the name of the function that has thrown |
| or re-thrown an exception. |
| lineNumber - Returns the line number of the statement in the |
| source file from which an exception has been |
| thrown or re-thrown. |
------------------------------------------------------------------------------*/
const char
*fileName ( ) const,
*functionName ( ) const;
unsigned long
lineNumber ( ) const;
private:
/*--------------------------------- Private ----------------------------------*/
const char
*pClFile,
*pClFunction;
unsigned long
ulClLineNo;
}; // IExceptionLocation
class IException {
/*******************************************************************************
* *
* This is the base class from which all exceptions thrown in the *
* library are derived. No exceptions are thrown by any function in *
* this class, because one probably has been thrown already, or is *
* about to be thrown. *
* *
* Instances of IException or one of its subclasses are created for *
* all error conditions encountered in the library. Each instance *
* contains a "stack" of exception text strings. IException provides *
* all of the functions required for it and its subclasses, including *
* functions that operate on the text strings in the "stack". *
* *
* The subclasses are defined so that exceptions can be caught by *
* their type, as desired. In general, an instance of IException *
* should never be created. Instead, an instance of the appropriate *
* subclass should be created and thrown. *
* *
* The subclasses of IException are: *
* *
* - IAccessError *
* - IAssertionFailure *
* - IDeviceError *
* - IInvalidParameter *
* - IInvalidRequest *
* - IResourceExhausted *
* *
* In addition, IResourceExhausted has the following subclasses: *
* *
* - IOutOfMemory *
* - IOutOfSystemResource *
* - IOutOfWindowResource *
* *
* The following macros are provided to assist in using exception *
* handling: *
* *
* ITHROW - Accepts as input a pre-defined instance *
* of any IException subclass *
* It expands to add the location *
* information to the instance, logs all *
* instance data, and then throws the *
* exception. *
* *
* IRETHROW - Accepts as input a pre-defined instance *
* of any subclass of IException that has *
* been previously thrown and caught. *
* Like the ITHROW macro, it also captures *
* the location information, and logs all *
* instance data before re-throwing the *
* exception. *
* *
* IASSERT - Expands to provide assertion support in *
* the library, but only if IC_DEVELOP has *
* been defined. This macro accepts an *
* expression to be tested as input. If *
* the test evaluation returns false, an *
* exception of type IAssertionFailure is *
* thrown. *
* *
* IEXCLASSDECLARE - Creates a declaration for a subclass of *
* IException or one of its subclasses. *
* *
* IEXCLASSIMPLEMENT - Creates a definition for a subclass of *
* IException or one of its subclasses. *
* *
* IEXCEPTION_LOCATION - Expands to create an instance of the *
* IExceptionLocation class. *
* *
* INO_EXCEPTIONS_SUPPORT - Provided in support of compilers that *
* lack exception handling implementation. *
* If it is defined, the ITHROW macro ends *
* the program after capturing the location *
* information and logging it, instead of *
* throwing an exception. This macro may *
* not work correctly on all compilers. *
* *
* Example: *
* *
* Following is an example of creating and throwing an exception. *
* It creates an instance of InvalidRequest, one of IException's *
* subclasses. *
* *
* IInvalidRequest exc = IInvalidRequest("Func B invalid before Func A"); *
* exc.addLocation(IEXCEPTION_LOCATION()); *
* exc.logExceptionData(); // to log the exception information *
* throw exc; *
* *
* The following example is a variation of the preceding *
* example, this time using the ITHROW macro. *
* *
* IInvalidRequest exc = IInvalidRequest("Func B invalid before Func A"); *
* ITHROW(exc); *
* *
*******************************************************************************/
public:
/*------------------------------ Related Type ----------------------------------
| The following enumeration type is defined to pass "modes" to various |
| implementation functions: |
| Severity - Used to determine the severity of the exception. |
| unrecoverable - The exception is classified as unrecoverable. |
| recoverable - The exception is classified as recoverable. |
------------------------------------------------------------------------------*/
enum Severity { unrecoverable, recoverable };
/*------------------------ Constructors/Destructors ----------------------------
| There are two ways to construct instances of this class: |
| |
| 1. The primary constructor |
| |
| This is normally the only way an instance of this class will |
| be constructed. The only required argument is the exception |
| text string. The third argument is the severity of the |
| exception. |
| |
| 2. The copy constructor |
| |
| This constructor is provided so the compiler can copy the |
| exception when it is thrown. This should be the only reason |
| to copy an exception instance. |
------------------------------------------------------------------------------*/
IException ( const char* errorText,
unsigned long errorId = 0,
Severity severity = IException::unrecoverable );
IException ( const IException& exception );
virtual
~IException ( );
class TraceFn {
/*******************************************************************************
| This class is used by instances of IException and its subclasses |
| to log exception instance data. |
| |
| If you want to provide your own tracing function, you should |
| subclass the IException::TraceFn class and register it with |
| IException by using the 'setTraceFunction' function. This will |
| allow you to implement IException::TraceFn's 'write' function, |
| which is called during exception processing. An instance of a |
| default subclass of IException::TraceFn is used if the application |
| does not register one. This default function writes output to wherever |
| ITrace output is being directed based on the ICLUI TRACETO environment |
| variable. |
| |
| Example: |
| |
| class ExampleTraceFn : public IException::TraceFn |
| { |
| public: |
| virtual void |
| write ( const char* buffer ) |
| { |
| fprintf(stderr,"%s\n", buffer); |
| } |
| }; |
| |
| ExampleTraceFn exampleTraceFn = new ExampleTraceFn; |
| IException::setTraceFunction(exampleTraceFn); |
*******************************************************************************/
public:
/*------------------------ Constructors/Destructors ----------------------------
| The only way to construct members of this class is to use |
| the default constructor with no arguments. |
------------------------------------------------------------------------------*/
/*---------------------------------- Trace -------------------------------------
| The following function is used by IException's 'logExceptionData' |
| function: |
| write - Writes a buffer of exception data. |
------------------------------------------------------------------------------*/
virtual void
write ( const char* buffer ) = 0;
}; // TraceFn
/*-------------------------------- Accessors -----------------------------------
| The following functions provide a means of getting and setting |
| the accessible attributes of instances of this class: |
| appendText - Appends text to the string that is on the top |
| of the exception text "stack". |
| setText - Adds a text string to the top of the exception text |
| "stack". |
| setSeverity - Sets the severity of the exception. |
| setErrorId - Sets the error ID of the exception. |
| addLocation - Adds location information regarding where an exception |
| is thrown or re-thrown to an array of |
| IExceptionLocation instances. Only 5 locations will be |
| stored in the array. After the array is full, each |
| location that is added will replace the fifth member of |
| the array. |
| isRecoverable - Returns 1 if the Severity is recoverable or 0 if the |
| Severity is unrecoverable. |
| name - Returns the class name (type) of the exception. |
| text - Returns an exception text string from the "stack" of |
| text strings. Index 0, which is the top of the stack, |
| is the default. |
| textCount - Returns the number of exception text strings in the |
| exception text "stack". |
| errorId - Returns the error ID of the exception. |
| locationCount - Returns the number of IExceptionLocation instances |
| stored in the location array. |
| locationAtIndex - Returns a pointer to the IExceptionLocation instance |
| stored at the zero-based index requested. If |
| the index value is invalid, a zero pointer is |
| returned. |
------------------------------------------------------------------------------*/
IException
&appendText ( const char* errorText ),
&setText ( const char* errorText ),
&setSeverity ( Severity severity ),
&setErrorId ( unsigned long errorId );
virtual IException
&addLocation ( const IExceptionLocation& location );
virtual int
isRecoverable ( ) const;
virtual const char
*name ( ) const;
const char
*text ( unsigned long indexFromTop = 0 ) const;
unsigned long
textCount ( ) const,
errorId ( ) const,
locationCount ( ) const;
const IExceptionLocation
*locationAtIndex ( unsigned long locationIndex ) const;
/*---------------------------- Logging Functions -------------------------------
| The following functions are provided for logging the exception |
| information: |
| setTraceFunction - Registers an IException::TraceFn object to be used to |
| log exception data. The object's 'write' function is |
| called during exception processing to write the data. |
| If no object is provided, data is written to |
| standard error output. |
| logExceptionData - Logs exception instance data. If a trace function has |
| been registered by using the 'setTraceFunction' |
| function, it is used to do the logging. Otherwise the |
| data is written to standard error output. |
------------------------------------------------------------------------------*/
static void
setTraceFunction ( IException::TraceFn& traceFunction );
virtual IException
&logExceptionData ( );
/*------------------------------ Ending an Application -------------------------
| The following function is part of the termination model that was |
| put in place to allow exceptions to be used by compilers that do |
| not fully support exception handling: |
| terminate - Ends the application. It is invoked by the ITHROW |
| macro if INO_EXCEPTIONS_SUPPORT is defined. |
------------------------------------------------------------------------------*/
virtual void
terminate ( );
/*------------------------------ Throw Support ---------------------------------
| The following function is used by the IASSERT macro: |
| assertParameter - Creates an IAssertionFailure exception, adds the |
| location information to it, logs out the exception data |
| and throws the exception. |
------------------------------------------------------------------------------*/
static void
assertParameter ( const char* exceptionText,
IExceptionLocation location );
private:
/*--------------------------------- PRIVATE ----------------------------------*/
Severity
exsevCl;
unsigned long
ulClErrorId;
IExceptionLocation
exlocClArray[5];
unsigned long
ulexlocClCount,
ulClTxtLvlCount;
IExcText
*msgtxtClTop;
IException
&operator= ( const IException& exc );
}; // IException
#if !defined( INO_EXCEPTIONS_SUPPORT )
#define INO_EXCEPTIONS_SUPPORT 0
#endif
#if defined ( INO_FUNCTION_NAMES )
#define IEXCEPTION_LOCATION() IExceptionLocation(__FILE__, 0, __LINE__)
#elif defined ( __FUNCTION__ )
#define IEXCEPTION_LOCATION() IExceptionLocation(__FILE__, __FUNCTION__, __LINE__)
#else
#define IEXCEPTION_LOCATION() IExceptionLocation(__FILE__, 0, __LINE__)
#endif
#if (INO_EXCEPTIONS_SUPPORT)
#define ITHROW(exc)\
exc.addLocation(IEXCEPTION_LOCATION()),\
exc.logExceptionData(),\
exc.terminate()
#else
#define ITHROW(exc)\
exc.addLocation(IEXCEPTION_LOCATION()),\
exc.logExceptionData(),\
throw exc
#endif
#define IRETHROW(exc)\
exc.addLocation(IEXCEPTION_LOCATION()),\
exc.logExceptionData(),\
throw
#if defined(IC_DEVELOP)
#define IASSERT(test)\
if(!(test))\
IException::assertParameter("The following expression must be true, but evaluated to false: " #test,\
IEXCEPTION_LOCATION())
#else
#define IASSERT(test)
#endif
#define IEXCLASSDECLARE(child,parent) class child : public parent {\
public:\
child(const char* a, unsigned long b = 0,\
Severity c = IException::unrecoverable);\
virtual const char* name() const;\
virtual ~child();\
child(const child &);\
private:\
operator = ( const child & );\
}
#define IEXCLASSIMPLEMENT(child,parent)\
child :: child(const char* a, unsigned long b,\
Severity c)\
: parent(a, b, c)\
{ }\
const char* child :: name() const\
{\
return ( # child);\
}\
child :: ~child() {;}\
child :: child(const child & a) : parent(a) {;}
IEXCLASSDECLARE(IAccessError,IException);
IEXCLASSDECLARE(IAssertionFailure,IException);
IEXCLASSDECLARE(IDeviceError,IException);
IEXCLASSDECLARE(IInvalidParameter,IException);
IEXCLASSDECLARE(IInvalidRequest,IException);
IEXCLASSDECLARE(IResourceExhausted,IException);
IEXCLASSDECLARE(IOutOfMemory,IResourceExhausted);
IEXCLASSDECLARE(IOutOfSystemResource,IResourceExhausted);
IEXCLASSDECLARE(IOutOfWindowResource,IResourceExhausted);
#endif /* _IEXCBASE_ */
