In general, variable definitions can not be 'nested', and variable assignments are not expanded recursively. The value specified on a $var_def command should not therefore contain an '@varname' expression.  For example, with the following statements:

$var_def NAME1 "Tim"

$var_def NAME2 "@NAME1"

$set_var PHRASE "My name is @NAME2"

The value of PHRASE will be set to "My name is @NAME1", which may not be the effect wanted.

There are a number of exceptions to this rule. Unfortunately they have accumulated over the years and in consequence in some cases there is more than one way of achieving the same result.

In the following descriptions, the characters @ and ` are used throughout: but if you have redefined these with $macro_char, your substitute characters will be used instead.

Variable Definitions

Special Configuration-File $var_def names

There are no special names.  All values are saved as entered.

Special User-Profile $var_def names

An definition for the TIME_OFFSET variable will be expanded if it contains an @variable name.

If the definition of USERINFO_EMAIL contains @@, it will be expanded (so that the two at-signs will become one).

For fax-receive USR files, variables defined with value starting @@ will be transferred, expanded, into an MCF file for the received fax.

All other values are saved as entered.

Special FS-file $var_def names

Values are expanded in a few special circumstances on $var_def commands in FS files:

Definitions of DATAx variables are always expanded.

Definitions of the system variables PHONE_ACCOUNT, ANSWER_TIME, ANSWER_XFER, TIME_OFFSET, and OB_ANI are always expanded and have the effects described in Appendix D.  (PHONE_ACCOUNT is actually only conditionally expanded).

When the value starts with an up-arrow (circumflex accent) (^), this character is effectively replaced with an @ and the value is is then expanded before use.  If you happen to need to define a value which starts with the ^ character, duplicate it. This syntax should not be used on definitions of the variables in the preceding two paragraphs, and the character substituted for ^ is always the regular variable expansion character, not the e-mail variable expansion character.

It is important to note that the three special cases described above expand variables when the FS file is first processed by the CopiaFacts engine. Thus they can only be usefully used to expand variables already defined earlier in the FS file or as system variables. By the time a retry or resubmit takes place, the values are already substituted. To assist with the sequencing, variable definitions with values starting with ^ are moved to the end of a job instance UJP file before a job is launched, so that they end up in the correct sequence in the launched FS files.

Special MCF-file $var_def names

These commands are written only by the system, including those transferred from the USR file as described above.

Variable Expansions

Broadcast Field Variables

When a BCF field name appears as the exact value of a variable being expanded, preceded , its value is always expanded recursively.  This is occasionally necessary to make use of broadcast field contents in other areas.  For example:

$var_def BCF6 "123.456.78.90"

$var_def EMAIL_BINDNAME `BCF6

Following the normal rules, EMAIL_BINDNAME is assigned the literal value "`BCF6".  But when this variable is expanded to select between multiple NIC cards to use for e-mail transmission, the BCF variable is recursively expanded and the correct value is used. Note that the e-mail expansion character (`) must be used to achieve this result.

Important note: this feature only works when the value of the variable starts with the appropriate expansion character, followed by BCF, followed by a number.  It cannot be used to expand a BCF field value in the middle of a string value.

Explicit Recursion Specification

For special purposes, an explicit specification of recursion can be used. This recursion occurs when the variable is referenced and expanded: at the time the variable is defined it follows the normal rule of no expansion, subject to the exceptions noted above.

Explicit specification of recursion is done by inserting either tilde (~) or up-arrow (^) or right-angle-bracket (>) between the variable expansion character and the variable name.  The expansion that is done is subtly different for each special character:

When using tilde, only the value of the referenced variable is recursively expanded (without the ~), and the value of the reference variable must include the expansion character:

$var_def name Steve

$var_def refname `name

$email_subject "Message from `~refname to someone"

The expansion proceeds as follows:

1. `~refname is expanded to the content of `refname, which is `name

2. `name is expanded to Steve.

Only the individual variable name is recursively expanded, and no additional characters are inserted, just the ones that appear in the variable values.  You can repeat this recursion for up to three levels.

When using up-arrow, the up-arrow is replaced by the appropriate expansion character and the whole expression from there onwards is expanded; then expansion continues again from the preceding expansion character.  In this case the value of the variable must not include the expansion character.

$var_def name Steve

$var_def refname name

$var_def toname Tim

$fax_header "Fax from @^refname to @toname"

The expansion proceeds as follows:

1. ^refname to @toname is changed to @refname to @toname

2. @refname to @toname is expanded to name to Tim

3. name to Tim is replaced in the string following the original @

4.  the remainder of the string is and then expanded again, so that the whole string becomes Fax from Steve to Tim.

When using right angle-bracket, the variable is first expanded in the normal way, to give a new value. Then a second look up is done for a variable named <value>, and only if found, its value replaces the original value.  This special expansion allows you to override, in a text-to-speech application, the pronunciation of a few of a set of predefined data items.  For example. consider a voice broadast (or an IVR application) that has looked up names in a company employee database, and where you need to speak the file:

<?xml version="1.0" encoding="ISO-8859-1"?>

<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US">

  <s>

    Please call and ask for `EMPLOYEE if you would like more information.

  </s>

</speak>

Some of your staff may have names which the TTS engine does not handle well, but you cannot modify the database you are looking in to obtain the names.  To solve this problem, just define those few names which are not pronounced correctly as 'angle-bracket variables', and provide a more accurate way of speaking them:

$set_var "<Mike Zhou>" "Mike <phoneme alphabet=""x-microsoft-ups"" ph=""JH AU""> Zhou </phoneme>"

Then change your reference to use the `> syntax:

<?xml version="1.0" encoding="ISO-8859-1"?>

<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US">

  <s>

    Please call and ask for `>EMPLOYEE if you would like more information.

  </s>

</speak>

The result is that when the value of the EMPLOYEE variable has a matching <value> defined, it will be double expanded, but when no such <value> variable is found, the EMPLOYEE is expanded normally.

When using this special expansion, the value of the <value> variable is limited to 512 characters, and the variable name following the @> must be a user variable (not a system variable) defined in the USR/UJP, FS or IIF command files.  The values defined with <value> can also be in the CFG file. The use of this syntax is not limited to TTS applications, of course.

Other Examples

The following is an example of simple recursion:

$var_def NAME1 "Tim"

$var_def NAME2 "@NAME1"

$set_var PHRASE "My name is @~NAME2"

In this case the value of PHRASE will be set to "My name is Tim" because having substituted NAME2 with its contents (which consist of "@NAME1") that expression is then evaluated recursively before insertion in the PHRASE variable.

Another specific use of this feature is for variables which supply the parameters from $email_... commands, for example EMAIL_SUBJECT.  In the special case of these parameters, the values are never expanded until the moment they are used in the e-mail text, so variables such as EMAIL_SUBJECT and EMAIL_FROM will contain `varname literals if these appear as parameters on the corresponding commands.  So for example you can use:

$var_def BCF2 "Steve Hersee"

$var_def PONUMBER "Order 123456"

...

$email_subject "Attn: `BCF2  Re: `PONUMBER"

which would expand in the e-mail subject itself to:

Attn: Steve Hersee  Re: Order 123456

but if you place `EMAIL_SUBJECT somewhere in the email body file, it would expand to:

Attn: `BCF2  Re: `PONUMBER

because the BCF variable does appear at the start of the value (see above) and because both remain unexpanded in the EMAIL_SUBJECT variable and are not recursively expanded when the e-mail body text is evaluated. To avoid this issue, use `~EMAIL_SUBJECT in the body text file instead. This syntax is unlike some of the others described above in that it is not required to be placed at the start of the string being evaluated.

Recursion limits

When recursion is used, explicitly or following the above rules for BCF variables, it is limited to three levels to reduce the damage from accidental self referencing, for example with:

$var_def NAME1 @~NAME2    ; do not do this

$var_def NAME2 @~NAME1    ; do not do this

$fax_receiver @NAME1

If you make this type of mistake, it will usually be less obvious an error than the above.  The resulting output will be clearly incorrect, but it will not be disastrously so by virtue of the limit.

Provided you avoid potential infinite recursion, there may be practical applications of the explicit recursion syntax used with multiple levels.