&MACRO, NAME, ARG(1), ARG(2), ..., ARG(n),  \
     -OPTION(1), OPTVAR(1), CARG(1) = DEFAULT(1), ... \
     -OPTION(2), OPTVAR(2), CARG(2) = DEFAULT(2), ...
     COMMAND(1)
     COMMAND(2)
     .
     .
     .

     &ENDMACRO

Here, COMMAND(i) is any command which is either an internal command or a valid program command. The data following &MACRO is called the "picture" of the macro and NAME is the name of the macro and ARG(i) are the valid arguments to the macro. While there are no restrictions on the names for macros, one should be careful not to choose a name which will conflict with a valid program command. If the valid arguments are specified as above, then MOSES will parse the command for you and check for syntax errors. In some cases, however, one neither knows nor cares precisely the number or type of the arguments which will be specified. In this case, only the macro name should be specified when defining the macro. In all cases, the arguments actually supplied to the macro by the user will be available in the local variable ARGV. Thus, one can parse the values himself using &TOKEN and ARGV.

The arguments are "local variables" to the macro. When the macro is invoked (or executed), the user defines the values of the variables on the command. In other words, to execute the above macro, one would issue the command:

     NAME, ARG1, ARG2, ...., ARGn

Now, suppose that for some command in the macro, the user had used the value for ARG1 which was accomplished by including the line:

     COMMAND, %(ARG1)

When the macro is executed, the string %(ARG1) will be replaced by the string which is passed to the macro.

The options in macro arguments allow one to construct macros which have optional arguments. Any string on the macro definition line which begins with a - is considered to be a macro option. The string following the option name OPTVAR(i) is the name of the option variable which is set to .FALSE. if the option is not exercised when the macro is executed and to .TRUE. if the option was exercised. The other strings following an option (ARG(i)) are "optional data". The values of the optional data are all blank if they were not specified when the macro was executed. Additionally, one can specify a default value for this data, using the " = DEFAULT " syntax after the optional data.

When MOSES parses the picture, it will associate any "excess tokens" with the last variable in the picture. As an example, suppose that a macro was defined as:

     &MACRO COW A B -OPT OPT C
     &ENDMACRO

and that it was executed by:

     COW C D E -OPT THIS IS AN OPTION

The results of this would be that the variable OPT would be set to .TRUE., A would be set to C, B would be set to D E, and C would be set to THIS IS AN OPTION. The same result can be obtained through the use of defaults. Consider the following macro defined as:

     &MACRO COW A = C B = 'D E'  -OPT OPT C = 'THIS IS AN OPTION'
     &ENDMACRO

and executed by:

     COW  -OPT

This operation would behave the same as the previous example, but with fewer keystrokes. Notice the use of the single quotes to delimit data containing blanks.

By definition, a macro will be executed whenever the user specifies the macro name as a command. One may restrict when a macro can be executed by the following command:

     &M_ACTIVE, NAME, COMNAM

After this command has been issued, macro NAME will only be executed from menus which have COMNAM as a valid command. This command should be used when one creates a macro containing commands which must be executed from a specific menu.

Sometimes, one will define a macro with a name which conflicts with a command name. If this occurs, it can be rectified by changing the name of the macro. This is accomplished via the &M_CNAME command. Its form is:

     &M_CNAME, OLD_NAME, NEW_NAME

Also, if one defines a macro which does not work properly and he wishes to change it, he can delete the macro and start over. This is accomplished as:

     &M_DELETE, MACRO_NAME