HRESULT

Alle TwinCAT Vision-Funktionen liefern nach ihrer Ausführung ein HRESULT zurück. Sein Wert gibt an, ob die Ausführung erfolgreich war oder fehlgeschlagen ist.

SUCCESS-Codes

Eine erfolgreiche Ausführung ist durch einen POSITVEN Code gekennzeichnet bzw. in der hexadezimalen Schreibweise ist die erste Ziffer zwischen 0 und 7.

Häufige SUCCESS-Codes sind:

Code	Name	Beschreibung
16#000	S_OK	Funktion wurde erfolgreich ausgeführt
16#001	S_FALSE	Funktion wurde erfolgreich ausgeführt, ist aber zu keinem vollständigen Ergebnis gekommen. (Tritt z.B. bei den Code Reading Funktionen auf, wenn kein Code im Bild gefunden wurde.)
16#203	S_PENDING	Asynchrone Methode wurde gestartet, aber es liegt noch kein Ergebnis vor (Tritt z.B. auf beim ersten Aufruf von fbCameraControl.StartAcquisition(), beim 2. Aufruf kommt dann z.B. S_OK zurück)
16#256	S_WATCHDOGTIMEOUT	Funktion wurde vom Watchdog abgebrochen.

ERROR-Codes

Eine fehlgeschlagene Ausführung ist durch einen NEGATIVEN Code gekennzeichnet, bzw. in der hexadezimalen Schreibweise ist die erste Ziffer >= 8. Die Endziffern des Codes entsprechen wiederum den ADS Return Codes.

Hinweis

Error-Code

Die Rückgabe eines Error-Codes bedeutet, dass sämtliche Rückgaben der Funktion invalide sind. Daher darf mit ihnen nicht weitergearbeitet werden.

Gängige ERROR-Codes bei den TwinCAT Vision API-Elementen sind:

Hex	Dec	Name	Beschreibung
16#70A	1802	NOMEMORY	Nicht genügend Speicher
16#70B	1803	INVALIDPARM	Ungültige Parameter-Werte
16#70C	1804	NOTFOUND	Nicht gefunden (Datei, Bild, ...)
16#70E	1806	INCOMPATIBLE	Objekte stimmen nicht überein
16#712	1810	INVALIDSTATE	Die Methode eines FBs wurde in einem unzulässigen Zustand aufgerufen.
16#719	1817	TIMEOUT	Zeitüberschreitung
16#71A	1818	NOINTERFACE	Interface-Abfrage fehlgeschlagen
16#71B	1819	INVALIDINTERFACE	Falsches Interface angefordert.
16#71D	1821	INVALIDOBJID	Object-ID ist ungültig.
16#734	1844	OUTOFRANGE	Außerhalb des gültigen Bereichs.

Die vollständige Liste entnehmen Sie bitte den ADS Return Codes.

Anwendung

Im Fehlerfall ist das HRESULT negativ (Errorcode), ansonsten positiv (Successcode). Verwenden Sie die FAILED () und SUCCEEDED () Funktionen, um dies zu überprüfen.

PROGRAM MAIN
VAR
    hr     : HRESULT := S_OK;
END_VAR

IF SUCCEEDED(hr) THEN
    //code
END_IF

	Eingeschränkte Abfrage Beachten Sie, dass die obere Abfrage nur auf eine erfolgreiche Ausführung der Funktion, nicht auf ein korrektes oder gewünschtes Ergebnis prüft.

Beispielsweise liefern Code Reading Funktionen den Successcode S_FALSE (16#001), wenn kein Code im Bild gefunden oder gelesen wird. Um diesen Fall zu erkennen, muss hr direkt mit S_OK oder S_FALSE verglichen werden. Entgegen dessen wird von Vermessungsfunktionen NOTFOUND (16#70C) zurückgegeben, wenn das zu vermessende Objekt gänzlich auf dem Bild fehlt.

Die meisten TwinCAT Vision-Funktionen erwarten ein HRESULT als letzten Eingangsparameter und werden nur dann ausgeführt, wenn es sich dabei um einen SUCCESS-Code handelt und somit bestätigt ist, dass es bisher keinen Fehler gegeben hat. Andernfalls wird die jeweilige Funktion nicht ausgeführt, sondern gibt das vorhergehende HRESULT zurück. Dadurch wird sichergestellt, dass bei der Übergabe des HRESULT von Funktion zu Funktion der zuerst aufgetretene Fehlercode ausgegeben wird, statt eines Folgefehlers.

	SUCCESS-Codes SUCCESS-Codes (z. B. `S_FALSE`) werden nicht weitergegeben und von der nächsten Funktion überschrieben. Bei Bedarf muss explizit der HRESULT-Wert der jeweiligen Funktionen überprüft werden.

Zugriff auf Interface-Methoden

Wenn eine Funktion einen Interface-Pointer erstellen soll, ist das HRESULT der Funktion ein Indiz dafür, ob der Interface-Pointer nun existiert. Zusätzlich muss der Interface-Pointer auf Null-Ungleichheit überprüft werden.

WARNUNG

Methodenzugriff auf ungültigen Speicherbereich führt zum kompletten Systemabsturz

Bei Interface-Methoden ist eine interne Überprüfung nicht möglich, da die zugehörigen Objekte existieren müssen, um die Methode aufrufen zu können.

Stellen Sie selbst außerhalb des Methodenaufrufs sicher, dass das entsprechende Objekt vorhanden ist (Interface Pointer ungleich 0) und das Programm bisher keinen Fehlercode zurückgeliefert hat.

Dies ist eine sichere Abfrage, um einen neu erstellten Interface-Pointer zu benutzen:

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

Einbindung in eigene Funktionsblöcke

Wenn Sie ein HRESULT in Ihre eigenen Bausteine einbinden wollen, geht das wie folgt:

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

Dies wird im Beispiel Selbstgeschriebene Funktionen genauer erklärt.

Extraktion des ADS Return Code

Falls z. B. zur Anzeige in einer HMI der reine ADS Return Code benötigt wird, kann dieser aus dem HRESULT wie folgt in numerischer und textueller Form extrahiert werden:

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);

Sie benötigen dafür die Bibliothek Tc2_Utilities.