### E STL description reference

E.1 Basics
E.2 Columns
E.3 Parameters
E.4 Directives

#### E.1 Basics

Description files are text files which can be created and modified with an editor. They have the following properties:

• they are free format; there is no requirement that items occur at fixed absolute positions in lines,
• the space character is used as a separator; items in the description must be separated by one or more spaces,
• keywords are case-insensitive (though throughout this manual they are shown in upper-case for clarity),
• blank lines are ignored; they may be introduced freely to improve readability as required.

A CURSA catalogue comprises: columns, parameters and textual information (see Section 4). All these items are defined in the description file. It can also contain directives which provide additional information. Each column, parameter, line of textual information and set of directives occupies one or more contiguous lines of the description file. The components can occur in any order.

The first non-blank character of a line determines the type of component it contains, according to the following scheme:

 C – column, P – parameter, T – textual information, D – directive, : – continuation of the preceding line.

These characters do not have to occur at the start of a line; they can be preceded by (and only by) an arbitrary number of spaces. The single character is all that is required to specify the type of component. However, it can be part of a word if required for clarity, as long as the word starts with the correct letter. For example, ‘COLUMN’ could be used instead of ‘C’ to introduce a column.

Columns and parameters have the following general format:

C or P    mandatory items     optional items

All items must be separated by one or more spaces. The mandatory items must be supplied. They occur in a fixed order and only the value is given. The optional items usually correspond to attributes of the column or parameter. They may be supplied if required; if they are omitted defaults are adopted. Optional items are specified using the notation:

item_name=value

Spaces are not permitted between the item name, equals sign and value. The mandatory and optional items for columns and parameters are described in Sections E.2 and E.3 respectively.

Textual information has the following format:

T    line of text

Note that there must be one or more spaces between the ‘T’ (or word beginning with ‘T’) and the line of textual information. CURSA accesses lines of textual information in the order in which they are entered into the description file.

Sets of directives have the format:

D    directives

An arbitrary number of directives can be specified on each line. Each directive is specified using the notation:

directive_name=value

Spaces are not permitted between the directive name, equals sign and value. The various directives are listed in Section E.4.

##### E.1.1 Continuation lines

A colon (‘:’) as the first non-blank character of a line indicates that it is continuing a definition begun on a previous line. An arbitrary number of spaces can precede the colon and at least one must follow it. An unlimited number of continuation lines are allowed.

##### E.1.2 Strings

Strings which include spaces (for example, perhaps the units or comments attribute of a column) must be enclosed in single or double quotes. The quotes must be ‘matching’: a string started with a single quote must be ended with a single quote and similarly for a double quote. A double quote can be included within a string terminated with single quotes and vice versa. Strings which do not include embedded spaces may optionally be enclosed in quotes, but they do not need to be.

Any text following an exclamation mark (‘!’) is treated as a comment and ignored. The exclamation mark introducing a comment may be either the first non-blank item in a line (‘comment lines’) or may follow other items (‘in-line comments’). Comments are terminated at the end of the line.

An exclamation mark within a string terminated with quotes is not interpreted as a comment, but is considered part of the string.

#### E.2 Columns

Columns have the following format:

C    name     data type     position     (optional items)

Values for the name, data type and position are mandatory and values must be given in the order indicated. An arbitrary number of optional items may be specified using the notation ‘item_name=value’. All items must be separated by one or more spaces. The individual items are described below.

##### E.2.1 Mandatory items
Name  The name of the column must conform to the usual CURSA rules for column names. Vector columns are indicated by using the usual notation: the number of elements is given in square brackets after the name. For example FLUX[4] indicates a four element vector. Data type  The permitted data types are listed in Table 24. Note that for character columns the size of the character string is indicated by the number at the end of the string (following the usual Fortran syntax).

 CURSA Data Type Description Standard Fortran 77? BYTE Signed byte No WORD Signed word No INTEGER Signed integer Yes REAL Single precision Yes DOUBLE Double precision Yes LOGICAL Logical Yes CHAR[$\ast n$] Character string Yes

$n$ is the number of elements in the character string; it is a positive integer.

Table 24: Permitted data types

Position  The position in the table where the column is located. For small text lists positions may be specified as either the sequence number of the column in the table or the sequence number of the first character corresponding to the column in each row, depending on the setting of directive POSITION (see Section E.4). In both cases counting starts at one.
##### E.2.2 Optional items

The optional items are listed in Table 25 and are described below. Most optional items correspond directly to an attribute of the column (see Section 4.1 and Table 2). If they are not specified a default is adopted.

 Item Description ORDER order of the column UNITS units EXFMT external format for display PREFDISP preferential display flag COMMENTS descriptive comments SCALEF scale factor ZEROP zero point TBLFMT format in the table

Table 25: Optional items for columns

ORDER  The order of the column. The permitted values are: ASCENDING, DESCENDING and UNORDERED. The default is UNORDERED. UNITS  The units of the column. The default is a blank string (corresponding to no units). Columns of angles may be represented internally within a CURSA application as radians and displayed as hours, degrees, minutes or seconds with optional sexagesimal subdivision using the notation described in Appendix B. EXFMT  The external format of the column; a Fortran 77 format specifier valid for the data type of the column which will be used to display it. The default depends on the data type. PREFDISP  The preferential display flag, indicating whether the column will be displayed by default. The permitted values are TRUE and FALSE. The default is TRUE. COMMENTS  Comments describing the column. The default is a blank string (corresponding to no comments). SCALEF  The scale factor used to calculate the actual value of a scaled column. For a scaled column the actual value of each field is computed by applying a scale factor and zero point to the value stored in the table, according to the formula:
 $actual\phantom{\rule{1em}{0ex}}value=\left($SCALEF×storedvalue) + ZEROP (15)
An example of an STL catalogue containing scaled columns is available in file:
/star/share/cursa/scale.TXT
ZEROP  The zero point used to calculate the actual value of a scaled column from the scaled value stored. See above for the formula used. TBLFMT  This item is not an attribute of the column, rather it is the format to be used to read the column from the table in small text lists. It will usually be a Fortran 77 format specifier valid for the data type of the column, though some special forms are provided for reading sexagesimal angles. These special forms are described in Section E.2.3, below. If TBLFMT is omitted then it defaults to the value of EXFMT for the column.
##### E.2.3 Storing sexagesimal angles

Columns of angles may be stored formatted as sexagesimal hours or degrees or as minutes or seconds of arc or time in an STL catalogue. These options both make the catalogues much easier to read by eye and allow STL descriptions to be prepared for many existing catalogues which are held as text files.

The TBLFMT item for a column in a catalogue is usually the Fortran 77 format specifier to read the column (see Section E.2.2 above). However, it has some special values to describe sexagesimal angles. These special values divide into two categories, one suitable for simple angles and the other covering more complex cases. In a simple angle a colon (‘:’) is used to separate the sexagesimal components. For complex angles the separator can be a space, or any other character, or indeed there may be no separator at all. The facilities for complex angles can handle most of the formats used in practice to represent angles in astronomical catalogues formatted as text files. The simple and complex options are described separately below. Simple sexagesimal angles

 TBLFMT Units Example Corresponding specifier angle DEGREES degrees 30:00:00 30${}^{\circ }$ HOURS hours 2:00:00 30${}^{\circ }$ or ${2}^{h}$ ANGLE varies † +30:00:00 30${}^{\circ }$ ARCMIN minutes of arc 30:00 30${}^{\prime }$ ARCSEC seconds of arc 30.0 30′′ TIMEMIN minutes of time 30 $3{0}^{m}$ TIMESEC seconds of time 30.0 $3{0}^{s}$
 †- signed values interpreted as degrees, unsigned values as hours.

Table 26: Values of column item TBLFMT for sexagesimal angles in tables

For simple sexagesimal angles the TBLFMT item has the form:

TBLFMT=units

where units is the units of the angle. The permitted values are shown in Table 26. For example, an angle tabulated in units of degrees would be represented as:

TBLFMT=DEGREES

The angles tabulated must use a colon as a sexagesimal separator (as shown in Table 26). Columns of angles stored in this form must obey the following constraints:

• they should be in units of hours, degrees, minutes of arc or time or seconds of arc or time,
• they should contain no embedded spaces,
• a colon (‘:’) should be used to separate the hours or degrees, minutes and seconds,
• if the units are hours or degrees then optionally either the seconds or the minutes and seconds may be omitted,
• small angles expressed in minutes of arc or time may optionally be subdivided into either seconds (with a colon as a separator) or decimal minutes,
• small angles expressed in seconds of arc or time may be represented either with or without a decimal fraction.

These simple sexagesimal formats are suitable for use in both free-format and fixed-format STLs. Indeed, they are the only way of representing sexagesimal angles in free-format STLs.

If a fixed-format STL is being read then the total width of the column (in characters) must be appended to the specifier. Figure 18 shows an example of this option; here column RA has a width of nine characters and column DEC a width of eight. The following files contain examples of the use of these options:

/star/share/cursa/simple.TXT
/star/share/cursa/complex.TXT
/star/share/cursa/propmotn.TXT
Complex sexagesimal angles  The TBLFMT item has additional options for reading more complex sexagesimal angles from STL catalogues. These options cover most of the formats used in practice to represent angles in astronomical catalogues held as text files. They should only be used in fixed-format STLs; if they are used in free-format STLs the results are unpredictable. For complex sexagesimal angles the TBLFMT item has the form:

TBLFMT=units{element_descriptors}

units is the units of the angle, as for simple sexagesimal angles. Again the permitted values are as listed in Table 26. element_descriptors is a series of Fortran-like descriptors for the individual components of the sexagesimal angle. A sexagesimal angle is allowed to comprise up to four components:

• an optional separate sign,
• the ‘main component’; the integer part of the angle in the specified units. Here this component is called the quotient (following more-or-less the usual usage of the term). This component is mandatory,
• either one or two sexagesimal subdivisions. These components are optional; the format for a given tabulated angle may contain zero, one or two sexagesimal subdivisions.

The descriptors used to read these components are very similar to the descriptors used in Fortran FORMAT statements. In the following $n$ is the total number of characters occupied by the item and $m$ the number of decimal places. Both $n$ and $m$ are positive integers. The following rules apply.

• The descriptor for a separate sign is of the form An.
• All the numeric components (the quotient and any sexagesimal subdivisions) have a descriptor of the form In for INTEGER values or Fn.m for REAL ones.
• Spaces, or any other separator characters, can be skipped by descriptors of the form nX.
• All components are separated by a comma (‘,’), again cf Fortran FORMAT statements.

You simply assemble an appropriate set of descriptors to describe a given angular format. The only real restriction is that the quotient and any sexagesimal subdivisions must occur in order of decreasing size (that is, quotient first, least significant subdivision last). However, it is very unusual for sexagesimal angles to be tabulated in any other order. The following additional points apply to the optional separate sign.

• It can occur anywhere in the format; it does not have to be the first component.
• Positive angles are indicated by any of the following characters: +, n or N (N for north). Negative angles are indicated by any of the following characters: -, s or S (S for south).
• The separate sign is optional. Negative values can also be indicated by including a minus sign (‘-’) as the first character of the quotient (cf the usual rules for reading numbers in Fortran).

Figure 19 shows an example of an STL format catalogue containing several columns of complex sexagesimal angles. This catalogue is available as file:

/star/share/cursa/angles.TXT

!+
! STL catalogue showing examples of complex sexagesimal angle formats.
!
! A.C. Davenhall (Edinburgh) 4/8/98.
!-

:  TBLFMT=DEGREES{A1,I2,1X,I2,1X,I2}

:  TBLFMT=DEGREES{A1,I2,I2,I2}

:  TBLFMT=DEGREES{A1,I2,1X,I2,1X,F5.2}

:  TBLFMT=HOURS{I2,1X,F4.1}

:  TBLFMT=DEGREES{F6.2,2X,A1}

:  TBLFMT=ARCMIN{F6.1}

D POSITION=CHARACTER  ! Table is fixed format.

! Notes.
! (1) The complex sexagesimal angle-formats can only be used in
!     fixed-format STL tables.
! (2) The last two rows of the table show various illegal cases
!     which CURSA interprets as null values.

!    ANGLE1    ANGLE2         ANGLE3    ANGLE4      ANGLE5  ANGLE6
!        10        20        30        40        50        60
! 3456789 123456789 123456789 123456789 123456789 123456789 123456789
BEGINTABLE
30 30 30    303030    30 30 30.12    6 34.5    30.12  N    23.1
N30:25  0   N3025 0   N30 25  0.34    8 56.7   178.34       17.5
n 6 23,45   n 62345   n 6 23 45.45   14 02.0    45.45  +   -45.6
+ 3  3  0   + 3 3 0   + 3  3  0.56    4 23.6    56.56      +23.4
-30 00 00   -300000   -30 00 00.67    5 45.2    40.67  -  -123.4
S25a57 00   S255700   S25 57 00.78   17 42.1    73.78  S    55.6
s40 00q37   s400037   s40 00 37.90   18 19.5   123.90  s    34.7
S25 67 00    256700    25 67 00.01    4 60.1   <null>        bad
S25 00 60    250060    25 00 60.12    1 60.0   <null>       55.x

Figure 19: An example STL format catalogue containing columns of complex sexagesimal angles

The interpretation of the TBLFMT items for these angles is quite straightforward. For example, column ANGLE1 starts in the third character of each record and has units of degrees. It has a separate sign as its first character. The quotient degrees, minutes and seconds are all two-character INTEGER values and are separated by one space (or rather by any single character).

#### E.3 Parameters

Parameters have the following format:

P    name     data type     value     (optional items)

Values for the name, data type and value are mandatory and values must be given in the order indicated. An arbitrary number of optional items may be specified using the notation ‘item_name=value’. All items must be separated by one or more spaces. The individual items are described below.

##### E.3.1 Mandatory items

The name and data type are the name and data type of the parameter respectively. They are specified as in exactly the same way as the corresponding items for columns (see Section E.2). Value is the value of the parameter. If it is a character string containing spaces it must be enclosed in quotes.

##### E.3.2 Optional items

The optional items are listed in Table 27. Their details are exactly the same as the corresponding optional items for columns (see Section E.2).

 Item Description UNITS units EXFMT external format for display PREFDISP preferential display flag COMMENTS descriptive comments

Table 27: Optional items for parameters

#### E.4 Directives

Sets of directives have the following format:

D    directives

An arbitrary number of directives can be included on each line. They must be separated by one or more spaces. Each directive is specified using the notation ‘directive_name=value’. The individual directives are listed in Table 28 and described below.

 Directive Description Default FILE name of the file containing the table § POSITION method of specifying column positions COLUMN SKIP number of header records to skip 0
 § - either specify FILE or include the table in the description file

Table 28: Directives

FILE  The name of the file holding the catalogue table in the case where it is not held in the same file as the description. The file name may optionally be preceded by a directory specification. The assemblage of the file name and directory specification are expressed in the syntax of the host operating system. To be pedantic this specification means that description files are not portable across operating systems (and, indeed, across different machines running the same operating system). However, this restriction is unlikely to be important in practice. If a file name is supplied without a directory specification it is assumed to reside in the same directory as the description file. POSITION  The way in which the location of columns in the table are specified in a small text list. The options are:
  COLUMN
Each column is identified by a sequence number (starting at one). This method is suitable for free format small text lists.
  CHARACTER
Each column is identified by the sequence number of the first character (starting at one) corresponding to it in each line, record or row of the table. This option is suitable for fixed format small text files. Characters in the input lines are counted starting at one.
SKIP  The number of lines or records to skip at the start of the table. It is intended for skipping over ‘header’ records. The default is zero.