PLCnext / PLCnextEngineer / SQL4PLCnext

Target: "Standard" / "UTF-16"

Voraussetzungen

Die Target-Bausteine wurden mit PLCnextEngineer Version 2026.0 entwickelt.

Die Funktionalität wird in der folgenden Bibliothek zur Verfügung gestellt:

• S4A_SQL4PLCnext.pcwlx

Vom Hersteller werden folgende Bibliotheken referenziert:

• PLCnextBase_1_7_2.pcwlx

  • PLCnextBase_1_7_2\ PLCnextBase.pcwlx

  • PLCnextBase_1_7_2\ PLCnextBaseServices.pcwlx

(Wir empfehlen die Installation der Libraries in den Standard-Ordner vom PLCnextEngineer für «User Libraries»: C:\Users\lt;user>\Documents\PLCnext Engineer\Libraries).

Es stehen zwei Beispiel-Projekte zur Verfügung:

• S4A_SQL4PLCnext_Example.pcwex: Die Kommunikation erfolgt über das Standard-Protokoll. Die Kommunikation kann sowohl unverschlüsselt als auch verschlüsselt erfolgen.

• S4A_SQL4PLCnext_UTF16_Example.pcwex: Die Kommunikation erfolgt über das UTF-16-Protokoll. Die Kommunikation kann sowohl unverschlüsselt als auch verschlüsselt erfolgen.

Das Verhalten ist bei beiden Varianten identisch. Deshalb wird nachfolgend nur auf die Variante mit dem Standard-Protokoll eingegangen.

Auch die Kommunikations-Verschlüsselung (TLS/SSL) ist identisch und wird in einem eigenen Kapitel behandelt.

Folgende Bausteine werden für die Anbindung an den Connector benötigt:

• Die Definitionen im Ordner „Local“ 🡪 → „Data Types“ 🡪 → „S4A_SQL4PLCnext“

  

• Eine Referenz auf die Bibliothek „S4A_SQL4PLCnext“

  

Die übrigen Definitionen und Bausteine sind Beispiele, mit welchen die Funktionsweise gezeigt wird. Diese können als Vorlage für die eigenen projektspezifischen Anwendungen verwendet werden.

fbSQL4PLCnext

Mit diesem Baustein aus der Bibliothek wird die Verbindung zum Connector hergestellt.

Der Baustein «fbSQL4PLCnext» wird zyklisch aufgerufen. Wir empfehlen, dies über einen zeitgesteuerten Task mit niedriger Priorität zu tun (z.B. tskUncritical, Interval=10ms, Priority=10).

Es können folgende Parameter eingestellt werden:

sIP                    : STRING;                 // Eingestellt IP-Adresse des Connectors
iPort                  : INT;                    // Eingestellte Port-Nummer des Connectors
tTimeout               : TIME;                   // Timeout (Standard: 10 Sekunden)
tFbExecTimeLimit       : TIME;                    // Maximal nutzbare Zeit pro Zyklus
xUseTLS                : BOOL;                    // Verschlüsselung der Kommunikation
sTlsIdentityStoreName  : STRING;                  // «IdentityStore» für eine verschlüsselte Kommunikation
sTlsTrustStoreName     : STRING;                  // «TrustStore» für eine verschlüsselte Kommunikation
stSql4PLCnextInterface : utSql4PLCnextInterface   // Request-Response-Struktur (Verbindung zum Connector)

stSQL4PLCnextInterface

Die Datenstruktur «stSQL4PLCnextInterface» wurde unter «IEC 61131-3» als globaler / externer Speicher instanziiert, damit alle Tasks darauf Zugriff haben.

utSQL4PLCnextInterface

Mit diesem Datentyp wird der Speicherplatz für die Kommunikation mit dem Connector definiert. Im PLCnextEngineer wird diese wie folgt erreicht:

Folgende Parameter können vom Benutzer entsprechend den projektspezifischen Bedürfnissen eingestellt werden:

Parameter	Standard-Wert	Beschreibung
SQL4PLCNEXT_USE_MRP_PARAMETER	TRUE	Ab Target-Link-Protokoll Version 4 steht der Parameter standardmäßig auf TRUE. Dies ermöglicht die Verwendung von Return-Parametern aus Stored Procedures. Falls das Target über einen Connector mit Version kleiner 4.0.0.0 kommunizieren soll, muss der Parameter auf FALSE gesetzt werden
SQL4PLCNEXT_REQUEST_BUFFER_SIZE	8192	Größe des Sende-Buffers
SQL4PLCNEXT_RESPONSE_BUFFER_SIZE	8192	Größe des Empfangs-Buffers
SQL4PLCNEXT_RESPONSE_RETURNPARAM_SIZE	5	Maximale Anzahl Return-Parameter in der Antwort-Tabelle
SQL4PLCNEXT_RESPONSE_ROW_SIZE	20	Maximale Anzahl Zeilen (Rows) in der Antwort-Tabelle
SQL4PLCNEXT_RESPONSE_COL_SIZE	10	Maximale Anzahl Spalten (Columns) in der Antwort-Tabelle
SQL4PLCNEXT_RESPONSE_MAX_STRING_SIZE	255	Maximale Länge der Antwort-Strings
SQL4PLCNEXT_RCVARRAY_SIZE	200	Größe des Empfangs-Arrays. Empfangen X-Bytes pro PLC-Zyklus

fbSQL4PLCnextConnectionObserver

Dieser Baustein aus der Bibliothek kann optional verwendet werden.

Bei Daten-intensiven Applikationen kann es Sinn machen, eine Verbindung nicht nach jeder Anfrage zu schließen und gleich wieder zu öffnen. Damit bei Kommunikations-Pausen kein Timeout-Fehler entsteht, wird dieser Baustein eingesetzt.

Wenn eine Verbindung nach einem konfigurierbaren Timeout nicht mehr benutzt wird, sendet der Baustein eine «Dummy-Abfrage» zur Datenbank.

Falls der Parameter «xCloseConnection» auf «FALSE» steht, bleibt die Verbindung offen und wird vom ConnectionObserver jeweils nach dem Erreichen des parametrierten Timeouts weiterhin mit einer «Dummy-Abfrage» unterhalten.

Falls der Parameter «xCloseConnection» auf «TRUE» gesetzt wurde, wird nach dieser Anfrage die Verbindung zur Datenbank geschlossen. Die Verbindung wird erst wieder geöffnet, wenn aus der Applikation eine neue Anfrage an die Datenbank geschickt wird.

Einstellungen der Ethernet-Schnittstelle

Um eine Kommunikation über die Ethernet-Schnittstelle auf der CPU und dem Connector herzustellen, muss diese parametriert werden. Die IP-Adresse der Ethernet-Schnittstelle muss im gleichen Netzwerkadressbereich mit gleicher Subnet-Maske sein, wie die des Connectors.

Die PLCnext-Steuerung (z.B. AXC F 2152) verfügt über einen integrierten HTTP-Server, über welchen Einstellungen vorgenommen werden können. Die Default-IP-Adresse einer neuen (oder zurückgesetzten) Steuerung ist 192.168.1.10. Der Benutzer lautet «admin» und das Standard-Passwort ist auf dem Gehäuse aufgedruckt.

Die Änderungen müssen gespeichert und die Steuerung neu gestartet werden.

Das Beispielprojekt

Das Beispielprojekt zeigt die wichtigsten Anwendungsfälle auf.

Es sind folgende Funktionsbausteine enthalten:

Alle Funktionsbausteine haben gemeinsam, dass diese eine Execute-Schnittstelle sowie eine Referenz auf ein utSql4PLCnextInterface haben:

Ü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 Requests (Anfrage an die Datenbank):

• Beispiel eines SELECT-Befehls (fbExample1A_Select_SCL).

  

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

  

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:

  • stSql4PLCnextInterface.diResultState: 0: kein Fehler >0: Fehlercode

  • stSql4PLCnextInterface.diResultRows: Anzahl Datensätze im Response-Telegramm

  • stSql4PLCnextInterface.diResultColums: Anzahl Datenspalten im Response-Telegramm

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

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

  • fcSql4PLCnext_GetColName: 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 (fbExample1A_Select_SCL)

  

Fehlercodes Return-Value

Die Variable “diResultState” beschreibt den Fehler.

Fehler-Nummer	Fehler-Beschreibung
1	Unbekannter SQL Befehl
2	Abfrage ergibt mehr Datensätze als mit MaxRows definiert. Abfrage anpassen oder MaxRows vergrößern
3	Abfrage ergibt mehr Spalten als mit MaxColumns definiert. Abfrage anpassen oder MaxColumns vergrößern
4	Abfrage ergibt mehr Daten zurück als die definierte Puffergröße. Abfrage anpassen oder die Buffer-Größe im Connector und in der Steuerung vergrößern
5	Abfrage gibt min. ein Wert zurück, der größer ist als mit MaxStringLength definiert. Abfrage anpassen oder MaxStringLength vergrößern
10	Interner Connector Fehler
11	Interner Connector Fehler, Datenbank kann nicht geöffnet werden
21	Keine IP-Adresse definiert
22	Keine Portnummer definiert
23	Request-String ist leer
29	Größe MaxStringLength ist ungültig
41	Keine Verbindung zum SQL4automation-Connector hergestellt. Firewall ausschalten, IP-Adresse und Remote-Port überprüfen
51	Fehler beim Senden der Anfrage. Firewall ausschalten, IP-Adresse und Remote-Port überprüfen
91	Timeout-Fehler. Keine Antwort vom Connector innerhalb des Zeitfensters
95	Fehler beim Empfangen der Daten
>100	Fehlernummern der ODBC Datenbankanbindung
40002	Allgemeiner Fehler bei der SQL Abfrage. Request-String ist ungültig

TLS-Verschlüsselung

Voraussetzungen

Für eine verschlüsselte Kommunikation muss ein Connector ab V5.1.0.0 eingesetzt werden.

Hardware-Architektur und SSL-Zertifikate

• SPS IP-Adresse: 10.100.100.160

• SQL4automation Connector IP-Adresse: 10.100.100.211

Es werden folgende Zertifikate generiert (OpenSSL). Beachten Sie, dass die Einstellungen, insbesondere die IP-Adressen, für die entsprechende Netzwerk-Architektur angepasst werden müssen.

CLIENT160

openssl genrsa -out client160.key 2048
openssl req -new -key client160.key -out client160.csr -subj "/C=CH/ST=Bern/L=Lyssach/CN=10.100.100.160/O=Inasoft"
openssl x509 -req -in client160.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out client160.crt -days 1825 -sha256
openssl pkcs12 -export -out client160.p12 -inkey client160.key -in client160.crt

→ PWD: SSLtest

SERVER211

openssl genrsa -out server211.key 2048
openssl req -new -key server211.key -out server211.csr -subj "/C=CH/ST=Bern/L=Lyssach/CN=10.100.100.211/O=Inasoft"
openssl x509 -req -in server211.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out server211.crt -days 1825 -sha256
openssl pkcs12 -export -out server211.p12 -inkey server211.key -in server211.crt

→ PWD: SSLtest

ROOT CA

openssl genrsa -out rootCA.key 2048
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1825 -out rootCA.pem -subj "/C=CH/ST=Bern/L=Lyssach/CN=SQL4automation/O=Inasoft"
openssl pkcs12 -export -out rootCA.p12 -inkey rootCA.key -in rootCA.pem

→ PWD: SSLtest

Die PLCnext-Steuerungen erwarten ein PEM-Format. Vom Hersteller wurde uns empfohlen, das Tool «XCA» einzusetzen. (Nachfolgend wird V2.9.0 eingesetzt).

Neue Datenbank erstellen («File» 🡪 «New Database»)

Root Schlüssel importieren («Private Keys» 🡪 «Import»)

Client Schlüssel importieren («Private Keys» 🡪 «Import»)

Root-Zertifikat importieren («Certificates» 🡪 «Import»)

Client-Zertifikat importieren («Certificates» 🡪 «Import»)

Root-Zertifikat als PEM+KEY-Datei exportieren («Zertifikat anwählen» 🡪 «Export»)

Client-Zertifikat als PEM+KEY-Datei exportieren («Client-Zertifikat anwählen» 🡪 «Export»)

Inbetriebnahme TLS-Verschlüsselung

Vor der Inbetriebnahme sind die Zertifikate für den SQL4automation Connector in die entsprechenden Pfade zu kopieren.

• Pfad «C:\ProgramData\SQL4automation\certs\CA» 🡪 Den Inhalt des RootCA in die Datei kopieren

  

• Pfad «C:\ProgramData\SQL4automation\certs\S4AConnector» 🡪 Die Server-Zertifikate werden an diesen Ort kopiert.

  

• Pfad «C:\ProgramData\SQL4automation\certs\S4AQueryTool» 🡪 Hier liegen die Zertifikate, um mit dem Query-Tool testen zu können.

Nach dem Kopieren des RootCA muss der SQL4automation Connector Dienst vor dem Betrieb neu gestartet werden.

Im weiteren Schritt wird empfohlen, die Verbindung zwischen SQL4automation und der Steuerung OHNE die TLS-Verschlüsselung in Betrieb zu nehmen.

Erst wenn die Kommunikation ohne Verschlüsselung funktioniert, empfehlen wir als nächstes die Verschlüsselung zu aktivieren. Beachten Sie, dass die Systemzeit an dieser Stelle kontrolliert und falls erforderlich eingestellt werden muss!

Passphrase: SSLtest

Um die Zertifikate auf die Steuerung zu laden, muss man sich mit einem Web-Browser auf die Steuerung verbinden und sich einloggen.

Einen neuen «Trust Store» anlegen

Im Trust Store «SQL4automation» das Root-Zertifikat hinzufügen

Einen neuen «Identity Store» anlegen und die Client-Datei auswählen.

In einem zusätzlichen Schritt muss noch der Key hinzugefügt werden.

Im PLC-Programm wird die Verschlüsselung beim Instanz-Aufruf von «fbSQL4PLCnext» eingestellt:

• xUseTLS = TRUE setzen

• Die Namen «sTlsIdentityStoreName» und «sTlsTrustStoreName» verweisen dabei auf die Konfigurationen, welche über den Browser unter «Security» 🡪 «Certificate management» vorgenommen wurden.

PLCnext Engineer mit der Steuerung verbinden und die verschlüsselte Verbindung zur Datenbank testen.

Die Abfrage war erfolgreich!

TLP – Target-Link-Protocol

Falls für Ihre Steuerung noch keine Bibliothek verfügbar ist, können Sie das Protokoll zwischen Steuerung und Connector anhand der folgenden Dokumentation emulieren. Bitte kontaktieren Sie uns in diesem Fall zuerst, da wir laufend Bibliotheken für weitere Steuerungen entwickeln.