Inhalt → Objekte → Aktionen

• Aktionen definieren | Aktions-Steuerung | System-Aktionen | Aktions-Bedingung | XML-Skripte | Beispiele | Beispiel 2 Bahnübergang
  • Kurzanleitung XML-Skripting
  • Text-Variablen
  • XML-Script-Beispiele | Virtuelle Rückmelder | Externe Taster und LEDs | Verkehrsampel | Rangieren

XML-Skripte können in Kombination mit der Aktion Ext. Programm starten benutzt werden.
Das primäre Ziel von XML-Skripten ist die Vereinfachung und die Reduzierung der Anzahl von Aktionen und Bedingungen.
Das für Skripting verwendete XML ist das gleiche wie im Rocrail plan.xml.

• UTF-8-kompatibler Editor, z.B. Notepad++ oder Gedit oder der Rocview-interne XML-Editor um eine XML-Datei auf dem Server zu editieren. (unten auf dieser Seite beschrieben)
• Der Windows-Notepad-Editor wird nicht unterstützt.
• Einige Programmier- und XML-Kenntnisse

• Die XmlScripts kurz sowie ohne lange Pausen (sleep) und lange Schleifen (loop) halten.
  Sonst blockiert es das aufrufende Objekt bei der Bearbeitung von Ereignissen und Befehlen, wenn es nicht als Asynchron definiert ist.
• Nicht versuchen, den Automatik-Modus zu überlisten; Satttdessen eine Funktions-Erweiterung (feature request) im Forum posten, wenn etwas Grundsätzliches vermisst wird.
• Objekt-Kennungen mit Leerzeichen werden nicht unterstützt; stattdessen Unterstriche verwenden.
• Variablen-/Funktions-Namen dürfen keine Steuerzeichen, wie + - * < > ^ ! = ? % / enthalten.

Leerzeichen in Pfad und Dateiname werden nicht unterstützt!

1. XmlScript erzeugen und in einer Datei speichern. (Siehe: Einfaches Beispiel)
2. Erzeugen einer "Ext. Programm starten"-Aktion.
3. Die XmlScript-Datei auswählen. (Wenn sich die Script-Datei im Arbeitsbereich-Ordner befindet, ist die Pfadangabe nicht erforderlich.)
4. Bereit, diese Aktion bei jedem Rocrail-Objekt zu verwenden.

Schaltet die Gleisspannung ein und startet den Automatik-Modus:

<xmlscript>
  <sys cmd="go"/>
  <auto cmd="on"/>
</xmlscript>

Das Erzeugen und Editieren von XmlScripten auf dem Server kann über den Aktionsdialog erfolgen:

Öffnen des XmlScript-Editors. Alternativ kann der Editor auch in der Übersicht durch Doppelklick auf eine Aktion geöffnet werden.	Nach Prüfen oder Speichern wurde ein Parser-Fehler1) erkannt.

Wenn das XmlScript auf dem Server noch nicht existiert, wird ein XmlScript-Skelett erzeugt:

<?xml version="1.0" encoding="UTF-8"?>
<xmlscript>
 
</xmlscript>

Wird zu "<xmlscript>" die Erweiterung "<desc="xxx">" angegeben (z. B. der Scriptname), so wird dieser auch im Trace aufgeführt. \ Also z.B:

<?xml version="1.0" encoding="UTF-8"?>
<xmlscript desc="Mein_Script.xml">
 
</xmlscript>

Prüft, ob das XML-Skript "Well Formed" ist. ²⁾

Fügt ausgewählte Anweisungen oder Befehle an der Cursor-Position ein.
Die [\n]-Optionen steuern die Line-Feeds (Zeilenvorschub-Zeichen) vor und nach der Anweisung.

Um diesen Editor zu verwenden, muss die Option "Typographische Interpunktion" deaktiviert sein, um das Erzeugen ungültiger XML's zu vermeiden:

Systemeinstellungen → Sprache & Region → Systemeinstellung "Tastatur" → Text

Mit dieser voreingestellten Option, werden doppelte Bindestriche (--), die in XML-Kommentaren verwendet werden, in einfache lange Bindestriche (—), sowie ("gerade") Anführungszeichen in typographische (“geschweift”) konvertiert.
Das macht das XmlScript ungültig.

Die foreach-Schleife wird für "tu dieses mit allem in dieser Tabelle" verwendet, optional mit einer Bedingung und/oder einem Status.
Die Schleife kann mit einer break- oder exit-Anweisung gestoppt werden.
Wenn die Bedingung und/oder der Status nicht passt, wird zum nächsten Objekt in der Tabelle gesprungen.

<xmlscript>
  <foreach table="lclist" condition="#var2%oid% < &time|#var1 < &time" alltrue="true">
    <fn fnchanged="3" f3="true"/>
    <vr id="var2%oid%" text="empty"/>
    <vr id="var2%oid%" value="0"/>
    <lc cmd="go"/>
    <sleep time="10"/>
  </foreach>
</xmlscript>

Dieses Skript wird die Lok-Tabelle iterieren³⁾, für jede Lok die Funktion 3 (F3) einschalten und das Start-Kommando (go) geben.
Die oid, die Kennung des aktuellen Objekts in der Liste, wird in der foreach-Schleife automatisch generiert.
Falls die Tabelle lclist ist, kann auch die Kurzkennung verwendet werden: %soid%".⁴⁾

<xmlscript>
  <foreach table="lclist" condition="%lcclass% # BA">
    <lc cmd="go"/>
  </foreach>
</xmlscript>

Diese foreach-Schleife startet alle Loks mit der Klasse BA.

<xmlscript>
<foreach table="lclist" state="co Test = on">
    <if state="lc %oid% = Block3|lc %oid% = Block2|lc %oid% = Block1" alltrue="false">
    <then>
     <lc cmd="go"/>
    </then>
   </if>
</foreach>
</xmlscript>

Startet jede Lok, die sich in Block 'Block3', 'Block2' oder 'Block1' befindet.

Die while-Anweisung ist eine Schleife und kann Bedingungen, Status und Klassen prüfen. Zumindest eines davon sollte definiert sein, sonst wird die while-Schleife nicht ausgeführt.
Solange die Anweisung wahr ist, werden die Befhle im while ausgeführt.

<xmlscript>
  <vr id="var1" value="0"/>
  <while condition="#var1 < 10" max="100">
    <vr id="var1" value="#var1 + 1"/>
    <continue condition="#var1 = 4" cmt="var1 is 4"/>
    <sys cmd="go"/>
  </while>
</xmlscript>

Wenn die while-Schleife endlos ist, wird sie gestoppt, wenn das max-Attribut erreicht wird, das auf 100 voreingestellt ist.

Die if-Anweisung wird für die Ablauf-Steuerung verwendet und kann Bedingungen, Status und Klassen prüfen.
Wenn die Anweisung wahr ist, werden die Befehle im then ausgeführt, wenn sie nicht wahr ist, werden die else-Befehle ausgeführt.
Das else ist optional.

<xmlscript>
  <if condition="#var1 < &time" state="sg sem3 = green" class="bk 4711 = AB" alltrue="true" connect="and">
    <then>
      <lc id="@loco" cmd="go"/>
      <tx id="booster1" format="var1 is #var1"/>
    </then>
    <else>
      <lc id="@loco" cmd="stop"/>  
      <lc id="@loco" cmd="classset" class="AB"/>  
      <bk id="4711" cmd="classdel" class="AB"/>  
      <bk id="4711" cmd="classadd" class="CD"/>  
    </else>
  </if>
</xmlscript>

Der Text-Inhalt der Variable loco enthält die Lok-Kennung.
Wenn die Lok-Kennung nicht existiert, wird nach einem Block mit dieser Kennung gesucht und im Falle das dieser existiert, wird die Lok-Kennung in dem Block verwendet.
Sowohl condition als auch state können in der if-Bedingung verwendet werden. Mindestens eines von beiden muss angegeben werden.

<xmlscript>
  <if state="st b1-b2 = locked|st b2-b3 = locked" alltrue="false">
    <then>
      <tx id="tx1" format="route is locked"/>
    </then>
    <else>
      <tx id="tx1" format="route not locked"/>
    </else>
  </if>
</xmlscript>

Text tx1 zeigt "route is locked" wenn Fahrstrasse "b1-b2" ODER Fahrstrasse"b2-b3" den Status locked hat.
Ist keine der Routen im Status locked, zeigt tx1 "route not locked".

Der Ganzzahlwert der Variablen wird verwendet, um den Fall mit dem gleichen Wert auszuwählen.
Wenn nichts passendes gefunden wird, wird der voreingestellte Wert verwendet, falls er definiert ist.

<xmlscript>
  <switch var="#var1">
    <case val="0">
      <sys cmd="go"/>
    </case>
    <case val="1">
      <auto cmd="on"/>
    </case>
    <default>
      <sys cmd="stop"/>
    </default>
  </switch>
</xmlscript>

Eine case-Anweisung kann mehrere Ganzzahlwerte in folgendem Format enthalten:

    <case val="0|1|5|8">

Einer der Werte muss passen.

<xmlscript>
  <switch var="%callerid%">
    <case val="loco1">
      <sys cmd="go"/>
    </case>
    <case val="but1">
      <sys cmd="reset"/>
    </case>
  </switch>
</xmlscript>

Hinweis: Eine switch-Anweisung hat nichts mit einem Rocrail-Weichen-Objekt zu tun. Es entspricht z.B. "select case" anderer Programmiersprachen.

Funktionen müssen auf der ersten Ebene des XMLScripts deklariert werden und eine Kennung (ID) haben.
Aufruf (call) mit der gewünschten ID: <call id="doeIets"/>⁵⁾
Mehrere Funktionen sind erlaubt.

<xmlscript>
  <function id="doeIets">
    <tx id="tx1" format="function doeIets"/>
  </function>
 
  <switch var="#var1">
    <case val="0">
      <sys cmd="go"/>
    </case>
    <default>
      <sys cmd="stop"/>
      <call id="doeIets"/>
    </default>
  </switch>
</xmlscript>

• Calls in Funktionen werden nicht unterstützt.

Zum Verlassen des XML-Skrips. cmt=“reason” kann für die Ablaufverfolgung (Tracing) angegeben werden.

<xmlscript>
  <if condition="">
    <then>
      <exit cmt="Test."/>
   </then>
  </if>
</xmlscript>

Beendet eine foreach-Schleife mit oder ohne Bedingung. cmt=“reason” kann für die Ablaufverfolgung (Tracing) angegeben werden.
Diese Anweisung hat keinen Effekt, wenn sie nicht innerhalb einer foreach-Schleife erfolgt.

<xmlscript>
  <foreach table="lclist">
    <if condition="">
      <then>
        <break cmt="Test."/>
     </then>
    </if>
  </foreach>
</xmlscript>

XmlScript-Traces werden in Rocview in grüner Farbe angezeigt.

<xmlscript>
  <trace text="Hi there! I'm %callerid%. :)"/>
</xmlscript>

Eine Pausen-Zeit in ms.

<xmlscript>
  <foreach table="lclist">
    <if condition="">
      <then>
        <sleep time="100"/>
     </then>
    </if>
  </foreach>
</xmlscript>

Ruft ein anderes XML-Skript mit file=“script.xml” und mit Funktion id="functionName" auf.

<xmlscript>
  <sub file="lib1.xml" id="doeIets"/>
</xmlscript>

Wenn die Funktions-ID auf Unterstrich, id="_", eingestellt wird, wird das gesamte XmlScript außer den Funktions-Definitionen ausgeführt.⁶⁾
Wenn keine Funktions-ID eingestellt ist, wird die %oid% verwendet, um eine passende Funktion zu finden.

Bibliotheks-Beispiel lib1.xml:

<xmlscript>
  <function id="doeIets">
    <sys cmd="stop"/>
  </function>
</xmlscript>

Die Funktions-ID muss zum Aufruf von Funktionen aus einer XmlScript-Bibliotheks-Datei verwendet werden.
Sehr hilfreich, wenn mehrere XmlScripte sich gemeinsam Funktionen teilen.

Mit der query-Anweisung (Abfrage) kann eine Variable verwendet werden, um das Attribut Text oder Integer-Wert eines bestimmten Objekts zu erhalten.

  <query vr="var1" table="waybilllist" id="%oid%" get="cartype"/>

Nach dem query kann die Variable für Vergleiche von Text und/oder Zahlen verwendet werden. Normaler Text hat einen Null-Wert als Ergebnis.

Um einen Wert von einem Sub-Knoten zu erhalten:

  <query vr="var1" table="sclist" id="%oid%" sub="scentry" subidx="3" get="text"/>

Anstelle von subidx kann auch subid verwendet werden, wenn der Sub-Knoten eine Kennung (ID) hat.

Die Lok-Kennung, locid, wird vom Block cb4 in Variable lcid abgerufen.
Dr Funktions-Befehl erfordert eine Lok-Kennung, die vom Textinhalt der Variablen @lcid bereitgestellt wird. .

<xmlscript>
  <query vr="lcid" table="bklist" id="cb4" get="locid"/>
  <fn id="@lcid" fnchanged="3" f3="true"/>
</xmlscript>

Mit der set-Anweisung (Einstellen)kann eine Variable verwendet werden, um das Attribut Text oder Integer-Wert eines bestimmten Objekts zu setzen.

  <set vr="var1" table="waybilllist" id="%oid%" set="cartype" setint="false"/>

Um einen Wert eines Sub-Knotens einzustellen:

  <set vr="var1" table="sclist" id="%oid%" sub="scentry" subidx="3" set="text" setint="false"/>

Anstelle von subidx kann auch subid verwendet werden, wenn der Sub-Knoten eine Kennung (ID) hat.

Mit dem "clock get"-Befehl:

  <clock cmd="get"/> 

werden drei Variable aktualisiert.

Der systemtick läuft bei 4294967295 (119,3 Stunden) auf 32bit und 18446744073709551615 auf 64bit-Systemen über.

Weitere Bedingungen müssen mit einem Pipe-Zeichen (senkrechter Strich: | ) ohne zusätzliche Leerzeichen getrennt werden.

condition="#var2%oid% < &time|#var1 < &time"

Für mögliche Variable siehe: Text-Variable

Alltrue ist standardmäßig 'true', wenn es nicht angegeben wird.
Wenn alltrue auf 'false' gesetzt wird, muss nur eine der Bedingungen "condition"/"state"/"class" wahr sein.

Falls die if-Anweisungen "condition", "status" und/oder "class" enthalten, sind diese standardmäßig mit and verknüpft.
Wenn nur einer der Werte wahr sein muss, kann das "connect"-Attribut auf or gesetzt werden.

Die Werte müssen mit Leerzeichen getrennt werden.

state="st b1-b2 = locked|st b2-b3 = locked"

Objekt-Kennungen dürfen keine Leerzeichen enthalten! Stattdessen z.B. Unterstriche oder Punkte verwenden.

Wenn ein Befehls-Attribut-Wert mit einem Fragezeichen '?' beginnt, wird er durch den Attribut-Wert des darauf bezogenen Objekts ersetzt.
Beispiel:

  <lc id="loco1" cmd="useschedule" scheduleid="?startupscid"/>

Der Wert "?startupscid" wird ersetzt durch startupscid von loco1:

20160422.085709.015 r9999I tid0x8BA OXmlScri 0571 execute [lc] id[loco1] cmd[useschedule] oid[] callerid[wefiu]
20160422.085709.016 r9999I tid0x8BA OXmlScri 0521 replaced attribute value: scheduleid="?startupscid" with "1-2"
20160422.085709.017 r9999a tid0x8BA OLoc     3644 <lc id="loco1" cmd="useschedule" scheduleid="1-2"/>

Die Objekt-Kennungen können Variable enthalten.
Siehe für mögliche Variable: Text-Variable

<xmlscript>
  <tx id="%callerid%-%substate%" format="%lcimg%"/>
</xmlscript>

Mit dem Format-Attribut ist es möglich, Variablen-Inhalt auf die gleiche Art zu formatieren, wie printf.

<xmlscript>
  <vr id="var1" value="3" text="Hello"/>
  <vr id="var2" value="5" text="RocrailFans"/>
  <vr id="var3" format="%s%02d:%04d%s" text="@var1 #var1 #var2 @var2"/>
  <trace text="@var3"/>
</xmlscript>

Ausgabe mit dem Format-Attribut sieht so aus:

Hello03:0005RocrailFans

Ausgabe ohne das Format-Attribut sieht so aus:

Hello 3 5 RocrailFans

Um das XML-Skript auf Konformität zu überprüfen, kann es mit einem Web-Browser geöffnet werden.
Einige Zeichen müssen dafür durch Escape-Codes ersetzt werden:

Folgendes ist nicht regelkonform, wird aber vom Rocrail-XML-Parser akzeptiert:

condition="#var2%oid% < &time"

Um dieses Beispiel mit einem Web-Browser zu überprüfen muss es wie folgt abgeändert werden:

condition="#var2%oid% < &time"

Das geänderte Beispiel ist für den Rocrail-XML-Parser ebenfalls gültig.