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:

	Copy Code
STORE '&gcX' TO gcX ? &gcX

Macro 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:

	Copy Code
STORE 'customer' TO gcTableName STORE 'company' TO gcTagName USE &gcTableName ORDER &gcTagName

use a name expression instead:

	Copy Code
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

	Copy Code
STORE SET('TALK') TO gcSaveTalk SET TALK OFF * * Additional program code * SET TALK &gcSaveTalk && Restore original TALK setting

See Also