Chapter 8
Specifying Parameter Values

8.1 Introduction

ADAM programs are controlled by specifying parameter values. You can specify them in two ways:

The thing to remember is that when you respond to prompts you are talking directly to the ADAM parameter system, whereas when you specify values on the command line, they will be processed by the language interpreter and then passed to the parameter system.

Usually, it is not necessary to specify parameters on the command line — you can just respond to prompts. However, there are three reasons why you may wish to do so:

• To avoid waiting for prompts.
• To set values for parameters which normally are not prompted.
• To use a command safely in a procedure.

8.2 Command line specification

This section refers to ICL commands. However, you can run ADAM programs by using DCL commands. These suffer from the following restrictions compared to ICL:

• It is not possible to use ICL expressions.
• It is not possible to return parameter values to the command language, and hence on to applications.
• Single quotes cannot be used, except where they are needed to force expansion of DCL symbols. Double quotes can be used.
• It is not possible to use an ! unless it is in a character string enclosed in double quotes. Normally this character indicates a comment.

There are two ways in which you can specify parameter values in an ICL command:

• By using a command which has been defined to run an ADAM program. (The definition is done by a DEFINE command.)
• By using the SETPAR command. (You can also store a parameter value in an ICL variable by using the analogous GETPAR command.)

The first way is the most usual and will now be considered further.

You will remember that a program’s parameters may be assigned values on the command line:

where command is a commmand that has been defined to run the program. This method is particularly useful for running programs in VMS batch mode, and for specifying values for parameters that would otherwise be defaulted. Normally, command-line specification will prevent prompting for a parameter’s value unless there is an error in the given value, say giving a character string for a parameter of type _REAL.

There are two ways in which parameter values may be specified on the command line:

• by keyword
• by position

The two forms may not be mixed.

The keyword method is usually preferable because the position method has these disadvantages:

8.2.1 Keyword method

In the keyword method, a parameter is identified by a keyword (specified in the program’s interface file) and a value is assigned to it using the syntax:

The keyword is the name by which the parameter is known to the user. This is usually, but not necessarily, the same as the parameter name.

In some cases (such as when setting a switch) the keyword itself is all that needs to be specified: Here is an example:

The keyword and data type corresponding to a particular parameter is specified in the program’s interface file:

Here, the keyword CURPIC is associated with a logical type parameter — just specifying its name sets its value to ‘TRUE’, specifying ‘NOCURPIC’ sets its value to ‘FALSE’. The keyword FRACTION is associated with a real type parameter which is given the value 0.4. Keyword forms may appear in any order on the command line, and are ignored when calculating the ‘position’ of other parameters.

8.2.2 Position method

In the position method, the position of a value on the command line identifies the parameter which is being given that value. Here is an example:

The parameter corresponding to a particular position is specified in the program’s interface file:

Here, the first parameter IN1 is given the value HISIMAGE, the second parameter IN2 is given the value HERIMAGE, and the third parameter OUT is given the value THEIRIMAGE. The fourth parameter TITLE is not given a value.

8.2.3 ICL variables and functions

Command-line specification can be used to put the values of ICL variables and functions into programs. A common situation where this is useful is when processing a sequence of files in the same way. For example, consider this ICL procedure:

This obtains the statistics of ten images named REDX01, REDX02, …, REDX10. The parameter with keyword INPIC is assigned the value of the ICL variable FILE. Variable FILE is in parentheses because syntactically it is an ICL expression. The ICL function SNAME is used to construct the appropriate file name, which must be preceded by an ‘@’.

Here is another example of the use of ICL variables in commands which uses KAPPA to ‘flat field’ a series of CCD frames:

Here, the parameters of the DIV program are given values stored in ICL string variables.

8.3 Prompts and suggested values

If program parameters are not given values on the command line, values will be prompted for (unless this is suppressed). If the value supplied is not acceptable, the prompt will be repeated. If no acceptable value is supplied after five prompts, a ‘Null value’ is given to the program.

The general form of a prompt is:

However, the /<suggestion>/ may not appear.

8.3.1 Prompts without a suggested value

The simplest type of prompt is one where the suggested value is omitted, for example:

In this case, if you just press ‘carriage return’, the prompt will be repeated up to five times, and then a null value will be given to the program:

You should specify the value you want, for example:

This value will be accepted, and then the next prompt will be displayed.

8.3.2 Prompts with a suggested value

When a prompt includes a suggested value, you can override it by entering a value of your own. However, when this prompt appears again during a subsequent use of the program, the suggested value may or may not be the same as the value you last entered. Sometimes the current (last) value of the parameter is used, sometimes a fixed default value is used, and sometimes a dynamic default value is calculated by the program from the values of other parameters. It all depends on the characteristics of the program and its interface file. Parameter XDIM of program CREFRAME is an example of a parameter that uses the current value:

Current values of parameters are stored in a file in ADAM_USER, so they persist between ADAM sessions. The file should not be deleted unless the old values are not required.

Parameter TYPED of program CREFRAME is an example of a parameter that always offers the same suggested value, no matter what the current value is:

8.3.3 Global parameters

Normally, a program’s parameter values are only accessible by that program. However, global parameters can be shared by many programs. The use of global parameters as suggested values can reduce the need for typing responses to prompts. For example, in this case:

the frame created by CREFRAME can be displayed by LOOK without having to retype its name. This is because parameter OUTPIC of program CREFRAME and parameter INPIC of program LOOK are both associated (in their interface files) with the global parameter GLOBAL.DATA_ARRAY. Thus, parameter INPIC offers as a suggested value the object name which was input as a value for the OUTPIC parameter of a different program.

In ICL you can create a global parameter using the CREATGLOBAL command, set its value using the SETGLOBAL command, and get its value using the GETGLOBAL command.

8.3.4 Missing prompts

Sometimes a prompt for a parameter value will not appear, even if you haven’t specified a value on the command line. This is because the parameter system looks for a value for a parameter in a number of places, as specified in a ‘search path’ in the program’s interface file. This feature is described in Chapter 14. A prompt will only appear if it cannot find a value in the search path, or if the search path specifically asks the parameter system to generate a prompt. This ability to supply values automatically enables programs with many options to avoid burdening the user unnecessarily with large numbers of prompts. If you want to supply your own value in these cases, you must specify a value on the command line, or demand to be prompted (see below).

When prompts don’t appear, the program documentation may tell you what the unprompted parameters are, what options are available, and what the suggested values are. Another way is to look at the online help on a program’s parameters; for example:

gives details of all the parameters of the KAPPA program CREFRAME.

8.3.5 Keywords — RESET, PROMPT, ACCEPT

Another way in which prompts and suggested values can be controlled is by use of the keywords RESET, PROMPT, and ACCEPT in ICL commands. RESET:  The RESET keyword causes the suggested value of all parameters (apart from those already specified before it on the command line) to be set to the original values specified by the program and interface file. For example, consider the prompt for the value of the XDIM parameter in the following successive executions of the CREFRAME program:

When the CREFRAME program is executed for the first time, the suggested value of the XDIM parameter is ‘64’. In the first prompt above, the value of XDIM is set to ‘10’. When CREFRAME is executed for the second time, the suggested value of XDIM has changed to ‘10’, i.e. it takes its ‘current value’ which was set during the previous execution of CREFRAME. In the third execution of CREFRAME we have included the keyword RESET in the command line. The effect is that when the value of parameter XDIM is prompted for, the suggested value has reverted to ‘64’.

RESET may be combined with the keywords PROMPT and ACCEPT described below. PROMPT:  The PROMPT keyword forces a prompt to appear for every program parameter not specified on the command line. For example, program CREFRAME has a parameter called TITLE which normally takes the value ‘KAPPA – Creframe’ without prompting. However, if you use the keyword PROMPT in the command line, a prompt for TITLE will be made:

the program would fail because it does not know where to write the output data. However, if you ran the program like this:

The program would generate an output image using suggested values for all the parameters except OUTPIC, and write the output to file RAMP.SDF.

Sometimes the keyword ACCEPT can be used alone. For example, you could follow the above command by the command:

and the central 7x7 array of the image created by CREFRAME would be displayed on your terminal without any parameter values being prompted for.

The symbol ‘\’ has the same effect as ACCEPT, thus:

would have the same effect as the previous example — and is much quicker to type.

8.4 Value formats

When specifying parameter values it is important to remember whether you are talking to the ICL command interpreter or to the ADAM parameter system. The differences are highlighted in Section 8.5

8.4.1 ICL command parameters

Parameter value specifications in an ICL command can take three forms:

• An expression enclosed in parentheses. E.g.
      (2)        (X)         (Y*SIN(THETA))

• A string enclosed in quotes. E.g.
      ‘String’               "Filtered and calibrated"

• Any sequence of characters not including a space, quote, comma or left parenthesis. E.g.
      NGC1635    X           PI*2

The first form is used to pass the value of an ICL expression to a command, or to give a command a variable in which to return a value. The other two forms both pass a string.

We can illustrate the three forms by using the PRINT command which prints its parameter values on the terminal:

In many cases you do not need to use the quoted form of a string because the simpler form will work. You need the quoted form for those cases in which you need to delimit a single string containing a left parenthesis or spaces. Consider the following example which contains a PRINT command which has several parameters:

Since spaces are parameter separators, ‘The’, ‘Square’, ‘Root’, and ‘of’ are all received by PRINT as separate parameters. However, PRINT simply concatenates all its parameters with a space between each pair. Thus, the output written by PRINT is the string, just as you typed it. Many other ICL commands which accept strings work in this way. This means that strings with single spaces may not need quotes when used as command parameters. However, in general this is not true of commands which run ADAM programs when strings are specified on the command line (see below).

The rules for specifying ICL command parameters can be summarized as follows:

• To pass the value of an expression or the name of a variable, enclose it in parentheses.
• Anything not in parentheses is passed as a string, or as a sequence of strings if it contains spaces or commas.
• Any string which does not fit these restrictions can be passed by placing it in quotes. Quotes may be included in a string by typing two consecutive quotes.

8.4.2 ADAM program parameters

Values can be specified for ADAM program parameters in an ICL command line and in response to prompts. However, some values are only acceptable when given in response to prompts; they are meaningless to ICL. Values acceptable in commands, and in response to prompts: 

in which case the parameter system would be handed the string ‘Sum of 2 images’ as the value of the first parameter of TESTC. However, if you type:

the parameter system will think there are four parameters ‘Sum’, ‘of’, ‘2’, and ‘images’.

Quotes are not needed when a string is input in response to a prompt. For example:

will successfully give parameter X the value ‘Sum of 2 images’ (provided X is of type _CHAR or LITERAL).

The use of single quotes (’) is dangerous when used from DCL as DCL will interpret them as indicating symbol substitution. Thus, when your input will be processed by the DCL command interpreter, double quotes (") should be used. Object names:  Strings are used to specify the names of files, data objects, and devices (graphics devices, tape drives etc.). Components of data objects are specified by a dot notation, e.g. RAMP1.TITLE refers to the TITLE component of the image RAMP1. Normally, a name can be typed without quotes. However, ambiguities can occur: a file name such as [ABC.DEF]FILE begins with a ‘[’ character and may be confused with an array specification. Such ambiguities can be resolved by prefixing the name with an ‘@’ character, e.g. @[ABC.DEF]FILE means the file of this name. As another example, in the prompt line:

the parameter PLTITL is given the value of the string contained in the object MYTITLE in GALAXY.SDF. If the ‘@’ were omitted, the string ‘ADAM_USER:GALAXY.MYTITLE’ would be used as the value of PLTITL. Note that the file extension (.SDF) should not be included when giving the name of a data file, otherwise the data system will look for the component SDF within the object GALAXY.MYTITLE. Logical names:  Logical names must be defined with the /JOB qualifier. Thus, if your IMAGE data files are stored in IMAGEDIR alias DISK$USER1:[XYZ.IRCAM.IMAGES]:

will enable you to respond to a prompt thus:

8.5 Comparison of ICL and ADAM parameters

Some values which are acceptable when specified as a parameter value in an ICL command are not acceptable when used in response to prompts from the ADAM parameter system. These unacceptable values are ICL functions. Thus, suppose program TESTR has been written to read a real number and print it out. We could do the following:

However, an attempt to use the ICL function TAND in a response to a prompt would be rejected:

You will have to specify a value which is acceptable to the ADAM parameter system.

Chapter 11 shows some example ADAM programs which read a parameter value and display it on the user’s terminal. These can be used to examine how ICL and the ADAM parameter system process input values. Program TESTI reads a parameter value of type ‘_INTEGER’. Here is how this program responds to various inputs specified first on the command line and then in response to a prompt:

Notice that:

• The input value ‘5.6’ is rounded up to ‘6’ by the parameter system before being given to the program. This is because the value is obtained by calling routine PAR_GET0I which converts an input value to integer type.
• The ICL function ‘tand(60)’ must be enclosed in parentheses if it is to be recognised as an expression, otherwise it is interpreted as an object name and the system goes looking for its container file.
• The expressions ‘(tand(60))’ and ‘(%B100110)’ are recognised as expressions when input on the command line, but not when input in response to prompts. When it is recognised, the value of tand(60) is rounded up from 1.732051 to 2.

The next table shows the response of program TESTR which reads the value of a parameter of type ‘_REAL’ from the environment and displays this value on the terminal:

The next table shows the behaviour of program TESTL which is like the previous programs but whose parameter is of type ‘_LOGICAL’:

Notice that the ICL function ‘lge’ is acceptable when specified on the command line, but not in response to a prompt.

The final table shows the input to and output from program TESTC, which is the same as the previous programs but has a parameter value of type ‘_CHAR’:

• For ‘command line’ input, ICL expressions are evaluated and the result is converted into a string before being given to the program. For ‘prompt’ input, the expressions are not evaluated but are just regarded as strings of characters.
• Spaces in strings separate parameters in ‘Command line’ input when the string is not enclosed in quotes or double quotes.

If you read Chapter 11 you will be able to create your own versions of the TESTx programs and try out various inputs on the system yourself.