PDS_VERSION_ID = PDS3
RECORD_TYPE = STREAM
OBJECT = TEXT
PUBLICATION_DATE = 1999-05-14
NOTE = "User documentation for vanilla software."
END_OBJECT = TEXT
END
Vanilla User Guide
1.0 Introduction
The vanilla program is a command line program that reads the binary
TES TSDR file format, correlates data between the various tables, and
outputs the data as columns of ASCII values. Vanilla can also search
the data for records that match a user specified criteria.
Vanilla uses a dataset.lst file to identify the data files it is to work
with, and treats those files as a set of tables constituting a
relational database. Each table contains several columns of data, and
records are related from table to table by having the same values in
key columns.
2.0 Usage
The usage for vanilla is:
vanilla directory -fields "col1 col2 ..." -select "select1 select2 ..."
The meaning of each of the arguments is explained below.
directory
This argument is required and must be the absolute or relative
path to a directory containing a dataset.lst file.
-fields "col1 col2 ..."
This argument is required and identifies the table columns to
output. The list of columns must be presented as a single
string, and so, must be enclosed in quotes if more than one
column is given. The column names are specified in the TES
TSDR Data Archive SIS, as well as in the individual .fmt files
included with the data. The format of a column identifier is:
table.column[index]
Where the 'table' and '[index]' portions are optional. Column
identifiers are separated by spaces, so no spaces are allowed
within a column identifier.
The table prefix is only necessary when multiple tables
contain columns with the same name (such as key columns). If
the table prefix is not specified, the first table listed in
the dataset.lst file that contains the named column is assumed.
It is possible for some columns in PDS tables to be specified
as containing an array of homogeneous data elements. For these
array columns, the optional [index] is used to specifies which
element(s) of the array to extract. The index can be a single
number, indicating a single element of the array, or a range
of numbers (specified by [low:high]), indicating multiple
consecutive elements. If the user specifies the name of an
array column and does not specify an index or leaves it blank
(eg: column[]), the entire array is output.
All variable length arrays require at least an empty index
(ie: name[]). Leaving off the index extracts the variable
length data pointer, (the position of the variable length data
in its file).
If columns from multiple tables are specified, an inner join
is performed between all the tables involved and only those
records that exist in all of the tables specified are output.
-select "select1 select2 ..."
This argument is optional and specifies a selection criteria
that a record must meet before it is output. Like the -fields
argument, all the selection criteria must be presented to
vanilla as a single string and so must be enclosed in quotes.
The format for a selection is as follows:
table.column[index] lowvalue highvalue
Like the -fields options, the 'table' and '[index]' portions
are optional and carry the same meaning, however with or
without the '[index]' portion, the column identifier must
specify only a single data element (e.g: the [low:high] format
for index is not allowed, and omitting the index is not
allowed for arrays).
The low_value and high_value portions of the selection specify
a range that the column value must lie within before a record
is output. Records that don't meet all the selection criteria
discarded. The ranges are inclusive; a value must satisfy the
following relation for the record to be considered for output:
lowvalue <= column value <= highvalue
If the column contains a character value, the comparison is
lexigraphical.
3.0 Examples
The following command extract the derived target temperature for each
detector, with the latitude and longitude of the center of the
detector:
vanilla . -fields "target_temperature detector latitude longitude"
The '.' means the current directory.
To perform the same search but limit the output to those observations
with a phase angle of less than 45 degrees, and within +/- 20 degrees
of isidis planitia (lon 270, lat 15):
vanilla . -fields "target_temperature detector latitude longitude" \
-select "phase_angle 0 45 longitude 250 290 latitude -5 35"
The TES spectra are stored in an array. You can extract a portion of the
array or the whole thing by using the range operator [low:hi] after the
field name. The following command extracts all the spectra in the area
around isidis major, where the target temperature was above 240 degrees
Kelvin:
vanilla . -fields "detector latitude longitude calibrated_radiance[]" \
-select "target_temperature 240 999 longitude 250 290 latitude -5 35"
The [] are necessary for fields that are variable length arrays. Otherwise
you get a single value, a pointer to the array, which is probably not what
you want.
4.0 System Specifics
A version of vanilla has been developed for use under Windows 95/98.
It is run from the command line of a MS-DOS window. The default
MS-DOS command line is only 127 characters, so entering long vanilla
commands may be difficult. There are 2 methods that will allow you
to enter longer commands:
1) Enter the command into a .BAT file and run the file.
2) Modify the parameters on your MS-DOS prompt window to run
the command.com with the parameter /u:250. To do this under
windows '95, right click on the title bar of a MS-DOS prompt,
and select Parameters from the menu. Add /u:250 to the end
of the "Cmd line" box and click on OK. Close and restart the
MS-DOS window.