4 Parameters

 4.1 Summary
 4.2 Defaults
 4.3 Globals
 4.4 Strings
 4.5 Arrays
 4.6 Abort and Null
 4.7 Help
 4.8 Menus
 4.9 Environment Variables
 4.10 Specifying Parameter Values on Command Lines
 4.11 Special Keywords: ACCEPT, PROMPT, RESET
 4.12 MIN and MAX parameter values
 4.13 Specifying Groups of Objects
 4.14 Output Parameters

Kappa is a command-driven package. Commands have parameters by which you can qualify their behaviour. Parameters are obtained in response to prompts or supplied on a command line.

For convenience, the main aspects of the parameter system as seen by a user of Kappa are described below, but note that most of what follows is applicable to any Starlink application.

4.1 Summary

For your convenience, here is a summary of how to use parameters. If you want more information, go to the appropriate section.

Command-line values
On the command line you can supply values by keyword or by position. See Specifying Parameter Values on Command Lines for more details including abbreviated keywords.
ACCEPT, PROMPT, RESET command-line special keywords
ACCEPT accepts all the suggested defaults that would otherwise be prompted. PROMPT prompts for all the parameters not given on the command line, and RESET resets all the suggested defaults to their initial values. You can find more details and examples in Special Keywords: ACCEPT, PROMPT, RESET.
NAME - Prompt string /Suggested default/ >
This is a schematic of a prompt. NAME is the parameter’s name. You normally respond with the value for the parameter, but there are special responses available (see below). If you just hit the return key, the suggested default becomes the parameter value. Many parameters are defaulted without prompting. See Defaults and Globals for more details.

Here is a list of some example parameter values to illustrate the possible ways you can respond to a prompt. Where there are command-line differences, they are noted.

5409.12
This is a scalar. Numerical values can be integer, real, or double precision.
12,34,56,78
This is a vector. They must be enclosed in [ ] if the array is supplied on the command line, or for character arrays.
[[11,21,31],[12,22,32]]
This is a 3×2 array. Arrays of dimension > 2 should appear in nested brackets. See Arrays for more about array values.
T
no
This is a TRUE value followed by a FALSE values for logical parameters. Acceptable values are TRUE, FALSE, YES, NO, T, F, Y, N and their lowercase equivalents. On the command line, the parameter name as a keyword means TRUE. If the name is prefixed with NO, the value is set to FALSE.
a string
"a string"
This is a string. Strings need not be quoted at prompts. Quotes are required on the command line if the string includes spaces or wildcards, or is a comma-separated array of strings. There is more in Strings. Some parameters offer a selection from a menu to which you give an unambiguous abbreviation to select an option. Other parameters can be numerical or a string. (See Menus for more information.)
filename
@123
This enters a filename (or tape drive). You give a text filename verbatim, and NDFs without the file extension. Foreign formats will usually have the file extension. Should the filename be a numerical value, it must be preceded by an @. There is more in Strings.
min
max
This selects the minimum- or maximum-allowed value, but not all parameters have a defined range of permitted values. See MIN and MAX parameter values.
!
Enters the null value. This has a variety of special meanings; which one will depend on the particular parameter. For example, null might indicate that an output file is not to be created, or a loop is to be ended. There are more examples in Abort and Null.
!!
This aborts the application cleanly.
?
??
A single question mark presents the online help for the parameter, and then reprompts. A double question mark leaves you in the help system to explore other help information. See Help for examples. These special values are not supported from the command line.
\
This accepts the suggested default for the prompted parameter and the respective suggested defaults for all subsequent parameters for which prompting would otherwise occur. On the command line \ is an abbreviation of the ACCEPT keyword, and it applies to all parameters that would otherwise be prompted. Note that from the shell you write \\, as \ is a shell metacharacter.

4.2 Defaults

Command-line values are used mostly for those parameters that are normally defaulted by the application. Defaulted parameters enable applications to have many options, say for controlling the appearance of some graphical output, without making routine operations tedious because of a large number of prompts. The values of normally defaulted parameters are given in the application specifications. You can also find them by obtaining online help on a specific parameter. They are enclosed in square brackets at the end of the parameter description.

       ICL> kaphelp median param *

gives details of all parameters in application MEDIAN. Other packages have similar help commands. If you want to override one of these defaults, then you must specify the parameter’s value on the command line.

When you are prompted you will usually be given a suggested default value in / / delimiters. You can choose to accept the default by pressing carriage return. For example, 64 is the suggested value below.

       XDIM - x dimension of output array /64/ >

Alternatively, enter a different value

       XDIM - x dimension of output array /64/ > 109

to override the default. Some defaults begin with an @.

       IN - Input image /@starfield/ >

These are associated with files (text and HDS) and devices (graphics and tape). If you want to override the default given, you do not have to prefix your value with an @, e.g.

       DEVICE - Name of display device /@xwindows/ > x2w

There are rare cases when the syntax is ambiguous, and it is then that you need to include the @. Strings describes when the @ is needed.

From both ICL and the shell the default value can be edited to save typing by first pressing the <TAB> key. The editor behaves like the shell command-line editor.

Defaults may change as data are processed. Often the current (last) value of the parameter will be substituted, or a dynamic value is suggested depending on the values of other parameters. Here is an example comprising a loop within an application.

  
       NDF - NDF to examine /@horsehead >
       CENTRE - Position at the centre of the listing /’64 64’/ > 100 120
          .              .               .              .
          .              .               .              .
          .              .               .              .
       CENTRE - Position at the centre of the listing /’100 120’/ >
       SIZE - The dimensions (in pixels) of the area to be listed /7/ >
          .              .               .              .
          .              .               .              .
          .              .               .              .
  

and so on. Notice that the current values of the centres are the suggested values at the second prompt.

Current values of parameters are stored in a parameter file, and so they persist between sessions. For tasks run from the shell, this is an HDS file $ADAM_USER/ <application >.sdf, where <application > is the name of the application. (If the environment variable ADAM_USER is not defined the parameter file is situated in $HOME/adam).

Unfortunately, tasks invoked from ICL use a monolith parameter file, which contains the individual application parameter files for the members. So for example, Kappa has kappa_mon.sdf, kapview_mon.sdf, and ndfpack_mon.sdf stored in the same directory as the individual files. This duality means that there are two independent sets of current values for each task depending on where you ran it from.

The parameter file should not be deleted unless the parameters values are to be completely reset, or the file has been corrupted in some way. If you suspect the latter case, say after interrupting a task(Section 3.5), run Hdstrace (SUN/102) on the file to check its integrity.

4.3 Globals

Kappa stores a number of global parameters that are used as defaults to reduce typing in response to prompts. Global means that they are shared between applications. The most common is the last dataset (usually NDF) written or accessed. In the example above, this was horsehead.sdf. If you just press <CR> in response to the prompt, the global value is unchanged. Only when you modify the parameter and the application completes without error is the global value updated.

All global parameters are stored in the HDS file $ADAM_USER/GLOBAL.sdf, or $HOME/adam/GLOBAL.sdf if the ADAM_USER environment variable is not defined. The full list is given below.

   GLOBAL.DATA_ARRAY    —   Last NDF or foreign data file accessed or written.
   GLOBAL.GRAPHICS_DEVICE   —   Current graphics workstation.
   GLOBAL.INTERACTIONMODE   —   Current interaction mode.
   GLOBAL.LUT    —   Last lookup table file accessed or written.
   GLOBAL.TRANSFORM    —   Current transformation structure.
      —   

Kappa uses the last DATA_ARRAY written or accessed as the suggested default value for the next prompt for an NDF structure or foreign data format. The same applies to the current lookup table and transformation structure. However, the remaining, including the graphics global parameter are defaulted—you will not be prompted. Details of how to control these parameters are given in the relevant sections.

The values of all global parameters may be inspected with the GLOBALS task. You can make them undefined using NOGLOBALS.

       ICL> globals
       The current data file                : @/home/dro/jkt/ccdpic
       The current graphics device is       : @ps_l
       The current lookup table file is     : @$KAPPA_DIR/spectrum_lut
       The current transformation is        : @/home/dro/deform/warpit
       The current interaction mode is      : <undefined>
       The current message-report level is  : NORMAL

In the above example no interaction mode is defined. The next time you call an application that uses the interaction mode you would be prompted for a value. (Under normal circumstances you will not have to enter the @ prefix yourself.)

Note that the message-reporting level is not a global parameter, but is defined by the MSG_FILTER environment variable. It controls the verbosity of informational messages. Since it applies to all tasks that report such messages, it is convenient to allow GLOBALS to show its value. Further details are in Section 5 for details. Since it is not a parameter as such, the message-reporting level is not unset by NOGLOBALS.

4.4 Strings

Notice that the single or double quotes around strings given in response to prompts for a character parameter can be omitted. However, on the command line these delimiters are needed if the string contains spaces, otherwise the second and subsequent words could be treated as separate positional parameters.

From the shell the quotes must be escaped. For example,

       % settitle myndf \"A new title\"

would assign the title "A new title" to the NDF called myndf.

To indicate that the parameter should come from a data-structure object, prefix the name with an @ to tell the parameter system that it is a file name, and not a literal value.

       TITLE - New NDF title /’ ’/ @$ADAM_USER/galaxy.mytitle

In this example TITLE has the value of object MYTITLE in galaxy.sdf. If the @ were omitted TITLE would be "$ADAM_USER/galaxy.mytitle". You will need the @ prefix if your file name is a number. Note that the file extension should not be included when giving the name of an HDS data file, including NDFs . Otherwise HDS will look for an object called SDF nested within the file.

Responses to prompts are case insensitive for comparison purposes. Strings for character components in NDFs, plot captions and labels are treated literally.

4.5 Arrays

If a parameter requires an array of values, the series should be in brackets separated by commas or spaces. For example,

       PERCENTILES - List of percentiles > [25,95.5,75]

would input three values: 25, 95.5, and 75 into the real parameter PERCENTILES. If the application is expecting an exact number of values you will be reprompted, either for all the values if you give too many, or the remaining values if you supply too few. There is one exception where you can omit the brackets—a fairly common one—and that is in response to a prompt for a one-dimensional numeric array as above.

From the shell you must escape the brackets.

       % display key=yes mode=pe percentiles=\[95,5\]
       % display key=yes mode=pe percentiles=’[95,5]’
       % display key=yes mode=pe percentiles="[95,5]"

All the above do this. Single quotes have the advantage that you can protect all the metacharacters that lie between the quotes, so you don’t need to escape each metacharacter.

Arrays of parameter values should appear in nested brackets. For example,

       CVALUE - Component values > [[2,3],[5,4],[7,1]]

supplies the values for a 2×3-element parameter array, where element (1,3) has value 7.

4.6 Abort and Null

Responding to a prompt with a null value ! will not necessarily cause the application to abort, but it can force a suitable default to be used, where this is the most-sensible action. A further use is when an optional file may be created, such as a lookup table; a ! entered in response to the prompt for the filename means that no file is to be output. Many tasks use null as a default for optional files. In some applications, a null ends an interactive loop.

Responding to a prompt with !! will abort the application. This process includes the various tidying operations such as the unmapping and closing of files. Any other method of stopping an application prematurely can leave files mapped or corrupted.

4.7 Help

To get help about a parameter enter ?. Usually, this will give access to the help-library information for that parameter, for example,

       BOX - Smoothing box size /3,3/ > ?
  
       BLOCK
  
         Parameters
  
           BOX() = _INTEGER (Read)
              The sizes (in pixels) of the rectangular box to be applied to
              smooth the data.  These should be given in axis order.  A value
              set to 1 indicates no smoothing along that axis.  Thus, for
              example, BOX=[3,3,1] for a three-dimensional NDF would apply a
              3x3-pixel filter to all its planes independently.
  
              If fewer values are supplied than the number of dimensions of
              the NDF, then the final value will be duplicated for the
              missing dimensions.
  
              The values given will be rounded up to positive odd integers, if
              necessary, to retain symmetry.
  
       BOX - Smoothing box size /3,3/ >

and then immediately reprompt you for the parameter. There are occasions when information about the parameter is insufficient; you may require to examine the examples or the description of related parameters. This can be achieved by entering ?? to the prompt. You can then delve anywhere in the help information. When you exit the help system you’re reprompted for the parameter.

4.8 Menus

Some parameters offer menus from which you select an option. You do not have to enter the full option string, but merely a string that selects a choice unambiguously. In many cases this can be as little as a single character. Here is an example,

       MODE - Method for selecting contour heights /’Free’/ > ?
           The method used to select the contour levels.  The options are
           described below.
  
             "Area"      - The contours enclose areas of the array for
                           which the equivalent radius increases by equal
                           increments.  You specify the number of levels.
             "Automatic" - The contour levels are equally spaced between
                           the maximum and minimum pixel values in the
                           array.  You supply the number of contour
                           levels.
             "Free"      - You define a series of contour values
                           explicitly.
             "Linear"    - You define the number of contours, the start
                           contour level and linear step between contours.
             "Magnitude" - You define the number of contours, the start
                           contour level and step between contours.  The
                           step size is in magnitudes so the nth contour
                           is dex(-0.4*(n-1)*step) times the start contour
                           level.
  

where an F would be sufficient to select the "Free" option, but at least two characters would be needed if you wanted "Area" or "Automatic".

Some parameters permit a mixture—a choice from a menu, or a numerical value within a range. The options are described in full in application specifications.

4.9 Environment Variables

Environment variables operate both on the command line and prompts, and both from the shell and ICL. Thus if IMAGEDIR is an environment variable pointing to a directory containing the NDF called ngc1365, you could access it at a prompt as shown below.

       IN - Input image /@starfield/ > $IMAGEDIR/ngc1365

4.10 Specifying Parameter Values on Command Lines

Parameters may be assigned values on the command line. This is useful for running tasks in batch mode and in procedures, and for specifying the values of parameters that would otherwise be defaulted. A command-line parameter will prevent prompting for that parameter unless there is an error with the given value, say giving an alphabetic character string where a floating-point value is demanded.

There are two ways in which parameter values may be given on the command line: by keyword and by position. The two forms may be mixed with care. The parser looks for positional parameters then keywords, so you can have some positional values followed by keyword values. See some of the examples presented in the application specifications.

4.10.1 Keyword

Keywords may appear in any order. Here is an example of command-line defaults using keywords.

       ICL> picdef current fraction=0.4

FRACTION is a real parameter. CURRENT is a logical parameter; by giving just its name it is assigned the value TRUE. CURRENT=T would have the same effect. To obtain a FALSE value for a logical parameter you add a NO prefix to keyword, for example,

       icl> picdef nocurrent

would be equivalent to the following.

       icl> picdef current=false
4.10.2 Abbreviations

There is an experimental system that allows you to abbreviate parameter keywords to the minimum unambiguous length. To use it, you must first create an environment variable called ADAM_ABBRV with an arbitrary value.

So for example

       % setenv ADAM_ABBRV true
       % display mo=pe pe=\[5,95\] ba=blue

would display an NDF between the 5 and 95 percentiles, and marking bad pixels in blue.

If you give an ambiguous keyword, the parameter system will present the list of possible keywords and ask you to select the one you intended.

4.10.3 Position

Alternatively, you can specify command-line values by position. Here is an example.

       % thresh raw clipped 0 255

This applies thresholds to the NDF called raw to form a new NDF called clipped. The values between 0 and 255 are unchanged. Note that trailing parameters may be omitted—NEWLO and NEWHI in the above example—but intermediate ones may not. The position of a parameter can be found in the Usage heading in the application specifications or the help for the application.

4.10.4 Keyword versus Positional Parameters

For tasks with a few parameters, using position is quick and convenient. However, in complex applications with many parameters it would be tedious not only to enter all the intermediate values between the ones you want to define, but also to remember them all. Another consideration is that some parameters do not have defined positions because they are normally defaulted. Keywords may also be abbreviated(Section 4.10.2). Thus the keyword technique is recommended for most parameters, especially in scripts and procedures. Unabbreviated keywords insulate scripts against new keywords and positional changes that are sometimes needed.

See custom Kappa commands if you want to learn how further to abbreviate command strings to reduce typing for manual operation.

4.10.5 Special Behaviour

Sometimes specifying a parameter on the command line induces different behaviour, usually to inhibit a loop for procedures, or to eliminate unnecessary processing. For instance,

       ICL> centroid blob init="51,42" mode=i

will determine the centroid near the point (51,42) in the NDF called blob, and then it exits, whereas without the INIT value you would be reprompted for a further initial position; and

       % display galaxy mode=sc high=3000 low=1000

prevents the calculation of the extreme values of the NDF called galaxy that are normally given as suggested defaults for parameters HIGH and LOW, because HIGH and LOW are already known.

4.11 Special Keywords: ACCEPT, PROMPT, RESET

Another way in which prompts and default values can be controlled is by use of the keywords ACCEPT, PROMPT and RESET.

The RESET keyword causes the suggested default value of all parameters (apart from those already specified before it on the command line) to be set to the original values specified by the application or its interface file. In other words global and current values are ignored.

The PROMPT keyword forces a prompt to appear for every application parameter. This can be useful if you cannot remember the name of a defaulted parameter or there would be too much to type on the command line. However, it may prove tedious for certain applications that have tens of parameters, most of which you normally never see. You can abort if it becomes too boring.

The ACCEPT keyword forces the parameter system to accept the suggested default values either for every application parameter if the keyword appears on the command line, or all subsequent parameters if it is supplied to a prompt. In other words, those parameters that would normally be prompted with a value between / / delimiters take the value between those delimiters, e.g. XDIM we saw in parameter defaults would take the value 64. Parameters that are normally defaulted behave as usual. The ACCEPT keyword needs to be used with care in scripts because not every parameter has a default, and therefore must be given on the command line for the application to work properly. For example, CREFRAME must have a value specified for parameter OUT, the name of the output NDF. If we run the application like this:

       ICL> creframe accept

it would fail in the sense that it would still have to prompt for a value—it does not know where to write the output NDF. However, if we run CREFRAME like this:

       ICL> creframe out=stars accept

it would generate an output image using default values for all the parameters except OUT, and write the output to file stars.sdf. Another point to be wary of is that some applications have loops, e.g. LOOK, LUTABLE, and if you use the ACCEPT keyword it will only operate the first time the application gets a parameter value.

Sometimes the keyword ACCEPT can be used without any parameter value specifications on the command line. For example, we could follow the above command by the command:

       ICL> look accept

and the central 7×7 array of the image created by CREFRAME would be displayed on your terminal without any parameter values being prompted. The symbol \ has the same effect as ACCEPT when used on the command line or at prompts, thus:

       ICL> look \

would have the same effect as the previous example—and is quicker to type. In command lines from the shell, the backslash is a metacharacter and has to be escaped. The easiest way to do that is to double the backslash.

       % look \\

How do you find out which parameters have suggested defaults, as opposed to those that are normally defaulted? Well, a good rule of thumb is that parameters for output files (images, lookup tables and text) will not have a default, but the remainder will. There are some exceptions, such as where null is the default for optional files. Consulting the description of the parameters should give the suggested defaults, where appropriate. If a parameter is given a suggested default it will have a line beginning ppath or a default line. If you want to use ACCEPT for an automatic procedure or batch job you could do some tests to find which parameters get prompted and then put them on the command line in your procedure.

The RESET and ACCEPT keywords will work in tandem. So for instance,

       ICL> look reset accept

will reset the suggested defaults of LOOK to their original, preset values, and accept these as the parameter values.

These special keywords may be abbreviated to no fewer than two characters, if you have enabled keyword-abbreviation (Section 4.10.2).

4.12 MIN and MAX parameter values

Many parameters have well-defined ranges of allowed values. In some cases it is useful to assign the maximum or minimum value to the parameter. Rather than give some numerical value, you can instead supply MIN to select the minimum-allowed value, and MAX to select the maximum. This applies both on the command line and at prompts. In the example,

       % block wlim=max

Parameter WLIM takes its maximum (1.0) meaning that if any of the input pixels in the smoothing box is bad, the corresponding output pixel is set bad.

Consult the reference section or the online help to see if a given parameter has such a range. If you attempt to use MIN and MAX where there is no range defined, you’ll see an error message like

      !! SUBPAR_MNMX: Parameter FONT - no upper limit set

and you’ll be invited to give another value.

4.13 Specifying Groups of Objects

Some parameters are describing in the reference documentation as being associated with a group of objects. For instance, some parameters may require a group of strings, others may require a group of numerical values, or data files. No matter what the nature of the object, groups are specified using a syntax called a group expression. The GRP library is used to interpret these group expressions, and the GRP documentation (SUN/150), should be consulted for full details. A summary is given here.

A group expression can identify the members of the group in any of the following ways:

A typical group expression will often include characters that are of significance to the shell. If the group expression is supplied on the command line it may be necessary to place quotes around the string to prevent the shell from removing these characters. Two lots of quotes are usually required, as in the following example where a group expression (in this case, a comma-separated list) is used to specify a plotting style:

     % display style=’"grid=1,colour(grid)=red,title=My new image"’

These quotes are not required if the group expression is given in response to a prompt.

If the supplied group expression is terminated with a hyphen, the user is re-prompted for another group expression (using the same parameter). The objects specified by this second group expression are added to those specified by the first. This re-prompting continues until a group expression is supplied that does not end with a hyphen.

Certain classes of objects have additional features, for instance if the objects are the names of data files, then wild-card characters are allowed in the supplied values.

4.13.1 Indirection

It is sometimes convenient to store the strings specifying the objects to be used within a text file. The name of the text file can then be given in response to a prompt for a group expression, rather than giving a long list of explicit values. This is done by preceding the name of the text file with an up-arrow ("^") character. For instance, the group expression "^style.dat" would result in the file style.dat being opened and the strings read from the file. Each line within the file is considered to be a group expression, and is processed in the same way as a group expression supplied directly. In particular, a text file may contain references to other text files. If the file style.dat contained the following two lines:

     grid=1,colour(grid)=red,border=1
     colour(border)=red,^labels.dat

then the strings grid=1, colour(grid)=red, border=1 and colour(border)=red would be returned to the application, and in addition the file labels.dat would be searched for further strings. This nesting of text files can go down to seven levels. Text files may also contain comments. Anything occurring after a "#" character is ignored. To ignore an entire line the # character must be in column 1 (any blanks in front of the # character are considered to be significant).

4.13.2 Editing

A group expression can contain a request to edit the supplied strings before passing them to the application. The editing facilities provided are fairly simple. You can:

To perform this editing, you:

(1)
Enclose the group expression specifying the strings to be edited within curly braces ("{" and "}"). Note, if no prefix or suffix is supplied, and the group expression is not a comma-separated list, then the curly braces can be omitted.
(2)
Precede the opening curly brace with the prefix (if any) to be added to the start of each string.
(3)
Follow the closing curly brace with the suffix (if any) to be added to the end of each string.
(4)
Append a string specifying the substitution to be performed (if any) to the end of the whole thing. This string should be of the form |<old>|<new>| where <old> is the text to be replaced and <new> is the text with which to replace it. Note, the substitutions occur before any specified prefix or suffix is added to the strings.

For instance;

     A{^file}B|my|your|

This will read strings from the text file file. Each occurence of the string "my" will then be replaced by "your". The resulting strings will then have "A" added at the start, and "B" added at the end.

4.13.3 Modification

A group of objects can be given by specifying some editing to apply to another already existing group of objects. For instance, if the string new_*b|_ds|_im| was given in response to a request for a group expression, then the following steps occur:

Thus if the existing group contained the strings file1_ds and file2_ds, the resulting group would be new_file1_imb and new_file2_imb. Note, this facility is only available if the parameter description identifies an existing group which will be used as the basis for the modified strings.

4.13.4 Ignoring Syntax Characters

You can see from the above that several characters have special meanings within group expressions. Examples are ^ | -. This may sometimes cause a problem if you want to include these characters within the strings being passed to the application. For instance, if you want to specify a group of data files using a shell pipe-line, you may want to do something like:

     % display
       IN - NDF to be displayed > ‘find . -newer a.fit | grep good ‘

Within a group expression, the | character indicates a request for a string substitution (as described above). In this case, the GRP library considers the request to be incomplete because there is only one | character, and issues an error report. Of course, the | character was actually intended to indicate that the output from the find command should become the input to the grep command. This can be accomplished by escaping the | character so that its special meaning within the context of a group expression is ignored.

To escape a group expression syntax character, it should be preceded with a backslash ("\"). So the above command should be changed to:

     % display
       IN - NDF to be displayed > ‘find . -newer a.fit \| grep good ‘

Any other special character can be escaped in the same way. For instance, you can escape commas within text strings using this method.

4.13.5 Groups of Data Files

If a group expression is used to specify a list of input data files (NDFs or positions lists), then file names may be specified that contain wild-card characters ("*" and "?"—character classes can also be matched using strings such as "[0-9]", "[abcd]"). These will be expanded into a list of explicit file names before returning the group to the application.

If a group of output data files are specified by modification of a previously supplied group of input data files, the asterisk in the output group expression refers just to the file base-name (i.e. without directory path or file type). So, for instance, the group expression B_* would cause each output file name to be equal to the corresponding input file name, but with "B_" added to the start of the file base name. Thus an input file /home/dsb/data.fit would result in an output file /home/dsb/B_data.fit. If no directory is given in the output group expression, the directory associated with the input file is then added to the start of the file name. Likewise, any HDS path or file type is inherited from the input file if none are given in the output group expression.

If the final character in a group expression is a colon (:), then a list of the data files represented by the group expression (minus the colon) is displayed, but no data files are actually added to the group of files to be processed. The user is then re-prompted for another group expression, using the same parameter.

If an HDS container file2 is supplied that contains two or more NDF structures, then each NDF within the container file is processed as a separate image. NDFs that are contained within an extension of another NDF are not included.

If a group of native output NDFs are created by modification of a group of native input NDFs (i.e. if the supplied string includes an asterisk), then the structure of each output container file will be copied from the corresponding input container file. For instance, if the container file o66_int.sdf contains 16 NDFs in components I1 to I16, then specifying "o66_int" when asked for a group of input images will result in all 16 NDFs being used. If the corresponding output images are specified using the string "*_A" then a single output file named o66_int_A.sdf will be created. The structure of this file will be copied from the input file, and will therefore contain the 16 output NDFs in components I1 to I16.

4.13.6 Examples

4.14 Output Parameters

Not only can programmes have parameters to which you supply values, but they can also write out the results of their calculations to output or results parameters. This makes the results accessible to subsequent tasks and to shell and ICL variables. Example results are statistics like the standard deviation or the FWHM of the point-spread function, the co-ordinates of points selected by a cursor, or the attributes of an NDF. They are not data files created by the application. In the application specifications they are listed separately from other parameters.

From the shell you can access these output parameters using the Kappa tool PARGET. Suppose that you want to subtract the mean of an NDF called myndf to make an a new NDF called outndf.

      % stats myndf > /dev/null
      % set mean = ‘parget mean stats‘
      % csub myndf $mean outndf

STATS calculates the statistics of myndf, the displayed output being discarded. PARGET reports the mean value which is assigned to shell variable mean. Thereafter the mean value is accessible as $mean in that process. Thus the final command subtracts the mean from myndf.

You can obtain vector values too.

      % ndftrace myndf > /dev/null
      % set axlab = ‘parget alabel ndftrace‘
      % display otherndf style="’label(1)=$axlab[1],label(2)=$axlab[2]"’ axes

This displays the image otherndf surrounded by axes, but the plot’s axis labels originate from another dataset called myndf 3. There are more examples in the C-Shell Cookbook.

At the time of writing, ICL only permits scalar variables. To do the first example above from ICL, you would enter something like this.

      ICL> stats myndf mean=(vmean)
      ICL> csub myndf (vmean) outndf

vmean is an ICL variable. The parentheses have the same effect as the $ in the C-shell example, meaning “the value of” the variable. Note that you can’t redirect the output to /dev/null.

If you use the PROMPT keyword (see Section 4.11) for an application with output parameters, the programme will bizarrely prompt you for these. It is not asking for a value, but a location where to store the value. It is strongly recommended that you just accept the default (normally zero) so that the values are written to their parameter file, and hence permits PARGET to work.

2HDS container files can usually be identified by the fact they have a file type of .sdf. They can be used to store one or more standard Starlink NDF structures.

3The style parameter specifies the appearance of the annotated axes, and is given as a comma-separated group of attribute settings, each of which is a name=value string specifying the attribute name and value. In this case, we assign values to the two attributes label(1) and label(2). The whole group must be enclosed in single quotes to prevent the parameter system splitting the string at the commas. The string must then also be enclosed in double quotes to prevent the UNIX shell from interpreting the parantheses and equals signs. A simpler way of specifying a plotting style is to put the attribute settings in a text file (see Section 7).