Values of variables are used in two main ways:

explicitly: the variable name can be 'expanded' to its value on a CopiaFacts command or in text files such as cover sheets.

implicitly: a CopiaFacts application may look for the value of a specific control variable and use it to control its operations.

'Expanding' Variable Values

CopiaFacts system- and user-defined variables can be used in most commands, where they can be 'expanded' by replacement with the value of the variable.

To use the value of a variable, you normally precede its name with an @ symbol. For example:

$play_var @count amount ; speak value of count

In e-mail and SMS applications, the @ character is frequently part of the data.  So to use a variable on an e-mail or SMS command (one starting $email_ or $sms..), you should normally precede its name with a ` symbol (grave accent, ASCII 96). For example:

$email_from `myaddress

The @ and ` characters can be changed for an entire CopiaFacts system by using the $macro_char configuration command. We do not recommend doing this.

There are two ways in which variable values can be expanded from variable names using this @varname or `varname syntax.

Expansion of Configuration Variables

Specific variable names, FFBASE, FFUSER, FFJOBS, FFREQ, FFLOG, FFPO or PFC, when used at the start of filename, immediately followed by a backslash, are expanded in all CopiaFacts applications.

Expansion of Other Variables

All other variables are in general only expanded within the CopiaFacts Server Engine (COPIAFACTS) program.  There are exceptions to this rule which are noted for specific commands, for example the expansion of certain job variables on the $end_job_tasks command by the JOBMON program.

The configuration variables listed above are also expanded by the COPIAFACTS program when used other than as filename elements.

Using Control Variable Values

Many of the 'control variables' listed in Appendix D are known to CopiaFacts applications and are used by them to control their operations.  The documentation in the appendix shows which principal applications use each control variable.

Failure to Match a Variable Name

When no variable can be found to match the name, the expansion character and the variable name are removed.  To do this, the variable name is assumed to have ended, in the string being expanded, when:

white space or the end of the string is encountered, or

one of the characters []{}/\<>-"#!.,:;?| is encountered.

These word-terminator characters can be overridden for special purposes by assigning a value to the WORD_TERMINATORS variable in an infobox or FS file.

See also Naming Variables.

Encoding Universal Resource Identifiers (URI, URL, URN)

When including a variable value in an e-mail body text it is often necessary to have an encoded form of the variable, to form a link which is 'clickable' by the recipient.  This is achieved by using one of the special constructs:

``URI[text]

``URIQ[text]

This expansion mechanism has the following features:

The doubled e-mail expansion character (`) is required.

The encoding uses the default character lists specified by RFC 3986.

It is only available in expansions during e-mail processing for bodies, alternate bodies, and HTML attachments.

The text may contain (will normally contain) other variables of the form `varname which will be expanded before encoding.  In case the variable is undefined, you should avoid using a WORD_TERMINATORS override (see above) which excludes the symbols ]}| since this may cause the removal of the unmatched variable name to remove following text also.

The character-pairs {text} and |text| may be used as alternate delimiters.  You must avoid using a delimiter which may appear in the expanded text.

The URIQ form should be used in the 'query' part of a URI (following the ? symbol).  It differs from the normal encoding in that space characters in the encoded text are converted to + characters.  Plus signs in the original encoded text will have been converted to %2B.

The text is UTF-8 encoded before URI encoding.  You should only use this technique when the $email_charset is utf-8.

The special BCF%n and BCX%fieldname variable syntax, together with variables EMAIL_URL_FROM and EMAIL_URL_TARGET currently remain available, but are deprecated for new applications.