Altova MapForce 2024 Enterprise Edition

Error Handling

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:
objMapForce.ActiveDocument.GenerateXSLT()

'additional code comes here

'exit
Exit Sub

ErrorHandler:
MsgBox("Error: " & (Err.Number - vbObjectError) & Chr(13) &
"Description: " & Err.Description)
End Sub

JavaScript

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.

C/C++

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

HRESULT hr;

// Call GenerateXSLT() from the MapForce API
if(FAILED(hr = ipDocument->GenerateXSLT()))
{
IErrorInfo *ipErrorInfo = Null;

if(SUCCEEDED(::GetErrorInfo(0, &ipErrorInfo)))
{
BSTR bstrDescr;
ipErrorInfo->GetDescription(&bstrDescr);

// handle Error information
wprintf(L"Error message:\t%s\",bstrDescr);
::SysFreeString(bstrDescr);

// release Error info
ipErrorInfo->Release();
}
}