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: Innerhalb eines EXEC-Scripts liefert diese Funktion u.U. nicht die aktuellen Werte, da das EXEC-Script asynchron (unabhängig von der Logik-Engine) ausgeführt wird. So ist es z.B. möglich, dass im EXEC-Script die Eingangsdaten abgerufen werden, diese jedoch im gleichen Moment von der Logik-Engine aktualisert wurden. Für ein zuverlässiges Abrufen im Kontext eines EXEC-Scripts ist daher eine Queue zur Zwischenspeicherung nutzbar: logic_setInputsQueued() bzw. logic_getInputsQueued() (s.u.)
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_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-Script führt bei einem sehr häufigen Aufruf in kurzer Zeit u.U. dazu, dass einzelne Aufrufe unwirksam bleiben (das EXEC-Script wird asynchron ausgeführt). Ggf. ist daher die Funktion logic_setOutputQueued() im EXEC-Script zu verwenden (s.u.).
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_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 wird nicht (zyklisch) ausgeführt
  • 1: LBS wird (zyklisch) ausgeführt
Funktionen für Logikbausteine mit EXEC-Script
Wichtig: Einige der folgenden Funktionen sind ausschließlich für die Verwendung innerhalb eines EXEC-Scripts geeignet.
logic_callExec(LBSID,$id[,$multitasking])
Alias: callLogicFunctionExec
Startet ggf. das EXEC-Script der LBS-Instanz $id. LBSID: Platzhalter für die LBS-ID (nicht verändern!) $multitasking (optional):
  • true: das EXEC-Script darf ggf. mehrfach gestartet werden
  • false: das EXEC-Script wird nur einmal gestartet (alle Aufrufe der Funktion werden ignoriert, solange das EXEC-Script ausgeführt wird)
  • Hinweis: Wird dieser Parameter nicht angegeben, entspricht dies dem Wert "false".
Hinweis: Der LBS wartet nicht auf die Ausführung des EXEC-Scripts: Das EXEC-Script wird im Hintergrund gestartet und die Abarbeitung des LBS-Abschnitts wird unmittelbar fortgesetzt.
logic_getStateExec($id) Liefert den aktuellen Status des EXEC-Scripts der LBS-Instanz $id zurück. Rückgabe: INTEGER (im Fehlerfall wird NULL zurückgegeben):
  • 0: EXEC-Script wird nicht ausgeführt (bzw. wurde beendet)
  • 1: EXEC-Script wird gerade gestartet (i.d.R. nur für wenige Millisekunden)
  • 2: EXEC-Script wird ausgeführt
Hinweis: Wird ein EXEC-Script mehrfach gestartet (s.o.), wird stets der Zustand des zuletzt gestarteten (oder beendeten) EXEC-Scripts zurückgegeben. Bei einem fehlerhaften EXEC-Script wird der Status zunächst 1 sein, anschließend 2 und unmittelbar danach 0 (da das Script aufgrund eines Fehlers beendet wurde).
logic_setInputsQueued($id,$E) Speichert alle aktuellen Eingangsdaten der LBS-Instanz $id in einer Queue, um eine asynchrone Verarbeitung der Eingangsdaten in einem EXEC-Script zu ermöglichen. $E: Array der Eingangsdaten, i.d.R. das zurückgegebene Array der Funktion logic_getInputs() Hinweis: Die Funktion generiert die Eingangsdaten nicht selbst, sondern erwartet das von der Funktion logic_getInputs() zurückgegebene Array als Parameter $E. Achtung: Bei der Verwendung dieser Funktion ist darauf zu achten, dass die Queue regelmäßig abgefragt bzw. geleert wird (s.u.). Wichtig: Diese Funktion sollte ausschließlich im LBS-Abschnitt verwendet werden.
logic_getInputsQueued($id[,$fallback]) Gibt alle Eingangsdaten der LBS-Instanz $id aus der Queue zurück und entfernt diese Eingangsdaten aus der Queue. Es werden stets die "ältesten" Eingangsdaten aus der Queue zurückgegeben. Die aktuellsten verfügbaren Daten werden zuletzt zurückgegeben. $fallback (optional):
  • true: Sind keine Eingangsdaten in der Queue verfügbar, verhält sich die Funktion wie logic_getInputs() - d.h. es werden die aktuellen Eingangsdaten (asynchron) zurückgegeben.
  • false: Sind keine Eingangsdaten in der Queue verfügbar, gibt die Funktion "false" zurück.
  • Hinweis: Wird dieser Parameter nicht angegeben, entspricht dies dem Wert "false".
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
Achtung: Nach der Rückgabe der Eingangsdaten aus der Queue werden die entsprechenden Daten aus der Queue entfernt. Ein erneuter Aufruf liefert bereits die nächsten verfügbaren Eingangsdaten aus der Queue zurück. Diese Funktion sollte daher i.d.R. nur einmal pro Schleifenzyklus im EXEC-Script aufgerufen werden. Wichtig: Diese Funktion sollte ausschließlich in einem EXEC-Script verwendet werden.
logic_deleteInputsQueued($id) Leert die Queue der LBS-Instanz $id, sämtliche Eingangsdaten werden aus der Queue entfernt. Hinweis: Beim Beenden des EXEC-Scripts wird die Queue automatisch geleert.
logic_setOutputQueued($id,$ausgang,$value) Wie logic_setOutput(), jedoch wird das Setzen des Ausgangswertes in einer Queue zwischengespeichert. Wenn ein Ausgang sehr häufig in kurzer Zeit auf einen Wert gesetzt werden soll, kann diese Funktion in einem EXEC-Script verwendet werden. Der Aufruf dieser Funktion ist zwar weniger performant, jedoch wird jeder Aufruf garantiert wirksam umgesetzt. Hinweis: 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! Wichtig: Diese Funktion darf ausschließlich in einem EXEC-Script verwendet werden.
logic_getEdomiState() Diese Funktion ermittelt, ob EDOMI betriebsbereit ist oder z.B. gerade beendet wird. Rückgabe: INTEGER:
  • 1: EDOMI ist betriebsbereit
  • 0: EDOMI ist nicht betriebsbereit ist oder wird z.B. gerade beendet
Wichtig: Diese Funktion sollte ausschließlich in einem EXEC-Script verwendet werden, z.B. um das EXEC-Script gezielt zu beenden.
logic_dbKeepalive() Diese Funktion dient ggf. zur Aufrechterhaltung der Datenbank-Verbindung (u.U. wichtig für EXEC-Scripte). 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. Hinweis: In der Regel ist die Verwendung dieser Funktion nicht erforderlich: Eine (Endlos-)Schleife im EXEC-Script sollte stets in der Form "while (logic_getEdomiState()==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 "logic_getEdomiState()" sorgt dabei bereits für eine Aufrechterhaltung der Datenbank-Verbindung. Wichtig: Diese Funktion darf ausschließlich in einem EXEC-Script verwendet werden.

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[0..2] (FLOAT) oder FALSE (Fehler):
  • 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[0..2] (FLOAT) oder FALSE (Fehler):
  • 0: Hue (0..255)
  • 1: Saturation (0..255)
  • 2: Value (0..255)