Script XML

Sommaire → Objets → Actions

• Configuration des Actions | Contrôle des Actions | Actions système | Condition des Actions | Script XML | Exemple
  • Guide de démarrage rapide de scripts XML
  • Variables Texte
  • Exemples:
    • Général | Détecteurs Virtuels (En anglais) | Clavier externe (En anglais) | Feu de circulation (En allemand) | Manoeuvre (En allemand)

XMLScript peut seulement être utilisé si une Clé de soutien valide est fournie.

1. Ne pas remplacer des fonctions standard Rocrail avec des scripts XML.
2. N'essayez pas de mutiler le moteur automatique Rocrail.
3. Les scripts sont exécutés de manière asynchrone, et nécessite un savoir-faire en matière de programmation multithread.
4. Si vous rencontrez un comportement inattendu: Arrêter les actions XMLScript.
5. En cas d'incertitude: N'utilisez pas de scripts XML, ou demandez de l'aide sur le Forum.
6. Ne pas utiliser les mêmes variables dans dans de multiples scripts XML, qui seront réglées sur de nouvelles valeurs, pour éviter des résultats inattendus incluant des pannes du Serveur.

A V E R T I S S E M E N T

Vérifier les fonctionnalités de base de Rocrail avant de réinventer la roue avec les scripts XML.

Le script XML peut être utilisé en combinaison avec l'action exécuter un programme externe .
Son objectif principal est de simplifier et de réduire le nombre d'action et de conditions.
Le script XML utilisé est le même que celui utilisé dans Rocrail plan.xml.

• UTF-8 Editor, par exemple Notepad++ ou Gedit or l'éditeur xml interne de rocview pour éditer un fichier XML sur le serveur comme décrit ci-dessous sur cette page.
• L'éditeur Notepad de windows n'est pas pris en charge.
• Quelques connaissances en programmation XML.

• Faire des XmlScripts court et sans aller en longueur et sans longues boucles; Cela bloquera l'objet appelant du traitement des événements et des commandes s'il n'est pas défini comme Asynchrone.
• N'essayez pas de surpasser le mode automatique; Publiez une demande de fonctionnalité dans le forum si quelque chose de basique manque.
• Les ID d'objet avec des espaces ne sont pas pris en charge; utilisez plutôt des caractères de soulignement.
• Les noms de variable/fonction ne doivent pas contenir des caractères d'opération comme "+-*<>^!=?%/".

Les espaces dans le chemin d'accès ou le non de fichier ne sont pas autorisés!

1. Créez un Script Xml et enregistrez_le dans un fichier. (voir: Exemple simple)
2. Créez un programme action "run ext." .
3. Sélectionnez le fichier Script Xml . (Si le fichier Script se trouve dans le répertoire de l'espace travail, un chemin n'est pas nécessaire.)
4. Prêt à employer cette action sur n'importe quel objet Rocrail.

Mettre le réseau sous tension et démarrer le mode auomatique :

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

Pour créer et modifier les Scripts Xml sur le serveur, la boite de dialogue d'action peut être utilisée:

Ouvre l'éditeur.	L'analyseur a détecté une erreur après validation ou enregistrer.

Si le Script Xml n'existe pas déjà sur le serveur, une ossature script Xml sera créé:

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

L'éditeur de Script Xml peut également être ouvert en double-cliquant sur l'index.

Si le "<Script Xml>" est modifié avec la description "<desc="xxx">" (par exemple, nom du Script ), la description sera affichée dans l'emplacement. Par exemple.

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

Vérifiez si le code Xml est "bien formé". ¹⁾

Insérez l'instruction ou la commande sélectionnée en position de curseur.
Le [\n] de la boite de dialogue contrôle les flux de lignes avant et après l'instruction.

Pour utiliser cet éditeur, l'option "Utilisez les guillemets et les tirets" doit être désactivée pour éviter de créer un Xml invalide:

Préférence du système → Language & Région → Préférence Clavier → Texte

Avec cette option activée par défaut, elle convertit automatiquemen les deux tirets (--), utilisés en commentaires Xml, dans les signes (—), les guillemets rectilignes et caractères typographiques de type (“curly”). .
Cela rendra le Script Xml non valide.

Les paramètres d'appel peuvent être accessible par des variables avec le nommage "%param1%…%paramN%".
Voir: Paramètre de contrôle d'action
Fragment:

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

La boucle foreach est utilisée pour "faire ceci à tout dans cette table" avec une condition optionnel d'état Et/Ou.
La boucle peut être arrêtée avec une déclaration de pause ou de sortie.
Si la condition d'état Et/Ou ne correspond pas, il passe à l'objet suivant dans ce tableau.

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

Ce Script itérait la table locomotive et allumera la fonction 3 et donnera la commande Go pour chaque locomotive.
L'oid, l'ID de l'objet actuel dans la liste, est automatiquement généré dans la boucle.
dans le cas ou le tableau est lclist, l'ID courte peut également être utilisée: %soid%".²⁾

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

Cette "foreach" démarre chaque locomotive avec la classe 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>

Démarrer chaque locomotive qui réside dans le 'Bloc3', 'Bloc2' ou 'Bloc1'.

L'instruction while est une boucle et peut vérifier, le statut et la classe. Au moins l'un d'entre eux devrait être défini, sinon la boucle while ne sera pas exécutée.
Tant que l'instruction est vraie, les commandes dans while seront exécutées.

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

Si la boucle while est sans fin, elle sera arrêtée par l'attribut max qui de par défaut de 10.
Les valeurs maximales supérieures à 100 seront tronquées à 100 pour éviter le blocage et le plantage du serveur automatiquement lorsque les locomotives fonctionnent.

L'instruction if est utilisée pour le contrôle du flux et peut vérifier la condition, les états et la classe.
Si la déclaration est vraie, les commandes seront alors (then) exécutées, Sinon (else) ce n'est pas vrai, les autres commandes seront exécutées.
Le else est optionel.

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

La valeur de la variable texte de la loco contient l'ID de la locomotive.
Si l'ID de la locomotive n'existe pas, un bloc sera recherché par cette identification et, s'il existe l'identification de la locomotive dans le bloc sera utilisé.
Lacondition et l' état peuvent être utilisés dans l'instruction if . Au moins une d'entre elles doit être spécifiée.

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

Le texte tx1 est défini sur "Itinéraire est verrouillé " si l'itinéraire "b1-b2" OU l'itinéraire "b2-b3" est en état verrouillé.
Si ces itinéraires ne sont pas verrouillés, le texte tx1 est défini "Itinéraire non verrouille".

La valeur entière de Switch var est utilisée pour sélectionner la "case" avec la même valeur.
Si aucune correspondance n'a été trouvée, la valeur par défaut sera utilisée au cas où elle serait définie.

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

Les valeurs de cas multiples sont obsolètes, et sont fortement déconseillés à utiliser.
Un cas peut avoir plusieurs valeurs entières dans le format suivant:

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

Une des valeurs doit correspondre.

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

Note: Une déclaration "switch" n'a rien à voire avec l'objet-switch Rocrail .

Les fonctions doivent être déclarées dans le premier niveau de Sript Xml et doivent avoir défini l'ID.
Appelez la fonction avec l'ID souhaité: <call id="doeIets"/>
Plusieurs fonctions sont autorisées.
les paramètres sont accessibles par %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>

• Dans une fonction "Call" n'est pas pris en charge.
• La profondeur d'appel Max. est 5.

Quitez le Script Xml. Le cmt="reason" peut être utilisé pour le traçage

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

Termine pour chaque et pendant une boucle avec ou sans condition. Le cmt="reason" peut être utilisé pour le traçage.
Cette déclaration n'a aucun effet si elle n'est pas dans une boucle "foreach".

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

Les traces Script Xml seront de couleur verte dans Rocview.

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

Un temps de sommeil en ms.

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

Appelez un autre Script Xml avec un file="script.xml" et la fonction id="functionName"

<xmlscript>
  <sub file="lib1.xml" id="doeIets" param="test1,test2"/>
</xmlscript>

Si l'ID de la fonction est définie au caractère de soulignement id="_", l'intégralité du Script Xlm sera exécuté à l'exclusion des définitions de fonction.³⁾
Si aucune ID de fonction n'est définie %oid% sera utilisé pour trouver une fonction d'ajustement.
Les paramètres sont accessibles par %subparam1%…%subparamN%.

Exemple librairie lib1.xml:

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

L'ID de fonction doit être utilisé pour appeler des fonctions à partir d'un fichier de bibliothèque Script Xml.
Le plus utile si plus d'un Script Xlm partage des fonctions communes.

Avec l'instruction query, une variable peut être utilisée pour obtenir le texte de l'attribut et la valeur entière d'un certain objet.
Une requête ne fournit que des propriétés d'objet et aucune information d'exécution.

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

Aprés la requête, la variable peut être utilisée pour comparer le texte et/ou les chiffres. Le texte normal aura un résultat de valeur nulle.

Pour obtenir une valeur à partir d'un "sous-nœud":

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

Au lieu de subidx le subid peut également être utilisé si le "sous-nœud" a une ID.

Les variables de requête doivent être uniques dans XMLScript pour éviter des résultats inattendus.

L'identifiant de locomotive, locid, est extrait du bloc cb4 dans la variable lcid.
La commande de fonction nécessite un identifiant de locomotive, qui est fournie par le contenu textuel de la variable @lcid.

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

Avec l'instruction"set", une variable peut être utilisée pour définir le texte d'attribut ou la valeur entière d'un certain objet.

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

Pour définir une valeur d'un"sous-nœud":

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

Au lieu de subidx le subid peut être utilisé si le sous-nœud a une ID.

Avec la commande clock get:

  <clock cmd="get"/> 

Trois variables seront mise à jour.

Le systemtick débordera à 4294967295(119.3 heures) sur 32 bits et 18446744073709551615 sur les systèmes 64 bits.

Les conditions supplémentaires doivent être séparées avec un caractère spécifique "|" sans blanc supplémentaire:

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

Voir les variables : Variables texte

alltrue est vrai par défaut s'il n'est pas défini.
Si alltrue est mis à "faux" pour une seule des conditions, l'un des états et l'une des classes doivent être vrais.

Dans le cas où les instructions if contiennent des conditions, les états ou les classes, ceux-ci sont connectés par défaut avec and.
Si un seul des éléments doit être vrai, l’attribut connect peut être défini sur or.

Les valeurs doivent être séparées par des blancs.
Les états supplémentaires doivent être séparés avec un caractère de type |sans blanc supplémentaire:

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

Les ID d'objet avec des espaces ne sont pas pris en charge; Utilisez plutôt des caractères de soulignement ou des points.

Note:

• Avec"Commands All" toutesles commandes d'objets spécifiées sont prises en charge dans Rocrail plan.xml
• Les commandes spéciales d'action sont répertoriées séparément.

Si une valeur d'attribut de commande commence par un point d'interrogation, elle sera remplacée par la valeur d'attribut de l'objet référencé.
Exemple:

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

la valeur "?startupscid" sera remplacée par startupscid de 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"/>

L'ID d'objet peut contenir des variables.
Voir les variables possibles: Variables texte

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

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

Avec l'attribut format, il est possible de formater le contenu variable de la même manière que 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>

Sortie avec l'attribut format ressemblant à:

Hello03:0005RocrailFans

Sortie sans l'attribut format ressemblant à:

Hello 3 5 RocrailFans

Sans les limites décrites au dessus, les noms des variables peuvent être librement nommé; mais dès que deux scripts avec les mêmes noms de variables fonctionnent en même temps les scripts peuvent ne pas fonctionner correctement. Dans ces cas un préfixe spécifique au script ajouté au nom de la variable peut éviter toute confusion:

• changer le nom de la variable d'origine de "vr_idx"
  
• Dans le script "MyScriptNumber1.xml" mettre le nom de la variable "vr_MSN1_idx" et
  
• dans le script "MyScriptNumber2.xml" mettre le nom de variable "vr_MSN2_idx" etc.
  

Au lieu de stocker une variable d'exécution en exécution dans Rocrail, ces variables doivent être définies comme "generated" "false":

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

La variable "vr_MSN3_lastUsedLocomotive" sera stockée dans le dossier du plan Rocrail.
La variable "vr_MSN3_tmp" sera effacée quand Rocrail sera arrêté et ne sera stockée dans le dossier du plan Rocrail.

Pour vérifier si le Script Xml est bien mise en forme, il peut être ouvert dans un navigateur Web .
Certains caractères doivent être "escaped (remplacés)":

Ce n'est pas bien mis en forme, mais accepté par l'analyseur de syntaxe XML Rocrail :

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

Pour vérifier avec un navigateur WEB il doit être changé en:

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

Cei est également valable pour l'analyseur de syntaxe XML Rocrail.