XML-Skripte

Einführung

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.


Voraussetzungen

  • UTF-8-kompatibler Editor, zum Beispiel Notepad++ oder Gedit. (Der Windows-Notepad-Editor wird nicht unterstützt.)
  • Einige Programmier- und XML-Kenntnisse


Empfehlung

  • 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.


Einstellung

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.


Einfaches Beispiel

Schaltet die Gleisspannung ein und startet den Automatik-Modus:

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


Auf dem Server editieren

Um XmlScripte auf dem Server zu erzeugen und editieren kann der Aktionsdialog verwendet werden:

Öffnen des Editors. Nach Prüfen oder Speichern wurde ein Parser-Fehler1) erkannt.

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

<?xml version="1.0" encoding="UTF-8"?>
<xmlscript>
 
</xmlscript>
Der XmlScript-Editor kann auch durch Doppelklick auf einen Eintrag in der Übersicht geöffnet werden.


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

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

Prüfen

Prüft, ob das XML-Skript “Well Formed” ist. 2)

Einfügen


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.

macOS

:!: Um diesen Editor zu verwenden, muss die Option “Typographische Interpunktiondeaktiviert 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.

Anweisungen

foreach

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 iterieren3), 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%”.4)

<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.


while

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.


if

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">
    <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-b2ODER Fahrstrasse”b2-b3” den Status locked hat.
Ist keine der Routen im Status locked, zeigt tx1route not locked”.

switch

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.

Zahlen-Beispiel

<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>

Zeichenketten-Beispiel

<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.

call

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”/>5)
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>

Einschränkungen

  • Calls in Funktionen werden nicht unterstützt.


exit

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>


break

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>


trace

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

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


sleep

Eine Pausen-Zeit in ms.

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


sub

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.6)
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.


query

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.

set

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.

Format von Bedingungen

Wert Komparator Wert

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

System-Variablen
&time Modell-Zeit in Sekunden


Komparatoren
= gleich; Zahlen
! nicht gleich; Zahlen
# gleich; Text
> größer als; Zahlen
< kleiner als; Zahlen

alltrue

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

Format von Status/Klassen

Objekt-Typ Objekt-Kennung ohne Leerzeichen Komparator Status-/Klassen-Wert

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.

Komparatoren
= Status: gleich
! Status: nicht gleich


Status-Objekte

Objekt-Name Objekt-Typ Status-Werte Hinweis
Signal sg red, green, yellow, white, blank, aspect number
Weiche sw left, right, straight, turnout, locked, free, unlocked, open, closed
Rückmelder fb true, false, on, off on + off sind alternativ: true = on; false = off
Ausgang co on, off, active
Block bk free, !free, occupied, closed, open, reserved
Fahrstraße st free, locked, unlocked, closed
System sys go, stop
Automode auto on, off
Lokomotive lc fwd, rev, +, -, min, mid, cruise, max, block, ”blockID”,
steam, diesel, electric, automobile, idle, wait, auto, f0…f28
block ist wahr, wenn die Lok in einem Block ist
blockID” ist wahr, wenn die Lok in einem Block mit ”blockID” ist
Wagen car empty, loaded, maintenance, cartype, waybill, ”blockID Siehe Lokomotive
Frachtschein waybill waiting, shipping, delivered, ”destinationID”, ”originID


Klassen-Objekte

Objekt-Name Objekt-Typ
Block bk
Lok lc
Fahrstraße st


Befehle

Objekt-Name Objekt-Typ Befehle Status Hinweise Beispiel
Lok lc Alle http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#lc Das Block-Kennungs-Attribut (bkid) kann verwendet werden, um die Lok-Kennung von einem Block zu erhalten.
Befehl "regularreset" ist mit "softreset" gleich, aber es entfernt auch den zugewiesenen Fahrplan.
Funktion fn Alle und fndesc, fncmd Das Funktionsänderungs-Attribut (fnchanged) oder die Finktons-Beschreibung (fndesc) signalisieren, welche Funktion geändert wurde: f0…f28 (true/false)
Der Funktions-Befehl (fncmd) kann für on/off/flip verwendet werden.
<fn id="loco1" fndesc="Horn" fncmd="flip"/>
Weiche sw Alle <sw id=“W5” cmd=“close”>
Signal sg Alle
Zubehör-Gruppe accgroup on, off, flip
Ausgang co Alle
Gleisspannung powercmd on, off Die ID ist die Booster-Kennung. Wenn leer, gilt der Befehl für alle Booster
Block bk Alle, reservieren open, closed Im Fall des Reservieren-Befehl Lok-Kennung (lcid) verwenden. <bk id="x" state="closed"/>
Rückmelder fb Alle, on, off, flip
Fahrstraße st go, lock, free, classset, classadd, classdel Die Befehle “lock” und “free” benötigen das zusätzliche Attribut locid=“myLoco”. <st id="x" state="closed"/>
Text tx showon, showoff Update-Ereignis durch Format-Attribut.
Die optionalen bkid und lcid können auch im Befehl verwendet werden.
<tx id="tx1" format="the loco id is %lcid%"/>
Variable vr random, start, stop
start, length (for substring)
Setzen durch Attribute: value=“0” (Wert) text=“zero”; (Wert-Text).
Um sie nur temporär anzulegen generated="true" setzen.
<vr id="var1" text="Rocrail"/>
<vr id="var2" text="@var1-XML-Scripting." tokeniser="-"/>
<vr id="var2" text="@var1" start="1" length="3"/>
Aktionskontrolle actionctrl Die Kennung in der Aktionskontrolle ist eine Referenz auf ein existierendes Objekt. Bedingungs-Kind-Knoten können hinzugefügt werden.
Fahrdienstleiter operator emptycar, loadcar, addcar, leavecar. Im Wagen-Kennungs-Attribut (carids) muss eine kommaseparierte Liste von Wagen-Kennungen spezifiziert werden.
System sys Alle http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#sys
Automat auto Alle http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#auto
Wagen car empty, loaded, maintenance, assignwaybill, resetwaybill, loco & function empty, loaded, maintenance, cartype, location <car id="test" cmd="assignwaybill" waybill="testbill"/>
Aufstellblock sb Alle http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#sb
Fiddle Yard seltab Alle http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#seltab
Ortschaft location Alle http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#location <location id="Blaak" cmd="info" svalue="tx1"/>
Uhr clock Alle http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#clock
Drehscheibe tt Alle http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#tt
Extern ext Alle http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#ext


Attribut-Werte

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"/>


Objekt-Kennungen

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

Beispiel

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


Tipps

Regelkonformes XML

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:

Zeichen Code
< &lt;
& &amp;
> &gt;

Beispiel

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% &lt; &amp;time"

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

1) Die Farbmarkierung erscheint erst nach Schließen der Fehler-Meldung
2) Ein XML-Dokument mit korrekter Syntax wird “Well Formed” genannt.
3) den gleichen Vorgang für jede in der Lok-Tabelle gefundene Lok wiederholen
4) 10073+
5) “doeIets” = niederländisch “mach Was”
6) 12.545+

Personal Tools