### 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:

  - A stack of exception message text strings (descriptions)
  - An error ID
  - A severity code
  - An error code group
  - Information about where the exception was thrown
  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:

  - IAccessError
  - IAssertionFailure
  - IDeviceError
  - IInvalidParameter
  - IInvalidRequest
  - IResourceExhausted
  In addition, IResourceExhausted has the following derived classes:
  - IOutOfMemory
  - IOutOfSystemResource
  - IOutOfWindowResource
  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.

~IException

      public:
      virtual ~IException()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

IException

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

  - Using the primary constructor. Normally, this is the only way you would construct an object of this class.
  - Using the copy constructor.

  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.

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.

errorCodeGroup

      public:
      ErrorCodeGroup errorCodeGroup() const

  Returns the error group the exception originated from.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

baseLibrary

      public:
      static ErrorCodeGroup const baseLibrary

  Specifies the error group for Open Class Library errors.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

CLibrary

      public:
      static ErrorCodeGroup const CLibrary

  Specifies the error group for the C library errors.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

operatingSystem

      public:
      static ErrorCodeGroup const operatingSystem

  Specifies the error group for operating system errors.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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.

errorId

      public:
      unsigned long errorId() const

  Returns the error ID of the exception.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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

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

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.

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

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.

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

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.

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

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

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

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.

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.

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

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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None