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.
For your convenience, here is a summary of how to use parameters. If you want more information, go to the appropriate section.
ACCEPT, PROMPT, RESETcommand-line special keywords
ACCEPTaccepts all the suggested defaults that would otherwise be prompted.
PROMPTprompts for all the parameters not given on the command line, and
RESETresets 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/
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.
[ ]if the array is supplied on the command line, or for character arrays.
TRUEvalue followed by a
FALSEvalues for logical parameters. Acceptable values are
Nand 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
@. There is more in Strings.
ACCEPTkeyword, and it applies to all parameters that would otherwise be prompted. Note that from the shell you write \\, as \ is a shell metacharacter.
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
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
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
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
is the name of the application. (If the environment variable
ADAM_USER is not defined the parameter file
is situated in
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
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.
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
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
All global parameters are stored in the HDS file
ADAM_USER environment variable is not defined. The full list is given below.
| ||Last NDF or foreign data file accessed or written.|
| ||Current graphics workstation.|
| ||Current interaction mode.|
| ||Last lookup table file accessed or written.|
| ||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.
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
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
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
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
"$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
Responses to prompts are case insensitive for comparison purposes. Strings for character components in NDFs, plot captions and labels are treated literally.
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 23-element parameter array, where element (1,3) has value 7.
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.
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
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,
F would be sufficient to select the
"Free" option, but at least two characters would be
needed if you wanted
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.
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.
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.
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
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.
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
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.
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.
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.
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.
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
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 77 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
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).
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
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
MAX where there is no range defined, you’ll see an error message
and you’ll be invited to give another value.
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:
"12.1, 23.2, 1.3"or
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.
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
" 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
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:
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
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:
"_ds"is replaced by the string
"b"is added to the end of 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.
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.
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
"[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
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.
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
.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
would read just the specified FITS files.
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”.
This means “Use hh1_b1s1_ds.sdf, hh1_b1s2_ds.sdf, etc.”.
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
"" matches either a single character
"1" or a single
"2". The string
"[0-9]" would match any single digit character. The string
would match any single lowercase alphabetical character.
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”.
This means “Read the names of data files from the text file files.lis.”
This means “Use all accessible data files contained in the directory ../data”.
This means “Use files data_new.sdf, data_old.sdf and data_back.sdf”.
This means “Read names of data files from text file files and append _A to the end of each one”.
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
This means “Create file1.sdf, file2.sdf and file3.sdf”.
This means “Read the names of the output data files from text file out.dat”.
This means “Append the string
"_ds" to the end of all the input data file names.”
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”.
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
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 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.
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
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).