Description files are text files which can be created and modified with an editor. They have the following properties:
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:
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:
Spaces are not permitted between the directive name, equals sign and value. The various directives are listed in Section E.4.
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.
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.
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.
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[] | Character string | Yes |
is the number of elements in the character string; it is a positive integer.
POSITION
(see Section E.4). In both cases counting starts at one.
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 |
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:
(15) |
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.
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 |
HOURS | hours | 2:00:00 | 30 or |
ANGLE | varies † | +30:00:00 | 30 |
ARCMIN | minutes of arc | 30:00 | 30 |
ARCSEC | seconds of arc | 30.0 | 30′′ |
TIMEMIN | minutes of time | 30 | |
TIMESEC | seconds of time | 30.0 | |
†- signed values interpreted as degrees, unsigned values as hours. |
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:
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:
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:
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:
The descriptors used to read these components are very similar to the descriptors used in Fortran FORMAT statements. In the following is the total number of characters occupied by the item and the number of decimal places. Both and are positive integers. The following rules apply.
A
n.
I
n for INTEGER values or F
n.m for REAL ones.
X
.
,
’), 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.
+
, n
or N
(N
for north).
Negative angles are indicated by any of the following characters: -
, s
or S
(S
for south).
-
’) 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:
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).
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.
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.
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 |
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 |
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
CHARACTER
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.