IException

The IException class is the base class from which all exception objects thrown in the library are derived. None of the functions in this class throws exceptions because an exception has probably already been thrown or is about to be thrown. Member functions in the Open Class Library create objects of classes derived from IException for all error conditions the functions encounter. Each exception object contains the following:

IException provides all of the functions required for it and its derived classes, including functions that operate on the text strings in the stack.

The library defines the derived classes so that you can catch exceptions by their type. In general, never create an IException object. Instead, create and throw an object of the appropriate derived class. The derived classes of IException are the following:

In addition, IResourceExhausted has the following derived classes: You can also derive your own exception type from IException.

The Open Class Library provides the following macros to assist in using exception handling. If you derive your own exception type and you want to use a macro, you must use the ITHROW macro or write your own macro.

ITHROW
Accepts as input a predefined object of any IException-derived class. The macro generates code to add the location information to the objects, logs all object data, and throws the exception.
IRETHROW
Accepts as input an object of any derived class of IException that has been previously thrown and caught. Like the ITHROW macro, it also captures the location information and logs all object data before rethrowing the exception.
IASSERT
If you define IC_DEVELOP during the compile for debugging purposes, this macro expands to provide assertion support in the library. This macro accepts an expression to test. If the test evaluation returns false, IASSERT calls assertParameter.
IEXCLASSDECLARE
Creates a declaration for a derived class of IException or one of its derived classes.
IEXCLASSIMPLEMENT
Creates a definition for a derived class of IException or one of its derived classes.
IEXCEPTION_LOCATION
Expands to create an object of the class IExceptionLocation.
INO_EXCEPTIONS_SUPPORT
Supports compilers lacking an exception-handling implementation. If you use the INO_EXCEPTIONS_SUPPORT macro, the following macros end the program after capturing the location information and logging it. These macros normally throw an exception:
ITHROW
Found in IException.
IASSERTPARM
Found in IBaseErrorInfo.
IASSERTSTATE
Found in IBaseErrorInfo.
ITHROWERROR
Found in IBaseErrorInfo.
ITHROWERROR1
Found in IBaseErrorInfo.
ITHROWLIBRARYERROR
Found in IBaseErrorInfo.
ITHROWLIBRARYERROR1
Found in IBaseErrorInfo.
ITHROWGUIERROR
Found in IGUIErrorInfo.
ITHROWGUIERROR2
Found in IGUIErrorInfo.
ITHROWSYSTEMERROR
Found in ISystemErrorInfo.

Attention: The INO_EXCEPTIONS_SUPPORT macro might not work correctly on all compilers.

Whenever the Open Class Library throws one of these exceptions, trace records are output with information about the exception. The class ITrace describes tracing in more detail.


IException - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class. You cannot assign one IException object from another.


[view class]
~IException
public:
virtual ~IException()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IException

You can construct objects of this class by doing the following:


Overload 1
public:
IException(const IException& exception)

The Open Class Library provides this constructor so the compiler can copy the exception when it is thrown.

exception
The exception object you want to copy.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IException( const char* errorText, unsigned long errorId = 0, Severity severity = IException::unrecoverable )
errorText
The text describing this error.
errorId
The identifier you want to associate with this particular error. Optional.
severity
Use the enumeration IException::Severity to specify the severity of the error. The default is unrecoverable. Optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Application Termination

These members provide support for terminating an application instead of throwing an exception.


[view class]
terminate
public:
virtual void terminate()

Ends the application. Normally, the Open Class Library only intends this function to be used internally by the library's exception-handling macros when the compiler you are using does not support C++ exception handling. This only occurs if you define the INO_EXCEPTIONS_SUPPORT macro. The macros that use this function are as follows:

ITHROW
Found in IException.
IASSERTPARM
Found in IBaseErrorInfo.
IASSERTSTATE
Found in IBaseErrorInfo.
ITHROWLIBRARYERROR
Found in IBaseErrorInfo.
ITHROWLIBRARYERROR1
Found in IBaseErrorInfo
ITHROWGUIERROR
Found in IGUIErrorInfo.
ITHROWGUIERROR2
Found in IGUIErrorInfo.
ITHROWSYSTEMERROR
Found in ISystemErrorInfo.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Error Code

Use these members to determine which class library an exception originated from.


[view class]
errorCodeGroup
public:
ErrorCodeGroup errorCodeGroup() const

Returns the error group the exception originated from.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setErrorCodeGroup
public:
IException& setErrorCodeGroup(ErrorCodeGroup errorGroup)

Sets the ID of the originating class library into the exception object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
baseLibrary
public:
static ErrorCodeGroup const baseLibrary

Specifies the error group for Open Class Library errors.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
CLibrary
public:
static ErrorCodeGroup const CLibrary

Specifies the error group for the C library errors.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operatingSystem
public:
static ErrorCodeGroup const operatingSystem

Specifies the error group for operating system errors.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
other
public:
static ErrorCodeGroup const other

Specifies the error group for errors which do not fall in any of the other groups.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
presentationSystem
public:
static ErrorCodeGroup const presentationSystem

Specifies the error group for presentation system errors.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Error Information

Use these members to get or modify the error identifier of the exception object.


[view class]
errorId
public:
unsigned long errorId() const

Returns the error ID of the exception.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setErrorId
public:
IException& setErrorId(unsigned long errorId)

Sets the error ID to the specified value.

errorId
The identifier you want to associate with this error.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Exception Location

Use these members to set and access the location information in the exception object.


[view class]
addLocation
public:
virtual IException& addLocation( const IExceptionLocation& location )

Adds the location information to the exception object. The Open Class Library captures this information when an exception is thrown or rethrown. An array of IExceptionLocation objects is stored in the exception object.

location
An IExceptionLocation object containing the following:
  • Function name
  • File name
  • Line number where the function is called

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
locationAtIndex
public:
const IExceptionLocation* locationAtIndex( unsigned long locationIndex ) const

Returns the IExceptionLocation object at the specified index.

locationIndex
If the index is not valid, a 0 pointer is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
locationCount
public:
unsigned long locationCount() const

Returns the number of locations stored in the exception location array.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Exception Logging

Use these members to log exception information.


[view class]
logExceptionData
public:
virtual IException& logExceptionData()

Logs the exception data stored in the IException object using the function specified by IException::setTraceFunction. If you have not set a tracing function, the exception information is written to standard error output.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setTraceFunction
public:
static IException::TraceFn* setTraceFunction( IException::TraceFn& traceFunction )

Registers an object of IException::TraceFn to be used to log exception data. The ITrace member functions and macros write the trace messages. IException::logExceptionData calls IException::TraceFn::write during exception processing to write the data. If you do not register an object, data is written to standard error output.

traceFunction
Your own trace function implementation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Exception Severity

Use these members to set and determine the severity of the error condition.


[view class]
isRecoverable
public:
virtual int isRecoverable() const

If the thrower (that is, whatever creates the exception) determines the exception is recoverable, 1 is returned. If the thrower determines it is unrecoverable, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setSeverity
public:
IException& setSeverity(Severity severity)

Sets the severity of the exception.

severity
Use the enumeration Severity to specify the severity of the exception.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Exception Text

Use these members to set, modify, and retrieve the exception text in the object.


[view class]
appendText
public:
IException& appendText(const char* errorText)

Appends the specified text to the text string on the top of the exception text stack.

errorText
The text you want to append.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setText
public:
IException& setText(const char* errorText)

Adds the specified text to the top of the exception text stack.

errorText
The error text you want to add.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
text
public:
const char* text(unsigned long indexFromTop = 0) const

Returns a constant char* pointing to an exception text string from the exception text stack.

indexFromTop
The default index is 0, which is the top of the stack. If you specify an index which is not valid, a 0 pointer is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
textCount
public:
unsigned long textCount() const

Returns the number of text strings in the exception text stack.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Exception Type

Use these members to determine the name (type) of the exception. This is used for logging out an exception object's error information.


[view class]
name
public:
virtual const char* name() const

Returns the name of the object's class.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Throw Support

These members support the throwing of exceptions.


[view class]
assertParameter
public:
static void assertParameter( const char* exceptionText, IExceptionLocation location )

The IASSERT macro uses this function to do the following:

  1. Create an IAssertionFailure exception
  2. Add the location information to it
  3. Log the exception data
  4. Throw the exception
exceptionText
The text describing the exception.
location
An IExceptionLocation object containing the following:
  • Function name
  • File name
  • Line number where the function is called

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IException - Enumerations


[view class]
Severity
enum Severity { unrecoverable, 
                recoverable }

Use these enumerators to specify the severity of the exception:

unrecoverable
Classifies the exception as unrecoverable.
recoverable
Classifies the exception as recoverable.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IException - Type Definitions


[view class]
ErrorCodeGroup
typedef const char * ErrorCodeGroup

This identifies the source of the exception's error code.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IException - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data