You are here: Start » Error Handling

Error Handling


Error handling is a mechanism which enables the application to react to exceptional situations encountered during program execution. The application can continue to run after errors raised in filters.

This mechanism should mainly be used for handling errors of the IO_ERROR kind. Usage for other kinds of errors should be taken with caution. Every application can be created in a manner which precludes DOMAIN_ERROR. This topic is elaborated in a separate article: Dealing with Domain Errors. A frequent cause of this kind of errors is the omission of filters such as SkipEmptyRegion.

Error handling can only be added to Task Macrofilters. A re–execution of the Task Macrofilter following an error results in a reset of stateful filters contained therein. This means in particular a possible reconnect to cameras or other devices. The error handler for each kind of error is executed in the manner of a Step Macrofilter.

A special case is the error handler of the Task Macrofilter set as Startup Program (usually: Main). The program execution is always terminated after the error handler finishes.

There are several kinds of errors which can be handled:

    An error during I/O operation or interaction with an external device (camera, network, digital I/O card, storage etc.).
    An error raised by the operating system (e.g. failed memory allocation, missing driver or library).
    Incorrect use of the filter or function, usually from input values (e.g. out of the valid range).
    An error caused by lack of a license required to use the library (FIL).
    Includes all of the above kinds as well as unspecified runtime errors arising during program execution.

The handling proceeds in two distinct ways, depending on the error kind:


    After occurrence of one of such errors, the program enters the nearest error handler. After completing the handler, the execution is resumed right after the Task in which the error was raised. The caller (parent Macrofilter) considers this Task to be completed successfully.

    These kinds are critical errors and the application cannot continue to execute. After occurrence of such an error the nearest error handler is executed, but after completion of the handler, the error stays "active". Which means, the caller, or any Macrofilter above it, can execute their own handler for this kind of error, and the program will finally be stopped. Handling these kinds of errors can be used to notify the operator about a critical system error and request service attendance.

Each Task Macrofilter can have multiple handlers, for different error kinds. If an error occurs, first a handler for the specific kind is checked, and if there is no such handler, the ANY_ERROR handler will be used (if it is defined).

Do not use ANY_ERROR handler if you wish your application to continue running after handling the error. Executing this error handler will always cause the application to stop.

Error handlers for ANY_ERROR should be treated as a way to inform the user about the problem (e.g. write to console, save text logs) before quitting the application.

Adding Error Handlers

Error handlers can be added by right–clicking a Task Macrofilter in the Project Explorer and choosing "Add New Error Handler ...".

Next, we need to choose the error kind for the handler.

After choosing the kind, it will appear in Project Explorer under the Task Macrofilter to which it was added:

After double–clicking the error handler can be edited.

Program Execution

During program execution in the IDE, after an error occurs, there will be a message pop–up, with the option to continue (that is, run the error handler). This message can be turned off in the IDE settings, by changing: Tools » Settings » Program Execution : "Break when exception occurred".

In the Runtime environment, understandably, there will be no message and the error handling will be executed immediately.


Below is a simple example, acquiring images from a camera in a loop. If the camera is not connected, we enter the error handler, where a message is returned until the error is no longer being raised. Without error handling the program would stop after the first failed image acquisition:

Sample program with error handler. Macrofilter GrabImage has error handler IO_ERROR (right) with error message.

Result after error handler execution.

Result after normal program execution.

Generated C++ Code

In C++ code generation there is an option to generate the error handling, or to leave it up to the user (programmer) to implement it separately. If the error handling option is enabled, the calls of filters in a function (generated from a Task Macrofilter with error handlers) will be enclosed in "try ... catch" blocks, such as:

void GrabImage( void )
	fil::WebCamera_GrabImageState webCamera_GrabImageState1;
	fil::Image image1;
			if (!fil::WebCamera_GrabImage(webCamera_GrabImageState1, 0, ftl::NIL, image1))
	catch(const ftl::IoError&)
		ftl::String string1;
		string1 = ftl::String(L"Camera is not connected");