1 /*! \page xml_loader XML file loader
3 \section toc Table of contents
6 - \ref loader_programming
11 \section loader_intro Introduction
13 The yacs loader is a class that can be used to load a calculation schema
14 in memory by reading and parsing a XML file describing it.
16 \section loader_programming Programming with the yacs loader class
18 To use the yacs loader class, first create a specific runtime (here a Salome one).
20 Then you can create an instance of the yacsloader class and call
21 the load method with the name of the XML file as argument.
23 The call to the method will return a calculation schema (instance of the Proc class).
26 #include "RuntimeSALOME.hxx"
29 YACS::ENGINE::RuntimeSALOME::setRuntime();
30 YACS::YACSLoader loader;
32 YACS::ENGINE::Proc* p=loader.load("file.xml");
36 You can then dump to a file a graphviz diagram by calling the writeDot
42 std::ofstream f("proc.dot");
47 You can display the diagram with: dot -Tpng proc.dot |display.
49 And then execute the schema with an Executor.
52 #include "Executor.hxx"
54 YACS::ENGINE::Executor executor;
58 \section loader_use Using the yacs driver
60 The driver program is a program that loads a schema file and executes it
61 until its end. It is possible to display the schema state during the
62 execution by specifying the --display option. An exemple of use is:
65 driver --display=1 schema.xml
68 Internally, it uses the loader class, the Salome runtime, the standard
69 executor with all is necessary to catch exceptions.
71 \section loader_file Writing a XML file
73 To write a XML file describing a calculation schema, you need to define
74 several objects that are listed here :
76 - the calculation schema
78 - elementary calculation nodes
79 - connections between nodes
80 - initialization parameters
81 - composed calculation nodes
84 \subsection loader_schema Defining calculation schema
85 To define a calculation schema, simply open a proc tag
91 All following definitions must be put betwween these tags.
93 \subsection loader_types Defining data types
94 A calculation schema is composed of interconnected calculation nodes.
95 These nodes exchange data through data ports (in and out). The first
96 thing you need to do is to define all types that can be exchanged
99 Some types are already defined by the runtime you use. For example, the
100 Salome runtime defines : int, double, string and bool types. It can also
101 define all types used by the declared components. At the moment, the
102 Salome runtime knows nothing about the types used by the declared components
103 so it is mandatory to define all data types except the four basic ones.
105 It is possible to define three kind of types : basic, sequence and objref.
107 A basic type is an atomic one so it can only be int, double, string and bool.
108 They are already defined so what can be defined is only alias to these types.
110 A definition of an alias to the double data type :
112 <type name="mydble" kind="double"/>
115 A sequence type is a constructed type that is built on already existing
116 types. A sequence type defines a list of elements. The definition
117 gives the name of the type and the type of the elements of the sequence.
119 To define a sequence of double type, add :
121 <sequence name="myseqdble" content="double"/>
124 All attributes in the sequence tag are mandatory.
126 You can then define a sequence of sequence by :
128 <sequence name="myseqseqdble" content="myseqdble"/>
131 An objref data type is an equivalent of a class in object languages.
132 Salome components use objects which have types such as Mesh, Field, ...
133 All these types can be related by inheritance relations.
135 Defining a base objref :
137 <objref name="mesh"/>
140 Defining a derived objref from mesh :
142 <objref name="refinedmesh">
147 It is possible to derive an objref from multiple base objref and objref names
148 can use name spaces. Just use a / as separator.
150 <objref name="myns/mesh"/>
152 It is useful for Salome components because objref must be mapped to
153 CORBA types which can use name spaces.
155 Finally, it is possible to define a sequence of objref :
157 <sequence name="myseqmesh" content="refinedmesh"/>
160 \b RESTRICTION : struct type is not supported
162 \subsection loader_nodes Defining elementary calculation nodes
163 The next step is to define calculation nodes : service nodes or inline
166 There are three kinds of inline nodes : script inline node, function
167 inline node and clone inline node,
168 and three kinds of service nodes : component service node, reference
169 service node and node service node.
171 The definition of all these nodes is described below.
175 This kind of node corresponds to the execution of a python script with input
176 and output parameters. Input and output parameters are passed to the
177 script through data ports.
178 A very simple example of an script inline node is :
180 <inline name="node1" >
184 <outport name="p1" type="int"/>
188 The inline node has a mandatory name as all kind of nodes.
189 The script tag indicates that it is a script inline node.
190 The python script appears in as much lines as necessary between code tags in the script
192 If your script contains a lot of "<" or "&" characters - as program code often does -
193 the XML element can be defined as a CDATA section.
194 A CDATA section starts with "<![CDATA[" and ends with "]]>":
196 In the example above the script calculates p1 that is an output parameter.
197 An output data port must then be defined. A output data port is defined
198 in an outport tag with two mandatory attributes : name and type that references
199 an already defined data type.
200 To define an input data port use the inport tag in place of outport.
202 Example of an inline node with input and output arguments :
204 <inline name="node1" >
206 <code>p1=p1+10</code>
208 <inport name="p1" type="int"/>
209 <outport name="p1" type="int"/>
212 Now the calculation node receives p1 as an input argument adds 10 to it
213 and sends it as an output argument.
215 - Function inline node
217 This kind of node corresponds to the execution of a python function with input
218 and output parameters. Input and output parameters are passed to the
219 script through data ports.
220 The main difference with the script node is the execution part. The definition
221 of input and output ports is unchanged. In the execution part use the function
222 tag in place of the script tag and add a name (mandatory) which must be the same
223 as that of the function.
225 An example of an function inline node is :
227 <inline name="node1" >
229 <code>def f(p1):</code>
230 <code> p1=p1+10</code>
231 <code> return p1</code>
233 <inport name="p1" type="int"/>
234 <outport name="p1" type="int"/>
240 This node is a convenience node to avoid repeating an inline definion.
241 It allows to create an inline calculation by using the definition
242 of another inline node. Such a kind of node is defined in a node tag
243 with two mandatory attributes : name (the node name) and type that indicates the name
244 of the already existing inline node to use for the definition. Example :
247 <node name="node2" type="node1"/>
250 - Reference service node
252 A service node corresponds to the execution of a service available from a
253 calculation server. It can thought of as the execution of an object method.
254 A service node is defined in a service tag in place of the inline tag for
257 In a reference service node the calculation server is known by its address (which
258 is a string meaningful for the runtime) and is supposed to exists
259 before executing the calculation schema. The service is known by its name.
260 Then the service has input and output arguments that are passed through ports
261 in the same way as the inline nodes.
262 The server address is defined as a string in a ref tag and the service name is
263 defined in a method tag.
266 <service name="node4" >
267 <ref>corbaname:rir:#test.my_context/Echo.Object</ref>
268 <method>echoDouble</method>
269 <inport name="p1" type="double"/>
270 <outport name="p1" type="double"/>
274 The service node node4 is a reference service node because it has a ref
275 section. The address of the calculation server to use is a CORBA address
276 that must be meaningful to the runtime. The service to use is the
277 CORBA operation echoDouble that just gets the input and returns it.
279 - Component service node
281 This kind of node is similar to the previous one but the server does not
282 exist before the beginning of the execution. It's the runtime that is in charge
283 of loading the calculation server or component for Salome platform.
284 Instead of defining the address of the server we give the name of the
285 component that will be loaded through the runtime by the platform.
286 This name is given in a component tag in place of the ref tag.
289 <service name="node4" >
290 <component>ECHO</component>
291 <method>echoDouble</method>
292 <inport name="p1" type="double"/>
293 <outport name="p1" type="double"/>
299 It's a special node that gives the possibility to create a service node that calls
300 a service of an already loaded component. To define such a node you need to
301 indicate the name of an already existing component service node in a node tag
302 in place of the previous component tag.
304 A short example is better than a long speech :
306 <service name="node5" >
308 <method>echoString</method>
309 <inport name="p1" type="string"/>
310 <outport name="p1" type="string"/>
313 Here, node5 is a service node that executes the echoString service of the
314 component that has been loaded by the component service node node4.
316 \subsection loader_connections Defining connections between nodes
317 After having defined all the calculation nodes needed, it is necessary
318 to connect them to define the order of execution (control flow)
319 and the exchanges of data (data flow).
323 The order of execution is defined by means of control links between
325 These links are defined in a control tag with subtags fromnode and tonode
326 which give the names of precedent node and following node.
327 Example of control link :
330 <fromnode>node1</fromnode>
331 <tonode>node2</tonode>
334 This control link indicates that execution of node2 must be after complete
339 Exchange of data between nodes is defined by means of data links between
340 output ports and input ports.
341 These links are defined in a datalink tag with subtags fromnode, tonode, fromport
342 and toport. The output port is specified with the node name and the output port
343 name. It's similar for the input port.
345 Example of data link :
348 <fromnode>node1</fromnode> <fromport>p1</fromport>
349 <tonode>node2</tonode> <toport>p1</toport>
352 This data link indicates that the output argument p1 of node node1
353 will be sent to node node2 and used as input argument p1.
354 By default, with this datalink definition, a control link is automatically defined between node1 and node2,
355 to ensure a complete execution of node1 before node2 starts.
356 Sometimes, this control link must not be created, for instance with loops (see below).
357 With most simple cases, yacs loader is able to decide to create or not the control link. It is always
358 possible to ask explicitely a data link without control link:
360 <datalink control="false">
361 <fromnode>node1</fromnode> <fromport>p1</fromport>
362 <tonode>node2</tonode> <toport>p1</toport>
366 So, it is equivalent to write:
369 <fromnode>node1</fromnode> <fromport>p1</fromport>
370 <tonode>node2</tonode> <toport>p1</toport>
376 <fromnode>node1</fromnode>
377 <tonode>node2</tonode>
379 <datalink control="false">
380 <fromnode>node1</fromnode> <fromport>p1</fromport>
381 <tonode>node2</tonode> <toport>p1</toport>
384 Control links may be defined implicitely several times without problem.
386 \subsection loader_parameters Defining initialization parameters
387 It is possible to initialize directly input ports with constants.
388 This is done with a definition put in a parameter tag with subtags tonode,
390 tonode is the name of the node and toport the name of the port to initialize.
391 value gives the constant to use to initialize the port. This constant is
392 given in XML-RPC coding convention (http://www.xmlrpc.com/).
394 Example of parameter initialization :
397 <tonode>node1</tonode> <toport>p1</toport>
398 <value><string>coucou</string></value>
403 This parameter initialization indicates that the input argument p1
404 of node1 is initialized with a string constant ("coucou").
406 \subsection loader_example1 Putting all this together
407 Now that we are able to define data types, calculation nodes and links, we
408 can define a complete calculation schema with interconnected calculation.
412 <inline name="node1" >
414 <code>p1=p1+10</code>
416 <inport name="p1" type="int"/>
417 <outport name="p1" type="int"/>
419 <inline name="node2" >
423 <inport name="p1" type="int"/>
424 <outport name="p1" type="int"/>
426 <service name="node4" >
427 <ref>corbaname:rir:#test.my_context/Echo.Object</ref>
428 <method>echoDouble</method>
429 <inport name="p1" type="double"/>
430 <outport name="p1" type="double"/>
433 <fromnode>node1</fromnode> <tonode>node2</tonode>
436 <fromnode>node1</fromnode> <tonode>node4</tonode>
439 <fromnode>node1</fromnode> <fromport>p1</fromport>
440 <tonode>node2</tonode> <toport>p1</toport>
443 <fromnode>node1</fromnode> <fromport>p1</fromport>
444 <tonode>node4</tonode> <toport>p1</toport>
447 <tonode>node1</tonode> <toport>p1</toport>
448 <value><int>5</int></value>
452 We have put together 2 inline nodes and one reference service node
453 with nodes node2 and node4 that will be concurrently executed as can
454 be seen on the control flow diagram below.
456 \image html schema.jpeg
458 \subsection loader_composed Defining composed calculation nodes
459 The next step is to define composed nodes either to modularize the calculation
460 schema or to introduce control nodes like loop or switch.
462 - Using block to modularize the schema
464 All the previously defined elements (except the data types) can be put
465 in block nodes. It is easy : create a bloc tag with an attribute name
466 that contains all the definitions and you have a composed node that is
472 <inline name="node1" >
474 <code>p1=p1+10</code>
476 <inport name="p1" type="int"/>
477 <outport name="p1" type="int"/>
479 <service name="node4" >
480 <ref>corbaname:rir:#test.my_context/Echo.Object</ref>
481 <method>echoDouble</method>
482 <inport name="p1" type="double"/>
483 <outport name="p1" type="double"/>
486 <fromnode>node1</fromnode> <tonode>node4</tonode>
489 <fromnode>node1</fromnode> <fromport>p1</fromport>
490 <tonode>node4</tonode> <toport>p1</toport>
494 This block can now be linked with other nodes of any kind in the same way
496 The rules are : it is not possible to set control links that cross the boundary
497 of the block. On the other end, it is possible to set data links that cross
498 this boundary either on input or on output.
500 - Defining a For Loop
502 If you want to execute a calculation n times, you can use a ForLoop node
503 to define this kind of computation.
504 A for loop is defined in a forloop tag that has 2 attributes : name and nsteps.
505 name is as always the name of the node and nsteps is the number of steps of the
506 loop. The for loop must contain one and only one node that can be an elementary
507 calculation node or a composed node. It is possible to have a for loop in a for loop, for
508 example. If you want to put more than one calculation node in a for loop, use
513 <forloop name="l1" nsteps="5">
514 <inline name="node2" >
516 <code>p1=p1+10</code>
518 <inport name="p1" type="int"/>
519 <outport name="p1" type="int"/>
523 The rules are the same as for the block node. But inside loops, to be able to perform
524 iterative computation, it is allowed to link an output port of an internal node
525 with an input port of a previous node in control flow. The only limitation is that
526 you have to put the node and the data link in a block node as links can't be defined
527 in a forloop section.
531 <forloop name="l1" nsteps="5">
533 <inline name="node2" >
535 <code>p1=p1+10</code>
537 <inport name="p1" type="int"/>
538 <outport name="p1" type="int"/>
540 <datalink control="false">
541 <fromnode>node2</fromnode> <fromport>p1</fromport>
542 <tonode>node2</tonode> <toport>p1</toport>
548 Last point : it is possible to link the nsteps entry of the for loop
549 with an output port that produces integer data. The input port
550 of the loop has the same name as the attribute (nsteps).
552 - Defining a While Loop
554 This kind of loop is mainly similar to the for loop. The only difference is that
555 the loop executes as long as a condition is true. A while loop is defined in
556 a whileloop tag and has only one attribute : name as usual.
557 The condition value is set through an input port (which name is condition)
558 that accepts boolean value.
560 Example of a while loop:
562 <whileloop name="l1" >
564 <inline name="node2" >
566 <code>p1=p1+10</code>
567 <code><![CDATA[ condition=p1 < 40.]]> </code>
569 <inport name="p1" type="int"/>
570 <outport name="p1" type="int"/>
571 <outport name="condition" type="bool"/>
573 <datalink control="false">
574 <fromnode>node2</fromnode> <fromport>p1</fromport>
575 <tonode>node2</tonode> <toport>p1</toport>
579 <datalink control="false">
580 <fromnode>l1.b.node2</fromnode> <fromport>condition</fromport>
581 <tonode>l1</tonode> <toport>condition</toport>
584 <tonode>l1.b.node2</tonode> <toport>p1</toport>
585 <value><int>23</int> </value>
589 It is here again possible to define composed node of any kind as internal
590 node to define loops in loops.
592 - Defining a Switch Loop
594 A switch node is equivalent to a switch C. It has an input port (which name
595 is select) that accepts integer data. According to the value in the select
596 port one or another case node is selected for execution. Each case is defined
597 in a case tag with one attribute id that must be an integer or default. If no case
598 is defined for the select value the switch node uses the default case.
599 A case can contain one and only one internal node.
601 A minimal but almost complete example :
605 <code>select=3</code>
607 <outport name="select" type="int"/>
613 <script><code>print p1</code></script>
614 <inport name="p1" type="double"/>
615 <outport name="p1" type="double"/>
620 <script><code>print p1</code></script>
621 <inport name="p1" type="double"/>
622 <outport name="p1" type="double"/>
627 <control> <fromnode>n</fromnode> <tonode>b1</tonode> </control>
628 <datalink> <fromnode>n</fromnode><fromport>select</fromport>
629 <tonode>b1</tonode> <toport>select</toport> </datalink>
631 <tonode>b1.3.n2</tonode> <toport>p1</toport>
632 <value><double>54</double> </value>
635 <tonode>b1.default.n2</tonode> <toport>p1</toport>
636 <value><double>54</double> </value>