Altova UModel 2025 Professional Edition

Navigation: UModel Programmer's Reference > The UModel API > How to...

Handle errors

The UModel API returns errors in two different ways. Every API method returns an HRESULT. This return value informs the caller about any errors 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.

VisualBasic, 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 UModel 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 example code listings below show how to deal with errors raised from the UModel API in different development environments.

Visual Basic

A common way to handle errors in VisualBasic 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 performs cleanup functions to avoid spare references and any kind of resource leaks.

VisualBasic 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 DoSomeWork fails, program execution continues at ErrorHandler:
objUModel.ActiveDocument.DoSomeWork()

'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 Visual Basic 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 DoSomeWork() from the UModel API
if(FAILED(hr = ipDocument->DoSomeWork()))
{
IErrorInfo *ipErrorInfo = Null;

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

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

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