XML Scripting

Content → Objects → Actions

• Action Setup | Action Control | System Actions | Action Condition | XML Scripting | Example
  • Quick Start Guide XML Scripting
  • Text variables
  • Examples:
    • General | Virtual Sensors | External keyboard | Traffic light (DE) | Shunting (DE)

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.

• UTF-8 Editor, for example Notepad++ or Gedit or the internal xml-editor of rocview to edit an XML file on the server as described below on this page.
• Windows Notepad editor is not supported.
• Some programming and XML knowledge.

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

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.

Switch on the track power and start the automatic mode:

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

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>

Check if the XML is “Well Formed”. ¹⁾

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

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.

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%”.²⁾

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

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.

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

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

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.

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

A case may have multiple integer values in the following format:

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

One of the values must match.

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

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>

• Calls in functions are not supported.

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

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

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>

XmlScript traces will be in green color in Rocview.

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

A sleep time in ms.

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

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

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.

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.

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

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

In case the if statements contains conditions, states and or classes, those are connected by default with and.
If only one of the must be true, the connect attribute can be set to or.

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.

Note:

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

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

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

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

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

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

This is also valid for the Rocrail XML Parser.