3 Getting started

 3.1 Accessing CAT-EXAMPLES
 3.2 INCLUDE files
 3.3 Linking
 3.4 Utility applications for examining catalogues

CAT is an optional Starlink software item. Before proceeding you should check with your local site manager whether it is installed at your site, and if not attempt to persuade him to install it.

Version 9.0 of CAT comprises a subroutine library and two INCLUDE files. In addition, the CAT-EXAMPLES package provides five simple applications which are either examples of how to write CAT applications or simple utilities to examine catalogues (cf the hdstrace utility for examining HDS files). To write programs which use CAT you should have access to the library, the INCLUDE files and the CAT-EXAMPLES package. Some of the CAT-EXAMPLES applications serve as examples in Part II of this manual.

You do not need any special quotas or privileges to use CAT.

3.1 Accessing CAT-EXAMPLES

The following description applies to all the variants of Unix supported by Starlink. Simply type:

  source /star/bin/examples/cat/cat-examples.csh

The following message should appear:

  CAT example programs now available -- (for CAT Version 4.2-1)

If it does not, then the probable cause is that CAT-EXAMPLES is not installed correctly at your site; check with your local site manager.

3.2 INCLUDE files

The programming interface to the CAT library includes two INCLUDE files: CAT_PAR and CAT_ERR. These INCLUDE files define symbolic constants which your application programs may use:

CAT_PAR
contains general constants pertaining to the CAT library,
CAT_ERR
contains constants corresponding to the various error codes which can be set by the CAT library.

All the symbolic constants defined in both these files begin with the prefix CAT__ (in conformance with normal Starlink practice).

You can INCLUDE either or both of these files in a subroutine by including either or both of the following lines in the subroutine, as appropriate:

  INCLUDE ’CAT_PAR’   ! CAT symbolic constants.
  INCLUDE ’CAT_ERR’   ! CAT error codes.

If you are using a standard ADAM prologue for the subroutine these lines will go in the ‘global constants’ section.

The example applications included with CAT (see Section 4), and probably your own applications, also need to access the standard ADAM INCLUDE file SAE_PAR. For convenience the instructions given below include setting up access to this file.

The following description applies to all the variants of Unix supported by Starlink. The files are kept in directory /star/include with names cat_par and cat_err. You should set up soft links to these files, following the normal Starlink procedure, which is described in SUN/111.2[8]. See in particular Section 4.4, p6. Simply type:

  star_dev
  cat_dev

3.3 Linking

It might seem slightly perverse to describe how to link with the CAT library before describing how to write an application which calls it. However the rest of this manual describes various aspects of writing applications which call CAT and it seems sensible to get the somewhat separate question of linking out of the way first.

Your application should be written as an ADAM A-task. The Starlink shell script for linking an A-task, alink, will automatically compile the source code for the A-task. Type:

alink your_source_code ‘cat_link_adam‘

This description applies to all the variants of Unix supported by Starlink.

3.4 Utility applications for examining catalogues

Once you have written an application which uses the CAT library to manipulate a catalogue you will often want to examine the contents of the catalogues which the application reads or writes. The catalogue browser xcatview in the Starlink package CURSA (see SUN/190[3]) is a convenient way to examine catalogues. It can access catalogues in any of the formats supported by CAT2.

Catalogues written in the STL or TST formats (see Appendix C) are text files and can be examined with standard Unix commands such as more or cat.

In addition, CAT-EXAMPLES contains two simple utilities for examining the contents of catalogues. These utilities are largely of historical interest and are less easy to use than xcatview. They are mentioned here for completeness. The utilities are:

details
reports the details of all the parameters and columns in a catalogue. All the attributes of every column and parameter are listed. The output is directed to the standard Fortran output stream.
listout
lists selected columns from a catalogue to the terminal screen or a text file, or both. You are prompted for the columns which are to be displayed.

To invoke either of these applications simply type either details or listout, as appropriate, and answer the prompts, which are self-explanatory.

Part II
Tutorial

2CURSA uses the CAT library to access catalogues.