Show TOC

User-Defined Parameters and Parameter SubstitutionLocate this document in the navigation structure

You can create internal parameters and any number of user-defined parameters in the cnxml file.

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. This simple example includes long lines that have been split for readability:

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

External environment variables, such as STREAMING_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 on the second pass, \\ turns into a single backslash.

Special substitution syntax for Windows convenience:

$/{value}

$+/{value}

Replaces all the forward-slashes in the value with backslashes, for convenience of specifying the Windows paths that would otherwise require all slashes to be escaped.

$%{value}

$+%{value}

Replaces all the % with %% as escaping for Windows.

If the resulting string is passed to shell or cmd.exe for execution, shell or cmd.exe performs its own substitution as well.

This example uses 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="$STREAMING_HOME/bin/streamingconvert
  		${platformSsl==1?-e}
   	$+{dateFormat<>?-m '$dateFormat'}
				-c '$+{user=?user:$user}:$password'
				-p $platformCommandPort
				   <"$directory/$filename" |
				   $STREAMING_HOME/bin/streamingupload
				   ${platformSsl==1?-e} 
    -m $platformStream.$platformConnection
				-c '$user:$password' 
    -p $platformCommandPort"
/>