HRESULT

All TwinCAT Vision functions return an HRESULT after their execution. Its value indicates whether the execution was successful or not.

SUCCESS codes

A successful execution is indicated by a POSITVE code. In hexadecimal notation the first digit is between 0 and 7.

Frequent SUCCESS codes are:

Code	Name	Description
16#000	S_OK	Function was executed successfully
16#001	S_FALSE	Function was executed successfully but did not reach a complete result. (Occurs, for example, with the Code Reading functions if no code was found in the image.)
16#203	S_PENDING	Asynchronous method was started but there is no result yet (occurs at the first call of fbCameraControl.StartAcquisition(), for example; at the second call S_OK is returned, for example)
16#256	S_WATCHDOGTIMEOUT	Function was aborted by the watchdog.

ERROR codes

A failed execution is indicated by a NEGATIVE code, or in hexadecimal notation the first digit is >= 8. The final digits of the code correspond to the ADS Return Codes.

Notice

Error code

If an error code is returned, it means that all returns of the function are invalid. and must therefore not be used.

Common ERROR codes with the TwinCAT Vision API elements are:

Hex	Dec	Name	Description
16#70A	1802	NOMEMORY	Insufficient memory
16#70B	1803	INVALIDPARM	Invalid parameter values
16#70C	1804	NOTFOUND	Not found (file, image, ...)
16#70E	1806	INCOMPATIBLE	Objects do not match
16#712	1810	INVALIDSTATE	The method of an FB was called in an impermissible state.
16#719	1817	TIMEOUT	timeout
16#71A	1818	NOINTERFACE	Interface query failed
16#71B	1819	INVALIDINTERFACE	Wrong interface requested.
16#71D	1821	INVALIDOBJID	Object ID is invalid.
16#734	1844	OUTOFRANGE	Outside the valid range.

Please refer to the ADS Return Codes for the complete list.

Application

In the event of an error, the HRESULT is negative (error code), otherwise it is positive (success code). Use the FAILED () and SUCCEEDED () functions to check this.

PROGRAM MAIN
VAR
    hr     : HRESULT := S_OK;
END_VAR

IF SUCCEEDED(hr) THEN
    //code
END_IF

	Restricted query Note that the above query only checks for successful execution of the function, not for a correct or desired result.

For example, Code Reading functions return the success code S_FALSE (16#001) if no code is found or read in the image. To detect this case, hr must be directly compared with S_OK or S_FALSE. In contrast, measurement functions return NOTFOUND (16#70C), if the object to be measured is missing from the image.

Most TwinCAT Vision functions expect a HRESULT as the last input parameter and are only executed if this is a SUCCESS code and it is therefore confirmed that no error has occurred so far. Otherwise, the respective function is not executed and instead returns the previous HRESULT. This ensures that, when the HRESULT is passed from function to function, the first error code that occurred is output instead of a subsequent error.

	SUCCESS codes SUCCESS codes (e.g. `S_FALSE`) are not forwarded and overwritten by the next function. If necessary, the HRESULT value of the respective functions must be checked explicitly.

Accessing interface methods

If a function is to create an interface pointer, the HRESULT of the function indicates whether the interface pointer now exists. In addition, the interface pointer must be checked to ascertain whether it is zero.

WARNING

Method access to invalid memory area leads to system crash

An internal check is not possible for interface methods, since the corresponding objects must exist to call the method.

Even outside the method call, make sure that the corresponding object exists (interface pointer not 0) and that the program has not yet returned an error code.

This is a secure query to use a newly created interface pointer:

IF SUCCEEDED(hr) AND ipImage <> 0 THEN
    hr := ipImage.GetWidth(nWidth);
END_IF

Integration into user-defined function blocks

An HRESULT can be integrated into user-defined function blocks as follows:

METHOD MyMethod : HRESULT
VAR_INPUT
    hr : HRESULT
END_VAR

IF FAILED(hr) THEN
    MyMethod := hr; //skip the whole method
ELSE
    (*
        code
        code
        code
    *)
    MyMethod := S_OK; // or some error code if something went wrong
END_IF

This is explained in more detail in the sample Self-written functions.

Extraction of the ADS Return Code

If, for example, the pure ADS Return Code is required for display in an HMI, this can be extracted from the HRESULT in numeric and textual form as follows:

PROGRAM MAIN
VAR
    hr             :   HRESULT;
    nReturnCode    :   DWORD;
    sReturnCode    :   STRING;
END_VAR

nReturnCode := DINT_TO_DWORD(hr) AND 16#FFF;
sReturnCode := DWORD_TO_HEXSTR(nReturnCode, 3, FALSE);

The library Tc2_Utilities is required for this purpose.