Assign Value to Variable

$set_var varname [=] value [start size]

The $set_var command is used to instantiate and assign a value to a variable. Values may also be assigned to CopiaFacts system variables which have "writeable" status. User variables disappear at the end of the current call, but are copied to $var_def commands in the FS file created for a fax-on-demand request, for use on a cover sheet if required. If a user variable has the same name as a variable defined by a $var_def command in the configuration file, then the configuration file variable is hidden for the remainder of the call.

A small subset of the $set_var command options allows loop variables to be maintained and new variables defined in 'conditional text'.  For this purpose, $set_var commands may also be used in normal text files to be processed for cover sheets and HTML documents.

For a discussion about how variables are defined and used, please see the Expansion of Variables topics.  These topics also describe advanced features such as variables which recursively contain the name of another variable, and precedence of variables.

The parameters on this command are used as follows:

varname the name of a variable to be set, normally without an @ prefix. Other advanced uses of this parameter are described in Scripting.  Note that variable names starting MEMO and BCF have special properties and should therefore be avoided .
value the value to be assigned, either as a fixed value or as the contents of a variable using the normal @ syntax. The following special prefixes may be used with the value:
| the value is concatenated with (appended to the end of) the previous value of the variable, if any, and the result replaces the contents of the variable.
+ - / * % &the value is assumed to be numeric and is respectively added to / subtracted from / divided into / multiplied by / taken as a division remainder of / masked 'and' by, the original value of the variable. If either the contents of the variable or the given value is non-numeric then it is treated as if it were zero. If the variable is a new one for this call, it is also treated as zero. Arithmetic is performed with whole numbers, not fractions, and that there is a size limit that numbers must lie between -2147483647 and 2147483647. CopiaFacts does not check for overflow. If you attempt to divide by zero on the division or remainder operations, the result will be silently set to zero.
  You may optionally place an equals sign between the target of a $set_var assignment and the value to be assigned. The equals sign must have a space on either side of it if you do. This feature allows you to assign a value which starts with one of the special characters +-*/%| without processing the character specially. You would use this syntax, for example, when assigning a numeric variable which could contain negative values:

$set_var newvar = @negvar

  Without the equals sign in the above example, the existing value of newvar would be decremented if negvar contained a negative value starting with a minus sign; with the equals sign the negative value in negvar is assigned to newvar.
^This prefix causes the variable name which must follow it to have its value expanded twice before assignment, instead of once. The prefix must be followed by a simple variable name, not by an expression that contains variables to be expanded. (To assign a literal value starting with an up-arrow character, use two up-arrow characters.)

The above prefix characters should immediately precede the value, without intervening space.

The following values of the value parameter are treated specially:

$brThe value of varname is replaced by a copy which has all 'newline' sequences replaced by the string <br>.  This may be needed to process a memo field returned to an an application using the CopiaFacts database interface.  The value can then be used in a graphical cover annotation which has the HTML attribute. Both combinations of, and single values of, carriage return and line feed are recognized as newline sequences.
$clean The value of varname is replaced by a copy which has all characters stripped other than the digits 0..9. This can be used to clean a value returned as CSID to make it suitable for phone mask processing or dialing.
$ext The value in varname is assumed to be a filename and its file extension is changed to the following argument on the command (which should normally contain an initial '.'. If there is no following argument the extension is deleted.
$fn:expression The expression is evaluated as a function call to the CopiaFacts Application Support DLL, and the result assigned to the named variable.
$fileinfo In this case the following argument on the command is taken to be the full pathname of a file from which information is to be collected. The variable is set to a value which contains information about the file referenced, in the format described below, or set to empty if the pathname is invalid or the file is not found. You may substring this variable and reference the components in $play_var commands (with custom algorithm files) to describe the file to the caller. The format of the information returned is YYYYMMDDHHMMWS, where YYYYMMDD represents the date of the file, HHMM the time of the file, W the day-of-week of the file (Sunday=1), and the remaining characters in the value are the file size in bytes. The provided VMAIL.ALG sample algorithm file will speak the day, date and time from this variable string in US or UK English.
$lwc The value of varname is replaced by its lower-case equivalent.
$run This keyword has been disabled in version 7 and above. It allowed the specification of an operating system command which could be run to return a value of up to 16 characters to be assigned to the variable. If you have older applications which still need this capability, please contact Copia support.
$upatThis special keyword ("up-arrow => at-sign") is for advanced applications. The value of varname is replaced by one in which all instances of the defined e-mail variable expansion character (default `) are replaced by the normal variable expansion character (default @).  See the 'advanced' examples below for more information.
$upc The value of varname is replaced by its upper-case equivalent.
$''The value of varname is replaced by one in which any instances of single-quote are replaced by two single-quote characters.  This may assist with passing parameter values in $fn:expression evaluation for the CopiaFacts Application Support DLL (see the example below).
$""The value of varname is replaced by one in which any instances of double-quote are replaced by two double-quote characters.  This may assist with command syntax in $type fsfile infoboxes (see the example below).
start specifies the starting point in the string representation of value to select a substring. The first character is numbered 1. A start value of zero causes the string to be left-zero-filled to a size specified by the size value. The start value may also be specified as the numeric contents of a variable, for example @startvar.
size the maximum length substring to be selected from the string representation of value. If the start and size parameters lie outside the string, you will end up with an empty value. The size value may also be specified as the numeric contents of a variable, for example @sizevar.


Simple assignment:

$set_var myvar1 FOO

$set_var myvar2 @yourvar

$set_var myvar3 "You selected: "

Assignment to system variables:

; File 00012345.IIF

$if ADMIN $in @CLASS ; caller PIN was for system admin

$set_var CALLTYPE 1 ; force callback

$set_var RCVRFAX 6659841 ; set fax phone


$next_box 00012346

Computed assignment:

$set_var count +1

$set_var diffvar @positivevar1

$set_var diffvar -@positivevar2

Concatenated assignments:

$set_var date @month

$ser_var date |/

$set_var date |@day

$set_var date @month

$set_var date |月

$set_var date |@day

$set_var date |日

Concatenated space character (note the | is a prefix on the value, not a separate operator):

$set_var results one

$set_var results "| "   ; (not |" ")

$set_var results |two

Concatenated assignment with zero-expansion:

$set_var fpath @FFBASE\image

$set_var fpath |@numvar 0 8

Substringing from MM/DD/YYYY original:

$set_var curr_year @date4 7 4 ; set year to e.g. "2013"

Get file info:

$set_var fi $fileinfo "C:\faxfacts\image\00001234.TIF"

$set_var filesize @fi 14 6

$set_var filetime @fi 9 4 ; HHMM

Change file extension:

$set_var sumfile @JOB_INSTUJP

$set_var sumfile $ext .SUM

Write a value which may contain single quotes to a file:

$set_var response $''

$set_var fnresult "$fn:WriteTextLine(@filename,'@response')"

Pass a value which may contain double-quotes to an e-mail text command, for example in a post-process:

$type fsfile

$set_var EMAIL_ERROR $""

$email_text "The e-mail was not sent, the error was `EMAIL_ERROR"


Advanced Examples:

The $set_var and the $if family of commands also support an indirect mode in which the name of a variable can be placed in another variable under control of the infobox logic. To set a variable whose name is specified at run time, use an @ on the first (target parameter)  of the $set_var command to perform an indirect assignment:

$set_var varref flag ; set a basename for a new variable

$set_var index 7 ; set the variable number

$set_var varref |@index ; set varref to 'flag7'

$set_var @varref YES ; set FLAG7 to 'YES'

To use such a variable in a test, it needs to be de-referenced twice. If we have a variable name as the value of another variable, then it would be nice to be able to write @@varref to obtain the value of the original variable. Unfortunately, the @@ syntax is already reserved in CopiaFacts to expand to a single @ character, so we use the special syntax @^ instead (assuming the settings above):

$if @^varref = YES ; does FLAG7 contain YES?

$ifn @^varref = @empty ; has FLAG7 been defined?

The same syntax may be used whenever a variable has to be expanded from the name of another variable:

$set_var mainflag @^varref ; set variable mainflag to YES

Though they appear to be similar, the use of the single ^ prefix is very different from the @^ syntax. In this case the value is simply expanded twice. This can be useful when a variable may contain an expression containing variables, for example when a command parameter is returned from a support DLL function:

$set_var USRNAME "$fn:GetFFConfigData(@FS_FILENAME,$user_profile,1,1,true)"


Note that the variable expansion will always be done using the defined macro character (default @). To double-expand a variable which may contain an e-mail macro character (default `), it must be explicitly changed:

$set_var BODYFILE "$fn:GetFFConfigData(@FS_FILENAME,$email_body,1,1,true)"

$set_var BODYFILE $upat


Other complete scripting examples are shown in Sample Script Applications and Recursive Expansion of Vairiables.