XMLScript

Content → Objects → Actions

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

XMLScript can only be used if a valid Support Key is provided.

1. Do not replace standard Rocrail functions with XMLScript.
2. Do not try to mangle the automatic Rocrail engine.
3. The scripts are executed asynchrone, and needs multithreading programming know how.
4. If encountering unexpected behaviour: Turn off XMLScript actions.
5. If uncertain: Do not use XMLScript, or ask for help in the Forum.
6. Do not use the same variables in multiple XMLScripts, which will be set to new values, to avoid unexpected results including Server crashes.

D I S C L A I M E R

Check basic Rocrail functionality before inventing the wheel again with XMLScript.

XMLScript 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 XMLScript 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 XMLScript 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.
• Variable/function names may not contain operation characters like "+-*<>^!=?%/".

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

Calling parameters can be accessed by variables with the naming of "%param1%…%paramN%".
See: ActionControl Parameter
Snippet:

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

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 10.
Higher max values than 100 will be truncated to 100 to avoid server blocking and crashing automatically running locomotives.

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>

Multiple case values are deprecated, and are strongly discourage to use.
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.
Parameters can be accessed by %subparam1%…%subparamN%.

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

• Calls in functions are not supported.
• Max. call depth is 5.

Exit the XMLScript. The cmt="reason" can be used for tracing

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

Ends a foreach and while 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" param="test1,test2"/>
</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.
Parameters can be accessed by %subparam1%…%subparamN%.

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.
A query does only provide object properties and no run time information.

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

Query variables must be XMLScript unique to avoid unexpected results.

The loco ID, locid, is retrieved from block cb4 in variable lcid.
The function command requires a loco ID, which is provided by the text contents of the variable @lcid.

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

With the set statement a variable can be used to set the attribute text or integer value, depending of setint, 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.

With the clock get command:

  <clock cmd="get"/> 

three variables will be updated.

The systemtick will overflow at 4294967295(119.3 hours) on 32bit and 18446744073709551615 on 64bit systems.

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>

see: https://wiki.rocrail.net/doku.php?id=text-gen-en#variable

With the format attribute it is possible to format variable content in the same way as 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>

Output with the format attribute looks like:

Hello03:0005RocrailFans

Output without the format attribute looks like:

Hello 3 5 RocrailFans

Within the limits described above, variable names can be freely named; but as soon as two scripts with the same variable name run at the same time the scripts may not work correctly. In those cases a script specific prefix added to the name of the variable may avoid any confusion:

• change the original variable name from "vr_idx"
  
• within script "MyScriptNumber1.xml" to the variable name "vr_MSN1_idx" and
  
• within script "MyScriptNumber2.xml" to the variable name "vr_MSN2_idx" and so on.
  

In order to store a variable from runtime to runtime in Rocrail, these variables must be defined as "generated" "false":

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

The variable "vr_MSN3_lastUsedLocomotive" will be stored within the Rocrail plan file.
The variable "vr_MSN3_tmp" will be deleted when Rocrail is finished and will not be stored within the Rocrail plan file.

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.