Commands > Infobox Information File [IIF] > $set

Assign Value to Variable

$set_var varname [=] value [start size]

The $set_var command is used to instantiate and assign a value to a user 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.

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.

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 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 simply 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 following values of the value parameter are treated specially:

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

$upat

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

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.

Examples:

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

$endif

$next_box 00012346

Computed assignment:

$set_var count +1

$set_var diffvar @positivevar1

$set_var diffvar -@positivevar2

Concatenated assignment:

$set_var date @month

$set_var date |@day

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. "1999"

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

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)"

$set_var USRNAME ^USRNAME

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

$set_var BODYFILE ^BODYFILE

Topic url: http://www.copia.com/support/refmanual/index.html?%24set_var.htm