The easiest way to introduce the STL (Small Text List) description file format is to explain an example. Figure 17 shows a simple description file for a small text list. This example is available as file:
In a small text list the table of values can be in the same file as the description (as in Figure 17) or in a
separate file. If the table is included in the description file it must occur after the description, from
which it is separated by a line containing the single word ‘BEGINTABLE’.
The first five lines of Figure 17 are comments. They are ignored by CURSA and their only purpose is
to provide information to a user reading the description file. Comments are identified by an
exclamation mark (‘!’). In the example the comments all occupy their own line. However, they can be
included on the same line as other elements of the description file; any text to the right of an
exclamation mark is interpreted as a comment.
Blank lines are ignored. They can be introduced to improve the readability of a description file as required.
Throughout this manual keywords and directives are shown in upper case for clarity. However, they are actually case-insensitive.
The example in Figure 17 contains five columns: RA, DEC, V, B_V and U_B. Each column must be defined
on a separate line (if necessary the definition of a column can be continued onto another line,
though in the example none are. However, a single line can only contain the definition of one
column).
The definition of each column starts with the letter ‘C’ (indicating that a column is being
defined), followed by the name, the data type and the ‘position’ in the column. Here the
‘position’ is simply the sequence number of the column in the table (starting counting
at one), with the columns being separated by one or more spaces. Further details of the
column are specified using an ‘item_name=value’ notation; in the example the units are
set in this way. All these items must be separated by one or more spaces. The full syntax
for defining columns is described in Section E.2. For columns RA and DEC the UNITS item
is indicating that the columns should be displayed as sexagesimal angles in hours and
degrees respectively. Similarly, the TBLFMT item is specifying that the columns are listed as
sexagesimal angles in the file. Note that sexagesimal angles stored in STL files must contain no
embedded spaces and a colon (‘:’) must be used to separate the hours or degrees, minutes and
seconds.
The example contains two parameters: EQUINOX and EPOCH. Parameters are defined in a similar way to
columns. Each column must be defined on a separate line (if necessary the definition of a column can
be continued onto another line, though in the example none are. However, a single line can only
contain the definition of one parameter).
The definition of each parameter starts with the letter ‘P’ (indicating that a parameter is being
defined), followed by the name, the data type and the value of the parameter. Further details of the
parameter can be specified using an ‘item_name=value’ notation, as for columns (though none are set
in the example).
The table of values immediately follows the ‘BEGINTABLE’ line, without any intervening lines. The
table is in ‘free’ format, with columns being separated by blanks. The example does not include any
character columns with embedded blanks, but any such columns would be enclosed in quotes. The
physical order of the columns in the table simply corresponds to the order specified when each
column was defined in the description. Thus, in the example the first column is RA, the second DEC,
etc.
In the example the columns of angles RA and DEC are stored in the file as sexagesimal hours and
degrees respectively. This format is convenient and is probably what you will usually use.
However, it is possible to store columns of angles in a file in radians (and in fact CURSA
does this when it writes an STL catalogue). There is an example of such a catalogue in
file:
Figure 18 is an example of a more complicated description file for an STL catalogue. This example is available as file:
It is basically similar to the description file for the small text list in Figure 17, but with the differences listed below.
POSITION=CHARACTER indicates that positions are specified in this way. This option is
particularly useful for reading existing fixed-format files. If a fixed-format STL is being
read then a format must be specified for each column using either TBLFMT or EXFMT.
Similarly, if a sexagesimal angle in hours or degrees is being read from a fixed-format STL
then the total width of the column must be appended to the units of HOURS or DEGREES
specified for the TBLFMT item.
FLUX is a four-element vector. Vector columns are defined using the usual CURSA
notation: appending the number of elements in the vector, enclosed in square brackets
(‘[]’), after the column name.
FLUX are continued on a second line. If the first non-blank
character in a line is a colon (‘:’) then the line continues the definition on the previous line.
The colon must be followed by at least one space. An arbitrary number of continuation
lines are allowed.
T’ are lines of textual information associated with the catalogue.
They are processed by CURSA in the order in which they appear. Note that the ‘T’ must
be followed by at least one space.
D’ define additional directives associated with the catalogue
(see Section E.4). There must be at least one space following the ‘D’. In the example each
directive occurs on its own line. However, an arbitrary number can be included on a
single line, if required (though if more than one are included on a line they must be
separated by one or more spaces). Note also the use of in-line comments in these lines;
the text to the right of the exclamation marks is a comment and is ignored.
FILE is the name and directory specification of the file holding the table of values
comprising the catalogue. It is expressed using the syntax of the host operating system
and there are no restrictions on it other than those imposed by the host operating system.