Managing Errors Using HRESULT

3D PLM Enterprise Architecture	Middleware Abstraction	Managing Errors Using HRESULT Creating, analyzing, enriching, and reacting to errors using HRESULT
Technical Article

Abstract

This article explains how to report a failure to calling methods by returning a HRESULT to which an error class and an error message is associated, how to process the errors returned by the methods you call, and how to convert exceptions into HRESULT errors. The error management described here complies with the CAA V5 Error Processing Rules [1]

Understanding Error Management Using HRESULT with an Example
What Is a CAA V5 Error Made Of?
Returning an HRESULT with an Error
Receiving an Error from a Called Method
Converting a Caught Exception to a HRESULT
In Short
References

Understanding Error Management Using HRESULT with an Example

Assume you have to create a method that adds two integers the end user has entered in a dialog box and returns their sum. Assume also that the intended scope of the method is to work correctly when both integers are greater than or equal to zero. Requesting to add negative integers is out of the scope of the method, and should then be processed as an error. The code for such a method could be:

HRESULT CAAClass::Add(int iFirstOperand, int iSecondOperand, int * oSum)
{
  if (iFirstOperand<0 || iSecondOperand<0)     // Out of the method scope
  { // Instantiate an error class instance with a message
    CATResourceError * pError = new CATResourceError("CAAAddingMsgKey",
                                                     "CAAAddingErrorCatalog"); 
    // Prepare parameters for the message
    CATUnicodeString Param1, Param2;
    Param1.BuildFromNum(iFirstOperand);
    Param2.BuildFromNum(iSecondOperand);
    // Assign parameters to the error
    pError->SetNLSParameters(2, &Param1, &Param2);
    // Inform caller that method fails, and pass the error object
    return CATReturnError(pError);
  }
  if (NULL != oSum)
  {
    *oSum = iFirstOperand + iSecondOperand;
    return CATReturnSuccess;      // Inform caller that method succeeds
  }
  else
    return CATReturnFailure;
}

where:

iFirstOperand and iSecondOperand are the two integers to add
oSum is the computed sum.

Note that the method returns a HRESULT, and not the computed sum which is passed as an output parameter, and that this HRESULT value is built using the macros CATReturnError when the method fails, and CATReturnSuccess when the method executes successfully.

Let's analyze what happens when one or both input parameters are less than zero. First, an instance of the CATResourceError class, supplied by the System framework, is created. The CATResourceError class constructor has two parameters:

CAAAddingMsgKey is the key of the message associated with this error
CAAAddingErrorCatalog is the message catalog containing this key and the associated message.

The message takes the two operands as parameters. According to the message processing rules, these parameters must first be converted into CATUnicodeString instances, and then attached to the error using the SetNLSParameters method, before the error be returned by the CATReturnError macro. The message extracted from the CAAAddingErrorCatalog.CATNls file could be:

...
CAAAddingMsgKey = "First operand /p1 and//or second operand /p2 is negative.\n Select only positive values";
...

Now let's look at the calling method. It should test the returned value to know whether the called method executes well or not. If it fails, the error class instance associated with the error can be retrieved from the error manager thanks to the GetLastError method. Depending on the error class, the action to perform can be one of the following:

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 deleted 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 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

...
  int a, b, aplusb;
...
  HRESULT rc = ptr->Add(a, b, &aplusb);
  ptr->Release();
  ptr = NULL;
  if (FAILED(rc))
  {       // Retrieve the last error from the error manager
    CATError * pOccurringError = CATError::CATGetLastError(rc);
    if (NULL != pOccurringError)
    {
      if (0 != pOccurringError->IsAKindOf(CATInputError::ClassName()))       // Repair
      {
        ... // Repair the error
        pOccurringError->Release();
        pOccurringError = NULL;
        ... // and go on
        return CATReturnSuccess;
      }
      else if (0 != pOccurringError->IsAKindOf(CATSystemError::ClassName())) // Return as is
      {
        return CATReturnError(pOccurringError);
      }
      else if (0 != pOccurringError->IsAKindOf(CATInternalError::ClassName()))  // Enrich
      {
        ... // Analyze the error
        pOccurringError->Release();
        pOccurringError = NULL;
        CATInternalError * pMyError = new CATInternalError("MsgKey", "MsgCatalog");
          ... // Add appropriate parameters, if any
        return CATReturnError(pMyError);
      }
      else                                                                   // Log and return
      {
        if (NULL == pPointer)
        {
          ... // Clean
          CATSysLogAbend("This pointer should never be NULL");
          return CATReturnedError(pOccurringError);
        }
      }
    }
  }
  ... // The Add method succeeds, and the method goes on normally
  return CATReturnSuccess;
}

Note that the different processing cases rely on whether the error class derives from a given class. Other criteria are available, such as the error type, the error message identifier, or the error identifier [2].

Error Class	Error Id	Description
CATInternalError	ComponentERR_1000	The component cannot be created because no default constructor exists for the requested class
CATInternalError	ComponentERR_1001	The component cannot be created because the class to instantiate doesn't exist
CATInternalError	ComponentERR_1002	The component was successfully created, but the interface query fails, whether the component doesn't implement the interface, or the IID passed is invalid. An IUnknown pointer to the component is returned
CATInternalError	ComponentERR_1003	The memory allocation failed for the component

[1]	CAA V5 Error Processing Rules
[2]	Using an Error Class with HRESULTs or Exceptions
[3]	Managing Errors Using Exceptions

Version: 2 [Nov 2001]	Enhanced with new error rules
Version: 1 [Mar 2000]	Document created
[Top]

3D PLM Enterprise Architecture

Middleware Abstraction