Program Template Definitions

PROGRAM TEMPLATE DEFINITIONS

This section gives the various XML elements that are available to use to create simple "XML programs" within any element of a model behavior, and some of these elements may be used within the panel.xml as well. For more details please see the following Model Behaviors section:

XML Programs

IMPORTANT: This page outlines the XML programing template definitions for Model Behaviours only. XML programing can also be used as part of the panel.xml file definition, however it is structured slightly differently and is explained in it's own page here: panel.xml

When working with XML programs, it is important to note that the XML will be parsed linearly and so your XML structure should be logically created with the order in which you wish things to be executed from top to bottom. It is also important to understand that all programs are built from the same three main building blocks - the <Condition>, the <Switch> and the <Loop> elements - and that you can nest these within each other. For example, you can have a "switch" that will perform various "conditional" checks for each "case", and each true/false return for the conditions could themselves have further "switches", "conditions" or "loops" within them. This means that with just these three types of element - and the small selection of logical tests available - you can create rather complex component and input behaviors.

You can find some examples of these XML Programs from the following section:

XML Program Examples

`<Condition>`

This element is used to check a specific condition and will generate a boolean result, which can then be parsed using the <True> and/or <False> sub-elements. Note that if the condition does not require a <False> sub-element, then you may omit the <True> sub-element as well, and simply place the "True" XML within the <Condition> element tags. When neither the <True> or <False> sub-elements are present, the content of the condition will only be parsed if the condition is "True". However, for clarity we recommend you always explicitly use the <True> and/or <False> sub-elements.

When creating conditions you should be aware that they come in two "types":

Attribute Condition: The true/false check will be performed using the element attributes listed below. Note that the "Match" and "Different" attributes are complimentary to the "Check" attribute and should only be used in conjunction with that. For example:
```
<Condition Check="BARO_COUNT" Match="1">
```
<Test> Condition : The true/false check is done by a <Test> element, and the condition element has no attributes. This is illustrated by the <Condition> Example.

This element may have the following optional attributes:

Attribute	Description	Type	Required
`Valid`	"True" if the parameter exists in the saved parameters and if the value is not "0", "False", or an empty parameter.	String	No
`Check`	"True" if a parameter for the given ID has been declared in the current parameters stack.	String	No
`NotEmpty`	"True" if the parameter exists and has a value of some kind.	String	No
`Match`	This will compare the given value with the contents of the `Check` attribute and return "True" if it's the same.	String	No
`Different`	This will compare the given value with the contents of the `Check` attribute and return "True" if it's different.	String	No
`Contains`	"True" if the parameter exists in the saved parameters.	String	No
`CheckSavedParameters`	"True" if the saved parameters with the given ID exists.	String	No

`<Switch>`

This element is used to create a check that will run through various "cases" until one of the comparisons is considered "True", and at this point the XML within the <Case> sub-element will be performed. If there is no applicable <Case>, the XML within the <Default> element will be performed (if a default case is supplied).

When creating switches you should be aware that they come in two "types":

Switch Parameter Check: When you supply the "Param" attribute to a switch, the value of the parameter will be what is compared with the "Value" of each <Case>, and only the case with a value the same as the "Param" value will be executed. For example:
```
<Switch Param="USE_GROUND_SPOILER">
```
Switch Case Check: When you do not supply an attribute to the switch, it means that each <Case> will instead perform a simple condition check based on it's attribute, and when one of these attribute checks evaluates as "True", the XML for the case will be executed. You can find an illustration of this switch type in the <Switch> Example.

This element may have the following optional attribute:

Attribute	Description	Type	Required
Param	A parameter value that you wish to check against the different `<Case>` elements.	String	No

`<Case>`

A <Case> element is a sub-element of a <Switch> which contains the XML to be executed when the switch evaluation is considered as "True". If the parent <Switch> has a "Param" attribute, then the case must have a corresponding "Value" attribute, since the condition check will be done between these two values, and only when the contents of "Param" are equal to the contents of "Value" will the case be performed. If the <Switch> has no attributes, then the <Case> should have one of the other available attributes - "Valid", "Check" or "Not Empty" - to generate a condition check which returns "True" or "False". When structured like this, the XML will be check all cases from top to bottom until one of the conditions returns "True", at which point the XML within will be parsed.

NOTE: The "Match" and "Different" attributes are complimentary to the "Check" attribute and should only be used in conjunction with that.

This element has the following attributes:

Attribute	Description	Type	Required
`Value`	The value that should be compared to the "Param" value from the parent `<Switch>`.	String	No
`Valid`	"True" if the parameter exists and if the value is not "0", "False" or an empty parameter.	String	No
`Check`	"True" if the parameter exists.	String	No
`NotEmpty`	"True" if the parameter exists and has a value of some kind.	String	No
`Match`	This will compare the given value with the content of the `Check` attribute and return "True" if it's the same.	String	No
`Different`	This will compare the given value with the content of the `Check` attribute and return "True" if it's different.	String	No

`<Default>`

This is a sub element of <Switch> and is used to define the XML that should be executed by default should the switch parameter not match any case values, or the cases themselves not resolve as "true".

`<Test>`

This is a container element that has no attributes and is used to hold the logic required to generate a "True" or "False" value for a <Condition>. You can see an example of how this element is used from the section on the <Condition> Example. Note that in most cases you can nest operations within operations and use that to create more complex logic if required.

`<And>`

This element acts as a logical "and" which will compare the results of two expressions and return "True" if they are both evaluating as "True", or "False" otherwise. Note that you cannot compare more than two expressions in a single <And>, but you can nest an <And> within an <And> and so compare more than the default 2 expression results in that way.

`<Or>`

This element acts as a logical "or" which will compare the results of two expressions and return "True" if either of them are evaluating as "True", or "False" otherwise. Note that you cannot compare more than two expressions in a single <or>, but you can nest an <or> within an <or> and so compare more than the default 2 expression results in that way.

`<Not>`

This element will check if an expression is not "True" and return "True" if it's not, or "False" otherwise. For example:

<Not>
    <Arg Check="LIGHT_TYPE" Match="Potentiometer"/>
</Not>

In this case we are checking to see if the parameter "LIGHT_TYPE" does not match the type "Potentiometer", so as long as this is not the case it will return "True", but when the parameter does match, then it will return "False".

`<Greater>`

This element will check whether the result of one expression (the first one listed within the element) is greater than the result of another (the second one listed in the element). For example:

<Greater>
    <Value>NUM_STATES</Value>
    <Number>2</Number>
</Greater>

Here we are checking if the value of the "NUM_STATES" parameter is greater than "2", and if it is then the return will be "True", and if it's not then the return will be "False".

`<Lower>`

This element will check whether the result of one expression (the first one listed within the element) is lower than the result of another (the second one listed in the element). For example:

<Lower>
    <Value>NEXT_ID</Value>
    <Value>MAX_ID</Value>
</Lower>

Here we are checking if the value of the "NEXT_ID" parameter is lower than the value of the "MAX_ID" parameter, and if it is then the return will be "True", and if it's not then the return will be "False".

`<GreaterOrEqual>`

This element will check whether the result of one expression (the first one listed within the element) is greater than or equal to the result of another (the second one listed in the element). For example:

<GreaterOrEqual>
    <Value>CUR_ID</Value>
    <Number>4</Number>
</GreaterOrEqual>

Here we are checking if the value of the "CUR_ID" parameter is greater than or equal to "4", and if it is then the return will be "True", and if it's not then the return will be "False".

`<LowerOrEqual>`

This element will check whether the result of one expression (the first one listed within the element) is lower than or equal to the result of another (the second one listed in the element). For example:

<LowerOrEqual>
    <Value>ID</Value>
    <Value>BUTTON_INOP_COUNT</Value>
</LowerOrEqual>

Here we are checking if the value of the "ID" parameter is lower than or equal to the value of the "BUTTON_INOP_COUNT" parameter, and if it is then the return will be "True", and if it's not then the return will be "False".

`<Equal>`

This element will check whether the result of one expression (the first one listed within the element) is equal to the result of another (the second one listed in the element). For example:

<Equal>
    <Value>NEXT_ID</Value>
    <Value>MAX_POINT_INDEX</Value>
</Equal>

Here we are checking if the value of the "NEXT_ID" parameter is equal to the value of the "MAX_POINT_INDEX" parameter, and if it is then the return will be "True", and if it's not then the return will be "False".

`<StringEqual>`

This element is the same as the <Equal> element and will compare two parameters, only instead of comparing numeric values it will compare strings. If the text in each string is the same, then the return will be "True" otherwise it will be "False". For example:

<StringEqual>
    <Value>MyTextParameter</Value>
    <Text>Hello World</Text>
</StringEqual>

`<Arg />`

This self-closing element is used to define a simple expression using attributes applied to the element and a parameter. It is used within the different <Test> container elements, or within a <Loop>, to perform a simple conditional check that will return either "True" or "False". The attributes available are:

Attribute	Description	Type	Required
`Valid`	"True" if the parameter exists and if the value is not "0", "False", or an empty parameter.	String	No
`Check`	"True" if the parameter exists.	String	No
`NotEmpty`	"True" if the parameter exists and has a value of some kind.	String	No
`Match`	This will compare the given value with the content of the `Check` attribute and return "True" if it's the same.	String	No
`Different`	This will compare the given value with the content of the `Check` attribute and return "True" if it's different.	String	No

`<Value>`

This element has no attributes and can be used to specify a parameter to be used for a value in an expression, for example:

<Value>NEXT_ID</Value>

`<Number>`

This element has no attributes and is simply used to define a single number value, for example:

<Number>5</Number>

`<Text>`

This element has no attributes and is simply used to define a single string of text, for example:

<Text>Hello World</Text>

`<Constant>`

This element has no attributes and is simply used to define a single constant value, for example:

<Constant>32</Constant>

`<Loop>`

This element has no attributes and is used to create loops that will repeat over a specific number of iterations based on the type of loop being used. This element requires a <Setup> sub-element, and a <Do> sub-element, and may also contain an optional <Then> element which will be performed after the loop has completed all its iterations.

The available loop types are:

The For loop: The "for" loop type takes a base value (<From>) and a target value(<To>), then increments the base value by a given amount (<Inc>) each iteration of the loop, performing the XML within the <Do> element each iteration. You can see an example of this structure from the following section: <Loop> Example. Note that if no <To> value is specified, the loop will be terminated after 64 iterations (this limit does not exist if the <To> element is specified, and the maximum value becomes a signed 32bit integer).
The While loop: The "while" loop type works similarly to the "for" loop, only the <From> value will be incremented by <Inc> for as long as the <While> element evaluates to "True", and the moment it evaluates to "False" the loop will end. The setup for a while loop looks like this:
```
<Setup>
    <Param>ID</Param>
    <From>1</From>
    <Inc>1</Inc>
    <While>
        <Arg Valid="MY_PARAM_#ID#"/>
    </While>
</Setup>
```
In this example, the local parameter "ID" will be incremented from 1 for as long as the generated "MY_PARAM_#ID#" parameter is valid. Note that with this format it may seem possible to create "infinite" loops, however the simulation will not permit this and the loop will be terminated if it goes above the hard limit of 64 iterations. This limit can be avoided by also including a <To> element, in which case the loop will be terminated when the "while" evaluation returns "False" or the <To> value is reached. Also note that "while" loops are more computationally expensive than the "for" type.

It is worth noting that loops can also iterate backwards, so you can have a <From> value of 9, a <To> value of 0, and an <Inc> value of -1, and the loop will iterate 10 times, counting down from 9 to 0.

`<Setup>`

This is a container element that sets up the values that will be used to create the loop. It should contain <Param>, <From>, and <Inc> sub-elements and either <To> or <While> sub-elements. This element should always go before the main <Do> element, and has no attributes.

`<Param>`

With this sub-element you can define a parameter name that will be the variable used in the loop. This will be set to the initial <From> value and then the value will be incremented each iteration of the loop. The parameter can be used within the main <Do> element by enclosing it in # symbols, as explained in the section on Templates.

`<From>`

This element has no attributes and defines the starting value for the loop (used in both "for" and "while" loop types). This is a signed integer value.

`<To>`

This element has no attributes and defines the final value for the loop (generally used with "for" loop types, but can be used in "while" loops to increase the upper bound of the check from the limit of 64 iterations). This is a signed integer value.

`<Inc>`

This element has no attributes and defines the value to increment by each iteration of the loop (used in both "for" and "while" loop types). This is a signed integer value.

`<While>`

This element has no attributes and requires at least an <Arg /> sub-element, although it can use all the same sub-elements available to <Test> to perform more complex operations, as long as the result of the operations is either "True" or "False". The loop will continue to iterate for as long as the evaluation is "True" and only end when the evaluation is "False" or the upper limit is reached (64 iterations by default, although this can be modified using the <To> element).

`<Do>`

This element has no attributes and is the container element for the XML to be used each iteration of the loop. The contents of this element may be any valid model behavior XML.

`<Then>`

This element has no attributes and a container element used to define something that should be processed after the final iteration of the loop has been processed. Like the <Do> element, the contents of this element may be any valid model behavior XML.

`<True>`

This element has no attributes and is the container element for the XML to be used when a <Condition> evaluates to "True". The contents of this element may be any valid model behavior XML.

`<False>`

This element has no attributes and is the container element for the XML to be used when a <Condition> evaluates to "False". The contents of this element may be any valid model behavior XML.