& 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
  ? &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:

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.

Example

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

See Also

Commands | STORE Command | && Command | Macro Substitution