Altova MapForce 2024 Enterprise Edition

The MapForce API returns errors in two different ways. Every API method returns an HRESULT. This return value informs the caller about any malfunctions during the execution of the method. If the call was successful, the return value is equal to S_OK. C/C++ programmers generally use HRESULT to detect errors.


Visual Basic, scripting languages, and other high-level development environments do not give the programmer access to the returning HRESULT of a COM call. They use the second error-raising mechanism supported by the MapForce API, the IErrorInfo interface. If an error occurs, the API creates a new object that implements the IErrorInfo interface. The development environment takes this interface and fills its own error-handling mechanism with the provided information.


The following text describes how to deal with errors raised from the MapForce API in different development environments.


Visual Basic

A common way to handle errors in Visual Basic is to define an error handler. This error handler can be set with the On Error statement. Usually the handler displays an error message and does some cleanup to avoid spare references and any kind of resource leaks. Visual Basic fills its own Err object with the information from the IErrorInfo interface.


Sub Validate()
'place variable declarations here
'set error handler
On Error GoTo ErrorHandler
'if generation fails, program execution continues at ErrorHandler:
'additional code comes here
Exit Sub
MsgBox("Error: " & (Err.Number - vbObjectError) & Chr(13) &
    "Description: " & Err.Description)
End Sub



The Microsoft implementation of JavaScript (JScript) provides a try-catch mechanism to deal with errors raised from COM calls. It is very similar to the VisualBasic approach, in that you also declare an error object containing the necessary information.


function Generate() {
  // please insert variable declarations here
  try {
  catch (Error) {
       sError = Error.description;
       nErrorCode = Error.number & 0xffff;
      return false;
  return true;



C/C++ gives you easy access to the HRESULT of the COM call and to the IErrorInterface.


  // Call GenerateXSLT() from the MapForce API
  if(FAILED(hr = ipDocument->GenerateXSLT()))
    IErrorInfo *ipErrorInfo = Null;
    if(SUCCEEDED(::GetErrorInfo(0, &ipErrorInfo)))
        BSTR   bstrDescr;
        // handle Error information
        wprintf(L"Error message:\t%s\n",bstrDescr);
        // release Error info

© 2018-2024 Altova GmbH