### D STL description tutorial

#### D.1 First example

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:

/star/share/cursa/simple.TXT

!+
! Simple STL example; stellar photometry catalogue.
!
! A.C. Davenhall (Edinburgh) 24/1/97.
!-

C RA   DOUBLE  1  UNITS=’RADIANS{HOURS}’    TBLFMT=HOURS
C DEC  DOUBLE  2  UNITS=’RADIANS{DEGREES}’  TBLFMT=DEGREES
C V    REAL    3  UNITS=’MAG’
C B_V  REAL    4  UNITS=’MAG’
C U_B  REAL    5  UNITS=’MAG’

P EQUINOX  CHAR*10  ’J2000.0’
P EPOCH    CHAR*10  ’J1996.35’

BEGINTABLE
5:09:08.7   -8:45:15   4.27  -0.19  -0.90
5:07:50.9   -5:05:11   2.79  +0.13  +0.10
5:01:26.3   -7:10:26   4.81  -0.19  -0.74
5:17:36.3   -6:50:40   3.60  -0.11  -0.47
...

Figure 17: A simple STL description 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:

#### D.2 Second example

Figure 18 is an example of a more complicated description file for an STL catalogue. This example is available as file:

/star/share/cursa/complex.TXT

It is basically similar to the description file for the small text list in Figure 17, but with the differences listed below.

!+
! More complicated example of an STL.
!
! A.C. Davenhall (Edinburgh) 24/1/97.
!-

C RA      DOUBLE    1  UNITS=’RADIANS{HOURS}’    TBLFMT=HOURS9
C DEC     DOUBLE   12  UNITS=’RADIANS{DEGREES}’  TBLFMT=DEGREES8
C NAME    CHAR*10  25  COMMENTS=’Star name.’     TBLFMT=A7
C FLUX[4] REAL     31  UNITS=’Jansky’            EXFMT=F6.1
:           COMMENTS=’Flux at 12, 25, 60 and 100 micron.’
C V       REAL     58  UNITS=’MAG’  COMMENTS=’V magnitude.’ EXFMT=F4.2
C B_V     REAL     64  UNITS=’MAG’  COMMENTS=’B-V colour.’  EXFMT=F5.2
C U_B     REAL     71  UNITS=’MAG’  COMMENTS=’U-B colour.’  EXFMT=F5.2

P EQUINOX  CHAR*10  ’J2000.0’
P EPOCH    CHAR*10  ’J1996.35’

T Catalogue of U,B,V colours and fluxes.
T
T UBV photometry from Mount Pumpkin Observatory,
T IR Fluxes from Sage, Parsley and Thyme (1987).

D FILE=’complex.dat’      ! File holding the table.
D POSITION=CHARACTER      ! Table is fixed-format.

Figure 18: A more complicated STL description file

• Here the ‘position’ of each column (the third item of information given for each column) is not a simple sequence number, but rather is the position of the first character associated with the column in each record of the table (starting counting at one). The directive 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.
• Column 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.
• The details specified for 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.
• The lines beginning with ‘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.
• The lines beginning with ‘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.