7 Interface files and Parameters

It must be admitted that the previous example has limited value. The facility to specify VALUE at run-time would be an improvement. A simple READ statement might seem like the answer, but as mentioned before, this approach is likely to fall foul of the way in which the ADAM environment deals with I/O. In any case, using the parameter system gives enormous advantages – as will become clear. (Already one ADAM parameter has been used in the example programs – the ’INPUT’ used to get the name of the input NDF for NDF_ASSOC.)

The program on the previous page could be modified by replacing the statement assigning 7.0 to VALUE with the call below which gets an ADAM parameter, in this case, named ’CONST’.

This change has been made in ADAM_EXAMPLES:ADDCONST.FOR. The ‘PAR_GET’ part is self explanatory, and the ‘0’ indicates that the parameter to be retrieved is a scalar (rather than a vector, or an $n$-D object). The final ‘R’ in the subroutine name indicates that the routine retrieves a variable of type REAL. Similarly PAR_GET0I retrieves an integer, PAR_GET0C, a character string etc. A list of the PAR routines with their functions and calling sequences is given in Appendix D.

The ADAM parameter ’CONST’ must now be declared in the interface file as shown:

When the PAR_GET0R routine is called, it looks to the interface file for instructions on retrieving the parameter in question. In this case, the only information found there is that the prompt ’Value to be added?’ should be issued. If a suitable number is then entered by the user, it is assigned to VALUE and STATUS remains ‘OK’. Any unsuitable response (e.g. a logical value) and the parameter system will issue an error message, and doggedly repeat the prompt five times or until a satisfactory value is entered.

The prompt is an example of a fieldname. Other fieldnames which are commonly defined in interface files are discussed briefly below, and a full discussion of the subject of interface files is contained in SUN/115.

$\bullet$ position – rather than simply typing $ RUN ADDCONST, you can set up a symbol:

  $ ADDCONST== "$mydir:ADDCONST"

where mydir is the logical name of the directory which contains ADDCONST.EXE. Typing ADDCONST will now cause execution of the program. It is now possible to enter the parameters the program needs on the command line. Possible that is, if the program knows the order in which to expect them. Including the lines, “position 1” and “position 2” within the parameter declarations of ’INPUT’ and ’CONST’ respectively provides this information. After modifying the interface file in this way, the example command below will work.

  $ ADDCONST SPECTRUM 15

$\bullet$ keyword – parameters can also be specified on the command line by using keywords. If a keyword is not declared for a parameter in the interface file, the parameter name itself is used as the keyword. Thus the same result as in the previous item can be obtained by typing:

  $ ADDCONST CONST=15 INPUT=SPECTRUM

It is not recommended that keywords be explicitly declared in interface files.

$\bullet$ppath – when an ADAM program prompts for a parameter, a suggested value may be appended to the prompt string. For example:

  CONST - Value to be added / 17.4 / >

This suggested value (17.4) is used if the user presses $<$CR$>$ in response to the prompt. The fieldname ppath is used to specify where the parameter system gets this suggested value. For example, if ppath is declared as current, the value supplied for the parameter during the previous run of the program will be used. It is also possible to select a fixed default value which is supplied via the default fieldname. In the example interface file below, the parameter INPUT has been given a default value of SPECTRUM. However, ppath for INPUT has been set to ’current,default’. This means that the prompt will contain the current value – that is, the last value assigned to the INPUT parameter – unless no value has been assigned, in which case the value specified by the default fieldname will be used. Other possibilities for defining ppath are described in SUN/115.

$\bullet$type – this can be any of the primitive data types recognised by the ADAM system, i.e. ’_INTEGER’, ’_REAL’, ’_DOUBLE’, ’_CHAR’ or ’_LOGICAL’. Alternatively a type such as ’NDF’ can be used, but this is purely descriptive and is ignored by the parameter system. If a primitive type is specified, the parameter system will check if a value of the appropriate type has been offered, and will perform any necessary type conversion if possible. N.B. If type is specified for a parameter, the declaration must appear before any of the default, range or in fieldnames are declared.

$\bullet$ help – the help fieldname contains a single line of text which will be displayed to assist the user who types ? in response to a prompt for a parameter. However a single line of help is seldom useful so the method described in the following item may be preferred.

$\bullet$ helpkey – multi-line help from a help library module is available via this fieldname. See Section 19 for a description of creating and accessing such a help library.

$\bullet$ access – if specified this will ensure that a program does not attempt to access a parameter in a way not allowed by the value of the access fieldname. For example, the interface file for ADDCONST below specifies UPDATE access for the ’INPUT’ parameter; if this were changed to READ, execution of the program ADDCONST would fail as the program can no longer update the input file and an error message would warn of ‘Inconsistent access mode’.

A modified version of ADDCONST.IFL incorporating some of the above fieldnames is shown below.

Some of the values assigned to fieldnames above are surrounded by quotes ’ ’. This is necessary if the values are character constants (such as the prompts), or contain more than one word (such as the ppath) but is optional otherwise. Comments in interface files are preceded by the ‘#’ symbol.