Commands > Expansion of Variables > Recursive variable definition

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.

Broadcast Field Variables

When a BCF field name appears as the exact variable value being expanded, 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.

Special FS-file $var_def names

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

•	Assignments to DATAx variables are always expanded.

•	Assignments to 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 at-sign (or the value defined on the $macro_char command) and the value is then expanded before assignment. If you happen to need to assign a value which starts with the ^ character, duplicate it. This syntax should not be used on assignments to the variables in the preceding two paragraphs, and the value 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.

Explicit Recursion Specification

For special purposes, an explicit specification of recursion can be used. This recursion occurs when the variable is 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 is done by inserting tilde (~) between the variable expansion character (normally @ or `) and the variable name:

$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.

A 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 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.

Topic url: http://www.copia.com/support/refmanual/index.html?recursive_variable_definition.htm