xmlscripting-en
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
xmlscripting-en [2019/05/05 14:50] – rjversluis | xmlscripting-en [2024/02/15 10:43] (current) – [Commands] rjversluis | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== | + | ====== |
[[: | [[: | ||
[[: | [[: | ||
- | * [[: | + | * [[: |
- | * [[: | + | * [[: |
* [[: | * [[: | ||
* Examples: | * Examples: | ||
- | * [[: | + | * [[: |
+ | |||
+ | |||
+ | | [[: | ||
- | \\ | ||
{{: | {{: | ||
+ | ^ NOT FOR NOVICE USERS !!! ^ | ||
+ | =====Warning===== | ||
+ | - Do not replace standard Rocrail functions with XMLScript. | ||
+ | - Do not try to mangle the automatic Rocrail engine. | ||
+ | - The scripts are executed asynchrone, and needs multithreading programming know how. | ||
+ | - If encountering unexpected behaviour: Turn off XMLScript actions. | ||
+ | - If uncertain: Do not use XMLScript, or ask for help in the __**[[https:// | ||
+ | - Do not use the same variables in multiple XMLScripts, which will be set to new values, to avoid unexpected results including Server crashes. | ||
- | \\ | ||
+ | __**[[start# | ||
+ | |||
+ | |||
+ | \\ | ||
=====Introduction===== | =====Introduction===== | ||
- | XML scripting | + | :!: Check basic Rocrail functionality before inventing the wheel again with XMLScript.\\ |
+ | |||
+ | XMLScript | ||
Its primary goal is to simplify and to reduce the number of actions and conditions.\\ | Its primary goal is to simplify and to reduce the number of actions and conditions.\\ | ||
- | The XML used for the scripting | + | The XML used for XMLScript |
\\ | \\ | ||
Line 28: | Line 43: | ||
=====Recommendation===== | =====Recommendation===== | ||
- | * Keep the XmlScripts | + | * Keep the XMLScript |
* Do not try to outsmart the automatic mode; Post a feature request in the forum instead if something basic is missing. | * 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. | * Object IDs with blanks are not supported; Use underscores instead. | ||
Line 38: | Line 53: | ||
//Blanks in path or filename are not supported!// | //Blanks in path or filename are not supported!// | ||
- | - Create a XmlScript | + | - Create a XMLScript |
- Create a "run ext. program" | - Create a "run ext. program" | ||
- | - Select the XmlScript | + | - Select the XMLScript |
- Ready to use this action on any Rocrail object. | - Ready to use this action on any Rocrail object. | ||
{{: | {{: | ||
Line 56: | Line 71: | ||
\\ | \\ | ||
=====Edit on the Server===== | =====Edit on the Server===== | ||
- | To create and edit XmlScripts | + | To create and edit an XMLScript |
| {{: | | {{: | ||
| Open the editor. | | Open the editor. | ||
- | If the XmlScript | + | If the XMLScript |
<code xml> | <code xml> | ||
<?xml version=" | <?xml version=" | ||
Line 66: | Line 81: | ||
</ | </ | ||
</ | </ | ||
- | > The XmlScript | + | > The XMLScript |
\\ | \\ | ||
If "< | If "< | ||
Line 97: | Line 112: | ||
%% | %% | ||
\\ | \\ | ||
- | __**This will make the XmlScript | + | __**This will make the XMLScript |
+ | \\ | ||
+ | =====Calling Parameters===== | ||
+ | Calling parameters can be accessed by variables with the naming of " | ||
+ | See: __**[[: | ||
+ | Snippet: | ||
+ | <code xml> | ||
+ | < | ||
+ | <if condition=" | ||
+ | < | ||
+ | </ | ||
+ | </if> | ||
+ | </ | ||
+ | </ | ||
\\ | \\ | ||
Line 161: | Line 189: | ||
</ | </ | ||
</ | </ | ||
- | If the while loop is endless it will be stopped by the max attribute which is default 100.\\ | + | If the while loop is endless it will be stopped by the max attribute which is default |
+ | Higher max values than 100 will be truncated to 100 to avoid server blocking and crashing automatically running locomotives.\\ | ||
Line 228: | Line 257: | ||
</ | </ | ||
+ | // Multiple case values are deprecated, and are strongly discourage to use.//\\ | ||
A case may have multiple integer values in the following format:\\ | A case may have multiple integer values in the following format:\\ | ||
<code xml> | <code xml> | ||
Line 255: | Line 285: | ||
Call the function with the wanted ID: ''< | Call the function with the wanted ID: ''< | ||
Multiple functions are allowed.\\ | Multiple functions are allowed.\\ | ||
+ | Parameters can be accessed by %subparam1%...%subparamN%.\\ | ||
+ | |||
<code xml> | <code xml> | ||
< | < | ||
Line 267: | Line 299: | ||
< | < | ||
<sys cmd=" | <sys cmd=" | ||
- | <call id=" | + | <call id=" |
</ | </ | ||
</ | </ | ||
Line 278: | Line 310: | ||
====exit==== | ====exit==== | ||
- | Exit the XmlScript. The cmt=" | + | Exit the XMLScript. The cmt=" |
<code xml> | <code xml> | ||
< | < | ||
Line 291: | Line 323: | ||
\\ | \\ | ||
====break==== | ====break==== | ||
- | Ends a foreach loop with or without condition. The cmt=" | + | Ends a foreach |
This statement has no effect if its not within a foreach loop.\\ | This statement has no effect if its not within a foreach loop.\\ | ||
<code xml> | <code xml> | ||
Line 307: | Line 339: | ||
\\ | \\ | ||
====trace==== | ====trace==== | ||
- | XmlScript | + | XMLScript |
<code xml> | <code xml> | ||
< | < | ||
Line 334: | Line 366: | ||
====sub==== | ====sub==== | ||
- | Call another | + | Call another |
<code xml> | <code xml> | ||
< | < | ||
- | <sub file=" | + | <sub file=" |
</ | </ | ||
</ | </ | ||
If the function ID is set to underscore, id=" | If the function ID is set to underscore, id=" | ||
If no function ID is set the %oid% will be used to find a fitting function.\\ | 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**: | Library example **lib1.xml**: | ||
Line 353: | Line 386: | ||
- | The function ID must be used to call functions from a XmlScript | + | The function ID must be used to call functions from a XMLScript |
- | Most helpfull if more then one XmlScript | + | Most helpfull if more then one XMLScript |
\\ | \\ | ||
====query==== | ====query==== | ||
With the query statement a variable can be used to get the attribute text and integer value of a certain object.\\ | 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.\\ | ||
<code xml> | <code xml> | ||
<query vr=" | <query vr=" | ||
Line 369: | Line 403: | ||
</ | </ | ||
Instead of the subidx the subid can also be used if the sub node has an ID.\\ | 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. :!: | | ||
===Function example=== | ===Function example=== | ||
Line 381: | Line 417: | ||
\\ | \\ | ||
====set==== | ====set==== | ||
- | With the set statement a variable can be used to set the attribute text or integer value of a certain object.\\ | + | With the set statement a variable can be used to set the attribute text or integer value, depending of setint, |
<code xml> | <code xml> | ||
<set vr=" | <set vr=" | ||
Line 391: | Line 427: | ||
</ | </ | ||
Instead of the subidx the subid can also be used if the sub node has an ID.\\ | Instead of the subidx the subid can also be used if the sub node has an ID.\\ | ||
- | |||
\\ | \\ | ||
+ | ====clock==== | ||
+ | | 15401+ | | ||
+ | With the clock get command: | ||
+ | <code xml> | ||
+ | <clock cmd=" | ||
+ | </ | ||
+ | three variables will be updated. | ||
+ | ^ Variable name ^ Value ^ Text ^ | ||
+ | | modeltime | hour * 3600 + minute * 60 + seconds | hh:mm.ss | | ||
+ | | realtime | hour * 3600 + minute * 60 + seconds | hh:mm.ss | | ||
+ | | systemtick | count of 10ms since Rocrail server start | - | | ||
+ | The systemtick will overflow at 4294967295(119.3 hours) on 32bit and 18446744073709551615 on 64bit systems.\\ | ||
+ | \\ | ||
=====Condition format===== | =====Condition format===== | ||
| value | comparator | value |\\ | | value | comparator | value |\\ | ||
Line 413: | Line 461: | ||
| > | greater than number | | | > | greater than number | | ||
| < | smaller than number | | | < | smaller than number | | ||
+ | | ~ | contains text (@var_1 ~ @var_2 is true, when text of var_1 contains complete text of var_2) - since version 2.1.1010| | ||
====alltrue==== | ====alltrue==== | ||
Line 448: | Line 497: | ||
| Sensor | fb | true, false, on, off | true = on, false = off | | | Sensor | fb | true, false, on, off | true = on, false = off | | ||
| Output | co | on, off, active | | | | Output | co | on, off, active | | | ||
+ | | Location | location | free | The ' | ||
| Block | bk | free, occupied, closed, open, reserved | | | | 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. | | | Turntable | tt | free, occupied, closed, open, reserved, #, pending | The # represents the current bridge position. \\ If state pending is true the bridge is moving. | | ||
Line 453: | Line 503: | ||
| System | sys | go, stop | | | | System | sys | go, stop | | | ||
| Automode | auto | on, off | | | | Automode | auto | on, off | | | ||
- | | Locomotive | lc | fwd, rev, +, -, min, mid, cruise, max, block, "// | + | | Locomotive | lc | fwd, rev, +, -, min, mid, cruise, max, block, "// |
- | | Car | car | empty, loaded, maintenance, | + | | Car | car | empty, loaded, maintenance, |
| Waybill | waybill | waiting, shipping, delivered, "// | | Waybill | waybill | waiting, shipping, delivered, "// | ||
+ | | Text | tx | on, off | In case the toggle switch option is set. | | ||
====Class Objects==== | ====Class Objects==== | ||
Line 467: | Line 518: | ||
=====Commands===== | =====Commands===== | ||
Note: \\ | Note: \\ | ||
- | * With " | + | * With " |
* The special implemented action commands are listed separately. | * The special implemented action commands are listed separately. | ||
Line 473: | Line 524: | ||
\\ | \\ | ||
^ Object Name ^ Object type ^ Commands ^States ^ Remark ^ Example ^ | ^ Object Name ^ Object type ^ Commands ^States ^ Remark ^ Example ^ | ||
- | | Loco | lc | All https:// | + | | Loco | lc | All https://wiki.rocrail.net/ |
- | | Function | fn | All and fndesc, fncmd | | The fnchanged or the fndesc, function description, | + | | Function | fn | All and fndesc, fncmd, group 1..7 | | The fnchanged or the fndesc, function description, |
| Switch | sw | All | | | | Switch | sw | All | | | ||
| Signal | sg | All | | | | Signal | sg | All | | | ||
Line 483: | Line 534: | ||
| Sensor | fb | All, on, off, flip | | | | 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**=" | | Route | st | go, lock, free, classset, classadd, classdel | open, closed | The lock and free command needs the extra attribute **locid**=" | ||
- | | Text | tx | showon, showoff | | Update event by format attribute. \\ The optional **bkid** and **lcid** may be used in the command also. | %%<tx id=" | + | | Text | tx | showon, showoff, blink, on, off, click | | Update event by format attribute. \\ The optional **bkid** and **lcid** may be used in the command also. | %%<tx id=" |
- | | Variable | vr | random, start, stop \\ start, length (for substring) | | Set by attribute: %%value=" | + | | Variable | vr | random, start, stop \\ start, length (for substring) | | Set by attribute: %%value=" |
| Action control | actionctrl | | | The id in the actionctrl is a reference to an existing action. Condition child nodes may be added. | | | 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. | | | Operator | operator | emptycar, loadcar, addcar, leavecar | | In the carids attribute a list of cars must be specified. | | ||
| System | sys | All https:// | | System | sys | All https:// | ||
| Automat | auto | All https:// | | Automat | auto | All https:// | ||
- | | Car | car | empty, loaded, maintenance, | + | | Car | car | empty, loaded, maintenance, |
| Staging block | sb | All https:// | | Staging block | sb | All https:// | ||
| Fiddle Yard | seltab | All https:// | | Fiddle Yard | seltab | All https:// | ||
| Location | location | All https:// | | Location | location | All https:// | ||
- | | Clock | clock | All https:// | + | | Clock | clock | All https:// |
| Turntable | tt | All https:// | | Turntable | tt | All https:// | ||
| External | ext | All https:// | | External | ext | All https:// | ||
- | | Weather | weather | setweather, weathertheme | | | + | | Weather | weather | setweather, weathertheme, go, stop | | |
- | | Light | light | flip, enable, disable | Enable a light from LightControl. | | + | | Light | light | flip, enable, disable |
- | | Model | model | All https:// | + | | LightControl | lightctrl | go, stop | | Enable / disable LightControl. | %%< |
+ | | Model | model | All https:// | ||
+ | | MVTrack | mv | reset, sets1, sets2, setdistance, | ||
====Attribute values==== | ====Attribute values==== | ||
Line 529: | Line 582: | ||
\\ | \\ | ||
+ | ===== System variables ===== | ||
+ | see: [[https:// | ||
=====Variable Format===== | =====Variable Format===== | ||
With the format attribute it is possible to format variable content in the same way as printf.\\ | With the format attribute it is possible to format variable content in the same way as printf.\\ | ||
Line 552: | Line 607: | ||
\\ | \\ | ||
+ | =====Variable Names===== | ||
+ | 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 " | ||
+ | * within script " | ||
+ | * within script " | ||
+ | |||
+ | =====Variables defined as " | ||
+ | In order to store a variable from runtime to runtime in Rocrail, these variables must be defined as " | ||
+ | ====Example==== | ||
+ | <code xml> | ||
+ | < | ||
+ | <vr id=" | ||
+ | <vr id=" | ||
+ | </ | ||
+ | </ | ||
+ | The variable " | ||
+ | The variable " | ||
+ | |||
+ | \\ | ||
+ | |||
=====Tips===== | =====Tips===== | ||
====XML Well Formed==== | ====XML Well Formed==== |
xmlscripting-en.1557060624.txt.gz · Last modified: 2019/05/05 14:50 by rjversluis