A Standard Method of Passing Parameters in AML

Passing parameters to AML programs using &args is fairly straightforward. The typical AML programmer will write some ad-hoc code to handle passed parameters when needed, resulting in functional but non-standard parameter handling over a number of programs.

I developed a standard method for passing parameters that is easy and flexible, and requires only a few lines of code. By including the following fragment at the top of an AML file, you can pass any number of parameters to the program in a logical and consistent manner.

I recommend using this methodology for both programs called by users as well as for AMLs that act as subroutines for other AMLs. Since the variables can be named on the command line, it is very clear what value is being assigned to what variable, and the process is, in some respects, self-documenting.

&args opts:rest

/*****
/* Set defaults for passed parameters:


/*****
/* Process passed parameters:

&s opts %opts%
&if [quoteexists -bound %opts%] &then &s opts [unquote %opts%]

&do i = 1 &to [token %opts% -count]
    &s opt [extract %i% %opts%]
    &if [search = %opt%] = 0 &then &s [unquote %opt%] .TRUE.
    &else &s [before %opt% =] [unquote [after %opt% =]]
&end

/*****

The above code should be placed at the top of your AML; the &args line must be the first AML statement in your program, though comments and blank lines may precede it.

How it works

The &args opts:rest statement takes all parameters that were passed to your AML and puts them into the variable opts. (You could add some other variable names between the &args command and the opts:rest if you wanted to pass required values without using named parameters, as shown in the example below.)

The main bit of code processes all parameters that were passed to the program, and sets program variables accordingly. If a particular option was not specified, the associated variable will retain the default value assigned to it.

Parameter syntax

Parameters can be specified in one of two ways:

param	The variable param is set to .TRUE.
param=value	The variable param is set to value

Any number of parameters may be passed in this manner, but should be separated by at least one space. Strings containing spaces should be surrounded by single quotes. Parameters can be passed in any order.

Example

/* Sample program
&args mainoption opts:rest


/*****
/* Set defaults for passed parameters:

&s shape poly
&s quiet .FALSE.
&s fastmode .FALSE.
&s number 10
&s string default

/*****
/* Process passed parameters:

&s opts [unquote %opts%]
&do i = 1 &to [token %opts% -count]
    &s opt [extract %i% %opts%]
    &if [search = %opt%] = 0 &then &s %opt% .TRUE.
    &else &s [before %opt% =] [unquote [after %opt% =]]
&end

/*****
/* Main program

&ty mainoption = %mainoption%
&ty shape = %shape%
&ty quiet = %quiet%
&ty fastmode = %fastmode%
&ty number = %number%
&ty string = %string%

Arc: &r sample tiger shape=line quiet string='Two words'

will produce the following output:

mainoption = tiger
shape = line
quiet = .TRUE.
fastmode = .FALSE.
number = 10
string = Two words

and

Arc: &r sample habitat fastmode quiet number=15 string=OneWord

will produce the following output:

mainoption = habitat
shape = poly
quiet = .TRUE.
fastmode = .TRUE.
number = 15
string = OneWord

As you can see, it is easy to mix required and optional parameters and switches, and this technique provides a simple way to set default values. By using this code in all your AMLs that accept passed parameters, you will make your programs more consistent and easier to understand.

Comments or questions to: