XML Scripting

Introduction

XML scripting can be used in combination with run ext. program action.
Its primary goal is to simplify and to reduce the number of actions and conditions.
The XML used for the scripting is the same as used in the Rocrail plan.xml.


Requirements

  • UTF-8 Editor, for example Notepad++ or Gedit. (Windows Notepad editor is not supported.)
  • Some programming and XML knowledge.


Recommendation

  • Keep the XmlScripts short and without long sleeps and long loops; It will block the calling object from processing events and commands if it is not defined as Asynchrone.
  • Do not try to outsmart the automatic mode; Post a feature request in the forum instead if something basic is missing.
  • Object IDs with blanks are not supported; Use underscores instead.


Setup

Blanks in path or filename are not supported!

  1. Create a XmlScript and save it in a file. (See: Simple Example)
  2. Create a “run ext. program” action.
  3. Select the XmlScript file. (If the script file is in the workspace directory a path is not necessary.)
  4. Ready to use this action on any Rocrail object.


Simple Example

Switch on the track power and start the automatic mode:

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


Edit on the Server

To create and edit XmlScripts on the Server the Action Dialog can be used:

Open the editor. Parser error detected after validate or save.

If the XmlScript does not already exist on the Server a XmlScript skeleton will be created:

<?xml version="1.0" encoding="UTF-8"?>
<xmlscript>
 
</xmlscript>
The XmlScript editor can also be opened by a double click on the Index.


If ”<xmlscript>” is amended with the description ”<desc=“xxx”>” (e. g. script name), the description will be displayed in the trace. E. g.

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

Validate

Check if the XML is “Well Formed”. 1)

Insert


Insert the selected statement or command at the cursor position.
The [\n] checkboxes control the line feeds before and after the statement.


macOS

:!: To use this editor the “Use smart quotes and dashes” option must be disabled to avoid creating invalid XML:

System preferences → Language & Region → Keyboard preferences → Text

With this option enabled, which is by default, it will automatically convert double hyphens (--), used in XML comments, into em dashes (—), and ("straight") quotation marks into typographical (“curly”) ones.
This will make the XmlScript invalid.


Statements

foreach

The foreach loop is used for “do this to everything in this table” with optional a condition and/or state.
The loop can be stopped with a break or exit statement.
If the condition and/or state does not match it skips to the next object in this table.

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

This script will iterate the loco table and will switch function 3 on and give the go command for every loco.
The oid, the ID of the current Object in the list, value is automatically generated in the loop.
In case the table is lclist the short ID can also be used: %soid%”.2)

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

This foreach starts every loco with the class 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>

Start every loco which resides in block 'Block3', 'Block2' or 'Block1'.


while

The while statement is a loop and can check condition, states and class. At least one of them should be defined otherwise the while loop will not be executed.
As long as the statement is true the commands in the while will be executed.

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

If the while loop is endless it will be stopped by the max attribute which is default 100.


if

The if statement is used for flow control and can check condition, states and class.
If the statement is true the commands in the then will be executed, if its not true the else commands will be executed.
The else is 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>

The text value of the variable loco contains the loco ID.
If the loco ID does not exist a block will be searched by that ID and in case it exist the loco ID in the block will be used.
Both condition and state may be used in the if statement. At least one of them must be specified.

<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 is set to “route is locked” if Route “b1-b2OR Route “b2-b3” is in state locked.
If this Routes are not in state locked, tx1 is set to “route not locked”.


switch

The integer value of the switch var is used to select the case with the same value.
If no match was found the default will be used in case its defined.

Number example

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

String example

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

Note: A switch statement has nothing todo with a Rocrail Switch-Object.


call

Functions must be declared in the first level of the XMLScript and must have set an ID.
Call the function with the wanted ID: <call id=“doeIets”/>
Multiple functions are allowed.

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

Restrictions

  • Calls in functions are not supported.


exit

Exit the XmlScript. The cmt=“reason” can be used for tracing

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


break

Ends a foreach loop with or without condition. The cmt=“reason” can be used for tracing.
This statement has no effect if its not within a foreach loop.

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


trace

XmlScript traces will be in green color in Rocview.

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


sleep

A sleep time in ms.

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


sub

Call another XmlScript with file=“script.xml” and function id=“functionName”

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

If the function ID is set to underscore, id=“_”, then the whole XMLScript will be executed excluding function definitions.3)
If no function ID is set the %oid% will be used to find a fitting function.

Library example lib1.xml:

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

The function ID must be used to call functions from a XmlScript library file.
Most helpfull if more then one XmlScript share common functions.

query

With the query statement a variable can be used to get the attribute text and integer value of a certain object.

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

After the query the variable can be use for comparing text and/or numbers. Normal text will have a zero value result.

To get a value from a sub node:

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

Instead of the subidx the subid can also be used if the sub node has an ID.

set

With the set statement a variable can be used to set the attribute text or integer value of a certain object.

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


To set a value of a sub node:

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

Instead of the subidx the subid can also be used if the sub node has an ID.

Condition format

value comparator value

Additional conditions must be separated with a pipe character without any extra blank:

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

See for possible variables: Text variables

System variables
&time Model time in seconds


Comparators
= equal number
! not equal number
# equal text
> greater then number
< smaller then number

alltrue

Alltrue is default true if its not set.
If alltrue is set to false only one of the conditions must be true.

State/Class format

Object type Object ID without blanks Comparator State/Class value

The values must be separated with blanks.
Additional states must be separated with a pipe character without any extra blank:

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

:!: Object IDs with blanks are not supported; Use underscores or dots instead.

Comparators
= equal state
! not equal state


State Objects

Object Name Object type State values Remark
Signal sg red, green, yellow, white, blank, aspect number
Switch sw left, right, straight, turnout, locked, free, unlocked
Sensor fb true, false, on, off true = on, false = off
Output co on, off, active
Block bk free, occupied, closed, open, reserved
Route st free, locked, unlocked, closed
System sys go, stop
Automode auto on, off
Locomotive lc fwd, rev, +, -, min, mid, cruise, max, block, ”blockID”, steam, diesel, electric, automobile, idle, wait, auto, f0…f28 block is true if the loco is in a block
blockID” is true if the loco is in a block with this ”blockID
Car car empty, loaded, maintenance, cartype, waybill, ”blockID See locomotive
Waybill waybill waiting, shipping, delivered, ”destinationID”, ”originID

Class Objects

Object Name Object type
Block bk
Loco lc
Route st


Commands

Note:

  • With “Commands All” all the object commands specified in the Rocrail plan.xml are supported.
  • The special implemented action commands are listed separately.


Object Name Object type Commands States Remark Example
Loco lc All http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#lc The bkid attribute can be used to get a loco ID from a block.
Command "regularreset" is the same as "softreset" but removes the assigned schedule too.
Function fn All and fndesc, fncmd The fnchanged or the fndesc, function description, attribute signals which function has been changed: f0…f28 (true/false).
The fncmd can be used for on/off/flip.
<fn id="loco1" fndesc="Horn" fncmd="flip"/>
Switch sw All
Signal sg All
Accessory Group accgroup on, off, flip
Output co All
Power powercmd on, off The id is the boosterID. If left empty the command is for all boosters
Block bk All, reserve open, closed Use lcid in case of reserve command. <bk id="x" state="closed"/>
Sensor fb All, on, off, flip
Route st go, lock, free, classset, classadd, classdel open, closed The lock and free command needs the extra attribute locid=“myLoco”. <st id="x" state="closed"/>
Text tx showon, showoff Update event by format attribute.
The optional bkid and lcid may be used in the command also.
<tx id="tx1" format="the loco id is %lcid%"/>
Variable vr random, start, stop
start, length (for substring)
Set by attribute: value="0" text="zero"
To make it temporary set generated="true"
<vr id="var1" text="Rocrail"/>
<vr id="var2" text="@var1-XML-Scripting." tokeniser="-"/>
<vr id="var2" text="@var1" start="1" length="3"/>
Action control actionctrl The id in the actionctrl is a reference to an existing action. Condition child nodes may be added.
Operator operator emptycar, loadcar, addcar, leavecar In the carids attribute a list of cars must be specified.
System sys All http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#sys
Automat auto All http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#auto
Car car empty, loaded, maintenance, assignwaybill, resetwaybill, loco & function empty, loaded, maintenance, cartype, location <car id="test" cmd="assignwaybill" waybill="testbill"/>
Staging block sb All http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#sb
Fiddle Yard seltab All http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#seltab
Location location All http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#location <location id="Blaak" cmd="info" svalue="tx1"/>
Clock clock All http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#clock
Turntable tt All http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#tt
External ext All http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#ext

Attribute values

If a command attribute value starts with a question mark it will be replaced with attribute value of the referenced object.
Example:

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

The "?startupscid" value will be replaced with the startupscid of 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"/>


Object IDs

The object IDs may contain variables.
See for possible variables: Text variables

Example

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


Tips

XML Well Formed

To check the XMLScript if its well formed it can be opened in a WEB Browser.
Some characters must be escaped:

Char Escape
< &lt;
& &amp;
> &gt;

Example

This is not well formed but accepted by the Rocrail XML Parser:

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

To check it with a WEB Browser it must be changed in:

condition="#var2%oid% &lt; &amp;time"

This is also valid for the Rocrail XML Parser.


1) An XML document with correct syntax is called “Well Formed”.
2) 10073+
3) 12.545+

Personal Tools