The FIGARO Parameter System.

Keith Shortridge, AAO

28th April 1995.

1. Introduction

This document is a reasonably formal description of the Figaro parameter system, as implemented in Figaro 4.1. This is the version of Figaro that runs `standalone' -- commands are entered from the command line of the system on which it runs (which can be VMS or one of several flavours of UNIX), and it does not depend on some other environment such as the Starlink ADAM system. Since some of the major differences between this version of Figaro and the ADAM version lie in the way parameters are handled, it is important to be sure just which version of Figaro you are using.

The parameter system is the main way in which the user of a Figaro program communicates with that program. By abstracting user interaction into nothing more than the setting of various parameters to specific values, it is possible to write a program that can be used in a number of different environments: a `batch' mode is an obvious example, but there are others.

The description given here is not intended to be an introduction to the use of Figaro. If you are quite new to Figaro you may find it worth glancing at the document called `FIGARO. An Introduction for Beginners', which has a more tutorial approach. This document is intended to be the formal description of the parameter system: the place you look when you want to know exactly what the rules are.

The rules governing the parameter system are the same in all cases, and are essentially the same whatever the underlying operating system. However:

* There are system dependencies when a file name has to be specified, since the filename syntax differs from system to system.

* There are some cases -- particularly under UNIX -- where care has to be taken to prevent the command interpreter intercepting certain symbols, such as `{` and `}' that are intended for the Figaro parameter system.

Where a command has to be given differently under UNIX because it contains such special characters it is shown separately for VMS and for UNIX. In these cases `quotes' are used around the specifications that contain the problem characters. There are other ways of getting the same effect, for example by escaping the problem characters by prefacing them with the `\' escape character.

This document does not cover the ways in which the Figaro parameter system is accessed by a Figaro application program. For that, you should refer to the `Figaro Programmer's Guide'. The information in this document is designed for the user of Figaro rather than the writer of application programs.

2. Commands and parameters

Figaro programs are invoked from the command line prompt of the operating system. The command line prompt is not shown in the examples in this document. Figaro programs may also be invoked from command language scripts (shell scripts under UNIX, command procedures under VMS), or through calls to the FIGARO subroutine provided as part of the Callable Figaro system.

We call a `Figaro command' an operating system command that results in the running of a Figaro application program. So `splot' is a Figaro command, as is `exam' or `image'.

Additional information is communicated to a Figaro program through a set of named parameters. For example, one of the parameters for the plotting program `splot' gives the name of the file to be plotted. Another gives the colour to be used for the lines of the plot. Most Figaro programs get all the information they need from the user through their parameters. A few Figaro programs are classed as `inherently interactive' (`arc', the interactive arc line fitting program, is a good example) and these may carry out a `prompt, response' dialogue with the user, but this style of user-interaction is discouraged since this makes them hard to use in any sort of batch mode. A Figaro program that gets all its information from parameters can have them all specified on the command line and this allows such a program to be used easily in a batch mode.

There are five basic types of Figaro parameters:

Character: A character parameter is nothing more than a character string. There are few restrictions on what the characters can be, and the case in which they are entered is left unchanged by the parameter system.

File: A file parameter is also a character string, but is restricted in what it can contain. It is expected to specify a Figaro data file -- or an item within that data file. File parameters can be classed as `input' files, in which case the file in question must already exist, or as `output' files, which need not already exist.

Numeric: A numeric parameter has to be a single valid number. Depending on the context in which it is used, a numeric parameter may be converted to an integer by the application program, in which case this is usually done by truncating it rather than rounding it, but this is under the control of the individual program. The parameter system treats all numeric parameters as floating point, and tries to accept them in as unrestricted a way as possible. So the number 5 can be specified as `5', `5.0', `0.5E1' etc. Arithmetic expressions are also accepted by the parameter system.

Numeric array: A numeric array is a set of numeric values. The comments about truncation and format made for a single numeric parameter also apply to the individual elements of a numeric array.

Keyword: A keyword parameter has a simple logical value: it is either `true' or `false'.

In addition, Figaro parameters may be classified as `hidden'. A hidden parameter is one that the writer of the application wanted to make available to the user, but thought that it would be used only rarely. So the parameter system does not generally trouble the user with prompts for hidden parameters. The parameter for `splot' that controls the colour used for the plotting is a hidden parameter since the author assumed that in most cases the user would not want to be bothered having to specify the plot colour. (When `splot' was first written, most terminals were monochrome.)

All Figaro parameters have names, and they also have minimum abbreviations for these names. The minimum abbreviation accepted is under the control of the application writer.

There is a specified order for the Figaro parameters of a given application. Again, this order is specified by the application writer, but is usually (but not always) the order in which the parameters are prompted for if not specified explicitly on the command line. This order exists so that parameters may be specified on the command line by position rather than by name. Keywords are an exception to this. Keywords cannot be specified in a form that does not include the name of the actual keyword, so there is no need to use their position in the command line to identify them, and so they have no defined position.

3. Reset and Default values

Each Figaro parameter has a `default' value and a `reset' value. The default value is used if no value is provided explicitly for the parameter by the user. For keywords, which in Figaro are thought of as ways of providing one-off control for a single invocation of a particular program, the default value is supplied by the program. For numeric and character parameters the default value depends on the recent use of the system, and in most cases the default value is just the previous value of the parameter. A program may modify the default value of a parameter, but this is rarely used except in the case of parameters used to specify output data files, where the program usually sets the default so that it is the same as one of the input data files. (This is because such an in situ operation is much more efficient than creating a new data file.) Of course, there are cases where a parameter has not been used before, and in this case there is no previous value that can be used. In this case, a `reset' value supplied by the program is used.

Sometimes, this reset value is useful in other cases. You may redisplay the same image many times, each time tweaking one parameter to get the exact result you want. In this case, it makes sense that the default value for each parameter is the one used previously. However, once you move to a new image, it may make more sense to use the reset values supplied by the display program, since these usually have been calculated so as to give an acceptable -- if not ideal -- display. So Figaro provides a means (the `RESET' keyword mentioned in the section `Special keywords') to specify that reset values should be used as the default values.

For keywords, the reset value provided by the program is usually that used as the default value. This difference in the way default values are set for keywords on the one hand and numeric and character parameters on the other is generally a useful feature, so long as programs do use keywords as intended, to control some one-off, relatively unusual behaviours such as suppressing the erase of a display before putting up a new display (as `splot' does). The parameter system does provide a means to `lock' a default value for a keyword, however, if this is needed.

4. User variables

Figaro maintains a set of variables called `user variables'. These can be set explicitly using the `let' command, they can be set by one program for use by another, and they can be used by the parameter system. User variables may have numeric or character values, and can be scalar values or arrays. The values of user variables can be displayed using the command `vshow'.

The names of user variables can appear in expressions evaluated by the parameter system and an important aspect of the way the parameter system works is that once a parameter is evaluated, a user variable with the same name as the parameter is set to that newly evaluated value.

For example, the command icadd has a first parameter called `image'. As a result of a command such as

icadd myimage 10 newimage

the user variable `image' will have been set to `myimage'. This setting is done as soon as the parameter is evaluated, and before later parameters are evaluated. This can be made use of in parameter system expressions, as discussed in the sub-section `Character expressions'.

Note that since user variables are, necessarilly, global -- there is only one user variable called `image', and this is common to all programs -- this has the effect that if two programs use the same name for a parameter, the default set by one will affect that used by the other. Often, this is useful -- once one program sets the default image in the user variable `image', all other programs inherit the same default image. However, if programs have poorly chosen parameter names this can cause some confusion.

5. Expressions

When Figaro parameters are specified, the {brace} characters are used to specify some sort of expression evaluation. The expressions involved may be iterative expressions such as {1:5}, which takes the five successive values 1,2,3,4,5, or may be an arithmetic expression such as {10*10} which evaluates to the single numeric value 100.

5.1. Numeric expressions

The parameter system can evaluate arithmetic expressions enclosed in {braces}. These can involve numeric constants and the names of Figaro user variables. The arithmetic operators supported are as follows:

+ addition

- subtraction

* multiplication

/ division

** exponentiation (x**y is x raised to the yth power)

Logical operations are supported, non-zero arithmetic values being interpreted as logical true values, zero arithmetic values being interpreted as logical false values. If the results of logical operations are used in an arithmetic context, false is treated as an arithmetic value of zero and true as an arithmetic value of one. The logical operators supported are:

! not

\ or

& and

> greater than

< less than

!= not equal

= equal to

>= greater than or equal to

<= less than or equal to

<> not equal (same as !=)

The following functions are supported:

max maximum of any number of arguments

min minimum of any number of arguments

sqrt square root of single argument

sin sine ratio of single argument in radians

cos cosine ratio of single argument in radians

tan tangent ratio of single argument in radians

ln natural logarithm of single argument

log base 10 logarithm of single argument

exp e raised to the power of the single argument

asin arcsine of the single argument - result in radians

acos arccosine of the single argument - result in radians

atan arctangent of the single argument - result in radians

int the single argument truncated to an integer

nint the single argument rounded to the nearest integer

The operator precedence is: unary operators, then +,-, then *, /, then **, then the logical operators. An almost unlimited number of (parentheses) can be used to control the order of expression evaluation, and this is usually more reliable than relying on quirks of the precedence rules.

5.2. Iterative expressions

An iterative expression has three parts, separated by colons. Each part may be a constant or a numeric expression. The first part specifies an initial value, the second part specifies a final value, and the third part specifies an increment. After each evaluation of the parameter, the value is incremented and if it does not exceed the final value, then the system will use this as a new value for the parameter. Once the final value is exceeded, the specification is exhausted.

If the third part, the increment, is omitted, a value of one is assumed. If the second part, the final value, is omitted, no final value is specified and the specification represents an infinite sequence of values. This can be used when it is not known how many values are needed, on the assumption that the program will be stopped for some other reason. For example,

icadd image{1:5} 10 output{1:} (VMS)

icadd 'image{1:5}' 10 'output{1:}' (UNIX)

will add 10 to `image1' through to `image5', producing `output1' through to `output5'. Once the first parameter's set of values is exhausted, the program will stop. As another example,

fits run{1:} \ (VMS)

fits 'run{1:}' \\ (UNIX)

will continue to read FITS files from a tape into successive files called `run1', `run2' etc. until the program hits the end of the data on the tape, at which point the application will stop with a tape error.


5.3. Character expressions

The parameter system does not offer any operators that operate on character strings as such, but expressions and user variables can be used in the specification of a character parameter in the following two ways:

If the name of a Figaro user variable that contains a character string appears in the specification enclosed in {braces} then the current value of the variable is substituted.

If an arithmetic expression or an iterative expression enclosed in {braces} appears in the specification, the numeric value is calculated and this is then formatted into a character string which is substituted for the expression. (This is implicit in the examples given above in the section on iterative parameters.)

Note that this evaluation can make use of the names of previously evaluated parameters, since a user variable with the same name as the parameter is set once a parameter is evaluated. This means that a command like icadd, which has an input parameter called `image' and an output parameter called `output' can accept a command such as

icadd run1 10 {image}_plus10 (VMS)

icadd run1 10 '{image}_plus10' (UNIX)

In this case, the `image' parameter is evaluated first, as `run1', and the user variable `image' is set to this value. When the `output' parameter is evaluated, the {image} in the specification is evaluated using the value of the user variable, to get the string `run1_plus10', so this is the same as the command

icadd run1 10 run1_plus10

This is a feature that can be used in command language scripts that run sequences of Figaro programs.

Iterative parameters can be specified with a number of leading zeros in the initial value to provide a small amount of format control. If leading zeros are used in this way, the value will be formatted with at least the same number of characters as were used for the initial value, leading zeros being inserted as needed. So, for example, the specification `image{08:10}' will generate `image08', `image09', `image10'.

6. Special keywords

The parameter system recognises four special keywords that apply to all Figaro applications. They are never prompted for, and so must be specified on the command line if they are to be used. These are:

PROMPT. This specifies that all parameters not explicitly specified in the command line must be prompted for, whether the programmer has designated them as `hidden' or not. The default is that PROMPT is false. Specifying PROMPT in the command line is the way to make sure that you are prompted for absolutely everything that the program gives you control over.

LIST. This specifies that the parameter system is to list the values of all the parameters it is using, `hidden' or not. The default is that LIST is false. Specifying LIST on the command line is a way of finding out what the various `hidden' parameters are and what values are being used for them, although it lists all parameter values, not just the `hidden' ones.

RESET. This specifies that the reset values provided by the program should be used as the defaults for any parameters that are not specified explicitly in the command line. This does not mean that they are not prompted for, merely that the reset value is used as the default value; to set all unspecified parameters to their reset values with no further user interaction, the RESET and `\' keywords can be used together.

\ This is treated as a keyword, although the `NO\' form (which is the default anyway) is not recognised. It specifies that the default value should be taken for any parameter not specified on the command line. Its effect is to suppress any further prompting by the program. This is a common requirement, particularly for practised Figaro users, which is why a single character was chosen. Unfortunately, this particular character is used as an `escape' character by most UNIX command shells, so usually needs to appear on a UNIX command line as a double backslash, `\\'.

7. Repeated parameter values

There are two ways in which a sequence of parameter values may be specified for a single parameter.

It is possible to specify that the parameter value be read from a file, in which case the file may contain a number of lines each containing a value for the parameter. Parameter specifications that make use of files containing parameter values all start with an `@' character, which is usually followed by the name of the file in question (although this can be defaulted, as described in the section `Reading parameter values from files').

It is also possible to specify a numeric expression, enclosed in {braces}, which specifies an iterative set of values, such as {1:10} which specifies the numeric values 1,2,3,4,5,6,7,8,9,10. All such iterative expressions make use of the `:' character. If such an expression appears in the specification for a character parameter, the set of numbers it produces are embedded in the character value produced, so "image{1:5}" is evaluated as the sequence "image1", "image2", "image3", "image4", "image5".

In all cases where a parameter specification generates a sequence of values, the Figaro program is re-run for each one of the set of values. When the program is re-run, all parameters that were specified using fixed values are kept at the single fixed value specified, and any that were specified as a sequence of values use the next value in the sequence. If more than one parameter has a sequence of values, then each parameter must have the same number of values in its sequence. For example,

icadd image{1:5} 100 output{1:5} (VMS)

icadd 'image{1:5}' 100 'output{1:5}' (UNIX)

will effectively generate the Figaro commands:

icadd image1 100 output1

icadd image2 100 output2

icadd image3 100 output3

icadd image4 100 output4

icadd image5 100 output5

but

icadd image{1:2} 100 output{3:5} (VMS)

icadd 'image{1:2}' 100 'output{3:5}' (UNIX)

will eventually generate an error message since the first parameter specification produces only two values while the third specification produces three. The program will run twice and then end with an error, complaining that insufficient parameters have been specified for the first parameter.

8. Command line parameters

All the parameters for a Figaro command may be specified on the command line used to invoke the application program in question. They may be specified by position, or by name, or by some combination of the two.

The command line format is:

command parameter-spec parameter-spec parameter-spec

The command must be followed by a space. The parameter specifications can be separated by any number of blanks, or by a comma with an arbitrary number of blanks (including none) on either side.

A command line parameter specification for a non-keyword scalar parameter (anything except a numeric array) can have any of the following forms:

value

name value

name=value

If an equals sign is used it may have an arbitrary number of blanks (including none) on either side. The name may be abbreviated. Each program specifies the minimum abbreviation for all of its parameters. This can be determined from the documentation for the program, or from the prompt used for the parameter if it is not specified on the command line.

The value string for a parameter is usually a literal value -- "2.0" for a number, "fred" for a character parameter, "YES" for a keyword. However, the parameter system allows a number of additional options, including the ability to read a number of parameter values from a file and the ability to specify an expression to be evaluated or a range of parameter values. This is discussed in more detail in the sections `Expressions', `Reading parameter values from files' and `Repeated parameter values'.

The value string for a character parameter may be enclosed in "double quotes." If it contains blanks, then the double quotes must be used in order to make it clear that the blanks are part of the value string.

The name used to identify the parameter must supply at least the minimum abbreviation for the parameter name.

If no name it used, i.e. if only a value is supplied, then the system has to work out which parameter is meant. It does this using the built-in order for the parameters for the command. So if a set of values are specified, with no names to identify the parameters in question, the first will be assumed to be the value for the first parameter, the second the value for the second parameter and so on. Once a name is used to specify a non-keyword parameter, subsequent parameters given on the command line must all be identified by name. (If not, the system really doesn't know which parameter is meant.)

Keyword parameters can be specified using any of the following forms:

name

NOname

name value

name = value

If an equals sign is used it may have an arbitrary number of blanks (including none) on either side. The name used to identify the parameter must supply at least the minimum abbreviation for the parameter name.

The simple presence of the name of the keyword is taken as setting the keyword parameter to a true value. The presence of the name prefixed by `NO' (which may be in lower case) is taken as setting the keyword parameter to a false value.

If a parameter is not specified explicitly on the command line that invokes the program, the program may use a default value, or it may prompt the user for the parameter value. The general intention is that only the important parameters are prompted for (the unimportant parameters are those the programmer designated as `hidden'). However, the user can control this to some extent, through the use of the `PROMPT' keyword (which forces the program to prompt for all unspecified parameters), and the `\' symbol (which suppresses almost all parameter prompting).

9. Prompting for parameters

When the Figaro parameter system has to prompt for a parameter it issues a prompt with the following form:

(NAme) Prompt string [default]

The (NAme) given in parentheses specifies the name of the parameter in question. The odd use of case reflects the allowed abbreviation for the parameter name when it is used on the command line. The section in upper case is the minimum abbreviation and the rest of the name is in lower case.

The prompt string is that specified by the writer of the program for the parameter.

The default value given in [square braces] is the value that the parameter system will use if no value is supplied by the user -- if the user just hits the `return' key.

If the user specifies an explicit value, instead of just accepting the default, then the parameter system expects a value for the parameter that follows the detailed specification rules in the next section. The specification may be an explicit value, which may involve the evaluation of an expression in {braces}, or it may start with a `@' character to indicate that a set of values for the parameter are to be read from a file. In addition, three special responses are recognised in response to a prompt for a parameter:

? Is a request for additional information. If on-line help is available for this parameter, then this will be output in response to the `?' and the prompt will be repeated.

\ Is a way of taking the default value for the parameter and suppressing any subsequent prompting by the program. Any subsequent prompts that the program might have made (for parameters not specified on the command line) will be suppressed and the default values for the parameters in question will be used.

!! Is used to indicate that you want to abort the program. A Figaro program can usually be aborted while it is running, using a mechanism supplied by the operating system -- usually control-C -- but this kills the program without giving it a chance to exit tidily. Using the `!!' response at a prompt is a much tidier way to shut down a program, although obviously it isn't aways an available option.

10. Specifying Parameter Values

This section describes in more detail the rules for specifying a parameter value. In general, these apply whether what is being specified is a value supplied on the command line or in response to a prompt. However, anything specified on a command line is subject to processing by the command interpreter being used (DCL for a VMS system, the command shell for a UNIX system). Since these will often attempt to interpret some of the special characters used in some of the more complex parameter specifications (the {braces} used for expression evaluation usually have a special meaning to a UNIX shell, for example), some form of `escape' mechanism must often be used to prevent this. This consideration does not apply to values specified in response to a prompt from a Figaro system, since these do not pass through the operating system's command interpreter.

The value specification for a parameter (the string shown as "value" in the section `Command line parameters') can be a single value or it can specify a set of values. If a set of values is specified then the Figaro program in question will be re-run as many times as necessary, each time using the next value in the set.

Sets of values are specified either by giving the name of a file that contains the set of values, or by giving a specification that when evaluated gives a sequence of values. An example of the first is "@file.lis", and an example of the second is "image{1:5}" which is evaluated as the sequence "image1", "image2", "image3", "image4", "image5". The use of sets of values is covered detail in the section `Repeated parameter values'. For the moment, we will restrict ourselves to single values.

10.1. Character parameters

The value specified for a character parameter can be any set of characters the user chooses. The only characters interpreted in any special way are the {brace} characters, the `@' character, and the "double quote" character.

If the string of characters includes spaces and the value is being specified on the command line, then the string needs to be enclosed in "double quotes" to delimit it. This means that it is not possible to specify on the command line a string that includes both spaces and the double quote character itself, since that double quote -- intended to be taken literally -- will actually be interpreted as ending the string. This is not regarded as a serious limitation.

The parameter system at present does not support expression evaluation involving character strings, but the {brace} characters can be used to specify an iterated numeric value that is formatted and included in the resulting character string, as in the example mentioned above where "image{1:5}" is evaluated as the sequence "image1", "image2", "image3", "image4", "image5". Iterative numeric values are described in the section `Repeated parameter values'.

If the character string begins with the `@' character, then this is taken as specifying that the parameter value should be read from a file whose name may follow the `@' character. This allows repeated execution of the program, as described in a later section..

10.2. File parameters

File parameters are handled just like character string parameters, but the values that are specified must represent either Figaro format data files or (less commonly) data structure items within those files. From the point of view of the user of a Figaro program, file and character parameters are almost indistinguishable in the way they are specified. The programmer of a Figaro application may designate a file parameter as representing an `input' or an `output' file. If an `input' file is being specified then it must exist, and if it does not, the user will be prompted for a different value. If an output file is being specified, the user is expected to specify it explicitly. Since the default value for an output file is usually to use one of the input files (such in situ operations being particularly efficient) the system regards it as important that it not be allowed to default. So the system will never use a default value for an output file parameter, even if the `\' symbol is specified on the command line to suppress parameter prompting.

10.3. Numeric parameters

A single numeric value can be specified either as a string beginning with the `@' character (which indicates that the value be read from a file), as a simple numeric constant, or as an expression enclosed in {braces}. An expression in {braces} may be an iterative numeric expression, or a more conventional arithmetic expression involving Figaro user variables.

If the value string begins with the `@' character, then this is taken as specifying that the parameter value should be read from a file whose name may follow the `@' character. This is described in the section `Repeated parameter values'.

Two special value strings allowed for numeric parameters are `MAX' and `MIN'. Application programs provide maximum and minimum values for all numeric parameters, and the `MAX' and `MIN' value strings are taken as specifying those values as supplied by the program.

A numeric constant is specified using a free-format syntax. Most ways of specifying a decimal number that would be valid in Fortran or C can be used, and the system is not fussy about floating point and integer values -- the number two can be specified as `2', `2.0', or `+2.00000', for example. An exponent can be specified by prefacing it with an `E' or a `D', so the number two can also be specified as `2E0', `0.2D1', `200E-2', etc.

A little-used feature supports the use of binary, octal or hexadecimal constants as well as the usual decimal values. Numbers may be specified enclosed in `single quotes' and followed by a letter indicating the base (`B', `O', `D' or `X' for binary, octal, decimal and hexadecimal), or may be prefaced by a percentage sign and the letter. Fractional values are allowed, the binary, octal and hexadecimal points being the same as the decimal point `.'. This means that

12 %D12 '12'D 'C'X %B1100 '1100'B %O14 '14'O

all represent the decimal number twelve, and

3.5 '3.4'O %X3.8

are all ways of specifying three and a half. Exponents in non-decimal bases are allowed, introduced by `E' in all cases except for hexadecimal where `E' is a valid hexadecimal digit and so `X' has to be used instead.

Iterative and arithmetic expressions involving constants and numeric user variables may be specified enclosed in {braces}. The operators used are all described in the section `Expressions'. The following examples are all ways of specifying the number twelve, if the variable `three' is set to 3 and the variable `four' is set to 4:

{three*four} {(1+3)*(4-(four-three))} {13-(5>(three+1))}

The last example is rather perverse. The logical expression `5>(three+1)', being true, is evaluated in an arithmetic context as a value of one. This may not be a particularly useful feature of the parameter system.

10.4. Numeric arrays

A numeric array can be specified as a set of numbers enclosed in (parentheses) and separated by commas. The numbers must be either constants or the names of Figaro numeric user variables -- expressions are not supported at present. A sequence of integers can be specified using a `n..m' syntax, so that the array specification `(1,4,5..8,10)' specifies the set of numbers 1,4,5,6,7,8,10.

As for all Figaro parameters, a specification beginning with `@' indicates that the values are to be read from a file, allowing repeated execution of the program.

10.5. Keyword parameters

A keyword parameter may be specified on the command line just by including its name in the line, which indicates that it is to be set true. If the name is preceded by a `NO', this indicates that it is to be set false. It may also be specified by using its name followed by an equals sign and a value. The value may be a string beginning with an `@' character, in which case the actual values are to be read from a file, allowing repeated execution of the program, or it may be an actual value.

If an actual value is specified, it can be one of the strings `YES' or `NO' (the case doesn't matter, and any abbreviation is accepted), or it can be a numeric value or a numeric expression enclosed in {braces} -- in which case any non-zero value is taken as `true'.

The default value for a keyword is usually supplied by the program rather than being the last value taken by the keyword. In cases where the user wants to `lock' the value supplied for the keyword as the default value to be used from then on, the parameter system allows the value specification to be followed by an exclamation mark, ie `YES!' or `NO!'. This will lock that value in as the default for the keyword. The standard keywords, `PROMPT', `LIST', `RESET' and `\' cannot be locked in this way. The DCL command processor used by VMS makes it difficult to specify an exclamation mark on the command line, so the parameter system will accept a hash (`#') character as an alternative.

11. Reading parameter values from files

Any parameter value may be specified, either on the command line or in response to a prompt, as `@n:file'. The `n:' represents an optional integer value, and `file' represents a filename which is also optional. In this case, a series of values for the parameter is read from `column' n of that file. The system regards as `column entries' any string delimited by blanks, or any string containing blanks but enclosed in (parentheses) or "double quotes". Any TAB characters in the file are treated as blanks, and files have a default extension of `.lis'. When the program finishes, if any parameters were specified using this `@' syntax, the system reads in the next line from each such file and repeats the application. This does not involve a reload of the application program, so avoids the image activation overheads associated with, say, running the same image repeatedly from DCL command files or UNIX scripts.

If the `n:' is omitted the system uses the next column in the file. If the file name is omitted then the last file specified is assumed. If all file names are omitted, the system prompts for one. In most practical cases all that is usually specified is `@filename' for a parameter, which is quite simple.

For example, if there are two files, `files1.lis' and `files2.lis' each with

a list of filenames, such as:

files1.lis files2.lis

RUN1 OUT1

RUN2 OUT2

RUN3 OUT3

etc, and the command

icadd @file1 20 @file2

is given, then ICADD will add 20 to the data in RUN1 to produce OUT1, 20 to RUN2 to produce OUT2, and so on. Alternatively, everything can be set up in one file, say `files3.lis', as

files3.lis

RUN1 20 OUT1

RUN2 30 OUT2

RUN3 40 OUT3

and then the command can be given as:

icadd @1:files3 @2:files3 @3:files3

or, more conveniently, using the default rules for filenames and column numbers, as

icadd @files3 @ @

and ICADD will add 20 to RUN1 to produce OUT1, will add 30 to RUN2 to produce OUT2 and so on.

Particularly under UNIX, this can lead to some very simple but effective operations. For example,

ls *.dst > files.lis (UNIX)

wifits @files current \\ (UNIX)

will write out all the .dst files in the current directory onto tape.