Anleitung:
In WinCC Global Script C stehen standardmäßig unterschiedliche "GetTagMultiWait()"-Funktionen zur Verfügung, um die Werte mehrerer WinCC-Variablen zu ermitteln:
- BOOL GetTagMultiWait(const char* pszFormat, const char* pszTag, void* pvValue, ...)
- BOOL GetTagMultiStateWait(DWORD* pdwState, const char* pszFormat, const* pszTag, void* pvValue, ...)
- BOOL GetTagMultiStateQCWait(DWORD* pdwState, DWORD* pdwQC, const char* pszFormat, const* pszTag, void* pvValue, ...)
Diese Funktionen sind sogenannte "Wait"-Funktionen, d.h. sie ermitteln die Variablenwerte direkt aus dem AS und nicht aus dem Abbild des WinCC-Datenmanagers. Die Anzahl der Parameter dieser Funktionen sind variabel, sie sind abhängig von der Anzahl der zu lesenden Variablen.
Parameter:
Den Funktionen werden folgende Parameter übergeben:
- DWORD* pdwState (nur bei GetTagMultiStateWait() und GetTagMultiStateQCWait())
Der Anwender der "GetTagMulti()"-Funktion muss ein Feld an DWORD-Variablen zur Verfügung stellen (Speicher reservieren). Der "GetTagMulti()"-Funktion wird der Zeiger auf das erste Element des Feldes übergeben. Die "GetTagMulti()"-Funktion schreibt an die übergebene Adresse fortlaufend die Variablenstatis der gelesenen WinCC-Variablen.
- DWORD* pdwQC (nur bei GetTagMultiStateQCWait())
Der Anwender der "GetTagMulti()"-Funktion muss ein Feld an DWORD-Variablen zur Verfügung stellen (Speicher reservieren). Der GetTagMulti()-Funktion wird der Zeiger auf das erste Element des Feldes übergeben. Die "GetTagMulti()"-Funktion schreibt an die übergebene Adresse fortlaufend die Quality Codes der gelesenen WinCC-Variablen.
- const char* pszFormat
Der Anwender der "GetTagMulti()"-Funktion muss eine Zeichenkette zur Verfügung stellen (Speicher reservieren) und diese mit den Formatinformationen für die zu lesenden WinCC-Variablen initialisieren. Der GetTagMulti()-Funktion wird der Zeiger auf das erste Element dieser Zeichenkette übergeben.
- const char* pszTag
"pszTag" ist ein Zeiger auf das erste Element einer Zeichenkette, die den Namen einer zu lesenden WinCC-Variablen enthält.
Der Anwender der "GetTagMulti()"-Funktion muss für jede zu lesene Variable eine Zeichenkette "pszTag" übergeben.
- void* pvValue
"pvValue" ist eine Adresse, an der die "GetTagMulti()"-Funktion die Inhalte der gelesenen WinCC-Variablen ablegt.
Der Anwender der "GetTagMulti()"-Funktion muss für jede zu lesene Variable eine Adresse übergeben.
Rückgabewert:
Die "GetTagMulti()"-Funktionliefern den Wert "FALSE" zurück, wenn mindestens einem Parameter der Wert "NULL" übergeben wird, sonst liefert sie den Wert "TRUE" zurück. Aus diesem Grund kann der Rückgabewert nicht verwendet werden, um zu prüfen, ob das Lesen der WinCC-Variablen wirklich erfolgreich war oder nicht. Verwenden Sie deshalb die Funktionen "GetTagMultiStateWait()" oder "GetTagMultiStateQCWait()" und verwenden Sie den Variablenstatus oder den Quality Code für die Fehlerauswertung.
Informationen zur Qualität von WinCC-Variablen (Variablenstatus und Quality Code) finden Sie im WinCC Information System unter:
- "Kommunikation > Diagnose der Kommunikation > Qualität von Variablen > Variablenstatus"
- "Kommunikation > Diagnose der Kommunikation > Qualität von Variablen > Quality Codes von Variablen"
Allgemeine Informationen zur Funktionsweise der "GetTag()" Funktionen und einfache Beispiele finden Sie im WinCC Information System unter:
- "Arbeiten mit WinCC > ANSI-C zum Erstellen von Funktionen und Aktionen > ANSI-C Funktionsbeschreibungen > Interne Funktionen > tag > get > Funktionsweise der GetTag Funktionen"
Die folgende Tabelle beschreibt die möglichen Formatangaben in der Formatzeichenkette und gibt Hinweise, welche Formatangaben mit welchen WinCC- und C-Datentypen verwendet werden dürfen.
| Format |
WinCC-Datentyp |
C-Datentyp |
| "%d" |
Ganzzahlige WinCC-Variablen
- Binäre Variable
- Vorzeichenbehafteter 8-Bit Wert
- Vorzeichenloser 8-Bit Wert
- Vorzeichenbehafteter 16-Bit Wert
- Vorzeichenloser 16-Bit Wert
- Vorzeichenbehafteter 32-Bit Wert
- Vorzeichenloser 32-Bit Wert
|
32-Bit Variable (4 Byte)
Die Formatangabe "%d" wird verwendet, um den Wert einer ganzzahligen WinCC-Variablen in eine C-Variable zu schreiben. Für die C-Variable muss unabhängig der Größe der WinCC-Variablen immer 4 Byte Speicherplatz reserviert werden, da die GetTagMulti()-Funktionen bei Verwendung der Formatangabe "%d" immer 32 Bit (4 Byte) auf die angegebene Zieladresse schreibt. Der Beitrag 26710239 beschreibt, wie Sie die Größe des benötigten Speicherplatzes für eine C-Variable ermitteln können. Mögliche Datentypen sind z.B.:
Beispiele:
- Um den Wert einer Vorzeichenlosen 8-Bit WinCC-Variablen zu lesen, können Sie eine C-Variable mit Datentyp DWORD anlegen und der "GetTagMulti()"-Funktion die Adresse auf diese Variable übergeben.
- Um den Wert einer Vorzeichenbehafteten 8-Bit WinCC-Variablen zu lesen, können Sie eine C-Variable mit Datentyp int oder long anlegen und der "GetTagMulti()"-Funktion die Adresse auf diese Variable übergeben.
Achtung!
Bei Verwendung einer WinCC-Variablen vom Datentyp "Vorzeichenloser 32-Bit Wert" (DWORD) darf das höchstwertige Bit (Bit 31) nicht gesetzt sein, da die GetTagMulti()-Funktion in diesem Fall einen Konvertierungsfehler erzeugt und den Wert 0 liefert. |
| "%f" |
Gleitkomma-WinCC-Variablen
- Gleitkommazahl 32-Bit IEEE 754
- Gleitkommazahl 64-Bit IEEE 754
|
"double"-Variable
Die Formatangabe "%f" wird verwendet, um den Wert einer Gleitkomma-WinCC-Variablen in eine C-Variable zu schreiben. Für die C-Variable muss 8 Byte Speicherplatz reserviert werden, da die GetTagMulti()-Funktion bei Verwendung der Formatangabe "%f" immer 64 Bit (8 Byte) auf die angegebene Zieladresse schreibt. Als Datentyp muss "double" verwendet werden.
Beispiel:
Um den Wert einer Gleitkommazahl 32-Bit WinCC-Variablen zu lesen, müssen Sie eine C-Variable mit Datentyp double anlegen und der "GetTagMulti()"-Funktion die Adresse auf diese Variable übergeben. |
| "%s" |
Text-WinCC-Variablen
- Textvariable 8-Bit Zeichensatz
- Textvariable 16-Bit Zeichensatz
- Textreferenz
|
"char*"-Variable (Zeiger auf ein Zeichen)
Die Formatangabe "%s" wird verwendet, um den Wert einer WinCC-Text- bzw. WinCC-Textreferenzvariablen in eine C-Variable zu schreiben. Der Anwender muss den Speicherplatz für eine "char"-Zeigervariable reservieren. Der GetTagMulti()-Funktion wird die Adresse auf diese Zeigervariable übergeben. Die GetTagMulti()-Funktion reserviert den benötigten Speicherplatz zum Ablegen des Inhalts der WinCC-Textvariablen selbst, legt den Inhalt der WinCC-Textvariablen in den reservierten Speicherbereich ab und schreibt die Adresse des reservierten Speicherbereiches an die übergebene Adresse.
Beispiel:
Um den Wert einer WinCC-Textvariablen zu lesen, müssen Sie eine C-Variable mit dem Datentyp "char*"(Zeiger) anlegen und der "GetTagMulti()"-Funktion die Adresse auf diese Variable übergeben. (...oh, ein Zeiger auf einen Zeiger!) |
Verhalten bei Projektierungsfehlern:
Nachfolgend ist das Verhalten für ausgewählte Fehlerfälle bei der Projektierung beschrieben:
- Zugriff auf eine WinCC-Variable, die nicht im WinCC-Variablenhaushalt angelegt ist
Wird mit der Funktion "GetTagMultiStateWait()" oder "GetTagMultiStateQCWait()" auf eine Variable zugegriffen, die nicht im WinCC-Variablenhaushalt angelegt ist, so wird im Global Script Diagnosefenster oder "APDIAG Output Window" eine "OnErrorExecute"-Fehlermeldung ("Tag unknown, timeout or conversation failed - Tag not found") erzeugt. Der Variablenstatus und Quality Code enthalten die Information, dass ein Zugriffsfehler aufgetreten ist.
Achtung!
Die Funktion "GetTagMultiWait()" erzeugt in diesem Fehlerfall keine "OnErrorExecute"-Fehlermeldung im Global Script Diagnosefenster oder "APDIAG Output Window".
- Verwendung des C-Datentyps "float", um eine WinCC Gleitkommazahl zu lesen
Soll der Inhalt einer WinCC-Variablen vom Datentyp "Gleitkommazahl 32-Bit IEEE 754" in eine C-Variablen vom Datentyp "float" geschrieben werden, so liefern die "GetTagMulti()"-Funktion den Wert "0.0" als Gleitkommawert zurück. Es erfolgt keine Fehleranzeige im Global Script Diagnosefenster oder "APDIAG Output Window". Der Variablenstatus und Quality Code enthalten keine Information, dass ein Zugriffsfehler aufgetreten ist.
- Verwendung eines C-Datentyps mit weniger als 4 Byte Speicherplatz, um eine WinCC Ganzzahl zu lesen
Wird eine C-Variable verwendet, die weniger als 4 Byte Speicherplatz belegt (z.B. BYTE, WORD, char oder short), um den Inhalt einer WinCC-Ganzzahl zu lesen, so kann dies zu einem undefinierten Verhalten des Systems oder der Anlage führen, da die GetTagMulti()-Funktion in diesem Fall in unerwünschte Speicherbereiche schreibt.
- Zugriff auf einen vorzeichenlosen 32-Bit WinCC-Wert, wobei das höchstwertige Bit (Bit 31) gesetzt ist
Soll der Inhalt einer WinCC-Variablen vom Datentyp Vorzeichenloser 32-Bit Wert ("DWORD") in eine C-Variablen vom Datentyp "DWORD" geschrieben werden, so liefern die "GetTagMulti()"-Funktion den Wert "0" (Hexadezimal 0x00000000) als Ganzzahl zurück. Im Global Script Diagnosefenster oder "APDIAG Output Window" wird eine "OnErrorExecute"-Fehlermeldung ("Tag unknown, timeout or conversation failed - OLE conversation failed") erzeugt. Der Variablenstatus und Quality Code enthalten jedoch keine Information, dass ein Zugriffsfehler aufgetreten ist.
Abhilfen:
- Stellen Sie wenn möglich sicher, dass das Bit 31 der vorzeichenlosen 32-Bit WinCC-Variablen nie gesetzt ist.
- Ist die 32-Bit WinCC-Variable eine externe WinCC-Variable, so können Sie z.B. im WinCC-Datenmanager die Obergrenze2147483648 (Hexadezimal 0x80000000) für diese Variable projektieren.
 
Bild 01
Im Quality Code und Variablenstatus wird dann die Verletzung der projektierten Obergrenze angezeigt und kann weiterverarbeitet werden.
- Verwenden Sie die Funktion "GetTagDWordXXX()".
- Legen Sie die WinCC-Variable im Variablenhaushalt als Vorzeichenbehafteten 32-Bit Wert an und verwenden Sie als Datentyp "DWORD" für die C-Variable.
- Fehlerhafter Aufbau der Formatzeichenkette
- Eine Formatangabe ist bezüglich des tatsächlich verwendeten Datentyps ungültig
Wird in der Formatzeichenkette eine Formatangabe verwendet, die für einen bestimmten Datentyp nicht zugelassen ist, so wird ein ungültiger Wert geliefert. Im Global Script Diagnosefenster oder "APDIAG Output Window" wird eine "OnErrorExecute"-Fehlermeldung ("Tag unknown, timeout or conversation failed - OLE conversation failed") erzeugt. Der Variablenstatus und der Quality Code enthalten jedoch keine Information, dass ein Zugriffsfehler aufgetreten ist.
Beispiel:
Dieser Fehler tritt z.B. auf, wenn eine WinCC-Textvariable mit der Formatangabe "%d" gelesen wird.
- Der Formatstring enthält zu viele Formatangaben
Werden nicht für alle Formatangaben in der Formatzeichenkette die notwendigen Parametern (pszTag, pvValue) der "GetTagMulti()"-Funktion übergeben, so wird im Global Script Diagnosefenster oder "APDIAG Output Window" eine "OnErrorExecute"-Fehlermeldung ("Tag unknown, timeout or conversation failed - Tag not found") erzeugt. Der Variablenstatus und der Quality Code enthalten die Information, dass ein Zugriffsfehler aufgetreten ist.
Hinweis:
Werden mehr Parameter (pszTag, pvValue) übergeben, als in der Formatzeichenkette angegeben sind, so werden die mit der Formatzeichenkette angeforderten Werte korrekt ermittelt. Die Werte, für die in der Formatzeichenkette keine Formatangabe vorhanden ist, werden nicht ermittelt. Der Variablenstatus und der Quality Code für diese Variablen enthalten die Information, dass ein Zugriffsfehler aufgetreten ist. Im Global Script Diagnosefenster oder "APDIAG Output Window" wird keine "OnErrorExecute"-Fehlermeldung angezeigt.
Projektierungsbeispiel: Dynamischer Aufbau der Formatzeichenkette
Sollen viele Variablen mit der GetTagMulti()-Funktion gelesen werden, so wird der Aufbau der Formatzeichenkette unübersichtlich. Es lässt sich nicht mehr schnell mit bloßem Auge erkennen, ob ausreichend Formatangaben in der Formatzeichenkette enthalten sind und ob die Formatangaben für die verwendeten Datentypen gültig sind. Um Fehler im Aufbau der Formatzeichenkette zu vermeiden, kann die Formatzeichenkette auch zur Laufzeit aufgebaut werden. Die Informationen, welche Variablen durch die GetTagMulti()-Funktion gelesen werden sollen, können in einem Feld abgelegt werden, wobei jedes Feldelement eine Struktur darstellt, die die notwendigen Informationen (Formatangabe, Variablenname und Zieladresse) enthält.
Nachfolgend wird ein Script zum Download (PDF- und Textdatei) zur Verfügung gestellt, das diese Vorgehensweise demonstriert.
 WinCC_GetTagMulti_c.zip ( 1 KB )
 WinCC_GetTagMulti_c.pdf ( 10 KB )
Die folgenden zwei Bilder zeigen die externen und internen WinCC-Variablen im Variablenmanager, die im Beispielscripts mit der Funktion"GetTagMultiStateQCWait()" gelesen werden.
Bild 02
Bild 03
Das Script kann als C-Aktion in einem Bild (z.B. Ereignis Mausklick bei einem Button) aufgerufen werden.
Das folgende Bild zeigt die Inhalte der WinCC-Variablen zur Runtime. Die WinCC-Variablen werden im Bild mittels Variabledirektverbindung an der Eigenschaft "Output Value" an E/A-Feldern.) dargestellt. Gleichzeitig ist das Output Window des Diagnosetools "APDIAG" dargestellt, das die gelesenen Werte darstellt.
Bild 04
Hinweis:
Das Script wurde mit WinCC V6.2 erstellt. |
englisch
