Download
Support
Wiki Documentation
Support Forum
Mobile
DIY
User
Wiki writer
Build
Legal
Download
Support
Wiki Documentation
Support Forum
Mobile
DIY
User
Wiki writer
Build
Legal
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.
Blanks in path or filename are not supported!
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:
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". 1)
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%".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'.
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>
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.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.
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.
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 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.
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 |
- | not equal text |
> | greater than number |
< | smaller than number |
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.
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 |
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 | |
Turntable | tt | free, occupied, closed, open, reserved, #, pending | The # represents the current bridge position. If state pending is true the bridge is moving. |
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, automatic, f0…f28, home | 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" |
Object Name | Object type |
---|---|
Block | bk |
Loco | lc |
Route | st |
Note:
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 | Set clock on System time: <clock divider="1" hour="%syshour%" minute="%sysmin%"/> | ||
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 | |||
Weather | weather | setweather, weathertheme | |||
Light | light | flip, enable, disable | Enable a light from LightControl. | ||
Model | model | All http://rocrail.net/software/rocrail-snapshot/rocrail/wrapper-en.html#model | With modify the sub nodes may contain attributes which will be merged in the objects. | <model cmd="change"> <tx id="x" backred="255" backgreen="0" backblue="0"/> </model> |
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:
Char | Escape |
---|---|
< | < |
& | & |
> | > |
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.