14

SUN/181.12

Starlink Project
Starlink User Note 181.12

A.C. Davenhall & D.S. Berry

27th July 2020

Copyright © 2001 Council for the Central Laboratory of the Research Councils


CAT
Catalogue and Table Manipulation Library

Version 9.0  

Programmer’s Manual



Abstract

CAT is the Starlink Fortran subroutine library for manipulating astronomical catalogues and similar tabular datasets. This manual is intended for programmers who plan to write applications which use the CAT library to manipulate such datasets. It is introductory in the sense that it contains sufficient information to enable a programmer new to the CAT library to write applications which use it. The version of the library intended for use in conjunction with the Starlink ADAM programming environment is described. All the subroutines in the interface to the library are covered. However, the principles underlying the library, and their justification, are described only insofar as they affect its use.

Contents

1 Introduction
2 Terminology
3 Getting started
 3.1 Accessing CAT-EXAMPLES
 3.2 INCLUDE files
 3.3 Linking
 3.4 Utility applications for examining catalogues
4 A simple example application
5 Carrying on
 5.1 Celestial coordinates in catalogues
 5.2 Vector columns
 5.3 Expressions
 5.4 Selections
 5.5 Indices
6 Components of a CAT catalogue
 6.1 Provision for future enhancements
 6.2 Symbolic constants
 6.3 Catalogues, components and attributes
 6.4 Identifiers
  6.4.1 The null identifier
 6.5 Attributes
 6.6 Catalogue attributes
 6.7 Columns
 6.8 Vector column elements
 6.9 Parameters
 6.10 Expressions
 6.11 Selections
 6.12 Indices
7 Subroutine interface
 7.1 Provision for future enhancements
 7.2 Symbolic constants
 7.3 Subroutine names
 7.4 Identifiers
 7.5 Initialization, opening and closing catalogues
 7.6 ADAM subroutines
 7.7 Catalogue inquiry routines
 7.8 Component manipulation
  7.8.1 Manipulating attributes of a component
  7.8.2 Parts: columns and parameters
  7.8.3 Columns
  7.8.4 Parameters
  7.8.5 Expressions
  7.8.6 Selections
  7.8.7 Indices
  7.8.8 Row level manipulation routines
  7.8.9 Getting and putting values
 7.9 Textual information
 7.10 Miscellaneous
8 Features of the library
 8.1 Copying parameters and fields
 8.2 Null and locum values
  8.2.1 Rationale and behaviour
  8.2.2 Reporting the generation of null and locum values
  8.2.3 CAT subroutine interface
  8.2.4 Handling nulls in expressions
  8.2.5 Handling nulls in applications
  8.2.6 Inquiring null values
 8.3 Storing and representing columns of angles
  8.3.1 Angular format specifiers
  8.3.2 Displaying angles in radians
A Detailed subroutine specifications
CAT_ASSOC – Open an existing catalogue; the name of the catalogue is obtained from an ADAM parameter
CAT_CINQ – Inquire the values of all the attributes for a column
CAT_CNEWA – Create a column, simultaneously setting all its attributes
CAT_CNEWS – Create a column, simultaneously setting some of its attributes
CAT_CREAT – Create a new catalogue; the name of the catalogue is obtained from an ADAM parameter
CAT_EGT0F – Get the formatted value of a scalar exprn. field or parameter
CAT_EGT0 <t > – Get the value of a scalar expression, field or parameter
CAT_EIDNT – Get an identifier for an expression
CAT_EXIST – Attempt to open a catalogue, the name being taken from the ADAM parameter system
CAT_FGT0F – Get the formatted value of a scalar expression or field for a given row
CAT_FGT0 <t > – Get the value of a scalar expression or field for a given row
CAT_GETXT – Get the next line of textual information from a catalogue
CAT_IINQ – Inquire all the attributes of an index
CAT_INEW – Create an index on a column
CAT_PINQ – Inquire the values of all the attributes for a parameter
CAT_PNEW0 – Create a scalar part (column or parameter)
CAT_PPTA <t > – Create a parameter, simultaneously setting all its attributes
CAT_PPTS <t > – Create a parameter, simultaneously setting some of its attributes
CAT_PUT0 <t > – Put a value to a scalar part (field or column)
CAT_PUTXT – Put a line of textual information to a catalogue
CAT_RAPND – Append the current row buffer to the end of the catalogue
CAT_RGET – Read a specified row into the current row buffer
CAT_RSET – Set the number of rows which a new catalogue is expected to contain
CAT_RSTXT – Reset the access to the textual information in a catalogue
CAT_SELCT – Create a selection of rows satisfying some expression
CAT_SFND <t > – Create a selection of rows within a given range
CAT_SINQ – Inquire all the attributes of a selection
CAT_SLIST – Create a selection from an array of row numbers
CAT_SRNG <t > – Get the rows corresponding to a range for a sorted column
CAT_SZTXT – Return the maximum permitted size of a line of text for a cat
CAT_TATT <t > – Set an attribute of a component to a given value
CAT_TCOLS – Get the number of columns in a catalogue
CAT_TDETL – Get the details of a catalogue
CAT_TIDNT – Get an identifier for a named pre-existing component
CAT_TIDPR – Determine the parent to a component
CAT_TIDTP – Determine the type of a component
CAT_TIQA <t > – Inquire the value of a single attribute for a component
CAT_TNDNT – Get an identifier for the Nth (pre-existing) component of a given type
CAT_TOPEN – Open a catalogue and obtain an identifier to it
CAT_TRLSE – Release a catalogue identifier
CAT_TROWS – Get the number of rows in a catalogue, selection or index
CAT_TUNEG – Get a CAT tuning parameter
CAT_TUNES – Set a CAT tuning parameter
CAT_TYFMT – Construct a character representation of a CAT data type

B Expression syntax
 B.1 Details of expressions
 B.2 Mathematical functions provided
 B.3 Rules for expressions
 B.4 Operator precedence
C Catalogue formats
 C.1 FITS
  C.1.1 Textual information
 C.2 STL
  C.2.1 Textual information
  C.2.2 Null values
 C.3 TST
  C.3.1 Textual information
  C.3.2 Null values
References

Readership

This manual is intended for programmers who wish to use the Starlink CAT subroutine library to manipulate astronomical catalogues and similar tabular datasets. The reader is assumed to be familiar with the following: standard Fortran 77 and the extensions permitted by Starlink, Starlink programming practices and procedures and the various packages and libraries of the ADAM programming environment.

How to use this document

You will not usually need to read this document from beginning to end in order to use the CAT subroutine library. The document is divided into three parts:

Part I
– Preliminaries,
Part II
– Tutorial,
Part III
– Reference.

Part I contains some preliminary details, such as an introduction to the terminology of CAT and details of how to access the library. Part II is a tutorial example of how to write a simple application which accesses the library and Part III contains reference material which describes the library.

If the CAT library is new to you, you should start by reading Part I and working through the tutorial in Part II. Finally, read Section 6 of Part III, but skipping the detailed descriptions of individual attributes.

If you are already familiar with the library you should consult the reference material in Part III, and probably also the details in Section 3 of Part I, as necessary.

Assistance and further information

I am happy to answer queries about using the CAT subroutine library and to receive comments or suggestions about how it could be improved. Details of how to contact me are included below.

Clive Davenhall.

Postal address: Institute for Astronomy, Royal Observatory, Blackford Hill, Edinburgh,

EH9 3HJ, United Kingdom.

Electronic mail: acd@roe.ac.uk

Fax:

from within the United Kingdom: 0131-668-8416
from overseas: +44-131-668-8416

Acknowledgments

The CAT subroutine library is far from being all my own work. Its specification evolved during extensive discussions with (alphabetically) Dave Giaretta, Clive Page, Rodney Warren-Smith and Alan Wood, all of whom have contributed substantially to its final form. Also, at various times, Brian Read, Malcolm Currie and Steven Beard have made useful comments.

Clive Page wrote the expression parser which CAT uses and Appendix B is based on documentation which he supplied. CAT accesses FITS tables through Bill Pence’s FITSIO subroutine library and CHI/HDS catalogues through Alan Wood’s CHI subroutine library.

Martin Bly assisted in preparing the Unix version for release. Alan Wood, Malcolm Currie and Peter Draper tested a pre-release version and suggested several useful improvements.

I am grateful to all these people for sharing their time and expertise.

Clive Davenhall
Department of Physics and Astronomy, University of Leicester
Saint Edmund’s Day 1994

Revision history

(1)
23rd June 1994: Original draft (ACD).
(2)
9th October 1995: Version 1 (ACD).
(3)
12th April 1996: Version 2. Modified so that the Latex source could be used to create an HTML as well as a paper version (ACD).
(4)
23rd January 1997: Version 3. Modified for release 3.1 of the CAT library. The major change was the addition of support for the Small Text List (STL) catalogue format (ACD).
(5)
12th June 1997: Version 4. Modified for release 4.1 of the CAT library. There are no major enhancements in this release, just some bug fixes. Perhaps the most important of these is the ability to handle catalogue file names longer than fifteen characters (ACD).
(6)
9th November 1997: Version 5. Modified for release 4.2 of the CAT library. There are no major enhancements in this release, just a couple of bug fixes and some minor revisions to the document (ACD).
(7)
11th June 1998: Version 6. Modified for release 5.1 of the CAT library. There were major internal changes to the CAT library in order to speed it up and to reclaim internal work-space for reuse when a catalogue is closed. Most of these changes should not be visible to the user (except that the library should be somewhat faster). One visible change is that the capitalisation of the file type specified by the user when a new catalogue is opened is now preserved. One new routine has been added: CAT_IINQ (ACD).
(8)
26th November 1998: Version 7. Modified for release 6.1 of the CAT library. The major enhancement to the library in this release was additional features for reading sexagesimal angles from STL format catalogues. Rather than document these features here the entire description of the STL format was removed. The STL format is now documented solely in the CURSA manual, SUN/190. This rationalisation removes a duplication which was becoming increasingly cumbersome. Release 6.1 also includes some further improvements to the error reporting (ACD).
(9)
15th November 1999: Version 8. Modified for release 7.1 of the CAT library. The major change was the addition of support for the Tab-Separated Table (TST) catalogue format. All references to the VAX/VMS version of CAT were removed from the manual (ACD).
(10)
16th July 2000: Version 9. Modified for release 7.2 of the CAT library. There are no major enhancements in this release, just some bug fixes and minor changes, most notably to the implementation of the Tab-Separated Table (TST) format. There are also some minor revisions to the document (ACD).
(11)
4th April 2001: Version 10. Modified for release 8.1 of the CAT library. Support for the CHI/HDS catalogue format has been removed from this version of the library. There are also a few bug fixes and some minor revisions to the document (ACD).
(12)
17th January 2017: Modified for release 8.4 of the CAT library. Catalogues can now be stored in files with names that include non-alphanumeric characters. (DSB)
(13)
27th July 2020: Modified for release 9.0 of the CAT library. Null values are no longer supported for _LOGICAL columns. (DSB)

Part I
Preliminaries

References

[1]   M.J. Currie and D.S. Berry, 20 October 2000, SUN/95.16: KAPPA — Kernel Application Package, Starlink.

[2]   A.C. Davenhall, September 1993, The Starlink Subroutine Interface for Manipulating Catalogues (StarBase/ACD/3.4). See also A.C. Davenhall, December 1992, Requirements for a Starlink RDBMS (StarBase/ACD/2.1). These documents were written as part of the project to define and implement the CAT subroutine library. StarBase/ACD/3.4 gives the complete specification of the CAT subroutine interface, and describes much of the thinking that went into the specification. StarBase/ACD/2.1 lists the original requirements for the Starlink subroutine library to manipulate catalogues and similar tabular datasets.

[3]   A.C. Davenhall, 25 July 2000, SUN/190.8: CURSA — Catalogue and Table Manipulation Applications, Starlink.

[4]   A.C. Davenhall, 26 July 2000, SSN/75.1: Writing Catalogue and Image Servers for GAIA and CURSA, Starlink.

[5]   P.W. Draper and N. Gray, 16 October 2000, SUN/214.8: GAIA — Graphical Astronomy and Image Analysis Tool, Starlink.

[6]   M.A. Roth, H.F. Korth and A. Silberschatz, 1989, Acta Informatica 26, pp615-642.

[7]   J.R. Rumble and F.J. Smith, 1990, Database Systems in Science and Engineering (Adam Hilger: Bristol).

[8]   D.L. Terrett and P.M. Allan, 1 February 1993, SUN/111.2: SPT – Software Porting Tools, Starlink.

[9]   P.T. Wallace, 23 March 1992, SGP/16.10: Starlink Application Programming Standard, Starlink.

[10]   R.F. Warren-Smith, 28 February 1995, SUN/39.2: PRIMDAT — Processing of Primitive Numerical Data, Starlink.

[11]   R.F. Warren-Smith and M.D. Lawden, 23 February 1999, SUN/92.11: HDS — Hierarchical Data System, Starlink.