The Parameter system is a central feature of the ADAM system architecture. It is a unifying concept which binds the various ADAM ‘facilities’ together and permeates many aspects of ADAM. Both users and programmers need to understand it clearly if they are to use ADAM properly.
A list of the routines which implement the system is given in Section 21.1.
Programs are usually written to be as general as possible in order to maximize their usefulness. Thus, you would not write a program to display a specific image but would make it accept any image stored in one or more specified formats. Because of this, at run time the program needs to know the name of the image to be displayed. The ‘name of the image’ is a parameter of the program. More complicated programs may have many parameters controlling their actions. Thus, your display program may need to know the format of the input image, the device on which it is to be displayed, the colour mappings to be used in the display, types of axes, scaling methods, and so on. All these things are parameters. When an ADAM program is run, the task of the ADAM parameter system is to associate the program’s parameters with objects in the outside world.
The word ‘object’ is rather overworked in ADAM, so you have to be aware of the context in which it is used. ‘Object’ is often used to mean a ‘data object’, i.e. an HDS structure accessed through the data system. When talking about parameters, the word ‘object’ has a wider meaning; in fact it can mean absolutely anything outside itself that a program wishes to refer to by name — a data object, a hardware device, a message, a graphics database, a file etc.
Figure 14.1 is a schematic illustration of the function of the ADAM Parameter System. Its main role is to provide a means of communication between the user and the programmer, and in particular to associate objects chosen by the user with a program’s parameters chosen by the programmer. The programmer communicates by using ADAM routines in his program and parameter specifications in his interface file. The user communicates by using a command language such as ICL.
You must be careful to distinguish between a ‘parameter name’ (used to identify which parameter is being talked about), and a ‘parameter value’ (the value a given parameter has at a particular moment). The word ‘parameter’ is often used loosely in both senses. However, the precise meaning is normally obvious from the context.
The programmer has two ways to associate an object with a program parameter:
causes the parameter system to obtain a real scalar value for parameter ‘X’ and store it in program variable ‘XVALUE’. Similarly, a call such as:
causes the parameter system to write the value stored in program variable ‘YVALUE’ into the data object associated with parameter ‘Y’.
The direct method only works for parameters whose values are scalars, vectors, or n-dimensional arrays of one of the five standard HDS primitive data types:
Values of other types (e.g. graphics plots, non-standard data types) must be associated with parameters by the indirect method. Indirect association: The various ADAM subroutine libraries enable you to access and manipulate objects of various kinds. The indirect method of accessing parameters first ‘associates’ an object of an appropriate type with a parameter by calling a special ‘ASSOC’ routine provided for that library. This routine provides the program with an ‘identifier’. From then on, this identifier is used to specify the object, rather than the parameter name. The usual form1 of the ASSOC routine is:
where:
Table 14.1 shows the names of the ASSOC routines for the ADAM subroutine libraries, together with the name of the object identifier ‘ID’ used in the documentation, and the type of object addressed.
Subroutine library | ASSOC routine | Object identifier | Object type |
NDF,DAT,CMP,HDS,REF,TRN | DAT_ASSOC | LOC | Data object |
GKS | GKS_ASSOC | WKID | GKS workstation |
SGS | SGS_ASSOC | ZONE | SGS zone |
IDI | IDI_ASSOC | DISPID | Display device |
AGI | AGI_ASSOC | PICID | Picture in database |
FIO,RIO | FIO_ASSOC | FD | File |
MAG | MAG_ASSOC | TD | Tape drive |
ADC | ADC_ASSOC | CD | Catalogue |
NCAR,SNX,PGPLOT,GNS,NAG | not specified | ||
PAR,MSG,ERR,EMS | not needed | ||
Once an object has been associated with a parameter, its identifier is used to access the object. Suppose, for example, that parameter ‘IMAGE’ is a data object which contains a pixel array stored in a component named ‘DATA_ARRAY’. This array can be accessed by the code:
in which the first call associates an HDS object with the parameter ‘IMAGE’ and makes the locator ‘LOC’ point to it. The second call finds the component ‘DATA_ARRAY’ in this image and makes another locator ‘LOCA’ point to it. The third call stores the value of the array in variable ‘VALUE’.
Most facilities also have ANNUL routines which are used to stop the identifier pointing to the object, thus:
will cause LOC to stop pointing to the object associated with parameter ‘IMAGE’. The object will still be associated with parameter ‘IMAGE’, but you won’t be able to access it. It is considered good practice to annul identifiers when you have finished using their objects. However, the system tidies up after you when your program finishes so you needn’t worry about it.
The ASSOC and CANCL routines (described later) are often referred to as ‘Parameter Routines’ because they are added to a ‘stand-alone’ subroutine library in order to integrate it with the ADAM parameter system. The equivalent ‘stand-alone’ routines are OPEN and CLOSE. In ADAM programs the OPEN routine is usually replaced by the ASSOC routine. For example, when the SGS graphics library is used outside ADAM, the first call to one of its routines would be:
which would cause the graphics workstation specified by WKSTN to be opened and an SGS zone specified by ZONE to be made available for plots. However, an ADAM program which used SGS would not use this call, but would replace it with:
Here, the workstation is specified through the parameter system, so PAR replaces WKSTN in the calling sequence. ZONE and STATUS have the same function as before, but a new variable, MODE, is introduced to provide the program with the ability either to clear or to retain the display screen contents. Parameter values: Your program relies on the parameter system to provide a value for a parameter. This process depends on a ‘search path’ defined in the interface file, as will be explained later. However, your program can influence the value provided by suggesting a ‘dynamic default’ to the parameter system. This is done by a set of ‘PAR_DEF’ commands. For example:
will set a dynamic default of 3.4 for parameter ‘X’.
The set of PAR_DEF routines is analogous to the PAR_GET and PAR_PUT sets, except that there is no ‘V’ form, i.e. you cannot set a dynamic default for an array mapped as a vector; you have to use the explicit array form.
An interface file for a single program has the following form:
The body of the file comes between the ‘interface’ and ‘endinterface’ statements, and consists of a sequence of ‘Parameter specifications’ and ‘Message specifications’. Each interface file has a unique name (PROGNAME) which should be the same as the name of the program with which it is associated. Comments may be introduced by the ‘#’ character — any characters following ‘#’ on a line will be ignored. Minimal interface files: The example interface file shown in Section 11.3 was quite large considering the simplicity of its associated program. Is all this complexity really essential? The answer is ‘No’ — the example given was made complex in order to show off the facilities of ADAM, and not because of any intrinsic complexity in using ADAM. Suppose you write the following abbreviated ADAM program to read in a real number and write it out on your terminal:
Now, suppose you don’t prepare an interface file for this program at all and try to run it using ICL in the usual way. This is what would happen:
When I tried it, the system hung and I had to use cntrl/Y to escape. So, you can’t get away with not storing an interface file because the system just won’t work without one. However, suppose you store one with no information on the program parameter X, i.e. an interface file containing the lines:
If you try to run the program again it still won’t work, but you will get a different error message:
However, at least the system won’t hang. Now let’s go one step further and put an empty specification for parameter X in the interface file:
This time the program will work, even though we haven’t stored a specification for the message parameter ‘MESS’:
So, the shortest interface file you can get away with is one which contains empty specifications for all the program parameters except message parameters (such as MESS) which do not need to be specified at all. Thus, the simplest way of testing a program you have compiled and linked is to prepare an interface file containing empty specifications for its non-message parameters, then use ICL to define a command to run it, and then type in that command. You will be prompted for a value for each of the program’s parameters. If you try to specify values on the command line by position, they will be ignored and you will be prompted anyway. However, you can specify them on the command line by keyword, using the parameter name as the keyword.
You can see now that the function of the interface file is to provide you with the ability to modify or enhance the user interface if required. The facilities available from the interface file are to:
These facilities are considered in more detail in the next sections where the fieldnames which are used to specify these controls are described. Search path: An interface file can be accessed through a search path. If a job logical name search path, ADAM_IFL, is defined, it will be used to find the interface file. If ADAM_IFL is not defined, or if an interface file is not found using it, an attempt will be made to find one in the directory in which the program executable image was found. Compilation: An interface file can exist in two forms. The first form is an ordinary text file which can be edited easily. This is used when a program is being developed. The file should have the same name as the program, but with a file extension of ‘.IFL’. When the user interface for a program has become relatively stable, the interface file should be compiled and stored as an ‘.IFC’ file — this is the second form. This is done as follows:
where ‘progname’ is the name of the interface file. (You must have previously entered the ADAMSTART and ADAMDEV commands.) The system can extract information from interface files stored in the second form faster than from files stored in the first form, so this improves efficiency.
The different types of fieldname provided in an interface file for controlling the user interface fall naturally into various groups which have a particular function, as shown in Table 14.2.
Group | Fieldname | Function |
Data type & access | TYPE | Data type |
PTYPE | Device type | |
ACCESS | Access mode | |
Command line | POSITION | Position in command line |
KEYWORD | Keyword in command line | |
Prompt | KEYWORD | Keyword in prompt |
PROMPT | Prompt text | |
HELP | On-line help text | |
HELPKEY | On-line help text | |
PPATH | Prompt-value search path | |
ASSOCIATION | Associated global parameter | |
DEFAULT | Default prompt-value | |
Value | VPATH | Parameter-value search path |
ASSOCIATION | Associated global parameter | |
DEFAULT | Default parameter-value | |
IN | Valid value set | |
RANGE | Valid value range | |
Some of the fieldnames have slightly different functions in different contexts and so belong to more than one group. The groups and their fieldnames are described in more detail below. Each fieldname description is headed by a line with the format:
This shows how this fieldname is specified.
These fieldnames specify the data type of the parameter, and how it should be accessed:
This specifies the type of a Normal parameter, i.e. any parameter except a device type. It may used by the system to check that a supplied parameter value is of a type that the application program is expecting. It also allows automatic conversion between the primitive data types. It is important to distinguish between the type of a parameter and the type of the value to be obtained from it by the application.
The data-type may be:
If the TYPE field is omitted, type UNIV is assumed.
Example:
An acceptable value for parameter INPIC1 is specified as being of type image.
This specifies that a parameter is of the Device type.
Most parameters are associated with objects whose values belong to some data type, e.g. _REAL. These are known as Normal parameters. However, some parameters are associated with a hardware device, e.g. a magnetic tape drive or a graphics terminal. These are known as Device parameters. The value of a device parameter is a device name.
Example:
The parameter PLOTTER is specified as being of device type.
This specifies the mode of access the program requires to a parameter value. Permitted values for the ‘access-mode’ field are:
Thus, if a program does not modify the value associated with a parameter, specify ‘read’ access. If the value is to be written, specify ‘write’ access. If the value is to be modified, specify ‘update’ access. The default value is ‘update’.
Example:
The parameter INPIC1 is specified as being restricted to ‘read’ access.
These fieldnames specify how a parameter should be specified on a command line:
This specifies the position on a command line where a value for a parameter may appear.
The ‘ipos’ field is an integer. A value of ‘1’ specifies the first parameter position, and so on.
This fieldname must be given for every parameter capable of being specified by position on the command line; there is no default value. Each such parameter must have a different position number. Positions allocated must form a contiguous set. If this fieldname is omitted, then a keyword must be specified whenever the parameter is used on a command line.
Example:
The parameter INPIC1 is associated with the first parameter position on the command line.
This specifies the name by which a parameter can be identified on the command line, and by which the parameter is known to the user.
The ‘name’ field specifies the keyword. This may differ from the parameter name.
This fieldname separates a program’s view of its parameters from a user’s view of them. It is possible for a programmer to re-write a program using completely different parameter names, but the command seen by a user can be kept the same as before by just leaving the keywords as they were. Conversely, a user’s view of a program can be changed by just changing the keyword specifications in the interface file.
If a keyword is not specified for a parameter, the system will use the parameter name as the keyword in the prompt and on the command line.
Example:
The keyword for parameter INPIC1 is specified as being PIC1. Thus, on the command line we could enter:
to specify that the input image is ramp1.
These fieldnames determine the appearance of the prompt for a parameter value. A prompt has the following syntax:
keyword – prompt-string /suggested-value/ >
The following fieldnames are involved:
The keyword forms the first part of the prompt. This fieldname is described above in the command line group.
This specifies the prompt-string field in the prompt for a parameter value.
This field is a character string with a maximum size of about 80 characters — it is not possible to give a single figure which is correct in all cases. The prompt-string can also be set by the program using the PAR_PROMT routine.
If this fieldname is not specified, the prompt-string field is omitted from the prompt.
Example:
The prompt-string for parameter INPIC1 is specified as ‘First input image’.
This gives information about the meaning of the parameter.
The ‘help-text’ field is a character string containing the information. The maximum size of the field is about 132 characters — it is not possible to give a single figure which is correct in all cases.
If the user is prompted for a parameter value, a possible reply is ‘?’. The system responds to this by displaying the ‘help-text’ on the terminal and re-prompting the user for a value.
Example:
This defines the help text for parameter INPIC1.
This specifies a help file, and module within it, at which multi-line help text for the parameter may be found. The text to be displayed is stored in the module defined by key1 key2 ... in the help file filename. (The keys represent the usual hierarchical keywords used to access the help system). This is replacing the earlier one-line help provided by the HELP specification.
If filename key1 key2 ... is replaced by * or ’*’, the default values:
will be used, where interface_name is the name specified in the current INTERFACE field. Use of this default implies that the library has been specified using the HELPLIB specification.
Example:
This specifies the search path to be followed to obtain a value for the suggested-value field in the prompt. This search path is usually referred to as the ‘ppath’.
If a suggested value is required, the system looks at the ‘ppath’ specification, picks out the first specifier, and tries to find a value from this source. If a value is not found, the next specifier is extracted and another search is made. This process continues until either a value is found, or the search path is exhausted.
The ‘prompt-value-resolution-path’ field consists of a set of specifiers separated by commas. The valid specifiers are the same as for ‘vpath’ (see below), except that the ‘prompt’ and ‘noprompt’ specifiers are invalid in this context and should not be used.
If ‘ppath’ is not specified, a default search path of ‘dynamic,default’ is used.
Example:
This specifies a ‘ppath’ of ‘global’ followed by ’current’ for parameter INPIC1.
See below in the ‘Value’ group.
See below in the ‘Value’ group.
These fieldnames determine the value given to a parameter, and check that this satisfies given criteria:
This specifies the search path to be followed when searching for a parameter value. This search path is usually referred to as the ‘vpath’.
A value can come from many different sources, and these sources may need to be searched in different orders. The ‘parameter-value-resolution-path’ field specifies these sources and the search order — this constitutes the search-path. The field consists of specifiers separated by commas. The valid specifiers are:
If the value of a parameter is not specified on the command line, the system looks at the ‘vpath’ specification, picks out the first specifier, and tries to find a value from this source. If a value is not found, the next specifier is extracted and another search is made. This process continues until either a value is found, or the search path is exhausted. If the search path is exhausted the user is prompted for a value, unless the ‘noprompt’ specifier has been given, in which case the system returns a PAR__NULL status value to the program.
Example:
This specifies a ‘vpath’ of ‘dynamic’ followed by ’current’ for parameter ‘INPIC1’.
This associates a program parameter with a global parameter.
If the system comes across the ‘global’ specifier in a vpath or ppath, this fieldname tells it which global parameter to use as a source for the value.
The ‘association-specification’ field is a character string which specifies the global parameter. This string has two parts:
The ‘association-operator’ field must one of the following:
‘write’ means that if the task completes successfully, the current value of the parameter will be copied to the global parameter.
The ‘parameter-specification’ field must be the name of a global parameter.
This fieldname only needs to be specified if the specifier ‘global’ is used in the ppath or vpath for the parameter.
Example:
The global parameter ‘global.data_array’ will be used as the suggested-value in the prompt. The parameter value will be obtained by prompting if it is not specified on the command line.
This specifies one or more default values for a parameter.
The ‘default-value’ field is a string of alphanumeric characters containing items to be used as values for the parameter. The values may be any expression acceptable to the parameter system. This fieldname must not be specified before the ‘type’ fieldname has been declared.
Example:
The default value for parameter OTITLE is ‘KAPPA - Add’. The vpath specifies that this will be used as the parameter value if one is not specified on the command line.
This specifies a set of valid values for a parameter.
The ‘set-of-values’ field consists of a list of constants separated by commas. These constants are the valid values.
Checking is carried out when a program attempts to get a value for a parameter. If the supplied value does not belong to the valid set, either the status SUBPAR__OUTRANGE is returned, or the system attempts to prompt for the value. No checking occurs when writing a value.
This fieldname should only be used for scalar parameters and must be specified after ‘type’. A parameter cannot have both a ‘range’ and an ‘in’ field.
Example:
The only valid values for parameter BOXSIZ are 3, 5, 7, 9, 11, 13, 15.
This specifies a range of valid values for a parameter.
The ‘range-of-values’ field consists of two constants separated by a comma. These constants specify the range boundaries. This fieldname has the same characteristics as the ‘in’ field described above.
Example:
The only valid values for parameter SIGMA lie in the range 0.1 to 5.0.
If a program uses the Message or Error systems it can specify one or more ‘Message Parameters’. Text can be associated with these parameters in the interface file by using a ‘Message Specification’. However, this is not essential since text specified in the program will be used by default.
The Message specification has the form:
where ‘PARNAME’ is the Message Parameter name which is used in the call to an ERR or MSG routine.
Currently only one fieldname is supported:
This specifies the text to be associated with the message parameter.
The ‘string’ field contains the text to be used. The string may be anything acceptable to the ERR or MSG routine (i.e. it may include tokens etc.).
Example:
This will replace the message defined in the program with the message specified by ‘text’.
When a set of programs are grouped into a monolith, their interface files should be concatenated into a single interface file as follows:
An example is given in Section 11.8.
A simple program will get values for its parameters, do something with them, and then finish. However, a programmer may wish to obtain a sequence of values for a single parameter, and a user may wish to indicate that no parameter value should be used. To deal with these requirements, ADAM uses the concept of Parameter State. A parameter can be in one of the four states shown in Table 14.3. This shows how the various states are entered.
State | Method of entry | Method of getting a value |
GROUND | Program entry | Follow the vpath in the interface file |
ACTIVE | GET, PUT, ASSOC routines | Use the current value |
ANNULLED | Input value of ‘!’ | Value not set; STATUS=PAR__NULL |
CANCELLED | CANCL routines | Prompt the user for a value |
In simple programs, each parameter goes from GROUND to ACTIVE state when it is given a value and stays in that state until the programs exits. The significance of the parameter state is its effect on what happens when a program asks for a value for a parameter; this is also shown in Table 14.3. If a program asks repeatedly for the value of a parameter, as in:
the first call will get a value for ‘X’ by following the vpath. However, the second and succeeding calls will obtain the same value as obtained by the first call since this is the ‘current value’ and the vpath is not used. In particular, the user will not be prompted for another value. However, if the programmer ‘cancels’ the parameter by calling PAR_CANCL before each attempt to get a value:
the user will be prompted for each call of PAR_GET0R. This technique is useful when you have finished processing one object associated with a parameter, and want to process a different object within the same program.
Each subroutine library which has been integrated with the ADAM system has a CANCL routine, identical in form to PAR_CANCL, with which to cancel the association of a parameter with an object previously made by the ASSOC routine. For example:
The CANCL routines are different from the ANNUL routines considered earlier. For example, in:
the second DAT_ASSOC will associate the same object with parameter X as the first one did, because DAT_ANNUL does not break the association. Notice that the first parameter of ANNUL routines is the identifier used to address the object, whereas the first parameter of CANCL routines is the parameter name.
The ANNUL routines have nothing to do with the ‘ANNULLED’ state of a program parameter; it’s just an unfortunate clash of words.