4 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$\times$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.

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.

Alternatively, enter a different value

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

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.

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.

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.

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.

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,

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.

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,

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.

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,

supplies the values for a 2$\times$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,

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,

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.

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.

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,

would be equivalent to the following.

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

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.

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,

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

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:

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:

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:

and the central 7$\times$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:

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.

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,

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,

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

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:

• As a comma-separated list ( e.g. "12.1, 23.2, 1.3" or "HH1_B1S1,HH2_B1S2" ).
• By reading them from a text file (see “Indirection”).
• By modifying an existing group of objects using editing specified within the group expression (see “Modification”).

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:

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:

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:

• Add a specified prefix to the start of each string.
• Add a specified suffix to the end of each string.
• Replace all occurences of a given sub-string in each string.
• Any combination of the above.

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;

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:

• Each element in some existing group of objects (identified in the description of the parameter concerned) is substituted in turn for the "*" character.
• Any occurrences of the string "_ds" is replaced by the string "_im".
• The string "b" is added to the end of the string.
• The string "new_" is added to the start of the string.

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:

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:

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 file² 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

• If an application asks for a group of input data files, the following are all possible responses:
       b1,b2,b3,b4

  This means “Use the NDFs stored in files b1.sdf, b2.sdf, b3.sdf and b4.sdf”. If ‘on-the-fly format conversion’ (see Section 18.1 and SUN/55) is being used, then this example would pick up data files with the highest priority data format (i.e. the format nearest to the start of the list of formats supplied in environment variable NDF_FORMATS_IN). So for instance, if the current directory contained both b1.sdf and b1.fit, then only one file would be used, depending on the relative positions of the .sdf and .fit formats within NDF_FORMATS_IN. If you want to restrict things explicitly to a particular data format, then you should include the corresponding file type in the group expression. An example such as:

       b1.fit,b2.fit,b3.fit,b4.fit

  would read just the specified FITS files.

       cena_b1-

  This means “Use cena_b1.sdf and then (because of the hyphen at the end) ask the user for more data files”.

       *

  This means “Use all accessible data files in the current directory”.

       hh1_b1s*_ds

  This means “Use hh1_b1s1_ds.sdf, hh1_b1s2_ds.sdf, etc.”.

       hh1_b[12]s*_ds

  This means “Use hh1_b1s1_ds.sdf, hh1_b1s2_ds.sdf, etc., and also hh1_b2s1_ds.sdf, hh1_b2s2_ds.sdf, etc.”. The string "[12]" matches either a single character "1" or a single character "2". The string "[0-9]" would match any single digit character. The string "[a-z]" would match any single lowercase alphabetical character.

       data.fit[12]

  This means “Use files data.fit1 and data.fit2 if they exist. If neither of these files exists, use the twelth image extension in the multi-extension FITS file data.fit”.

       ^files.lis

  This means “Read the names of data files from the text file files.lis.”

       ../data/*

  This means “Use all accessible data files contained in the directory ../data”.

       data_{new,old,back}

  This means “Use files data_new.sdf, data_old.sdf and data_back.sdf”.

       {^files}_A

  This means “Read names of data files from text file files and append _A to the end of each one”.

       ‘grep -l "OBJECT  = ’m57’" *.fit‘

  The string is enclosed in back quotes (‘) which causes the string to be executed as a shell command, and the resulting output to be used as the group expression. Thus this example means “Use all FITS files that contain an OBJECT keyword equal to ’m57’”.

• If an application asks for a group of output data files, the following are possible responses:
       file1,file2,file3

  This means “Create file1.sdf, file2.sdf and file3.sdf”.

       ^out.dat

  This means “Read the names of the output data files from text file out.dat”.

       *_ds

  This means “Append the string "_ds" to the end of all the input data file names.”

       ../bk/*|_ds|_bk|

  This means “Substitute the string "_bk" for all occurrences of the string "_ds" in the input data file names, and put the files in directory ../bk”.

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 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.

This displays the image otherndf surrounded by axes, but the plot’s axis labels originate from another dataset called myndf ³. 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.

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.