Rules and Standards

Error Management Overview

The V5 frameworks deal with four ways of handling errors:

1. A "custom" returned value is used to convey the method failure to the caller by returning a NULL pointer or a non null integer
2. The method returns an HRESULT and uses E_FAIL or other E_codes to convey the failure to the caller. A CATError class instance may be associated with the HRESULT
3. The method throws exceptions to handle critical failures. A CATError class instance makes up the exception
4. No error management.

Notes:

1. Throwing exceptions is sometimes associated with returning an HRESULT, a pointer, an integer, etc.
2. The word exception used alone always means V5 exception, that is CATError class instances thrown using the CATThrow macro. When C++ exceptions are discussed, they are referred to as C++ native exceptions.
3. mkmk deactivates by default C++ native exceptions. If you need to use C++ native exceptions in your module, add the following flag in the Imakefile.mk file to reactivate them:
   CXX_EXCEPTION=
   Do not add any value after the equal sign. Pay attention not to nest V5 exceptions and C++ native exceptions.

[Top]

Error Management Rules

The following rules must be applied:

• Rule 1: Each framework border must use HRESULT to report errors and must be exception proof, even if exceptions are internally used.
• Rule 2: All the returned CATErrors either using an HRESULT or an exception must be documented
• Rule 3: Do not include code that requires error processing in constructors and destructors

[Top]

Rule 1: Each framework border must use HRESULT to report errors and must be exception proof, even if exceptions are internally used.

The framework border that must use HRESULT is made of:

• The methods and global functions declared in frameworks' PublicInterfaces directories
• The interface methods implemented by implementation or extension classes declared in frameworks' ProtectedInterfaces, PrivateInterfaces or LocalInterfaces directories
• The precondition functions
• The redefined methods of the classes declared in frameworks' ProtectedInterfaces, PrivateInterfaces or LocalInterfaces directories that derive from classes declared in frameworks' PublicInterfaces directories.

The remaining part of the framework border that cannot use HRESULT is made of:

• Constructors and destructors
• Callback methods

This rule is declined as follows:

• HRESULT-based frameworks
  • All existing methods of each framework border return HRESULT possibly associated with a CATError to convey additional information, including the getters
  • All CATErrors returned by methods of each framework border are documented
  • All new methods of Public/Protected/Private/LocalInterfaces return HRESULT possibly associated with a CATError, including the getters
  • All CATErrors of new Public/Protected/Private/LocalInterfaces methods are documented
• Exception-based frameworks
  • Same as above
  • All exceptions caught in methods of each framework border are changed to HRESULT possibly associated with a CATError, including the getters
  • All other existing thrown exceptions are documented
• Frameworks that use both HRESULT and exceptions
  • Same as above
  • All custom errors in methods of each framework border are changed to HRESULT possibly associated with a CATError, including the getters
  • All custom errors of existing Private/LocalInterfaces methods are documented
• New frameworks
  • All methods of Public/Protected/Private/LocalInterfaces return HRESULT possibly associated with a CATError, including the getters
  • All CATErrors of Public/Protected/Private/LocalInterfaces are documented.

The error management process that this rule implies is:

• When a method you call fails you must try in the following order:
  • If you know how to repair the error repair and go on
  • If it is not a major error, clean up and
    • Either return CATReturnError with the received CATError and possibly change the CATError message
    • Or return CATReturnError after having released the received CATError and created a new CATError (more expensive)

    Even if the failure can be fixed, such as just ignoring an item in a loop, there are problems you may want to log because something wrong happens that needs to be investigated. In these cases, use CATSysLogError.

  • If it is a major error, use CATSysLogAbend. (This call will make a core dump at DS and will continue after having logged the error in the abend trace at customer’s location.) Because the call doesn't make a core dump at customer’s locations, you need to manage the error as if it were not a major error as described above.

  Note: there is not always a CATError when a method you call fails.You must check the CATError availabilty

• When catching an exception you must try in the following order:
  • If you know how to repair the exception, repair the error and go on (in this case you need to try/catch at each call)
  • If it is not a major error and
    • If there is no clean up to do, and if your method doesn't belong to the framework border, do nothing. At last, the exception will be converted into an HRESULT when reaching the framework border
    • Otherwise, catch the exception, clean up and
      • If your method doesn't belong to the framework border
        • Either rethrow the received CATError while possibly having changed the CATError message
        • Or release the received CATError, create a new CATError and throws this new CATError (more expensive)
      • If your method belongs to the framework border
        • Convert the exception into an HRESULT, with or without an associated CATError
  • If it is a major error, catch the exception, use CATSysLogAbend. (This call will make a core dump at DS and continue after having logged the error in the abend trace at customer’s location.) Because the call doesn't make a core dump at customer’s locations, you need to manage the error as if it were not a major error as described above.

[Top]

Rule 2: All the returned CATErrors either using an HRESULT or an exception must be documented

This rule implies that:

• All methods returning or throwing CATErrors must document the CATErrors that can be returned or thrown in their headers. This description is part of the method signature and impact analysis must be done when modifying or adding a CATError
• Virtual methods define the CATErrors that can be used in all the derived class methods and all their corresponding implementations (No other CATError class can be used)
• Function pointer templates define the CATErrors that can be used in referenced functions (No other CATError class can be used in these functions)

[Top]

Rule 3: Do not include code that requires error processing in constructors and destructors

This rule implies to either:

• Do in the constructors an in the destructors what can be done without managing errors, and do the remaining and manage errors in a Build, Init, or Start method, and in a Stop method or in some already existing methods

  class CATDimBoolean : public CATBaseUnknown { CATDimBoolean(); virtual ~CATDimBoolean(); HRESULT Start(); HRESULT Stop(); HRESULT SomeExistingMethod(); }

• Use a factory to do the error prone work, manage errors and call a non-exposed constructor with checked arguments.

[Top]

Comparison between V5 Exceptions, C++ Native Exceptions, and HRESULT

The following table shows differences between these three ways of managing errors.

[Top]

History

Copyright © 2000, Dassault Systèmes. All rights reserved.