Inhalt → Objekte → Aktionen

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

XMLScript ist nur mit gültigem Unterstützungs-Schlüssel verfügbar.

1. Standard-Rocrail-Funktionen nicht durch XMLScript ersetzen.
2. Nicht versuchen, die Rocrail-Automatik durch den Wolf zu drehen.
3. Die Scripte werden asynchron augeführt und erfordern Kenntnisse in Multithreading-Programmierung.
4. Wenn unerwartetes Verhalten auftritt: Die XMLScript-Aktionen deaktivieren.
5. Wenn Unsicherheit besteht, kein XMLScript verwenden oder im Forum um Hilfe buitten.
6. Nicht die gleichen Variablen in mehreren XMLScripten verwenden, denn die Werte könnten neu gesetzt werden,
   was zu unerwarteten Ergebnissen, einschließlich Serverabstürzen führen kann.
   

H A F T U N G S A U S S C H L U S S

Es sollten immer erst die grundlegenden Rocrail-Funktionen bekannt sein, bevor mit XMLScript das Rad neu erfunden wird.

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

Im linken Feld eingegebener Text wird im Script gesucht und markiert.

Bei aktivierter Option wird der gefundene Text durch den im rechten Feld eingegeben Text ersetzt.

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.

Auf Aufruf-Parameter kann durch Variablen mit der Benamung "%param1%…%paramN%" zugegriffen werden.
Siehe: Aktions-Steuerung Parameter
Beispiel-Schnipsel:

<xmlscript>
  <if condition="%frombkid% # %param1%">
    <then>
    </then>
  </if>
</xmlscript>

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 10 voreingestellt ist.
Höhere Werte als 100 werden auf 100 begrenzt, um Serverblockierungen und Unfälle automatisch fahrender Lokomotiven zu vermeiden.

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.
Auf Parameter kann durch %subparam1%…%subparamN% zugegriffen werden.

<xmlscript>
  <function id="doeIets" param="test1,test2">
    <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.
• Max. Aufruf Tiefe ist 5.

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- und while-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" param="test1,test2"/>
</xmlscript>

Wenn die Funktions-ID auf Unterstrich, id="_", eingestellt wird, wird das gesamte XML-Script außer den Funktions-Definitionen ausgeführt.⁶⁾
Wenn keine Funktions-ID eingestellt ist, wird die %oid% verwendet, um eine passende Funktion zu finden.
Auf Parameter kann durch %subparam1%…%subparamN% zugegriffen werden.

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.
Ein query bietet nur Objekt-Eigenschaften, aber keine Laufzeit-Informationen.

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

Query-Variable müssen XMLScript-eindeutig sein, um unerwartete Ergebnisse zu vermeiden.

Die Lok-Kennung, locid, wird vom Block cb4 in Variable lcid abgerufen.
Der 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, abhängig von setint 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>

siehe: https://wiki.rocrail.net/doku.php?id=text-gen-de#variablen

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

Innerhalb oben beschriebener Grenzen können Variablen-Namen frei gewählt werden; aber es kann vorkommen, daß zwei gleichnamige Variablen in zwei unterschiedlichen Skripten, die zur gleichen Zeit aufgerufen werden, Konflikte hervorrufen, Solche Fälle kann man vermeiden, indem man die Variablen-Namen je Script mit einem eigenen Präfix versieht:

• der ursprüngliche Variablen-Name "vr_idx"
  
• wird im Script "MeinScriptNummer1.xml" geändert zu "vr_MSN1_idx" und
  
• wird im Script "MeinScriptNummer2.xml" geändert zu "vr_MSN2_idx" und
  

Um eine Variable von Laufzeit zu Laufzeit in Rocrail zu speichern, muss diese Variable als „generiert“ "false" definiert werden:

<xmlscript>
  <vr id="vr_MSN3_zuletztBenutzteLokomotive" value="0" text="br89" generated="false"/>
  <vr id="vr_MSN3_tmp" value="0" text=""/>
</xmlscript>

Die Variable "vr_MSN3_zuletztBenutzteLokomotive" wird in der Rocrail Plan-Datei gespeichert.
Die Variable "vr_MSN3_tmp" wird nicht in der Rocrail Plan-Datei gespeichert, sondern mit dem Beenden von Rocrail gelöscht.

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.