The Starlink (ADAM) parameter system used by the HDSTOOLS application programs allows parameter values to be specified on the command line by ‘positional’ or ‘keyword’ parameter specifiers.
Keyword parameter specifiers have the syntax keyword=value
where name
is the parameter
keyword. (For HDSTOOLS the keyword is always the same as the parameter name.) Keyword
specifiers may appear in any order on the command line and the case of the keyword is not
significant.
Parameter specifiers which are not keyword specifiers are positional – the first of them applies to the parameter whose position is defined as 1, the second to the parameter whose position is defined as 2 etc. For example:
The parameter whose position is 1 takes the value file
, the parameter whose keyword is DIMS takes
the value 10
and the parameter whose position is 2 takes the value _REAL
. Precisely how the values are
interpreted depends upon the type of the parameter.
Parameters of type _CHAR take a character string as their value. If a string containing space or comma is specified on the command line, the parameter system requires that it is enclosed in double quotes. (Positional specifiers must also be quoted if they contain‘=’.)
Parameters of type _LOGICAL take the value YES, Y, NO, N, TRUE, T, FALSE or F (regardless of case). Alternatively the keyword specifiers ‘KEYWORD’ or ‘NOKEYWORD’, where KEYWORD is the parameter’s keyword may be given to set TRUE or FALSE respectively.
Note that when programs are run from the Unix shell and values are specified on the command line, it is often necessary to protect characters from the shell by inserting ∖ or enclosing them in single quotes. Characters which are likely to cause trouble are: ()[]*!". This is not a problem when replying to prompts or when running from ICL.
If a parameter value is not specified on the command line, its value may be obtained by following a ‘value-path’ (known as the vpath) until a value is found. The path consists of a list of possible ‘default’ sources, including prompting the user (which will always produce a value).
Prompts may include a ‘suggested value’ obtained by following a ‘ppath’ similar to the vpath. In response to a prompt, you can type in a value, terminated by the <return> key, or the suggested value may be used by just hitting the <return> key, or placed in the input area by hitting the <tab> key. The input area may be edited (see SUN/144 for details).
Other possible responses to a prompt are:
! | The ‘null’ response. This will usually terminate the program but has a special meaning for some parameters (see the program description). |
!! | The ‘abort’ response. This will invariably abort an HDSTOOLS program. |
? | The ‘help’ response. This will display a one-line help message about the parameter and then re-prompt. |
?? | The ‘fullhelp’ response. This will put the user into the full help system, displaying the help for the parameter. On exit from the help system the user will be re-prompted. |
An HDS object is specified as a pathname comprising a ’container file’ optionally followed by a number of component names separated by ‘.’ – all but the last component must be structures. For example:
specifies component DATA of a structured component DATA_ARRAY of the container file image.sdf
.
Note that the file extension (.sdf
is not given and the case of component names is not
significant.
Usually, where an object is required, a cell or slice of an array object may be specified instead. Cells and slices are specified in parentheses after the component name and consist of ranges for each dimension, separated by ‘,’. Ranges take the form: ll:ul, where ll and ul are lower and upper limits. Either limit may be omitted implying the beginning or end. If the ‘:’ is also omitted the upper and lower limits will be the same i.e. the one number given.
For example:
specifies elements 1 to 50 in the first dimension and 100 to 150 in the second the DATA component of
the DATA_ARRAY structure of the second structure in the top-level structure array in container file
container.sdf
.
Note that when running direct from the Unix shell, the parentheses will need protecting.
In addition to the parameter keywords, there are several ‘special keywords’. You may find the following two useful:
PROMPT | Forces a prompt for any values not defined on the command line, regardless of what is on the vpath. |
ACCEPT | Forces the suggested value to be used if a prompt would otherwise occur. |
For example:
will cause a prompt for all the parameters of hcreate
, including the dimensions which would
otherwise be defaulted to produce a scalar.
Parameters may be ‘associated’ with a ‘global’ parameter and thus values may be shared between different programs. The association may be to write the parameter’s value on successful completion and/or use its value on the vpath or ppath. Several HDSTOOLS programs use the global parameter HDSOBJ to remember the last-used HDS object and/or offer it as a suggested value at a prompt. In this way a sequence of operations may be easily performed on the same object.
Each program’s parameters and their positions, keywords, vpaths, ppaths and associations etc. are defined in an ‘Interface File’ (see SUN/115)
Interface files are provided for each program but it is possible to use private customised files instead.