Starlink Project
Starlink System Note 76.2

A.C. Davenhall

24 May 2001

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

CATREMOTE — a Tool for Querying Remote Catalogues


catremote is a tool for querying remote astronomical catalogues, databases and archives via the Internet. It allows remote catalogues to be queried and the resulting table to be saved as a local file. It also provides a number of related auxiliary functions. catremote can be used interactively. However, it is more likely to be incorporated in a script or GUI. This document describes the use of catremote in sufficient detail to allow a programmer to use it in a script or GUI that he is developing.

Who Should Read this Document?

This document is aimed primarily at programmers who wish to incorporate catremote in a script or GUI that they are developing. It may also be useful to users who wish to simply run catremote interactively, particularly if they wish to make use of all its facilities. A simple introduction to catremote, which is more suitable for new users, is included in SUN/190.


1 Introduction
2 The ACL Format
3 System Requirements and Getting Started
4 Environment Variables
5 The Functionality of catremote
6 Running catremote
 6.1 list mode
 6.2 details mode
 6.3 query mode
 6.4 name mode
 6.5 help mode
7 Interactive Examples
8 Scripting Examples
9 Remote Access Utility
A Detailed Description of Applications
CATREMOTE – A simple script to query remote catalogues
GETURL – Retrieve a specified URL and write it to standard output

Modes of operation

Mode Description

list list the databases currently available
details show details of a named database
query submit a query to a remote database and retrieve the results
name resolve an object name into coordinates
help list the modes available

Command-line arguments for the various modes

catremote list server-type
catremote details db-name
catremote query db-name αδ radius additional-condition
catremote name db-name object-name
catremote help

The individual arguments are as follows.

Type of server to be listed; one of: all, catalog, archive, namesvr, imagesvr or local (optional).
Name of the database to be queried.
Central Right Ascension of the query. The value should be for equinox J2000 and given in sexagesimal hours with a colon (‘:’) as the separator.
Central Declination of the query. The value should be for equinox J2000 and given in sexagesimal degrees with a colon (‘:’) as the separator. Southern Declinations are negative.
Radius of the query in minutes of arc.
Any additional condition applied to the query (optional).
The name of an astronmical objects whose coordinates are to be found. Give the name without embedded spaces and in either case (upper or lower).

Environment variables

Variable Default Description

CATREM_URLREADER Program to submit query
CATREM_CONFIG URL of configuration file
CATREM_MAXOBJ 1000 Maximum number of objects in results table
CATREM_ECHOURL no Echo URL sent to remote server?

Accessing this document

A hypertext version of this document is available. To access it on Starlink systems type:

  % showme  ssn76

On non-Starlink systems access URL:

Obtaining assistance

catremote is part of the CURSA package for manipulating astronomical catalogues and tables. Reports of bugs in CURSA, including catremote, should always be sent to username However, you are welcome to contact me for advice and assistance; details of how to do so are given below.

Postal address:

A.C. Davenhall. Institute for Astronomy, Royal Observatory, Blackford Hill,
Edinburgh, EH9 3HJ, United Kingdom.

Electronic mail:


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

Revision history

24th May 2001: Version 1. Original version (ACD).


I am grateful to Allan Brighton, Martin Bly, Peter Draper, Horst Meyerdierks and Mike Read for either advice or comments on the draft version of the document. Any mistakes, of course, are my own.


[1]   M.J. Bly, 16 June 1999, SUN/193.4: PERL — Practical Extraction and Report Language, Starlink.

[2]   M.J. Bly, 13 October 2000, SUN/200.3: TCLSYS — TCL, TK and EXPECT utilities, Starlink.

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

[4]   A.C. Davenhall, 14 May 2001, SUN/190.9: CURSA — Catalogue and Table Manipulation Applications, Starlink.

[5]   A.C. Davenhall, 29 May 2001, SUN/240.1: FINDCOORDS — Finding the Coordinates of a Named Object, Starlink.

[6]   J.K.Ousterhout, 1994, Tcl and the Tk Toolkit (Addison-Wesley: Reading, Massachusetts).