Документ взят из кэша поисковой машины. Адрес оригинального документа : http://xmm.vilspa.esa.es/sas/5.4.1/doc/param.ps.gz Дата изменения: Fri Jan 10 21:32:33 2003 Дата индексирования: Tue Oct 2 01:21:05 2012 Кодировка: Поисковые слова: http astrokuban.info astrokuban

XMM-Newton Science Analysis System Page: 1
Parameter Handling System
January 10, 2003
Abstract
The parameter handling system allows tasks to retrieve parameters which are spec-
ied on the command line. The parameters are dened in a Parameter Specication
File, which may also specify default values and allowable ranges.
1 Introduction
Tasks may be congured by a set of parameters, which are entered on the UNIX command line. Every
task has a Parameter Specication File which denes the name and type of each parameter and possibly
a default value, allowable range, etc. An Application Programmers Interface (API) allows parameters to
be retrieved by tasks written in either C++ or Fortran-90.
Parameters may also be entered using the Graphical User Interface (GUI). This reads the parameter
specication le and provides a dialog window into which the user can enter parameters. The GUI then
launches the task by generating a command line. For further information, see the documentation of the
`gui' package.
2 Specifying parameters
2.1 The command line
Parameters are specied on the command-line in either of the following formats:
 GNU long option style: - -=
 FTOOLS XPI parameter interface style: =
The command line may only specify parameters which are dened in the parameter le.
Examples:
foo --ival=42 --rval=1.23 # Simple parameters
foo --sval=hello # Simple string
foo --sval='hello world' # String with space
foo --slist='"one two" three' # List of two strings
xmmsas 20030110 1802-5.4.1

XMM-Newton Science Analysis System Page: 2
Arguments which contain spaces must be quoted. This also applies if the string has a leading or trailing
space which must be preserved. For example:
foo --sval=' hello world'
The shell's le-name expansion mechanism cannot be used directly to specify a list of lenames. File-
name expansion may be implemented within the parameter package, at a later date. In the meanwhile,
the following example shows a work-around solution:
foo --flist="'echo *.fits *.out'"
The single-quote character may be used in an argument, provided that it is correctly quoted or escaped.
The following examples are both valid:
foo --sval="can't wait"
foo --sval='can'\''t wait'
If the parameters are not allowable values, as dened by the parameter specication le, an error message
is given and the task is not run. The user should then correct the command-line, using the shell's history
mechanism.
Command-line options with a single '-' are used for certain generic functions and are not considered as
task parameters. See the documentation of the `taskmain' package for further details.
2.2 Parameter types
2.2.1 Summary
The following parameter types are supported:
b boolean
i integer
r real
s string
y directory
f file-name
e data-set
k block
t table
a array
c column
u angle
w time
Upper-case letters are used for lists of the corresponding lower-case type:
B list of booleans
I list of integers
xmmsas\_20030110\_1802-5.4.1

XMM-Newton Science Analysis System Page: 3
R list of reals
S list of strings
Y list of directories
F list of file-names
E list of data-sets
K list of blocks
T list of tables
A list of arrays
C list of columns
U list of angles
W list of times
The use of dierent types allows the parameter interface to check that the value is syntactically correct
and, where appropriate, within an allowable range. It also allows the GUI to provide appropriate widgets
for entering the values.
For example, a le-name is simply a string, as far as the task is concerned. However, using a separate
type allows the GUI to present the user with a le dialog, instead of a simple string-edit eld.
2.2.2 Boolean
Boolean values (type `b') may be represented by any of the following symbols:
0, n, no, f, false
1, y, yes, t, true
For example:
taskname --foo=n --bar=yes
2.2.3 Integer
Example:
taskname --foo=42 --bar=-123
The parameter le may specify a minimum and/or maximum value for an integer parameter.
2.2.4 Real
Real parameters (type `r') may be specied in simple decimal values or using exponent notation. For
example:
taskname --foo=1 --bar=1.23 --x=-1.23e-5
The parameter le may specify a minimum and/or maximum value for an integer parameter.
xmmsas 20030110 1802-5.4.1

XMM-Newton Science Analysis System Page: 4
2.2.5 String
String parameters (type `s') are used to represent text strings. Strings containing spaces should be
enclosed in quotes. For example:
taskname --foo=hello --bar='hello world'
The parameter le may, optionally, specify a set of allowable values for a string.
2.2.6 Directory
Directory parameters (type 'y') are used to specify a directory.
The directory may be expressed as a relative or absolute path. For example:
bar
../foo/bar
/data/foo/bar
2.2.7 File-name
File-name parameters (type `f') is used for miscellaneous les, which are not data-sets (FITS les). The
SAS GUI uses a le dialog so that the user can select a le.
A le-name parameter may specify an absolute or relative path. For example:
bar.dat
../foo/bar.dat
/data/foo/bar.dat
A later release of the parameter system may support additional attributes for le-name parameters, such
as "read-only".
2.2.8 Data-set
Data-set parameters (type `e') are used to specify SAS datasets (i.e. FITS les).
The parameter may specify an absolute or relative path. For example:
bar.FIT
../foo/bar.FIT
/data/foo/bar.FIT
There are additional parameter types which allow components of a dataset, such as tables, arrays and
columns to be specied (see below). The SAS GUI provides a special browser for examining and selecting
datasets and their components.
xmmsas 20030110 1802-5.4.1

XMM-Newton Science Analysis System Page: 5
2.2.9 Block, Table and Array
Table parameters (type `t') and array parameters (type `a') allow a block (table or array) and its associated
dataset to be specied by a single parameter, using a colon-separated pair of the form `set:table' or
`set:array'.
Block parameter (type `k'), are used where the value may be either a table or an array. This is appropriate
for tasks which can perform generic operations, such as deleting a block.
Examples:
foo.FIT:R1SPE1 # Table R1SPE1 in set foo.FIT
/data/bar.FIT:FILTER_U # Array FILTER_U in array bar.FIT
The SAS GUI allows a block, table or array to be selected in a single operation, using a dataset browser.
This is simpler than entering separate parameters for the dataset and block-name.
2.2.10 Column
Column parameters (type `c') allow a column, table and dataset to be specied as a single parameter,
using a colon-separated triple, of the form `set:table:column'.
For example:
foo.FITS:R1SPE1:CCDNODE # Column CCDNODE in table R1SPE1 in set foo.FITS
The SAS GUI allows a column to be selected in a single operation, using a dataset browser. This is
simpler than entering 3 separate parameters for the dataset, table and column.
2.2.11 Angle
Angle parameters (type `u') are intended for right ascensions and declinations, where conversion from
hours/minutes/seconds or degrees/minutes/seconds may be needed. For other angles, such as small oset
angles, a real parameter is more appropriate. Note that the maximum range of the angle type is [-360,360]
degrees.
The angle can be entered in one of the following formats:
(+|-)xxdxxmxx[.xxx]s (degrees, minutes and seconds)
xxhxxmxx[.xxx]s (hours, minutes and seconds)
[(+|-)]xxx[.xxx] (decimal degrees)
where `x' is a single digit, `d',`m',`s' and `h` are literal characters and square brackets denote optional
items. The number of digits shown is not signicant.
Note: Angle parameters are accessed by the task as a real value, in degrees.
xmmsas 20030110 1802-5.4.1

XMM-Newton Science Analysis System Page: 6
2.2.12 Time
Time parameters (type `w') allow times to be entered in a variety of dierent formats:
xxxx-xx-xxTxx:xx[:xx.xxx] (FITS date and time)
jdxxxxxx.xxx (Julian day)
mjdxx.xxx (modified Julian day)
yxxxx.xxx (decimal year - Not yet implemented)
[-]xxxx[.xxx] (seconds since XMM reference time)
xxx xxx xx xx:xx:xx xxxx (calendar format)
where `x' is a single digit, `m','j',`d' and `T' are literal characters and square brackets denote optional
items. The number of digits shown is not signicant.
Examples:
1997-10-13T00:00:00.000 (FITS date and time)
jd2450734.5 (Julian day)
mjd50734 (modified Julian day)
-6.912e+06 (seconds since XMM reference time)
Mon Oct 13 00:00:00 1997 (calendar format)
Note: Times are accessed by the task as real values which represents the number of seconds since the
XMM mission reference time.
2.2.13 List
Special types are provided for lists of each of the simple parameter types. List items are separated by
spaces. For example:
taskname --name=john --namelist='john bill'
String lists may use double-quotes to allow items which contain spaces or empty strings. For example,
the following list contains 3 items ("ab cd", "ef", ""):
taskname --slist='"ab cd" ef "",,,"String list"'
2.3 Default values
Each parameter has a default value, which is used if no parameter is specied on the command line. A
parameter may either mandatory (mode=q) or optional (mode=h). The default value and mandatory
attribute are specied in the parameter le.
A mandatory parameter must be explicitly given on the command-line, otherwise an error message will
be printed to prompt the user to re-enter the command. If an optional parameter is not specied, the
default is used.
Note: Mandatory parameters have a default value for use in the GUI. The GUI assigns values to all
parameters and does not treat mandatory parameters specially.
xmmsas 20030110 1802-5.4.1

XMM-Newton Science Analysis System Page: 7
3 Use with FTOOLS
The format of the SAS parameter specication les is based on XPI/FTOOLS, with various extensions
to support new parameter types, etc.
When existing FTOOLS and SAS tools are used together, from the command line, each reads its own
parameter le. Consequently, the SAS extensions are never seen by the FTOOLS.
The SAS Graphical User Interface takes integration one stage further; it reads parameter les (SAS or
FTOOLS) and launches the appropriate task. It is possible to provide a GUI layout le to customise
the appearance of the GUI for an FTOOL. If this le is not present, the GUI generates a simple default
layout.
The SAS parameter interface does not implement the following FTOOLS behaviour:
 prompting for missing values
 hidden parameters
 learn mode
 INDEF (special `undened' value)
4 Environment variables
The parameter system uses the following environment variables:
4.0.1 SAS PATH
Parameter specication les are located by searching the 'cong' directory of each path specied by the
SAS PATH environment variable.
4.0.2 PFILES
FTOOLS parameter les will be located using the PFILES environment variable. This feature is not yet
implemented; in the meanwhile, a work-around solution is to have a dummy task 'ftools', which contains
a symbolic link called 'cong', which points to the FTOOLS parameter directory.
4.0.3 SAS CLMODE
This environment variable may be used to select the command-line syntax:
 SAS - Normal SAS mode
 PCS - Special mode for PCS tools
The default mode is `SAS'.
xmmsas 20030110 1802-5.4.1

XMM-Newton Science Analysis System Page: 8
5 PCS mode
The parameter system includes support for an alternative command-line syntax, required by the PCS
tools. This mode is selected using the following environment variable:
setenv SAS_CLMODE PCS
In this mode, only the parameter names CCF, SF, COEFF and ODF should be specied. These options
should have a single minus sign and be followed by a space-separated list of arguments. Arguments before
the rst of these ags are assumed to be ODF items.
For example, the following PCS command line:
foo odf1 odf2 -COEFF co1 co2 -CCF ccf1 ccf2 -SP res
is equivalent to the following SAS command line:
foo --ODF="odf1 odf2" --COEFF="co1 co2" --CCF="ccf1 ccf2" --SP=res
PCS mode should not be used for normal SAS tools. PCS mode is a deprecated feature, which may
disappear if later releases of the PCS tools use the normal SAS format.
References
xmmsas 20030110 1802-5.4.1