Click above to get retro games delivered to your door ever month!

&              Macro substitution                         (Macro)


Syntax:        &<memvarC>[.]

Operand:       <memvarC> is a character memory variable that
               contains a string of characters to be substituted for a
               complete expression or a literal command argument when
               encountered at runtime.  All or a part of a literal
               argument can be substituted.

Options:       The period (.) is the macro terminator and is used to
               indicate the end of the macro variable.  It is useful
               where you wish to only substitute a portion of an
               identifier or expression.

Description:   The macro operator (&) forces Clipper to substitute the
               contents of the <memvarC> for the variable reference.
               The contents are then evaluated.

               Note: In instances where a macro variable is used to
               substitute for a literal command argument, generally you
               can use an expression in place of the literal argument if
               bounded by parentheses.  For example, the following:

                    file = "Invoices"
                    USE &file.

               can be replaced with:

                    file = "Invoices"
                    USE (file)

               Consult the syntax reference for the specific command
               arguments that support this extended expression
               capability.

Notes:         . Arrays: References to arrays and array elements can
                 be made with macro variables with one exception: the
                 brackets cannot be within a macro variable when
                 DECLAREing the array.  Note, however, you cannot use an
                 array element as a macro variable.  To do this, you
                 must first assign the contents of the array element to
                 a macro variable and then expand the macro variable.
                 For example, the following returns the contents of a
                 field:

                    PRIVATE fields[FCOUNT()]
                    AFIELDS(fields)

                    fld_name = fields[1]
                    ? &fld_name.

               . Command keywords: Clipper will not expand macro
                 variables containing command keywords.  For example,
                 you can not perform the following:

                    indx_command = "SET INDEX TO Ntx1"
                    &indx_command

               . Lists as arguments of commands: As stated above,
                 Clipper will not fully expand a macro variable to
                 substitute for a list as an argument of a command.
                 Instances of this are arguments of the FIELDS clause
                 and SET INDEX.  An exception are the arguments of SET
                 COLOR.  If you attempt this, the expansion terminates
                 with the first comma (,) character.  For example, in
                 this example only the first index file will opened:

                    indx_list = "Ntx1, Ntx2"
                    SET INDEX TO &indx_list

                 In this case, use a macro variable for each argument in
                 the list.  For example:

                    indx_1 = "Ntx1"
                    indx_2 = "Ntx2"
                    SET INDEX TO &indx_1, &indx_2

               . Macro conditions: The number of conditions that a
                 macro variable can hold is limited only by its
                 substitution's total complexity.  That is, a macro is
                 limited to:

                   . 254 characters
                   . 15 simple conditions
                   . Complexity of conditions (the more complex, the
                     less number of conditions)

               . Nested macros: The expansion and evaluation of
                 macro variables in Clipper is quite dynamic allowing
                 you to define nested macros.  In Clipper, after
                 assigning a macro variable to another macro variable,
                 the original macro variable can be expanded resulting
                 in the expansion of the second macro variable and
                 evaluation of its contents.  For example:

                   one   = "&two"
                   two   = "three"
                   three = "hello"

                   ? &one               && Result: "hello"

               . Procedures and functions: Procedure and function
                 calls can be referenced using macro variables.  With
                 DO, the macro variable reference to the procedure
                 argument can comprise all or part of the procedure
                 name.  With a call to a function (built-in or
                 user-defined), the macro variable reference must
                 include the function name and all of its arguments.
                 See the examples below.

               . References into overlays: Procedures and
                 user-defined functions used in overlays and referenced
                 using a macro variable must be declared EXTERNAL.

               . TEXT...ENDTEXT: Macro variables referenced within a
                 TEXT...ENDTEXT construct are expanded.  Note that a
                 field cannot be expanded so you must first assign the
                 field value to a memory variable and then reference the
                 memory variable as a macro variable within the
                 TEXT...ENDTEXT.  For example:

                    mem_var = Field
                    TEXT
                       This is text with a macro &mem_var..
                    ENDTEXT


----------------------------------- Examples -------------------------------

     var1 = "test string"
     var2 = "var1"
     ? var1                             && Result: test string
     ? var2                             && Result: var1
     ? &var1.                           && Result: test string


   The following example uses a macro variable to substitute for an
   expression:

     string = "test string"
     macro_var = "SUBSTR(string, 1, 4)"

     ? &macro_var.                      && Results: "test"


   These examples use macro variables to call procedures and a
   user-defined function:

     proc_name = "Say_get"
     DO &proc_name.

     menu_number = "1"
     DO Menu&menu_number.

     menu_name = "menu1(parm1, parm2, parm3)"
     ? &menu_name.


   This example uses a macro variable to refer to an array as well as an
   element:

     array_name    = "mega_array"
     array_element = "mega_array[1]"

     * Create the array using a macro variable.
     PRIVATE &array_name.[5]

     * Refer to the array element using macro variables.
     ? &array_name.[1]
     ? &array_element.