7 Subroutine interface

This section introduces all the subroutines in the CAT library, with the subroutines arranged by function. For each subroutine the calling sequence and a brief description is given. Standard names are used for the calling arguments. A complete description of each subroutine is given in Appendix A. Following normal Starlink practice the subroutine arguments are arranged in the order:

7.1 Provision for future enhancements

This manual describes version 9.0 of the CAT library. The original specification for the library is described in the document The Starlink Subroutine Interface for Manipulating Catalogues (StarBase/ACD/3.4)[2]. Version 9.0 of CAT is a subset of this full implementation and some of the items present in it serve no apparent purpose. These items correspond to features which were in the original specification but which are not currently implemented. These items may be implemented in future versions and have been included so that applications written now will be compatible with future versions of the library.

7.2 Symbolic constants

Two INCLUDE files of symbolic constants are available for use with these subroutines: CAT_PAR and CAT_ERR. CAT_PAR contains symbolic constants which specify the size of various items, codes corresponding to various types of items, values for various flags etc. CAT_ERR contains symbolic constants corresponding to the various error codes which the CAT library can set. Section 3.2 explains how to access these files. I recommend that you print out copies of these files and have them to hand when writing applications. The comments included in the files should be sufficient to explain the purpose of each constant. If your application needs to access one of these values you should always use the appropriate symbolic constant; never hard-code the actual value into your code. The values may (and probably will) change in subsequent releases of the CAT library.

7.3 Subroutine names

The CAT subroutine names follow the normal Starlink format of a prefix, an underscore (‘_’) and a five-character routine name (see SGP/16[9]).

For most routines, the first letter of the main body of the subroutine name denotes the sort of item that the subroutine operates on, according to the following scheme:

The ADAM routines (see Section 7.6) are exceptions; they have names chosen to be consistent with the corresponding routines in other ADAM libraries.

7.4 Identifiers

CAT identifies catalogues and components by various sorts of identifiers; INTEGER numbers, each with a unique value. In the calling arguments for the subroutines the following names are usually used for the various sorts of identifier:

The following rules apply:

(1)

A generic identifier may be substituted by any type of identifier,

(2)

there are circumstances where it is sensible to consider columns and parameters to be a single sort of component; in these circumstances, components and parameters are referred to collectively as parts; a part identifier may be substituted by either a column or a parameter identifier.

(3)

an expression identifier may be substituted by a field, parameter (or hence part) identifier.

7.5 Initialization, opening and closing catalogues

Every open catalogue is identified to CAT by a catalogue identifier; an INTEGER number with a unique value. The catalogue identifier is subroutine argument CI in the following notes. The ADAM routines (see Section 7.6, below) provide an alternative to CAT_TOPEN for opening or creating a catalogue.

CAT_TOPEN (CNAME, STATE, MODE; CI; STATUS)

 
Open a catalogue and obtain an identifier to it.
STATE = one of: NEW or OLD,
MODE = one of: WRITE or READ.

CAT_TRLSE (CI; STATUS)

 
Release a catalogue identifier.

CAT_RSET (CI, ROWS, STATUS)

 
Set the number of rows which a new catalogue is expected to contain. This routine is optional. If used, then it is ignored by some catalogue formats. With others, such as the Small Text List, then the catalogue may be created more efficiently.

7.6 ADAM subroutines

These subroutines interact with the ADAM parameter system. They provide alternatives to CAT_TOPEN (see Section 7.5, above) for opening a catalogue. They are provided for compatibility with other ADAM libraries and each provides analogous functionality to equivalently named routines in other ADAM libraries.

CAT_ASSOC (PCNAME, MODE; CI; STATUS)

 
Open an existing catalogue; the name of the catalogue is obtained from an ADAM parameter. Argument MODE must always be ‘READ’ in version 9.0 of CAT.

CAT_CREAT (PCNAME; CI; STATUS)

 
Create a new catalogue; the name of the catalogue is obtained from an ADAM parameter.

CAT_EXIST (PCNAME, MODE; CI; STATUS)

 
Attempt to open a catalogue, the name being taken from the ADAM parameter system. If the attempt fails then instead of re-prompting the subroutine returns with an error status. This subroutine can be used to check the existence of a catalogue.

7.7 Catalogue inquiry routines

These routines perform general ‘high-level’ inquiries on a catalogue. CAT_TCOLS is not strictly necessary; its function is provided by CAT_TDETL. However, it is convenient in practice.

CAT_TDETL (CI, COLFLG; NUMROW, NUMCOL, NUMIND, NUMPAR, DATE; STATUS)

 
Get the details of a catalogue. In CAT version 9.0 argument COLFLG should be set to CAT__GPHYS.

CAT_TROWS (CI; NUMROW; STATUS)

 
Get the number of rows in a catalogue, selection or index. This routine may be given a catalogue, selection or index identifier. It will return the number of rows in the catalogue, selection or index, as appropriate.

CAT_TCOLS (CI, COLFLG; NUMCOL; STATUS)

 
Get the number of columns in a catalogue. In CAT version 9.0 argument COLFLG should be set to CAT__GPHYS.

CAT_TIDTP (GI; IDTYP; STATUS)

 
Determine the type of an identifier. The codes for the various types of identifiers are shown in Table 2.

7.8 Component manipulation

CAT_TIDNT (CI, GNAME; GI; STATUS)

 
Get an identifier for a named pre-existing component.

CAT_TNDNT (CI, IDTYP, N; GI; STATUS)

 
Get an identifier for the $n$th (pre-existing) component of a given type. Note that if component $n$ could not be found then the routine returns an ok status, but GI is set to null identifier CAT__NOID.

CAT_TIDPR (GI; CI; STATUS)

 
Determine the parent of a component.

7.8.1 Manipulating attributes of a component

CAT_TATT<t> (GI, ATTRIB, VALUE; STATUS)

 
Set an attribute of a component to a given value. Type conversions are performed if necessary.

CAT_TIQA<t> (GI, ATTRIB; VALUE; STATUS)

 
Inquire the value of a single attribute for a component.

7.8.2 Parts: columns and parameters

CAT_PNEW0 (CI, PTYPE, PNAME, DTYPE; PI; STATUS)

 
Create a scalar part (column or parameter).

7.8.3 Columns

CAT_CNEWA (CI, FNAME, EXPR, DTYPE, CSIZE, DIMS, SIZEA, NULL, EXCEPT,

 
SCALEF, ZEROP, ORDER, UNITS, EXTFMT, PRFDSP, COMM; FI; STATUS)
Create a column, simultaneously setting all its attributes.

CAT_CNEWS (CI, FNAME, DTYPE, CSIZE, UNITS, EXTFMT, COMM; FI; STATUS)

 
Create a column, simultaneously setting some of the more frequently used attributes. These attributes deliberately correspond to the ones usually used in FITS tables. Note that if a CHARACTER column is created then the default CHARACTER size of twenty will be adopted unless CAT_TATTC is used to set the character size.

CAT_CINQ (FI, SZDIM; CI, FNAME, GENUS, EXPR, DTYPE, CSIZE, DIMS, SIZEA,

 
NULL, EXCEPT, SCALEF, ZEROP, ORDER, UNITS, EXTFMT, PRFDSP, COMM,
DATE; STATUS)
Inquire the values of all the attributes for a column. Type conversions are performed if necessary. If the conversion fails a status is set (this is only likely to be important for null values). Note that the exception value is forced into type CHARACTER in order to avoid having a family of routines. Note also that the genus attribute is returned explicitly.

7.8.4 Parameters

CAT_PPTA$<$t$>$ (CI, QNAME, CSIZE, DIMS, SIZEA, UNITS, EXTFMT, PRFDSP, COMM,

 
VALUE; QI; STATUS)
Create a parameter, simultaneously setting all its attributes.

CAT_PPTS$<$t$>$ (CI, QNAME, VALUE, COMM; QI; STATUS)

 
Create a parameter, simultaneously setting its value and comment attributes. These attributes deliberately correspond to the ones usually used in FITS tables. Note that if a CHARACTER parameter is created then the default character size of CAT__SZVAL will be adopted unless CAT_TATTC is used to set the character size.

CAT_PINQ (QI, SZDIM; CI, PNAME, DTYPE, CSIZE, DIMS, SIZEA, UNITS, EXTFMT,

 
PRFDSP, COMM, VALUE, DATE; STATUS)
Inquire the values of all the attributes for a parameter.

7.8.5 Expressions

CAT_EIDNT (CI, EXPR; EI; STATUS)

 
Get an identifier for an expression. The syntax of expressions is described in Appendix B.

7.8.6 Selections

The selection routines return a selection identifier which corresponds to the set of rows which satisfy the criteria of the selection. There are two routines for generating a selection: CAT_SELCT and CAT_SFND$<$t$>$. CAT_SELCT allows complex selections to be performed according to complicated criteria. A logical (or boolean) expression defining the selection is supplied and all the rows in the catalogue for which this expression evaluates to .TRUE. are selected. CAT_SFND$<$t$>$ allows a simple range of values to be selected for a sorted column. Usually CAT_SELCT will execute more slowly than CAT_SFND$<$t$>$ because whereas CAT_SELCT must necessarily access every row in the catalogue, CAT_SFND$<$t$>$ can exploit the ordering of the chosen column to immediately identify the required rows (remember the mnemonic F for Find and Fast, S for Select and Slow).

CAT_SLIST allows a specialized application to create a non-standard selection.

All the selection routines may operate on either an entire catalogue or some previous selection. They all uniformly and consistently provide an option to create a second selection of all the rejected rows.

CAT_SELCT (CI, EI, REJFLG; SI, NUMSEL, SIR, NUMREJ; STATUS)

 
Create a selection of rows satisfying some expression.

CAT_SFND$<$t$>$ (CI, FI, MINRNG, MAXRNG, REJFLG; SI, NUMSEL, SIR, NUMREJ;

 
STATUS)
Create a selection of the rows in a catalogue for which the fields of a specified sorted column lie within a given range.

CAT_SLIST (NUMSEL, SELIST, CRIT, REJFLG, CI, SI, SIR, NUMREJ, STATUS)

 
Create a selection from an array of row numbers.

CAT_SINQ (SI; CI, EXPR, NUMSEL, COMM, DATE; STATUS)

 
Inquire all the attributes of a selection.

7.8.7 Indices

The index generation routine generates an index from a given numeric column and returns an identifier which allows the rows in the catalogue to be accessed as though they were sorted on the column. In CAT version 9.0 only temporary indices, which persist for the duration of the application which generated them, are supported.

CAT_INEW (FI, DISP, ORDER; II; STATUS)

 
Create an index on a column.

CAT_IINQ (II; CI, FI, ORDER, NUMSEL, COMM, DATE; STATUS)

 
Inquire all the attributes of an index.

7.8.8 Row level manipulation routines

These routines manipulate a single row in a catalogue. They are based around the concepts of the ‘current row’ and the ‘current row buffer’. The current row is a single row in a catalogue which CAT is currently operating on. A copy of the current row is kept in a buffer within CAT. The various row and field manipulation routines operate on the copy of the current row in the current row buffer. As appropriate, the current row buffer can be copied out to the catalogue and a new row copied into the current row buffer.

The ‘current row buffer’ is an abstract concept to describe how CAT behaves when an application calls it. It is my solution to obtaining an arbitrary number of fields of arbitrary type in a single pass through a catalogue. The trick is separating reading rows in the catalogue into the ‘current row buffer’ and having the GET and PUT operations operate on this buffer. Applications should be written in the form:

None of the solutions to this problem are ideal and the disadvantage of the one adopted is that the resulting subroutine interface is quite ‘low level’ and verbose to use. However, it does allow an arbitrary number of columns of arbitrary type to be extracted in a single pass through the catalogue.

New rows can be added to an existing catalogue only by appending them to the end of the catalogue.

When a catalogue is opened (that is, an identifier is obtained for it), its first row is copied into the current row buffer. Thus, if the current row buffer is accessed without first GETting a specified row with CAT_RGET the contents of the first row will be obtained.

CAT_RGET (CI, ROWNO; STATUS)

 
Read a specified row from the catalogue into the current row buffer. CI may be either a catalogue, selection or index identifier.

CAT_RAPND (CI; STATUS)

 
Append the current row buffer as a new row at the end of the catalogue. CI must necessarily be a catalogue identifier.

7.8.9 Getting and putting values

The basic routines for getting and putting values GET from and PUT to the current row buffer. The following rules apply:

• scalar values are always GOT from expressions (that is, an expression is evaluated using the values of fields extracted from the current row buffer). However, simple column names and parameter names are valid expressions. Therefore, any one of an: expression, column, vector column element or parameter identifier may be used in the GET routine CAT_EGT0$<$t$>$,
• values can only be PUT to scalar columns or vector column elements, not to expressions or parameters (the notion of PUTting to an expression is a nonsense and there are alternative routines for setting the value of a parameter).

Section 8.2.5 prescribes how applications should handle null values.

CAT_EGT0<t> (GI; VALUE, NULFLG; STATUS)

 
Get the value of a scalar expression, evaluated from the current row buffer. GI may be either: an expression, column, vector column element or parameter identifier.

CAT_EGT0F (GI; VALUE, NULFLG; STATUS)

 
Get the value of a scalar expression, evaluated from the current row buffer and formatted into a character string using the external display format for the column, parameter or expression. GI may be either: an expression, column, vector column element or parameter identifier.

CAT_PUT0<t> (FI, VALUE, NULFLG; STATUS)

 
Put a value to a field. The value is written to the current row buffer. FI may be either a column or vector column element identifier.

For convenience two additional routines are provided for getting values which include the row from which the value is to be obtained. Otherwise they are similar to CAT_EGT0<t> and CAT_EGT0F (indeed they are wrap-arounds of CAT_RGET followed by CAT_EGT0<t> or CAT_EGT0F).

CAT_FGT0<t> (CI, ROWNO, GI; VALUE, NULFLG; STATUS)

 
Get the value of a scalar expression, evaluated from a specified row. CI may be either: a catalogue, selection or index identifier. GI may be either: an expression, column, vector column element or parameter identifier.

CAT_FGT0F (CI, ROWNO, GI; VALUE, NULFLG; STATUS)

 
Get the value of a scalar expression, evaluated from a specified row. and formatted into a character string using the external display format for the column, parameter or expression. CI may be either: a catalogue, selection or index identifier. GI may be either: an expression, column, vector column element or parameter identifier.

7.9 Textual information

This set of routines provide access to any textual information associated with the catalogue¹⁴. They try to keep access to the textual information as simple as possible. The text is accessed one line at a time, with each line corresponding, for example, to a single FITS COMMENT or HISTORY keyword. No facilities are provided to interpret a line. It is assumed that each line will either be displayed to the user or copied to another catalogue.

CAT_GETXT returns a single line of text. Subsequent calls to CAT_GETXT work sequentially through the textual information, returning the lines in sequence. The application cannot specify that it wants a particular line. However CAT_RSTXT is provided to ‘reset’ the sequence for a catalogue, so that the textual information can be read through an arbitrary number of times.

Each line has a class associated with it. When a line is read the class is returned; an application cannot prescribe that it wants a class of a particular value. The classes supported vary for the different catalogue formats, though on output the standard classes COMMENT and HISTORY are always available. Appendix C lists the classes supported by individual catalogue formats.

A call to CAT_PUTXT appends a line of textual information to the end of the existing textual information for a catalogue. The only way to add new textual information is by appending it to the end.

In all these routines CI must be a catalogue identifier.

CAT_GETXT (CI; FINISH, CLASS, TEXT; STATUS)

 
Get the next line of textual information from a catalogue.

CAT_PUTXT (CI, CLASS, TEXT; STATUS)

 
Put a line of textual information to a catalogue.

CAT_RSTXT (CI; STATUS)

 
Reset the access to the textual information in a given catalogue. A subsequent call to CAT_GETXT would return the first line of textual information.

CAT_SZTXT (CI, ACCESS; LINESZ; STATUS)

 
Return the maximum permitted size of a line of textual information in a catalogue. The maximum size is determined by the format of the catalogue and the access mode (READ or WRITE).

7.10 Miscellaneous

CAT_TUNES (CATPRM, VALUE; STATUS)

 
Set a CAT tuning parameter. Note that all these parameters are of type CHARACTER.

CAT_TUNEG (CATPRM; VALUE; STATUS)

 
Get a CAT tuning parameter. Note that all these parameters are of type CHARACTER.

CAT_TYFMT (DTYPE, CSIZE; STRING, POSN; STATUS)

 
Construct a character string representation of a CAT data type and append it to a character string. This character string representation is (deliberately) identical to that used by HDS.

CAT_SRNG$<$t$>$ (CI, FI, MINRNG, MAXRNG; FIRSTR, LASTR; STATUS)

 
Get the rows corresponding to a range for a sorted column. This routine is similar to CAT_SFND$<$t$>$, but it returns the first and last rows within the specified range, rather than generating a selection.