Host Command-Line Interface

Miriad tasks can always be run by specifying their parameters on the host command line. A parameter is specified by equating its keyword to its value. For example, out=gauss sets the parameter out to the `value' gauss. As an example, we shall first create an image dataset, gauss, with the task imgen. At the system prompt type
   % imgen out=gauss
In this case, default values are used for all parameters, other than out. The names of all parameters, and their default values, are described in a help file (see below) which is always available on line.

Next, we will run a histogram task, histo, with the input image dataset gauss that we just created:

   % histo in=gauss

Several parameters can be given on the command line, separated by spaces. Often a parameter value consists of several numbers and/or strings. These values should be separated by commas. For example:

   % histo in=gauss range=0,1 nbins=10

Strings will often be file names. These are the names used by the host computer, and so they should obey the file-naming rules of the computer. Some tasks support wildcard expansion for file names.

Whether strings are in lower or upper case is usually significant. That is,

   % histo in=gaus
is very different to
   % HISTO IN=GAUS
Generally lower case is preferred.

A parameter value cannot contain a space. Often a parameter value will be composed of one or more strings out of a fixed set. In this case, the strings can be abbreviated to the minimum number of characters required for uniqueness.

The host's shell may try to interpret special characters in your commands - most notably the UNIX shells treat asterisks and brackets as special. This will often result in the host shell issuing cryptic messages and failing to invoke the Miriad task. For example, giving the command

   % histo in=gaus*
will probably result in
   No match.
Similarly
   % histo in=gaus region=quarter(1)
will result in
   Badly placed ()'s.
You can avoid this by escaping the special character or quoting the text containing the special characters. For example:
   % histo in=gaus "region=quarter(1)"

The command-line interface is quite appropriate for tasks that take relatively few parameters, or in shell scripts. However, it is cumbersome when a task has many parameters. Here the use of a keyword file comes in handy:

Keyword files are files containing parameter=value pairs, one per line, and can be created with an editor (most front-ends to be discussed in the next sections create such .def files by themselves) and passed to a Miriad task using the -f command line switch, or flag. Hence the previous example would be equivalent to:

   % histo -f histo.def
where the file histo.def would contain:
   in=gaus
   region=quarter(1)
Unknown keywords are simply ignored (though you will get a warning). The file should not use the same keyword twice. As parameter values do not go through the host's shell, special characters do not need to be escaped or quoted.

Help on a Miriad task can be obtained on the host command line with the command mirhelp. Example:

   % mirhelp histo
This will provide description of the task parameters and their default values.

The mirhelp command can be used to save help on a Miriad task as a text file, or to get a print-out of a help file. In UNIX, you would use the normal shell output redirection and piping. For example, to redirect the help on task histo to a file histo.hlp, use:

   % mirhelp histo > histo.hlp
Alternately, to print out this help file, use
   % mirhelp histo | lw80
where lw80 is your favourite print command.

Miriad manager
2016-06-21