Processing math: 100%

3 Supplying Parameters

 3.1 Command Line Parameters
 3.2 Vpaths and Prompts
 3.3 Specifying HDS Objects
 3.4 ‘Special’ Keywords
 3.5 Global Parameters
 3.6 Interface Files

3.1 Command Line Parameters

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:

  % hcreate file dims=10 _REAL

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.

3.2 Vpaths and Prompts

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.

3.3 Specifying HDS Objects

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:

  image.data_array.data

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:

  container(2).data_array.data(:50,100:150)

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.

3.4 ‘Special’ Keywords

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:

  % hcreate prompt

will cause a prompt for all the parameters of hcreate, including the dimensions which would otherwise be defaulted to produce a scalar.

3.5 Global Parameters

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.

3.6 Interface Files

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.