& Command
Performs macro substitution.
& VarName[.cExpression]
Parameters
& VarName
Specifies the name of the variable or array element to reference in the macro substitution. Do not include the M. prefix that distinguishes variables from fields. Such inclusion causes a syntax error. The macro should not exceed the maximum statement length permitted in Visual FoxPro.A variable cannot reference itself recursively in macro substitution. For example, the following generates an error message:
STORE '&gcX' TO gcX ? &gcXMacro substitution statements that appear in DO WHILE, FOR, and SCAN are evaluated only at the start of the loop and are not reevaluated on subsequent iterations. Any changes to the variable or array element that occur within the loop are not recognized.
[. cExpression]
The optional period (.) delimiter and .cExpression are used to append additional characters to a macro. cExpression appended to the macro with .cExpression can also be a macro. If cExpression is a property name, include an extra period (cExpression..PropertyName).
Remarks
Macro substitution treats the contents of a variable or array element as a character string literal. When an ampersand (&) precedes a character-type variable or array element, the contents of the variable or element replace the macro reference. You can use macro substitution in any command or function that accepts a character string literal.
Tip
Whenever possible, use a name expression instead of macro substitution. A name expression operates like macro substitution. However, a name expression is limited to passing character strings as names. Use a name expression for significantly faster processing if a command or function accepts a name (a file name, window name, menu name, and so on). For additional information on name expressions, see Name Expression Creation.
While the following commands are acceptable:
STORE 'customer' TO gcTableName
STORE 'company' TO gcTagName
USE &gcTableName ORDER &gcTagName
use a name expression instead:
USE (gcTableName) ORDER (gcTagName)
Macro substitution is useful for substituting a keyword in a command. In the following example, the TALK setting is saved to a variable so the setting can be restored later in the program. The original TALK setting is restored with macro substitution.
Note
Performing concatenation with a single ampersand (&) when attempting to include double ampersands (&&) in a string literal might produce undesirable results. For example, suppose you assign the string "YYY" to a variable, BBB. Performing concatenation using "AAA&" and "&BBB" replaces "BBB" with "YYY" so instead of getting the result "AAA&&BBB", the result is "AAA&YYY". For more information, see && Command.
Example
STORE SET('TALK') TO gcSaveTalk
SET TALK OFF
* Additional program code
SET TALK &gcSaveTalk && Restore original TALK setting
See Also
Concepts
Macro Substitution (Visual FoxPro)