Logikbausteine (allgemein)***r-0Entwicklung von Logikbausteinen***r-0-0Funktionsreferenz

Die nachfolgend aufgeführten Funktionen stehen sowohl im LBS-Abschnitt, als auch im EXEC-Abschnitt zu Verfügung. Einige Rückgabewerte sind im EXEC-Script jedoch nicht sinnvoll auswertbar, da das EXEC-Script als eigenständlicher Prozess ausgeführt wird und somit unabhängig von der Logik-Engine asynchron abläuft (Hinweise beachten). Hinweis: Für die meisten Funktionen existiert aus historischen Gründen ein gleichwertiger "Alias"-Name. Dieser alternative Funktionsname kann mit den entsprechenden Parametern ebenfalls verwendet werden, es wird aber empfohlen den Alias-Funktionsnamen nicht mehr zu verwenden (u.U. werden die Alias-Funktionsnamen in zukünftigen Versionen entfernt).

Grundlegende LBS-Funktionen

Funktion Erläuterung
logic_getInputs($id)
Alias: getLogicEingangDataAll
Liefert die aktuellen Daten aller Eingänge der LBS-Instanz $id zurück. Rückgabe: ARRAY[Eingang]['value';'refresh'] (im Fehlerfall wird FALSE zurückgegeben)
  • Eingang: Nr. des Eingangs (1..∞)
  • 'value': aktueller Wert am Eingang
  • 'refresh':
    • 1=Eingang wurde aktualisiert
    • 0=Eingang wurde nicht aktualisiert
Wichtig: Die 'refresh'-Eigenschaft kann in einem EXEC-Script nicht zuverlässig ausgewertet werden, da das Script nicht im Kontext der Logik-Engine ausgeführt wird.
logic_getState($id)
Alias: getLogicElementStatus
Liefert den aktuellen Status der LBS-Instanz $id zurück. Rückgabe: INTEGER (im Fehlerfall wird NULL zurückgegeben)
  • 0=LBS läuft nicht
  • 1=LBS läuft
logic_setState($id,$status[,$delay[,$interval]])
Alias: setLogicElementStatus
Aktiviert oder deaktiviert das zyklische Aufrufen der LBS-Instanz $id durch die Logik-Engine. $status:
  • 0=nicht zyklisch aufrufen
  • 1=LBS zyklisch aufrufen (mit kleinstmöglichem Intervall)
  • Hinweis: $status=0 hat stets Priorität ($delay wird dann ignoriert)
$delay (optional):
  • Verzögerung des nächsten zyklischen Aufrufs in Millisekunden ($status muss =1 sein, ansonsten wird $delay ignoriert)
  • $delay=0 ist nicht erlaubt (in diesem Fall wird $delay ignoriert und $status hat Priorität)
  • $delay=1: nächster automatischer Aufruf mit kleinstmöglicher Verzögerung
  • $delay=2..∞: nächster automatischer Aufruf mit dieser Verzögerung (ms)
  • Hinweis: $delay erwartet einen INTEGER-Wert (ms)
  • Achtung: Das Timing ist nicht unbedingt präzise, $delay ist daher als Mindestverzögerung zu verstehen!
$interval (optional ergänzend zu $delay):
  • false: $delay nur einmalig(!) anwenden (nach dem verzögerten Aufruf wird der LBS weiterhin zyklisch aufgerufen, jedoch mit kleinstmöglicher Verzögerung)
  • true: $delay immer wieder anwenden (nach dem verzögerten Aufruf wird der LBS immer wieder mit der Verzögerung $delay aufgerufen)
  • Hinweis: wird $interval nicht angegeben, wird $delay nur einmalig angewendet (entspricht $interval=false)
logic_setOutput($id,$ausgang,$value)
Alias: setLogicLinkAusgang
Setzt einen Ausgang der LBS-Instanz $id auf einen Wert. $ausgang: Nr. des Ausgangs (1..∞) $value: zu setzender Wert Hinweis: Intern wird nicht der Ausgang auf einen Wert gesetzt, sondern alle Eingänge, die mit dem Ausgang verbunden sind. Wichtig: Die Verwendung dieser Funktion in einem EXEC-Abschnitt führt bei einem sehr häufigen Aufruf in kurzer Zeit u.U. dazu, dass einzelne Aufrufe unwirksam bleiben (der EXEC-Abschnitt wird asynchron ausgeführt). Ggf. ist daher die Funktion logic_setOutputQueued() im EXEC-Abschnitt zu verwenden.
logic_setOutputQueued($id,$ausgang,$value) Wie logic_setOutput(), jedoch wird das Setzen des Ausgangswertes in einer Queue zwischengespeichert. Wichtig: Die Verwendung dieser Funktion ist ausschließlich für den EXEC-Abschnitt (bei Bedarf) einzusetzen, z.B. wenn ein Ausgang sehr häufig in kurzer Zeit auf einen Wert gesetzt werden soll. Der Aufruf dieser Funktion ist zwar weniger performant, jedoch wird jeder Aufruf garantiert wirksam umgesetzt. Achtung: Diese Funktion verwendet die selbe Queue wie z.B. Telegramme, Visuelemente, etc. - d.h. bei einer sehr "hochfrequenten" Nutzung dieser Funktion, wird die Abarbeitung von Telegrammen etc. entsprechend verzögert erfolgen!
logic_getVars($id)
Alias: getLogicElementVarAll
Liefert ein Array mit den aktuellen Werten aller Variablen der LBS-Instanz $id zurück. Rückgabe: ARRAY[Variablen-ID]
logic_getVar($id,$varid)
Alias: getLogicElementVar
Liefert den aktuellen Wert einer Variable der LBS-Instanz $id zurück. $varid: Nr. der Variable (1..∞) Rückgabe: Variant oder NULL (Fehler)
logic_setVar($id,$varid,$value)
Alias: setLogicElementVar
Setzt eine Variable der LBS-Instanz $id auf einen Wert. $varid: Nr. der Variable (1..∞) $value: zu setzender Wert
logic_callExec(LBSID,$id)
Alias: callLogicFunctionExec
Startet ggf. das EXEC-Script der LBS-Instanz $id. LBSID: Platzhalter für die LBS-ID (nicht verändern!) Hinweis: Der LBS wartet nicht(!) auf die Ausführung des EXEC-Scripts.
logic_dbKeepalive() Diese Funktion dient ggf. zur Aufrechterhaltung der Datenbank-Verbindung (u.U. wichtig für EXEC-Logikbausteine). Hinweis: Einige der o.g. Funktionen greifen intern auf eine Datenbank zu. Die Datenbank-Engine trennt jedoch die Verbindung, sobald länger als 8 Stunden keinerlei Zugriff erfolgt - der Aufruf der o.g. Funktionen innerhalb eines EXEC-Scripts(!) wird dann u.U. scheitern! Es ist daher ggf. dafür zu sorgen, dass z.B. stündlich ein Datenbank-Zugriff erfolgt, um die Verbindung aufrecht zu erhalten. Die kann z.B. durch einen zyklischen Aufruf (z.B. alle 60 Minuten) dieser Funktion erfolgen. Wichtig: Die Verwendung dieser Funktion ist ggf. aussschließlich im EXEC-Abschnitt erforderlich - im LBS-Abschnitt sorgt die Logik-Engine bereits für die Aufrechterhaltung der Datenbank-Verbindung. In der Regel ist die Verwendung dieser Funktion jedoch nicht erforderlich: Eine (Endlos-)Schleife im EXEC-Abschnitt sollte stets in der Form "while (getSysInfo(1)>=1)" implementiert werden (siehe Beispiel "EXEC-Script als Dämon"***r-0-4), damit der Prozess beim Beenden von EDOMI kontrolliert beendet wird. Die Funktion "getSysInfo(1)" sorgt dabei bereits für eine Aufrechterhaltung der Datenbank-Verbindung.

Hilfsfunktionen

Funktion Erläuterung
convertHSVtoRGB($h,$s,$v) Wandelt $h/$s/$v in R/G/B um. $h/$s/$v: H/S/V-Werte (H=0..255, S=0..255, V=0..255) Rückgabe: ARRAY(FLOAT) oder FALSE (Fehler) Array[0..2]:
  • 0: Rot (0..255)
  • 1: Grün (0..255)
  • 2: Blau (0..255)
convertRGBtoHSV($r,$g,$b) Wandelt $r/$g/$b in H/S/V um. $r/$g/$b: R/G/B-Werte (R=0..255, G=0..255, B=0..255) Rückgabe: ARRAY(FLOAT) oder FALSE (Fehler) Array[0..2]:
  • 0: Hue (0..255)
  • 1: Saturation (0..255)
  • 2: Value (0..255)