Dollar-sign expansions are definitions of text replacements used in the script or in expressions. This process is known as expansion - even if the new text is shorter. The replacement is made just before the script statement or the expression is evaluated. Technically it is a macro expansion.
A macro expansion always begins with '$(' and ends with ') ' and the content between brackets defines how the text replacement will be done. To avoid confusion with script macros we will henceforth refer to macro expansions as dollar-sign expansions.
Note! Macro expansion is unrelated to script macros (VB or Java script defined in the script module).
Note! A dollar-sign expansion is limited in how many macro expansions it can calculate. Any expansion over 1000 will not be calculated!
Dollar-Sign Expansion Using a Variable
When using a variable for text replacement in the script or in an expression, the following syntax is used:
$( variablename )
$( variablename) expands to the value in variablename. If variablename does not exist the expansion will be the empty string.
For numeric variable expansions, the syntax $( variablename ) will generate a number using the regional decimal separator, i.e. for many countries a decimal comma. Such an expansion should not be used for numbers inside the script since these must use decimal point. Instead the expansion $(# variablename ) should be used. (Note the hash sign). It always yields a valid decimal-point representation of the numeric value of variablename, possibly with exponential notation (for very large/small numbers). If variablename does not exist or does not contain a numeric value, it will be expanded to 0 instead.
After execution of the following script:
LET X = 7/2;
$(X ) will expand to 3,5 while $(#X ) will expand to 3.5.
load * from $(MyPath)abc.csv;
select * from table1 where Year=$(CurrentYear);
Dollar-Sign Expansion with Parameters
Parameters can be used in variable expansions. The variable must then contain formal parameters, such as $1, $2, $3 etc. When expanding the variable, the parameters should be stated in a comma separated list.
set X=$(MUL(3,7)); // returns '3*7' in X
let X=$(MUL(3,7)); // returns 21 in X
If the number of formal parameters exceeds the number of actual parameters only the formal parameters corresponding to actual parameters will be expanded. If the number of actual parameters exceeds the number of formal parameters the superfluous actual parameters will be ignored.
set X=$(MUL); // returns '$1*$2' in X
set X=$(MUL(10)); // returns '10*$2' in X
let X=$(MUL(5,7,8)); // returns 35 in X
The parameter $0 returns the number of parameters actually passed by a call.
set MUL='$1*$2 $0 par';
set X=$(MUL(3,7)); // returns '3*7 2 par' in X
Dollar-Sign Expansion with an Expression
Expressions can be used in dollar-sign expansions. The content between the brackets must then start with an equal sign:
$( =expression )
The expression will be evaluated and the value will be used in the expansion.
$(=Year(Today())); // returns e.g. '2008'
$(=Only(Year)-1); // returns the year before the selected one
Dollar-Sign Expansion of File - Include Statement
File inclusions are made using dollar-sign expansions. The syntax is then:
$( include=filename )
The above text will be replaced by the content of the file specified after the equal sign. This feature is very useful when storing scripts or parts of scripts in text files.
Just a small warning: be precise when dealing with special symbols and punctuation marks (You will be glad I said this once you start working with set analysis ) or posting on the community about these elements..
You can put a $-sign in front of a variable without any problem, and the variable will still be a variable. For example, this script statement
LET $Variable = 5 * 7;
will store the value 35 in variable $Variable. No expansion whatsoever. Here the $-sign is part of the variable name.
It's a different ball game when you use $(stuff) (the dollar sign is followed by opening and closing parentheses and inbetween there is ... stuff) because this doesn't define/reference anything. It's a construct that leads to text subsitution before anything else is done with the resulting expression or statement. The stuff inside the parentheses may consist of variable names, special elements (e.g. include = path), expressions, references to other variables, entire pseudo function calls etc. that may produce text output ranging from nothing at all to entire files.
And the mightiest thing about $-sign substituion is: you can use it almost anywhere!