MODEL BEHAVIORS PARAMETERS

Within the model behaviors XML you will be using many parameters. In the context of the behavior XML a parameter is used to store a value that you will want to use later in some function or element. They are created within some specific scopes defined by the following nodes:

  1. <Parameters>
  2. <UseParametersFn>
  3. <UseTemplate>
  4. <UseInputEvent>
  5. <ReturnParameters>
  6. <SaveParameters>

 

Components essentially push a scope on the stack of parameters, and parameters defined within a component will be valid for the whole parsing of the elements defined in the same scope or below. Parameters are a fundamental part of using model behaviors, and at their most basic they consist of an identifier and a value. An identifier can only consist of a combination of the following characters:

  • 0 to 9
  • A to Z and a to z
  • _ and -

for example:

<A_PARAMETER>A parameter value</A_PARAMETER>

The value of a parameter can be anything as long as it is written with ASCii characters, however it should be noted that the value of parameters have to follow the strict XML restrictions, which means that some characters have to be escaped:

 

Character Escaped character
> (greater-than) &#62; or &gt;
< (less-than) &#60; or &lt;
& (ampersand) &#38;

 

Once defined a parameter can be used in the scope it was defined in, and referencing a parameter value is done using the # symbol, as shown in this example:

<Parameters Type="Default">
    <A_PARAMETER>Hello</A_PARAMETER>
</Parameters>
<Parameters Type="Override">
    <A_PARAMETER>#A_PARAMETER#, world!</A_PARAMETER>
</Parameters>
<!-- Here A_PARAMETER value will be "Hello, world!" -->

 

Note, however, that you cannot use a parameter in the same node that it was defined in, for example, this would give an error:

<Parameters Type="Default">
    <A_PARAMETER>Hello</A_PARAMETER>
    <AN_OTHER_PARAMETER>#A_PARAMETER#, world!</AN_OTHER_PARAMETER>
    <!-- Error, A_PARAMETER value is undefined -->
</Parameters>

 

A parameter can be defined several time with the same identifier, depending on the scope, and when this happens the parameter value will be overridden. The only exception to this rule is when using the "Default" override, which ensures that if the parameter was defined before, a redefinition will not override the previous value. This default override rule is only used by the <Parameters> and <SaveParameters> elements and is specified using the Type or Append attribute. The sample below shows how things work when the Type is omitted or set to "Override" for a parameter (save parameters are explained in the section below):

<Parameters Type="Default">
    <A_PARAMETER>A value</A_PARAMETER>
</Parameters>
<Parameters Type="Override">
    <A_PARAMETER>An other value</A_PARAMETER>
</Parameters>
<!-- Here A_PARAMETER value will be "An other value" -->
<Parameters>
    <A_PARAMETER>A value</A_PARAMETER>
</Parameters>
<Parameters>
    <A_PARAMETER>Another value</A_PARAMETER>
</Parameters>
<!-- Here A_PARAMETER value will be "Another value" -->

 

And this sample shows what happens when Type is set to "Default":

<Parameters Type="Default">
    <A_PARAMETER>A value</A_PARAMETER>
</Parameters>
<Parameters Type="Default">
    <A_PARAMETER>Another value</A_PARAMETER>
</Parameters>
<!-- Here A_PARAMETER value will be "A value" -->

 

 

Save parameters

A parameter save using <SaveParameters> can be defined anywhere <Parameters> can be defined. The save is given a unique identifier value and a list of parameters to save, which are then saved to a stack separate to the main one . For example: 

<SaveParameters ID="Save_ID">
    <A_PARAM>A Value</A_PARAM>
</SaveParameters>

 

At it's most basic, this way of saving parameters is destructive, meaning that - unless an Append rule is defined - the save will be reset if it already existed, and only the new parameters being set for saving will be stored:

<SaveParameters ID="My_Saved_Parameters">
    <A_PARAM>A Value</A_PARAM>
</SaveParameters>
<SaveParameters ID="My_Saved_Parameters">
    <B_PARAM>Another Value</B_PARAM>
</SaveParameters>
<!-- /!\ warning A_PARAM has been deleted -->
<!-- the saved parameters with ID Another_Save_ID has a parameter -->
<!-- B_PARAM with value "Another Value" -->

 

Using an Append rule will prevent this behavior and give you some control over how any existing parameter values should be handled. Similar to the <Parameters> element, this is done by setting the Append attribute, with the "Default" behaviour being to append parameters onto the save stack, as shown in the example below:

<SaveParameters ID="My_Saved_Parameters">
    <A_PARAMETER>A value</A_PARAMETER>
</SaveParameters>
<SaveParameters ID="My_Saved_Parameters" Append="Default">
    <B_PARAMETER>An other value</B_PARAMETER>
</SaveParameters>
<!-- Within My_Saved_Parameters A_PARAMETER value will be "A value" -->
<!-- Within My_Saved_Parameters B_PARAMETER value will be "An other value" -->

 

The Append attribute will also modify how existing parameters will behave when saved to the stack. When set to "Default" and you save a parameter with the same name as one already saved, the parameter will not be overridden:

<SaveParameters ID="My_Saved_Parameters">
    <A_PARAMETER>A value</A_PARAMETER>
</SaveParameters>
<SaveParameters ID="My_Saved_Parameters" Append="Default">
    <A_PARAMETER>An other value</A_PARAMETER>
    <!-- A_PARAMETER won't be overriden here as we append with the "default" rule -->
</SaveParameters>
<!-- Within My_Saved_Parameters A_PARAMETER value will be "A value" -->

 

However, when the attribute is set to "Override", it will be:

<SaveParameters ID="My_Saved_Parameters">
    <A_PARAMETER>A value</A_PARAMETER>
</SaveParameters>
<SaveParameters ID="My_Saved_Parameters" Append="Override">
    <A_PARAMETER>An other value</A_PARAMETER>
    <!-- A_PARAMETER will be overriden here as we append with the "override" rule -->
</SaveParameters>
<!-- Within My_Saved_Parameters A_PARAMETER value will be "An other value" -->

 

 

Load parameters

The element <LoadParameters /> can be used to load a copy of the contents of the given save stack ID onto the current parameter stack. Note that performing a load operation is not destructive, and loaded parameters will still exist in the save with the same value. Essentially, the action is always to load a copy.

<SaveParameters ID="Save_ID">
    <A_PARAM>A Value</A_PARAM>
</SaveParameters>
<LoadParameters ID="Save_ID"/>
<!-- Stack now has a parameter A_PARAM with a value "A Value" -->
<!-- Save_ID still exists -->

Note that if a save isn't found for the given ID then the load will simply fail silently. The existence of a saved parameter stack can be checked using the <Condition> attribute CheckSavedParameters where the attribute value is the ID of the save stack to look up.

 

 

Remove saved parameters

The element <RemoveSavedParameters /> can be used to remove a saved stack of parameters.

<SaveParameters ID="Save_ID">
	<A_PARAM>A Value</A_PARAM>
</SaveParameters>
<LoadParameters ID="Save_ID"/>
<RemoveSavedParameters ID="Save_ID"/>
<!-- Stack now has a parameter A_PARAM with a value "A Value" -->
<!-- Save_ID doesnt exist anymore -->

Similarly to <LoadParameters />, if a save isn't found for the given ID, the removal will fail silently.

 

 

Macros

Macros are a kind of a constant parameter, where the value of a macro is defined in one place and can then be used anywhere. The lifetime of a macro is the same as the global scope, which is to say the same as the <Template>, <InputEvent>, and <ParametersFn> elements. The global scope simply keeps track of which item is defined as a "global" item and maps an identifier to the definition value. In the case of macros, anywhere you’d use the #PARAMETER# syntax you can safely use the @MacroName syntax, for example:

<Macro Name="16K">16384</Macro>
<Parameters Type="Default">
    <A_PARAMETER>@16K</A_PARAMETER>
</Parameters>
<!-- A_PARAMETER value is "16384" -->

 

 

Parameter Attributes

A parameter value can be processed by adding the Process attribute to it. Processing a parameter can be used to simplify a calculation or make some simple string operations. Processing will interpret the value as RPN and execute it, then the return value will be assigned to the parameter value, overriding its previous contents.

 

Attribute Description Type Required
Process This processes the contents of the parameter ins a specific way, as explained below.

String:

  1. "Int"
  2. "Float"
  3. "Param"
  4. "String"
  5. "Macro"
 No

 

The attribute types listed above will do the following:

 

  • Float
    Compute the contents of the element using RPN, with an float result of up to 6 decimal places: 
    <Macro Name="16K">16384</Macro>
<Parameters Type="Default">
    <ONE_TENTH_OF_16K Process="Float">@16K 10 /</ONE_TENTH_OF_16K>
</Parameters>
<!-- ONE_TENTH_OF_16K value is "1638.400000" -->
  • Int
    Compute the contents of the element using RPN, with an integer result, truncating the decimal part (you can use near in the RPN to round the number to avoid unwanted truncation): 
    <Macro Name="16K">16384</Macro>
<Parameters Type="Default">
    <ONE_TENTH_OF_16K Process="Int">@16K 10 /</ONE_TENTH_OF_16K>
</Parameters>
<!-- ONE_TENTH_OF_16K value is "1638" -->
  • Param
    Get the content of a parameter by name when it is not possible to use #PARAM_NAME#. What this means is that the # parameter will first be evaluated, then it's value will be used to create the parameter within the node. Essentially the value of the parameter will be looked up in the parameter stack for a matching parameter identifier and - if a parameter is found - its value will be copied otherwise the parameter will be declared "empty": 
    <Parameters Type="Default">
    <PARAM_ID>0</PARAM_ID>
    <PARAM_0>A value</PARAM_0>
    <PARAM_1>An other value</PARAM_1>
</Parameters>
<Parameters Type="Default">
    <A_PARAM Process="Param">PARAM_#PARAM_ID#</A_PARAM>
</Parameters>
<!-- A_PARAM value is "A value" -->
  • String
    Allow a parameter to be processed as a string using the RPN String Operators: 
    <Parameters Type="Default">
    <HELLO_WORLD_UC Process="String">'Hello, world!' uc</HELLO_WORLD_UC>
</Parameters>
<!-- HELLO_WORLD_UC value is "HELLO, WORLD!" -->
  • Macro
    This will look for a <Macro> with the provided name and if it exist copy it’s value to the parameter. Useful when one wants to programmatically choose one macro. If the macro is not found the parameter will be "empty": 
    <Macro Name="GetMyVar">(L:1:XMLVAR_MY_VAR)</Macro>
<Macro Name="GetAnotherVar">(L:1:XMLVAR_ANOTHER_VAR)</Macro>
<Parameters Type="Default">
    <VAR_NAME>MyVar</VAR_NAME>
</Parameters>
<Parameters Type="Default">
    <GET_VAR Process="Macro">Get#VAR_NAME#</GET_VAR>
</Parameters>
<!-- GET_VAR value is "(L:1:XMLVAR_MY_VAR)" -->

 

 

Conditional Statements

Parameters definition is compatible with conditional statements, ie: a parameter can be defined depending on an other parameter value, as shown in the example below:

<Parameters Type="Default">
    <USE_PARAMETER_A>True</USE_PARAMETER_A>
</Parameters>
<Parameters Type="Default">
    <Condition Valid="USE_PARAMETER_A">
        <True>
            <A_PARAMETER/>
        </True>
        <False>
            <B_PARAMETER/>
        </False>
    </Condition>
</Parameters>
<!-- A_PARAMETER is defined, B_PARAMETER is undefined -->

 

In the case of a <Loop> within a parameter definition, the parameters defined within the <Do> or the <Then> will be given the scope of the parameter definition the loop is defined in, eg:

<Parameters Type="Default">
    <Loop>
        <Setup>
            <Param>PARAM</Param>
            <Value>VALUE</Value>
            <Parameters>
                <PARAM_A>1</PARAM_A>
                <PARAM_B>2</PARAM_B>
                <PARAM_C>3</PARAM_C>
            </Parameters>
        </Setup>
        <Do>
            <#PARAM#>My ID is #VALUE#</#PARAM#>
        </Do>
    </Loop>
</Parameters>
<!-- PARAM_A is defined with a value "My ID is 1" -->
<!-- PARAM_B is defined with a value "My ID is 2" -->
<!-- PARAM_C is defined with a value "My ID is 3" -->

You can find more information on conditional statements from the following page:

 

Related Topics

  1. Aircraft XML and Model CFG
  2. Model Behaviors
  3. Using Model Behaviors
  4. Template Explorer