Job-Methoden

Das Konzept der Job-Methoden hat im Vergleich zu den regulären Methodenaufrufen einen grundlegenden Unterschied: Die OPC-UA-Methoden werden nicht mehr 1:1 auf eine SPS-Methode abgebildet, sondern anstelle dessen auf einen Funktionsbaustein mit einer bestimmten Signatur. Hierdurch können auch Methodenaufrufe realisiert werden, welche aus Sicht einer SPS-Anwendung länger als einen Zyklus dauern.

	Voraussetzungen Diese Funktionalität steht nur für Data-Access-Geräte basierend auf TwinCAT 3 und dem Import von TMC-Symboldateien, sowie der Online-Symbolik zur Verfügung.

Der SPS-seitige Aufbau einer solchen Job-Methode ist hierbei wie folgt definiert: Es existiert ein Funktionsbaustein, welcher über ein SPS-Attribut als Job-Methode definiert wird. Der Funktionsbaustein beinhaltet dann verschiedene SPS-Methoden, auf welche vom TwinCAT OPC UA Server in Form eines Handshake-Mechanismus zugegriffen wird, um diese als OPC-UA-Methode bereitstellen zu können.

Methode	Beschreibung
Start	Wird vom Server aufgerufen, sobald ein OPC UA Client die OPC-UA-Methode aufruft. Beinhaltet die Eingabeparameter des OPC-UA-Methodenaufrufs als VAR_INPUT. Über den HRESULT Rückgabewert der Methode kann direkt ein OPC UA Status Code in dessen Dezimalrepräsentation zurückgegeben werden, z. B. „0“ für den Status Code „Good“. Als Wert wird hierbei der entsprechend in der OPC-UA-Spezifikation definierte numerische Wert eines Status Codes verwendet. Eine Definition aller verfügbaren Status Codes kann hier eingesehen werden: http://www.opcfoundation.org/UA/schemas/StatusCode.csv Typischerweise returniert diese Methode den Wert „0“ (Good). Der SPS-Entwickler kann sich jedoch auch dazu entscheiden, dass zum Beispiel die Eingabeparameter validiert werden sollen. Im Fehlerfall könnte man den OPC-UA-Methodenaufruf dann fehlschlagen lassen, z. B. mit dem Rückgabewert „2158690304“ (BadInvalidArguments).
CheckState	Wird zyklisch vom Server aufgerufen, um zu überprüfen, ob der Job noch in Bearbeitung ist oder nicht. Solange der Job noch in Bearbeitung ist, gibt diese Methode den Wert „Busy“ zurück, andernfalls „Done“. Ausgabeparameter für die OPC-UA-Methode werden hier als VAR_OUTPUT deklariert. Über den HRESULT Rückgabewert der Methode kann direkt ein OPC UA Status Code in dessen Dezimalrepräsentation zurückgegeben werden, z. B. „0“ für den Status Code „Good“. Als Wert wird hierbei der entsprechend in der OPC-UA-Spezifikation definierte numerische Wert eines Status Codes verwendet. Eine Definition aller verfügbaren Status Codes kann hier eingesehen werden: http://www.opcfoundation.org/UA/schemas/StatusCode.csv Bei einer erfolgreichen Abarbeitung des Jobs returniert diese Methode typischerweise den Wert „0“ (Status Code „Good“). Der SPS-Entwickler kann sich jedoch auch dazu entscheiden, dass im Falle eines Fehlers der OPC-UA-Methodenaufruf fehlschlagen soll, z. B. mit dem Rückgabewert „2151415808“ (BadOutOfRange) oder dem allgemeineren „2147483648“ (Bad).
Abort	Diese Methode wird vom Server aufgerufen, falls ein Job abgebrochen werden muss, zum Beispiel, wenn der Server heruntergefahren wird oder neu startet. Der SPS-Entwickler hat dann die Möglichkeit seinen SPS-Code entsprechend aufzuräumen.

Methode

Beschreibung

Start

Wird vom Server aufgerufen, sobald ein OPC UA Client die OPC-UA-Methode aufruft. Beinhaltet die Eingabeparameter des OPC-UA-Methodenaufrufs als VAR_INPUT.

Über den HRESULT Rückgabewert der Methode kann direkt ein OPC UA Status Code in dessen Dezimalrepräsentation zurückgegeben werden, z. B. „0“ für den Status Code „Good“. Als Wert wird hierbei der entsprechend in der OPC-UA-Spezifikation definierte numerische Wert eines Status Codes verwendet. Eine Definition aller verfügbaren Status Codes kann hier eingesehen werden:

http://www.opcfoundation.org/UA/schemas/StatusCode.csv

Typischerweise returniert diese Methode den Wert „0“ (Good). Der SPS-Entwickler kann sich jedoch auch dazu entscheiden, dass zum Beispiel die Eingabeparameter validiert werden sollen. Im Fehlerfall könnte man den OPC-UA-Methodenaufruf dann fehlschlagen lassen, z. B. mit dem Rückgabewert „2158690304“ (BadInvalidArguments).

CheckState

Wird zyklisch vom Server aufgerufen, um zu überprüfen, ob der Job noch in Bearbeitung ist oder nicht. Solange der Job noch in Bearbeitung ist, gibt diese Methode den Wert „Busy“ zurück, andernfalls „Done“. Ausgabeparameter für die OPC-UA-Methode werden hier als VAR_OUTPUT deklariert.

http://www.opcfoundation.org/UA/schemas/StatusCode.csv

Bei einer erfolgreichen Abarbeitung des Jobs returniert diese Methode typischerweise den Wert „0“ (Status Code „Good“). Der SPS-Entwickler kann sich jedoch auch dazu entscheiden, dass im Falle eines Fehlers der OPC-UA-Methodenaufruf fehlschlagen soll, z. B. mit dem Rückgabewert „2151415808“ (BadOutOfRange) oder dem allgemeineren „2147483648“ (Bad).

Abort

Diese Methode wird vom Server aufgerufen, falls ein Job abgebrochen werden muss, zum Beispiel, wenn der Server heruntergefahren wird oder neu startet. Der SPS-Entwickler hat dann die Möglichkeit seinen SPS-Code entsprechend aufzuräumen.

Workflow

Der Handshake-Mechanismus zwischen Server und SPS kann vereinfacht wie folgt dargestellt werden:

Beispiel

Das folgende Beispiel ist in ausführbarer Form auch in den Samples enthalten. Dieser Teil der Doku soll noch einmal die grundlegenden Zusammenhänge zur Funktionsweise erläutern. Das Beispiel „simuliert“ einen Job-Methodenaufruf, dessen Abarbeitung in der SPS circa vier Sekunden dauert. Dies wurde mit Hilfe eines Timers realisiert, welcher im Funktionsbaustein-Teil des Jobs deklariert und verwendet wurde. Über die State Machine des Funktionsbausteins wird hierbei der Abschluss des Jobs verzögert (die Handshake-Methode CheckState returniert „busy“) und erst nach Ablauf des Timers wird der Job beendet (die Handshake-Methode CheckState returniert „done“).

In diesem Beispiel wurde für die OPC-UA-Methode mit dem Namen „MyJob“ ein Funktionsbaustein namens FB_Job erzeugt, welcher die oben genannte, benötigte Signatur aufweist.

Die Funktionsbaustein-Deklaration enthält das Attribut OPC.UA.DA.JobMethod und als dessen Wert den zu verwendenden Namen der OPC-UA-Methode.

{attribute 'OPC.UA.DA.JobMethod' := 'MyJob'}
FUNCTION_BLOCK FB_Job
VAR
END_VAR

Die drei Methoden Abort, CheckState und Start enthalten in ihrer Deklaration das Attribut TcRpcEnable (damit die Methoden auch über ADS aufgerufen werden können). Beispiel:

{attribute 'TcRpcEnable' := '1'}
METHOD Start : HRESULT

{attribute 'TcRpcEnable' := '1'}
METHOD Abort : HRESULT

{attribute 'TcRpcEnable' := '1'}
METHOD CheckState : HRESULT

Die Eingabeparameter der OPC-UA-Methode werden in der SPS-Methode Start() als VAR_INPUT deklariert. Kommentare hinter den Variablen werden als Description des jeweiligen OPC-UA-Eingabeparameters verwendet. Beispiel:

{attribute 'TcRpcEnable' := '1'}
METHOD Start : HRESULT
VAR_INPUT
  a : INT; // some description
  b : LREAL; // some description
  c : BOOL; // some description
  d : ST_Complex_1; // some description
END_VAR
VAR_OUTPUT
  hdl : UDINT; // handle, can be used for concurrent calls
END_VAR

Die Ausgabeparameter der OPC-UA-Methode werden in der SPS-Methode CheckState() als VAR_OUTPUT deklariert. Kommentare hinter den Variablen werden als Description des jeweiligen OPC-UA-Ausgabeparameters verwendet. Beispiel:

{attribute 'TcRpcEnable' := '1'}
METHOD CheckState : HRESULT
VAR_INPUT
  hdl : UDINT; // handle, can be used for concurrent calls
END_VAR
VAR_OUTPUT
  a : INT; // some description
  b : LREAL; // some description
  c : BOOL; // some description
  d : ST_Complex_1; // some description
END_VAR

(In diesem Beispiel werden zu Zwecken der Veranschaulichung die Werte der Eingabeparameter 1:1 auf die Ausgabeparameter gelegt. Daher sind die Eingabe- und Ausgabeparameter identisch.)

Gleichzeitige Methodenaufrufe

Gleichzeitige Methodenaufrufe können über die SPS-Applikation verwaltet werden. Hierfür kann über einen Rückgabewert der Start() Methode ein Handle (Ausgangsvariable hdl) an den Server zurückgegeben werden, welches dann bei allen weiteren Aufrufen der CheckState() Methode als Eingangsvariable verwendet wird. Hierdurch wird es der SPS-Applikation ermöglicht, einen Ausführungskontext für den jeweiligen Methodenaufruf zu bestimmen. Zusammengefasst ist der Workflow somit wie folgt:

Start() Methode bestimmt den Ausführungskontext und liefert über die Ausgangsvariable „hdl“ ein Handle an den Server zurück.
Der Server verwendet nun bei den zyklischen CheckState()-Aufrufen dieses Handle und lässt die SPS-Applikation hierüber wissen, um welchen Ausführungskontext es sich handelt.