4 The Parameter Specification

4.1 Introduction

Each program parameter must have a Parameter Specification in the Interface File. The Parameter Specification is of the form:

where parametername is a character string giving the program parameter name which is used in the program (in a call to DAT_ASSOC or PAR_GETnx etc.). Case is not significant in parameter names. For a discussion of valid parameter names, see Appendix A.1.

The possible subfields in the Parameter Specification are described in detail below – they are all optional and, apart from TYPE, which must appear before DEFAULT, RANGE or IN fields, the order is unimportant.

4.2 Summary of Parameter Specification Subfields

The Parameter Specification subfields are described in detail in the following sections. This is a classified list to show the features available.

Data Type and Access Fields

Command Line Control Fields

Value Control Fields

Prompt Control Fields

4.3 The TYPE Field

This field specifies the type of the parameter. This field is used by the system to determine the type of storage to be used for the parameter and its default values, etc. If a primitive value of a different type is supplied, it will be converted to the specified type for storage if possible. If conversion is not possible, an error is reported.

It is important to distinguish between the type of the parameter and the type of the value to be obtained from it by the program.

The field is of the form:

where datatype is a character string giving the required type of the parameter. datatype may be:

• A ‘standard’ HDS primitive type (i.e. _INTEGER, _REAL, _DOUBLE, _LOGICAL, _CHAR).
• LITERAL – formerly used to specify that the parameter is of type _CHAR and to force the parameter system to accept unquoted character strings as character values rather than HDS object names. This is now the standard behaviour for parameters of type _CHAR so datatype LITERAL is no longer required.
• A ‘user-defined’ type (IMAGE, SPECTRUM etc.).
• UNIV – used by convention when the parameter type is unimportant. Actually this is treated the same as other ‘user-defined’ types. Parameter storage corresponding with the type of the value given will be created.
• A ‘facility-recommended’ type (TAPE for MAG, FILENAME for FIO etc.). These are used by convention – actually any user-defined type will do.

If the TYPE field is omitted, type UNIV is assumed.

Notes:

(1)

Internally only the ‘standard’ primitive types (_LOGICAL, _INTEGER, _REAL, _CHAR, _DOUBLE) are differentiated – all other types are treated the same.

(2)

Only values of the standard types, or names, can be given in the Interface File or as parameter values at run time.

(3)

The dimensionality of parameters is not declared in the Interface File, but is defined by the value given at run time. The given dimensionality must be acceptable to the program (e.g. when it does a call to PAR_GETnx).

(4)

The PAR_GETnx/_PUTnx routines only GET/PUT values of the standard HDS types – other types have to be handled by calls to the appropriate facility_ASSOC routine (DAT_ASSOC for example). Where primitive values are being handled, conversion between the value type and the storage type will be performed if necessary and possible.

Example

Suppose there is a program DISP that draws an image on an image display device. It has three parameters:

IMAGE

the dataset containing the image to be drawn,

DISPLAY

the name of the image display device, and

LIMITS

an integer array of limiting values.

The Interface File might be:

If the user specified a value of [1.2,511.8,255.6,512.1] for the LIMITS array, i.e. a _REAL array where type _INTEGER is specified for the parameter, the system knows that this is a valid conversion and can perform it for the user (i.e. [1,511,255,512] is stored).

Similarly, the program could try to obtain a _REAL array from the parameter storage (by calling PAR_GET1R). In that case, the array would be converted back to _REAL although the numbers supplied by the user would have been truncated (i.e. [1.0,511.0,255.0,512.0] would be supplied to the program).

4.4 The PTYPE Field

Most parameters are associated with values of one type or another, e.g. primitive data types, or data-system objects. These are known as normal parameters.

However, there is a class of parameters which are intimately associated with some type of device (e.g. a magnetic tape drive, or a graphics terminal). These are known as device parameters. Device parameters are typically used in calls such as GKS_ASSOC. A parameter is defined as a device parameter by the PTYPE field.

where parameter-type is a character string which can currently only be DEVICE.

The precise type of the device can be indicated by the TYPE field. The specification for parameter DISPLAY in our example above would then be:

The value of a device parameter is a name which can be translated to define the device to be used. For details of possible values, see the appropriate facility description, SGS, GKS, FIO etc.

Currently PTYPE is not used by the system – only the TYPE is of significance and there anything other than a standard HDS type will have the same effect.

4.5 The ACCESS Field

This field specifies the mode of access which the program requires to the parameter. It is used to restrict access to parameters handled by PAR routines or by DAT_ASSOC.

Note that the field has no effect for facilities such as NDF, FIO and GKS which only use the parameter system to get the name of a file or device which is accessed by other means. The access mode applies to the parameter itself, not to any file or device, etc. that the parameter refers to.

The field has the form:

where mode is a character string which may be:

READ

which gives read access.

WRITE

which gives write access.

UPDATE

which gives read and write access.

Thus if a program does not modify the parameter, READ should be specified in the Interface File. If the value is to be written or modified, then WRITE or UPDATE should be specified.

If the ACCESS field is omitted, UPDATE is assumed.

Example

The access fields for the parameters in our DISP example could be:

4.6 The POSITION Field

Defines the parameter position on the command line at which values for this parameter may be given.

There are a limited number (See Appendix E) of command line positions available to be allocated. Not every parameter need be allocated a position, but the positions allocated must form a contiguous set starting at 1. Each position may have only one parameter allocated to it.

Note that, for ADAM I-tasks, the POSITION field may be overridden by an individual action NEEDS list (see the ACTION specification, Section 7).

The field is of the form:

where n is an integer constant which specifies the allocated position.

If the POSITION field is omitted, no command line position is allocated to this parameter.

Example

Again taking our DISP example, if the positions were specified as follows:

and the user gives the command:

Then the HDS object iue.image.swp2099 would be associated with parameter IMAGE, XWINDOWS would be used as the DISPLAY and LIMITS would take the value [1,511,255,512].

4.7 The KEYWORD Field

This field defines the name by which the parameter is known to the person running the program and which can be used on the command line to specify a value for the parameter. It will also be used to refer to the parameter in prompts and error messages. Case is not significant in keywords – they are always displayed in upper case.

The field is of the form:

where name is a valid keyword³.

This completes the separation between the program’s view of parameters, and the user’s view of them. It is possible for the programmer to re-write the program using completely different parameter names, but the user’s view could be kept the same by just changing the parameter names in the Interface File. Similarly, the user’s view of the program can be changed by just changing the KEYWORD fields.

If the KEYWORD field is not specified for a parameter, then the system will use the parameter name as the keyword.

Example

If the names of the parameters in the DISP example were changed, the user’s view could be preserved by specifying keywords as follows (Note: the example is not intended as an illustration of common practice – it is only to illustrate the principle):

The user could then specify:

Note that keyword-style parameter specifiers are ignored in calculating position. Therefore, with the above Interface File, the same effect would be produced by the command:

Logical Keywords

If a parameter is of type _LOGICAL, its keyword alone may be used on the command line to specify the value TRUE for the parameter and the keyword prefixed by NO to specify the value FALSE.

For example, assume a program TEST with a logical parameter, keyword SWITCH, then:

and

4.8 The DEFAULT Field

This field is used to specify a static default value for a parameter. The static default value is one of the options available to be used as the parameter value.

The field is of the form:

where default_value may be:

• A constant (number, character or logical).
• A name.
• An array. (Currently only 1-D arrays may be given, and the run-time syntax for arrays, involving square brackets, cannot be used – they must be specified as a sequence of constants and may be enclosed in parentheses.)
• The null value (!).

The field is terminated by the next reserved-word token, therefore names which correspond with a reserved word cannot be given unless enclosed in quotes.

Note that DEFAULT cannot be specified before the TYPE field has been declared and the value specified must be appropriate for the specified type. A character constant (quoted string) may be given as default_value for a non-primitive type – the string within the quotes will be used as the ‘name’ when required. This can be useful if non-standard strings are to be given as defaults (e.g. lists for the GRP facility handling parameters declared as TYPE NDF).

Example

4.9 The ASSOCIATION Field

This field is used to specify that another parameter is to be associated with this parameter. The value of the associated parameter is one of the options available to be used as the value of this parameter. Furthermore, the value of a parameter can be used to automatically update the value of its associated parameter on successful completion of the program.

This behaviour is primarily of relevance to ADAM A-tasks. I-tasks can obtain parameter values from an association, but do not write parameters on completion.

The field is of the form:

where association-specification is a character string consisting of two parts – an association operator followed by a parameter specifier.

There are three association operators:

• <- The associated parameter may be used by the program (see Sections 4.10 and 4.14) but will not be updated by it.
• -> The associated parameter will be set to the value of the program parameter if:
  • The program has ended successfully, i.e. STATUS = SAI__OK.
  • The program parameter has a value and has not been cancelled.
  • The program is an A-task or A-task monolith.
• <-> combines <- and ->.

Currently, only global parameters may be associated with program parameters – they are stored in the GLOBAL data structure and provide a common pool of parameter values for programs in an integrated system. Global parameters can be created by the association write mechanism or by an ICL CREATEGLOBAL or SETGLOBAL command. They may also be read into ICL variables by the GETGLOBAL command. It is necessary to be careful when multi-tasking in ADAM because an error will occur if two programs attempt to update the GLOBAL data structure simultaneously.

The specifier of a global parameter is of the form:

If the ASSOCIATION field is omitted, no association is made.

Example

This gives the parameter DISP.IMAGE read and write access to the global parameter GLOBAL.IMAGE.

4.10 The VPATH Field

This field is used to specify the way in which a value is obtained for a parameter if the user does not specify a value (on the command line, or by an ICL SEND SET command, for example) before it is required by the program. In that case, there are several potential sources for parameter values and different applications will want to use different sources for their various parameters.

The VPATH field is the means whereby this order of searching for parameter values is specified.

The field is of the form:

where value-resolution-path is a character string which gives a path used for searching for a parameter value. It consists of a set of path specifiers. If there are two or more path specifiers, they must be separated by commas and the string must be enclosed in single quotes.

The valid specifiers are:

CURRENT

Use the current (last-used) value of the parameter. (See Section 3 for more information on the current value.)

DYNAMIC

Use the dynamic default value specified by the program. Dynamic defaults are set by the program calling a subroutine such as PAR_DEFnx or DAT_DEF specifying the required values.

DEFAULT

Use the static default specified in the Interface Module (see Section 4.8).

GLOBAL

Use the value of the associated parameter (see Section 4.9, The ASSOCIATION Field).

PROMPT

Prompt the user and obtain a value. (See also Section 4.14, The PPATH Field.) There is an implied PROMPT at the end of every VPATH. Note that PROMPT will always give a result to the program, even if it is a bad status, therefore PROMPT only makes sense as the last thing on the path.

NOPROMPT

Give up trying to get a value and return status PAR__NULL. This only makes sense as the last specifier in the path and will prevent a prompt being issued as a last resort if the value-resolution-path is exhausted.

INTERNAL

This specifier can only be used as the first and only specifier on the VPATH. A value-resolution-path of ’DYNAMIC,CURRENT,NOPROMPT’ is implied⁴. ‘Internal’ storage will be used to hold the parameter values. Scalar values are stored in memory to give enhanced performance; array values are stored in the parameter file.

If the value for a parameter has not been specified when it is required, the system looks at the VPATH specification, picks out the first path specifier and tries to find a value from this source. If a value is not found, the next path specifier is extracted and another search is made. This process continues until a value is found, the specifier is NOPROMPT or the path specification runs out. If the path specification is exhausted, the user is prompted for a value.

Note that the VPATH field is only used the first time a parameter value is obtained. If the parameter is cancelled before another attempt to ‘get’ a value, a prompt will be issued, even if NOPROMPT is put on the VPATH. If the parameter is not cancelled, the existing value will be returned again.

If the VPATH field is omitted, VPATH PROMPT is assumed.

Example

Suppose the parameters of DISP are specified as follows:

Then, if the user just types:

(i.e. does not give any parameter values), the following actions occur:

When the program asks for the value of the IMAGE parameter, no value has been given so the first part of the VPATH specification is extracted (GLOBAL). This path specifier tells the system to look for a value of the associated parameter (GLOBAL.IMAGE). If it has a value, this value is taken as the value of IMAGE; if not, the resolution path is exhausted so the user will be prompted for a value for IMAGE.

When the program asks for a value of DISPLAY, the specifier CURRENT is extracted from the VPATH. If DISPLAY has a current value, the same value is used again; if not, the static default value (XWINDOWS) specified in the Interface File is taken.

Similarly, when the program asks for the value of LIMITS, the system attempts to use the dynamic default suggested by the program. If no dynamic default has been set, the user is prompted for a value for LIMITS.

Run-time Modification of VPATH Action

The user can modify the action of VPATH at run time by using the special command-line keywords PROMPT and/or RESET.

PROMPT

causes the VPATH to be ignored and a prompt to be issued for any required parameters which have not already been given values.

RESET

makes the system ignore CURRENT on the VPATH. See also Section 4.14 for the effect of RESET on prompts.

For example, assuming the Interface File above,

causes all parameters to be prompted for, irrespective of VPATH.

causes the system to ignore ‘CURRENT’ in the VPATH for parameter DISPLAY, and use the DEFAULT value.

4.11 The RANGE Field

This field is used to specify a range of permitted values for the parameter. The RANGE values will also be used if MIN or MAX is specified as the parameter value in the absence of any dynamic minimum or maximum values set by the program.

RANGE can only be specified for parameters of standard primitive type other than _LOGICAL, and is only relevant if the parameter value is a scalar. A RANGE field will also constrain any dynamic minimum or maximum values which the program may set.

A parameter cannot have both a RANGE and an IN field and RANGE cannot be specified before TYPE has been declared.

Range checking is carried out when a program attempts to get the value of a parameter or set a minimum or maximum value. No range checking occurs when putting a value. For _CHAR parameters, all values are converted to upper case for checking and the ASCII collating sequence is used.

If the constraints are violated, the system reports the error and, if the violation was on getting a parameter value, prompts for another value unless the parameter had VPATH INTERNAL, in which case status SUBPAR__OUTRANGE is returned.

The field is of the form:

where min and max are two character or number constants specifying the minimum and maximum values for the parameter – the values must be convertible to the type of the parameter.

If min > max, the value must not lie between them. The values themselves are always acceptable.

Example

4.12 The IN Field

This field is used to specify a set of values which the parameter may take. IN can only be specified for parameters of standard primitive type other than _LOGICAL, and is only relevant if the parameter value is a scalar.

A parameter cannot have both a RANGE and an IN field and IN cannot be specified before TYPE has been declared.

Checking is carried out when a program attempts to get the value of a parameter.

No checking occurs when putting a value. For _CHAR parameters the check is case independent.

If the constraints are violated, the system reports the error and prompts for another value unless the parameter had VPATH INTERNAL, in which case status SUBPAR__OUTRANGE is returned.

The field is of the form:

where set-of-values consists of a list of character or number constants specifying the valid values for the parameter. The specified values must all be convertible to the type of the parameter. The set of values is terminated by the next reserved-word token, therefore any required string which corresponds with a reserved word must be enclosed in quotes.

Example

4.13 The PROMPT Field

This field is used to specify a prompt string for the parameter⁵.

The field is of the form:

where text is a character string (n.b. it must be enclosed in quotes if it consists of more than one token).

If the PROMPT field is omitted, the parameter keyword is used as the prompt.

Example

Suppose that the user has given the command:

The program will take the specified value as the value of the IMAGE parameter. When it requires the DISPLAY parameter value, none has been specified on the command line so, as the VPATH field specifies that the user is to be prompted for a value, the system generates a prompt line such as:

to which the user has to reply with a suitable value. (The prompt may also have a suggested value for the parameter, obtained via the PPATH field, see below).

4.14 The PPATH Field

This field specifies a path used for searching for a suggested value ⁶. The suggested value will be displayed as part of the prompt string and used as the parameter value if the user responds to the prompt by hitting the carriage return key. Hitting the TAB key will make the suggested value available in the terminal input buffer where it can be edited with the normal line editing commands.

The field is of the form:

where value-resolution-path is a character string consisting of a set of path specifiers. If there are two or more path specifiers, they must be separated by commas and the string must be enclosed in single quotes.

The valid specifiers are:

CURRENT

Use the current value of the parameter. (See Section 3 for more information on the current value.)

DYNAMIC

Use the dynamic default value specified by the program. Dynamic defaults are set by the program calling a subroutine such as PAR_DEFnx or DAT_DEF specifying the required values.

DEFAULT

Use the static default value specified in the Interface Module (see Section 4.8).

GLOBAL

Use the value of the associated global parameter (see Section 4.9, The ASSOCIATION Field).

If the suggested value for a parameter is required, the system looks at the PPATH specification, picks out the first path specifier and tries to find a value from this source. If a value is not found, the next path specifier is extracted and another search is made. This process continues until a value is found, or until the path specification runs out. The value is then passed, together with the prompt string, in a parameter request message to the user interface.

If the PPATH field is omitted, or fails to give a value, ’DYNAMIC,DEFAULT’ is used. If this fails to give a value, there is no suggested value.

Example

Assuming that:

(1)

There is no current value for IMAGE.

(2)

GLOBAL.DEVICE has the value XWINDOWS.

(3)

The program has not specified a dynamic default for LIMITS.

Then, with the above Interface File, if the user just types:

(i.e. does not give any parameter values), and the VPATH field results in the user being prompted, the three prompts would be something like:

Note the ‘@’ in the suggested values is inserted by the system to avoid ambiguity between names and character strings.

Run-time Modification of PPATH Action

The user can modify the operation of the PPATH at run-time by using the special command-line keywords RESET and/or ACCEPT.

RESET

Causes CURRENT to be ignored on the PPATH.

ACCEPT (or $\setminus$)

causes the suggested value to be used for any required parameters which would otherwise be prompted for. The user may also respond to a prompt with $\setminus$. The suggested value will be taken for the prompted parameter and for any remaining parameters. It is also possible to force ACCEPT for individual parameters by putting keyword=ACCEPT or keyword=$\setminus$ on the command line (where keyword is the keyword of the parameter).

If there is no suggested value, the prompt will be issued anyway.

E.g. with the Interface File above, the command:

will cause the static default value, rather than the current value, to be used as the suggested value for IMAGE, and that value to be used as the parameter value without prompting.

4.15 The HELPKEY Field

This field is used to specify a help file and a module within it at which multi-line help text for the parameter may be found⁷. Text read from a help file is known as multi-line help although it could in fact be only one line.

The field is of the form:

where help_specifier is a character string of the form:

specifying that the text to be displayed may be found in the help file filename and the module defined by key1 key2 etc... (but see also the HELPLIB Specification, Section 5). For more information on multi-line help and a discussion of help filenames, see Appendix D.

help_specifier may also be * or ’*’, in which case a default value of:

will be used, where interface_name is the name specified in the current INTERFACE field. (Use of this default implies that there is an associated HELPLIB Specification.)

If the user is prompted for a parameter value, and responds with ‘??’, the specified text is displayed at the terminal and the user will be left in the help system and prompted for further topics of interest.

If the user responds with ‘?’ and there is no HELP field specified for the parameter the effect is the same except that the user will be re-prompted for the parameter value immediately (except from SMSICL).

Example

The previous example is therefore better written:

4.16 The HELP Field

This field is used to specify some help text for a parameter⁸.

This field is of the form:

where help-specifier is a character string giving help information about the parameter, it may be either a single line of text to be displayed (single-line help) or a string of the form:

specifying that multi-line help may be found in the help file filename and the module defined by key1 key2 etc...

Note that the preferred way of specifying multi-line help is using the HELPKEY field and that single-line help is not generally considered very useful.

If the user is prompted for a parameter value, and responds with ‘?’, the specified text is displayed at the terminal and the user is re-prompted. (Except in the case where SMSICL outputs multi-line help – then the user is left in the help system and prompted for further topics of interest. When the user exits from the help system, the parameter prompt will reappear.)

If the user responds with ‘??’ and there is no HELPKEY field specified for this parameter, the effect is the same except that if multi-line help is output the user will be left in the help system and prompted for further topics.

Example