Handling errors in extension packages🔗
Defining own error codes🔗
Error messages are represented by integer constants, the error codes of type Herror.
If an error occurs, the corresponding error code should be returned by the procedure.
The file %HALCONROOT%\include\HErrorDef.h contains predefined error messages for all typical errors, see also HALCON error codes.
It may still happen that none of them fits an error occurring in a new, user-defined operator.
Therefore, you can define new codes, which should be greater than 10 000 to avoid re-using an already allocated code or a code reserved for future extensions of the HALCON system.
If the user-defined operator returns a user-defined error, the error will be reported as
To provide user-defined errors with error messages, the function HSetErrText can be called immediately before the operator returns the error code with return H_ERR_*:
In this case, the error message error_message will be displayed by the next call of the HALCON operator get_error_text.
Within this call, the error message is reset to “No error message available …” again to ensure that the user-defined error message is up to date.
Error codes are specified via #define and are called H_ERR_XYZ.
Example
H_ERR_WIPN1 /* wrong number of values in input control */
/* parameter 1 */
H_ERR_WIPV3 /* wrong parameter value (control param. 3) */
H_ERR_WIPT2 /* wrong type of values (control param. 2) */
H_ERR_WION1 /* wrong number of objects in input object */
/* parameter 1 */
H_ERR_WIT /* wrong image type */
H_MSG_TRUE /* no error (supply procedure) */
H_MSG_OK /* no error (any other procedure) */
All HALCON procedures return an error code.
This code has to be checked after calling any HALCON procedure, for example, by encapsulating the procedure call in the macro HCkP.
This macro checks the return value and exits the current procedure if an error occurred (a detailed description of the macro is given in the HCkP).
Some of the Extension Package Interface macros described in the Reference of the Extension Package Interface (for example, HGetCPar) implicitly use the macro and therefore automatically return a proper error code.
Extending error codes🔗
There is also a mechanism to add some extended error information about the thread’s current HALCON error.
The function HSetExtendedErrorInfo can be called immediately before the operator returns the error code with return H_ERR_*:
Herror HSetExtendedErrorInfo(Hproc_handle proc_handle, INT4_8 error_code,
char const *error_message)
In this case, the extended error information (error_code and error_message) will be set thread-locally and can be queried by the next call of the HALCON operator get_extended_error_info.
The set information gets cleared by both the next occurring HALCON error or the next call of HSetExtendedErrorInfo.
In error_code, a user-defined error code can be set, for example, a third-party SDK error code or a 0 value (indicating that no extended error code is set).
In error_message, a user-defined error message can be specified, for example, a third-party SDK error message or an empty string "" (indicating that no extended error message is set).
When HSetExtendedErrorInfo is called, it creates a copy of the error message.
This means that you do not have to ensure the input remains valid after the function has been called.
For example, apart from a string literal, you can also use a dynamically generated value for error_message.
Instead of HSetExtendedErrorInfo, you can also use the function HSetExtendedErrorInfoF, which allows you to use printf-like formatting of the error_message:
Herror HSetExtendedErrorInfoF(Hproc_handle proc_handle, INT4_8 error_code,
char const* error_message, ...)
An example showing how to use HSetExtendedErrorInfo is provided in the file $HALCONEXAMPLES/extension_package/useropencl/source/CIPOpenCLFilter.c.
An example showing how to obtain the extended error information by means of get_extended_error_info is provided in $HALCONEXAMPLES/extension_package/useropencl/examples/testuseropencl.hdev.