Zum Hauptinhalt springen

CODESYS V3 / SQL4CODESYSV3

Target: "Standard" / "UTF-16"

Voraussetzungen​

Dieses Target setzt mindestens CODESYS 3.5.11.0 voraus.

Der Funktionsblock fbSQL4Codesys verwendet folgende CODESYS-Bibliotheken:

  • Memory V3.5.7.0

  • Network V3.5.7.0

  • Standard V3.5.9.0

  • SysMem 3.5.5.0

  • SysTypes2 Interfaces 3.5.4.0

Das Beispielprojekt kann auf der Soft-SPS „CODESYS Control Win V3“ oder einer Hardware-SPS ausgeführt werden. Voraussetzung ist, dass die Steuerung einen TCP/IP Anschluss hat und die obenstehenden Bibliotheken unterstützt.

Bibliothek installieren​

Die Bibliothek «S4A_SQL4CodesysV3.compiled-library» wird über das Projektarchiv «S4A_SQL4CODESYS_Sample.projectarchive» installiert.

Aufruf fbSQL4CODESYS​

Der Funktionsblock fbSQL4CODESYS mit seinen Ein- und Ausgangssignalen

Parameter von fbSQL4Codesys​

Beschreibung der Schnittstellen-Signale:

xExecute                  : BOOL;         // Datenbankabfrage starten
sIPAddress                : STRING(15);   // Eingestellte IP-Adresse des SQL4automation-Connectors
iPort                     : INT;          // Eingestellte Port-Nummer des SQL4automation-Connectors
tTimeout                  : TIME;         // Timeout
xHoldConnection           : BOOL;         // Behält nach einer Datenbankabfrage die Socketverbindung offen
dwRequestBufferSize       : DWORD;        // Größe des Request-Datenbuffers
dwResponseBufferSize      : DWORD;        // Größe des Response-Datenbuffers
dwResponseMaxReturnParams : DWORD;        // Maximale Anzahl Return-Parameter
                                          // (Connector-Version >= 4.0, ansonsten 0)
dwResponseMaxRows          : DWORD;       // Maximale Anzahl Zeilen in der Antwort der Datenbank-Abfrage
dwResponseMaxColumns       : DWORD;       // Maximale Anzahl Spalten in der Antwort der Datenbank-Abfrage
dwResponseMaxStringLen     : DWORD;       // Maximale Stringlänge in der Antwort der Datenbank-Abfrage
dwResponseCutStringLen     : DWORD;       // Strings in der Antwort werden auf die entsprechende Länge gekürzt
                                          // (0=inaktiv)
xReady                     : BOOL;        // Bereit für eine Datenbankabfrage
xBusy                      : BOOL;        // Datenbankabfrage läuft
xDone                         : BOOL;              // Datenbankabfrage abgeschlossen
xError                        : BOOL;              // Datenbankabfrage endete mit einem Fehler
stResult.diResultState        : DINT;              // Status Datenbankabfrage / Fehlernummer
stResult.dwResultRows         : DWORD;             // Anz. erhaltene Zeilen aus der Datenbankabfrage
stResult.dwResultColumns      : DWORD;             // Anz. erhaltene Spalten aus der Datenbankabfrage

Fehlercodes Return-Value​

Die Variable “diResultState” beschreibt den Fehler.

Fehler-NummerFehler-Beschreibung
1Unbekannter SQL Befehl
2Abfrage ergibt mehr Datensätze als mit dwMaxRows definiert, Abfrage anpassen oder dwMaxRows vergrößern
3Abfrage ergibt mehr Spalten als mit dwMaxColumns definiert, Abfrage anpassen oder dwMaxColumns vergrößern
5Abfrage gibt min. ein Wert zurück, der größer ist als mit MaxStringLength definiert, Abfrage anpassen oder MaxStringLength vergrößern
10Interner Connector Fehler
11Interner Connector Fehler, Datenbank kann nicht geöffnet werden
21Keine IP-Adresse definiert / sIPAddress=’’
22Keine Portnummer definiert / iPort=0
23Request-String ist leer
24Anzahl MaxRows nicht definiert / dwResponseMaxRows=0
25Anzahl MaxColumns nicht definiert / dwResponseMaxColumns=0
41

Keine Verbindung zum SQL4automation-Connector hergestellt.

Firewall ausschalten.

51Der Request-string ist größer als der Sendepuffer
99Timeout
>100Fehlernummern der ODBC Datenbankanbindung (anbei ein paar bekannte Fehlernummern)
40002Allgemeiner Fehler bei der SQL Abfrage, Request-String ist ungültig

Das Beispielprojekt​

Das Beispielprojekt kann über den Download-Bereich von SQL4automation (http://www.SQL4automation.com) oder über den CODESYS Store (https://store.codesys.com) bezogen werden.

Die Bibliothek «S4A_SQL4CodesysV3.compiled-library» wird beim Öffnen des Projektarchivs installiert.

Das Beispiel kann auf einer «CODESYS Control Win V3» Steuerung sehr einfach getestet werden.

Das Beispielprogramm sollte vor Anpassungen an die eigene Applikation zuerst zum Laufen gebracht werden.

Dadurch sind etwaige Fehlerquellen einfacher zu finden.

Passen Sie die IP-Adresse und den Remote-Port beim Aufruf des Bausteins «fbSQL4CODESYS» im Programm «prgUncritical» an ihr System an.

Der Baustein fbSQL4CODESYS im Programm prgUncritical

Der Connector muss gestartet und die Verbindung zur Beispiel-Datenbank „S4A_Test_DB.mdb“ konfiguriert sein.

Wie die Verbindung zur Testdatenbank konfiguriert wird, ist unter Einrichten der Verbindung an die Testdatenbank beschrieben.

Die Beispiel-Programme «Basic examples» zeigen die 4 SQL-Grundbefehle (SELECT, INSERT, UPDATE, DELETE) sowie den Umgang mit den SQL-Daten.

Die Beispiel-Programme basic examples im Projektbaum

Alle Funktionsbausteine haben gemeinsam, dass diese eine Execute-Schnittstelle sowie eine Referenz auf eine Sql4Codesys-Instanz verfügen:

Execute-Schnittstelle und Referenz auf eine Sql4Codesys-Instanz

Über das Signal «xExecute» wird die Kommunikation zur Datenbank angestoßen. Der Status wird über die Signale «xReady», «xBusy», «xDone» und «xError» zurückgemeldet.

Die Logik innerhalb des Bausteins wird über eine kleine Schrittkette (Variable «iStep») gesteuert:

  • iStep = 0 (Inactive): Es ist keine Kommunikation zur Datenbank aktiv

  • iStep = 1 (Create the request): In diesem Schritt wird gewartet, bis die Schnittstelle frei ist. Sobald dies der Fall ist wird das SQL-Query entsprechend der Kunden-Applikation erstellt und das Signal «xExecute» gesetzt. Damit schickt das SQL4automation-Framework das Telegramm zur Datenbank.

  • iStep = 2 (Parse the response): In diesem Schritt wird auf eine Antwort vom Connector gewartet. Falls Daten zurückgeschickt werden, können diese bei einer erfolgreichen Ausführung ausgewertet werden. Im Fehlerfall oder wenn keine Antwort vom Connector eintrifft wird eine entsprechende Fehlermeldung ausgegeben.

  • iStep = 3 (Reset execute signal): In diesem Schritt wird gewartet, dass das Signal «xExecute» zurückgesetzt wird, worauf die Schrittkette wieder in den Grundzustand «Inactive» versetzt wird.

Das Kommunikations-Prinzip ist bei allen Beispiel-Bausteinen das gleiche. Die SPS schickt eine Anfrage (Request) zur Datenbank und erhält darauf eine Rückmeldung (Response). Der Datenfluss ist dabei sekundär - es können Daten von der Datenbank gelesen (SELECT) oder auch geschrieben werden (INSERT, UPDATE).

Die genaue Syntax vom SQL-Befehl wird einerseits vom Datenbank-Modell bestimmt und andererseits von der Aufgabe, welche ausgeführt werden soll.

Erstellen eines Request (Anfrage an die Datenbank):

  • Beispiel eines SELECT-Befehls (fbExample1_Select).

    Beispiel eines SELECT-Befehls (fbExample1_Select)

  • Beispiel eines INSERT-Befehls (fbExample1_Insert). Die Variablenwerte werden mit Convert-Funktionen zur Laufzeit gewandelt.

    Beispiel eines INSERT-Befehls (fbExample1_Insert)

Parsen der Response (Antwort von der Datenbank):

  • Das Antwort-Telegramm wird beim Empfang auf Korrektheit geprüft. Wichtige Informationen werden intern gespeichert und stehen dem Anwender zum Auslesen der Daten zur Verfügung:

    • inSQL4Codesys.stResult.diResultState: 0: kein Fehler >0: Fehlercode

    • inSQL4Codesys.stResult.dwResultRows: Anzahl Datensätze im Response-Telegramm

    • inSQL4Codesys.stResult.dwResultColums: Anzahl Datenspalten im Response-Telegramm

  • Um die Daten auszulesen stehen folgende Methoden zur Verfügung:

    • inSQL4Codesys.GetData(): Gibt das entsprechende Datenfeld zurück. Der Zeilen-Index und der Spalten-Index sind 0 basiert.

    • inSQL4Codesys.GetColumnName(): Gibt den Spalten-Namen anhand des entsprechenden Spalten-Index zurück. Der Spalten-Index ist 0 basiert. Die Spalten-Namen können beispielsweise zur Plausibilitätsprüfung benutzt werden, ob die Daten in der erwarteten Reihenfolge zurückgegeben werden.

  • Beispiel (fbExample1_Select)

    Parsen der Response — Beispiel (fbExample1_Select)

Der ConnectionObserver​

Der ConnectionObserver ist ein Bestandteil der Beispiel-Applikation und kann bei Bedarf optional genutzt werden.

Mit der Standard-Anwendung (ohne ConnectionObserver) wird die Verbindung zur Datenbank vor jeder Anfrage geöffnet und unmittelbar nach jeder Anfrage auch wieder geschlossen. Bei kurzzeitigem hohem Datenvolumen ist dies nicht sonderlich performant und es wäre besser, eine bestehende Verbindung nicht zu schließen. Bei technischen Problemen (z.B. Verbindungsunterbrüchen) spricht gegen diesen Ansatz, dass die Lösung dadurch störungsanfälliger wird.

Der ConnectionObserver stellt ein Hilfsmittel zur Verfügung, um bei Bedarf offen gehaltene Verbindungen gezielt zu schließen oder weiterhin offen zu halten, ohne dass dies zu systembedingten Fehlermeldungen führt.

Bei aktiviertem ConnectionObserver stellt dieser bei irgendeiner Anfrage aus der Steuerung den Parameter «xHoldConnection» auf TRUE. Damit wird die Verbindung nach deren Ausführung nicht mehr geschlossen.

Stellt nun der ConnectionObserver bei der Überwachung fest, dass eine Verbindung während der Dauer von «tTimeout» ungenutzt offen gehalten wurde, tritt er seiner Konfiguration entsprechend in Aktion:

  • Parameter «xCloseConnection» = TRUE

Es wird eine «Dummy-Select-Abfrage» zur Datenbank geschickt. Gleichzeitig wird der Parameter «xHoldConnection» auf FALSE gesetzt. Das bewirkt, dass die Verbindung nach deren Abfrage geschlossen wird.

  • Parameter «xCloseConnection» = FALSE

Es wird eine «Dummy-Select-Abfrage» zur Datenbank geschickt. Da der Parameter «xHoldConnection» nicht verändert wird, bleibt die Verbindung offen. Durch das Senden neuer Daten wird kein Timeout auf der Verbindung ausgelöst und es werden daher keine Systemfehlermeldungen generiert. Durch die offen gehaltene Verbindung wiederholt der ConnectionObserver bei erneutem Erreichen des Timeouts seine Aktion. Falls die Applikation Nutzdaten überträgt, bleibt er aber passiv und tritt nicht in Aktion.