Macros with Arguments

It is often convenient to write a macro in a generalized form, using parameters to represent dimensions, part numbers, and so on, and to assign specific values to those parameters only when the macro is to be run.

In the simplest case, parameters are allocated positions in the command lines as macro arguments by inserting escape codes of the form: $n.

Here, n is an integer in the range 1 to 9. These arguments are then specified as part of the command to run the macro. They follow the macro name, with spaces separating the individual arguments.

For example, if a macro named beam.mac includes the following command line:

NEW BOX XLEN $1 YLEN $2 ZLEN $3

Then the macro call $M/BEAM.MAC 5000 200 300 will run the macro and will set the lengths defined as $1, $2, $3 to 5000, 200, and 300, respectively.

Arguments may be either values or text, but note that a space in a text string will be interpreted as a separator between two different arguments.

Apostrophes in text arguments are treated as parts of the arguments, not as separators between them. For example, if a demonstration macro arg.mac includes the lines:

$P First Argument is $1

$P Second Argument is $2

$P Third Argument is $3

and is called by the command:

$M arg.mac 'Arg1a Arg1b' 'Arg2' 'Arg3'

the resulting output will be:

First Argument is 'Arg1a'

Second Argument is 'Arg1b'

Third Argument is 'Arg2'

whereas the intended output was:

First Argument is 'Arg1a Arg1b'

Second Argument is 'Arg2'

Third Argument is 'Arg3'

If you need to include spaces or newlines in an argument, you must enclose the argument between the escape codes

lt; and

gt;.

The correct form for the preceding example is therefore:

$M/arg.mac

lt;'Arg1a Arg1b'gt; 'Arg2' 'Arg3'

As an alternative, you may redefine the separator between arguments to be the escape code $, instead of a space.

If you do this, you must end the argument list with the escape code $.

Note:
The full stop is part of the escape code, not punctuation.

Using this convention, the preceding example becomes:

$M/ARG.MAC $,'Arg1a Arg1b'$,'Arg2'$,'Arg3'$.

If an argument is omitted when a macro is called, the $n in the macro command line is ignored. Whether or not this leaves a valid command depends upon the syntax which applies.

To avoid possible errors, a default setting may be defined for each argument. If the argument is omitted when the macro is called, the default setting will be used.

To define an argument’s default setting, use the command $Dn = default_string, where n is the argument number (1-9) and default_string is any sequence of characters ending in a newline.

The default setting may be specified at any point in the macro, but it will only be applied from that point onwards. It is usually best, therefore, to define any defaults at the beginning of the macro. If an argument has been specifically defined, a subsequent default specification is ignored.

Arguments may be omitted in the following ways:

• If the normal macro calling sequence is used (spaces as separators, Return as end-of-line marker), trailing arguments may simply be omitted.

• If a non‑trailing argument is to be omitted, the escape code

  lt;
  gt; must be used to replace the argument which is not required.

• If the $, argument separator is being used, the argument may be omitted from the list.

For example, if the macro demo.mac expects three arguments, the following calls to run the macro all omit one of the arguments: