User-Defined Parameters and Parameter Substitution

All system and user-defined parameters can be referenced in the command or script arguments. These parameters behave in a similar way to shell substitution variables. The simple example shows long lines that have been split for readability:

    <Internal id="x_unixCmdExec" 
      label="Execute Command" 
      type="string"
      default="$ESP_HOME/bin/esp_convert 
						-p $platformCommandPort &lt;&quot;$directory/$filename&quot; | $ESP_HOME/bin/esp_upload 
						-m $platformStream.$platformConnection 
						-p $platformCommandPort"
    />

External environment variables, such as ESP_HOME, may be expanded, as well as internal system parameters (platformCommandPort) and user-defined parameters (filename). The full semantics for parameter expansion are:

$name
${name}
${name=value?substitution[:substitution]}
${name<>value?substitution[:substitution]}
${name!=value?substitution[:substitution]}
${name==value?substitution[:substitution]}
${name<value?substitution[:substitution]}
${name<=value?substitution[:substitution]}
${name>value?substitution[:substitution]}
${name>=value?substitution[:substitution]}

All forms with {} may have a + added after $ (for example, $+{name}). The presence of + means that the result of the substitution is parsed again and any values in it are substituted. The \ symbol escapes the next character and prevents any special interpretation.

The conditional expression compares the value of a parameter with a constant value and uses either the first substitution on success or the second substitution on failure. The comparisons == and != try to compare the values as numbers. The = comparisons and <> try to compare values as strings. Any characters like ?, : and } in the values must be shielded with \. The characters { and } in the substitutions must be balanced, all unbalanced braces must be shielded with \. The quote characters are not treated as special.

This form of substitution, $+{...}, may contain references to other variables. This is implemented by passing the result of a substitution through one more round of substitution. The consequence is that extra layers of \ may be needed for shielding. For example, the string $+{name=?\\\\} produces one \ if the parameter name is empty. On the first pass each pair of backslashes is turned into one backslash, and then on the second pass \\ turns into a single backslash.

If the resulting string is passed to shell or cmd.exe for execution, shell or cmd.exe would do its own substitution too.

Here is an example using some of the more powerful substitution features to define the execution command as in the simple example. However, you may make use of the conditional features to support optional authentication and encryption and an optional user-defined date format.

<Internal id="x_unixCmdExec"
		label="Execute Command"
	 type="string"
  default="$ESP_HOME/bin/esp_convert
  		${platformSsl==1?-e}
   	$+{dateFormat<>?-m '$dateFormat'}
				-c '$+{user=?user:$user}:$password'
				-p $platformCommandPort
				   <"$directory/$filename" |
				   $ESP_HOME/bin/esp_upload
				   ${platformSsl==1?-e} 
    -m $platformStream.$platformConnection
				-c '$user:$password' 
    -p $platformCommandPort"
/>