Macros with Arguments

PML Customisation User Guide

Macros : PML Macros : Macros with Arguments

It is often convenient to write a macro in a generalised form, using parameters to represent dimensions, part numbers etc, 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

where 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 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 $< and $>.

The correct form for the preceding example is therefore

$M/arg.mac $<’Arg1a Arg1b’$> ’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 $<$> 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:


Macro Call	Effect
$M/demo.mac arg1 arg2	Omits third argument
$M/demo.mac arg1 $<$> arg3	Omits second argument
$M/demo.mac $,$,arg2$,arg3$.	Omits first argument