25 Accessing remote catalogues

 25.1 Running catremote
 25.2 Environment variables
 25.3 Specifying the list of remote catalogues
 25.4 How remote access works
 25.5 Peculiarities and shortcomings
 25.6 Local or remote access?

CURSA provides some limited facilities for accessing remote catalogues held on-line at various astronomical data centres and archives around the world. You can select a subset from one of these catalogues and save it as a catalogue on your local computer using either catremote or the catalogue browser xcatview19 (see Section 11). catremote and xcatview provide the same functionality for accessing remote catalogues, though xcatview is slightly more convenient to use. Currently the only sort of selection which is permitted on remote catalogues is to select all the objects in the catalogue which lie within a given angular distance from a given point on the celestial sphere (thus, the selection corresponds to the ‘circular area’ or ‘cone search’ option of catselect, see Section 16). The remote catalogues are accessed via the Internet and obviously the option will only work when CURSA is being run on a computer with suitable network connections. If you are using CURSA at a normal Starlink node then remote access will usually be available. Conversely (and obviously) if you are using it on a stand-alone Linux PC without network connections then remote access will not be possible.

The remainder of this section refers to catremote. However, all the material, apart from the specific instructions for running catremote, is equally applicable to accessing remote catalogues using xcatview. Section 25.1 describes how to run catremote and Section 25.3 how to configure it to specify the list of remote catalogues which are accessible. Strictly speaking this information is all that you need to know in order to use catremote. However, it is useful if you understand various peculiarities and shortcomings which are contingent on the way that the remote access operates; subsequent sections provide the details.

25.1 Running catremote

Unlike most other CURSA applications catremote is not an ADAM A-task (it is, in fact, a Perl script). Usually this difference will not be important to you, but it does mean that catremote behaves slightly differently from the other applications when it is prompting for input values. In particular, it has no default replies for prompts and the special replies described in Section 9 are not available. Nor does it support either the normal options for copying textual information (see Section 10.1) or the quiet mode (see Section 10.2).

Mode Description

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

Table 14: The modes of catremote

The basic purpose of catremote is to query remote astronomical catalogues and archives. In addition to this basic query function it has a number of auxiliary functions, and each function corresponds to a mode of the program. For completeness all the various modes are listed in Table 14, though the modes that you are likely to use are:

list all the catalogues which are currently available.
submit a query to a named catalogue and retrieve the results. The basic type of query supported is the ‘cone search’ or ‘circular area search’ which returns all the objects found in a given circular area of sky. This area is specified by its central Right Ascension and Declination and angular radius. The objects returned are formatted as a catalogue and written to a local file.
submit a name of an astronomical object to a remote name-resolver. If the name-resolver finds this name in its database then the Right Ascension and Declination of the object are returned and displayed.

These modes are described briefly below. Though incomplete, this description should be enough to allow you to use catremote. There is a comprehensive description in SSN/76[11].

All of catremote’s arguments can be specified on the command line, where they are identified by position. The first command-line argument of catremote is always the mode of operation, and is one of the values listed in Table 14. The mode can only be specified on the command line. If it is omitted then ‘help’ mode is assumed and the various modes are listed. The subsequent arguments required depend on the mode chosen and are summarised in Table 15. These arguments may optionally be omitted, starting at the right. Omitted arguments (other than the mode) will always be prompted for.

catremote list
catremote query cat-name α δ radius
catremote name name-resolver object-name

Table 15: Arguments for the various modes of catremote

25.1.1 Listing the accessible catalogues

To obtain a list of all the remote catalogues which are currently accessible simply type:

  catremote  list

A list of all the catalogues which are accessible will be displayed. This list will look something like the extract shown in Table 16. Each line of the list refers to a different catalogue. The first item on each line is the name of the catalogue. The second item is the type of the catalogue; the usual value is ‘catalog’, which corresponds to a simple catalogue, though other alternatives are possible. The remainder of the line is a brief description of the catalogue. Thus, ‘ppm@eso’ is the name of the PPM20 catalogue at ESO. You will give this name when you specify the catalogue to be queried. The catalogue descriptions are usually quite brief and often contain acronyms.

usno@eso catalog USNO PMM at ESO
gsc@lei catalog Guide Star Catalog at LEDAS
ppm@lei catalog Positions and Proper Motions (PPM) Catalogue at LEDAS
sao@cadc catalog Smithsonian Astrophysical Observatory (SAO) Catalog at CADC
bd@lei catalog Bonner Durchmusterung (BD) Catalogue at LEDAS
simbad@eso catalog CDS SIMBAD object database at ESO

Table 16: Example extract from list of remote catalogues accessible to catremote

By convention the names have the form catalogue@institution where catalogue is an abbreviation for the catalogue and institution an abbreviation for the institution where the on-line version is located. The common values for institution are listed in Table 17.

Abbreviation Institution

cadc Canadian Astronomy Data Centre, Dominion Astrophysical Observatory
eso European Southern Observatory, Garching bei München
lei Department of Physics and Astronomy, University of Leicester
roe Royal Observatory Edinburgh

Table 17: Abbreviations for institutions hosting remotely accessible catalogues

25.1.2 Querying a remote catalogue

To query a remote catalogue to find the objects which lie within a given angular distance of a central Right Ascension and Declination simply type:

catremote   querycat-name α δ radius

For example:
  catremote query usno@eso  12:15:00  30:30:00  10

The arguments can be omitted from the right and any that are omitted will be prompted for. The individual arguments are as follows.

Name of the catalogue 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.

This description of the query mode is something of a simplification: for some catalogues it is possible to apply an additional condition which the objects satisfy as well as lying within a given circle of sky; see SSN/76[11] for details. If your coordinates for the central position are for some equinox other than J2000 then you can use the Starlink utility COCO (see SUN/56[31]) to convert them to the required equinox.

catremote writes the extracted objects to a catalogue in your current directory. This catalogue is formatted as a Tab-Separated Table (TST)21. The name of the catalogue is generated automatically from the name of the remote catalogue and the coordinates of the central position. For example, if the name of the remote catalogue was ‘usno@eso’ and the central position was Right Ascension 10:30:00 and Declination 20:40:00 then the name of the local catalogue would be:


Note that the ‘@’ in the remote catalogue name has been replaced with an underscore (‘_’) and the colons (‘:’) have been removed from the coordinates. Also, for a negative Declination the minus sign is replaced by an ‘m’. These substitutions are made in order to ensure that the catalogue name consists only of alphabetic characters, digits and underscores. This restriction is not really necessary on Unix systems but may be useful if the catalogue is ever copied to another operating system.

25.1.3 Finding the coordinates of a named object

catremote can be used to query a remote ‘name resolver’ to find the coordinates of a named object. Type:

catremote   namename-resolver object-name

For example:
  catremote name simbad_ns@eso ngc6240
  catremote name simbad_ns@eso iras20056+1834
  catremote name simbad_ns@eso bd+303639
  catremote name simbad_ns@eso pks1417-19
  catremote name simbad_ns@eso mkn477

If the name is recognised then the Right Ascension and Declination of the object are displayed (the Right Ascension is in sexagesimal hours, the Declination is in sexagesimal degrees and both are for epoch and equinox J2000). The technique only works if the name is recognised by the name resolver. The details of individual arguments are as follows.

The name of the name resolver which is to be queried. In the above examples the SIMBAD name resolver provided by ESO using the SIMBAD integrated database maintained by the Centre de Données astronomiques de Strasbourg (CDS) is being used. This name resolver is included in the default list of remote on-line catalogues provided with CURSA.
The name of an astronomical object which is to be resolved. It should be entered without embedded spaces. The case of letters (upper or lower) is not usually significant. That is, case is not significant for simbad_ns@eso and probably will not be significant for other name resolvers.

25.2 Environment variables

catremote takes some input from Unix shell environment variables and these variables can be used to control its behaviour. Some of the variables are optional, but others are mandatory and must be set before catremote is invoked. Default values are set when CURSA is started. All the environment variables used are listed in Table 18, though the only ones that you are likely to need to change are CATREM_CONFIG and CATREM_MAXOBJ, which are described briefly below. For a complete description see SSN/76[11].

Environment Variable Description

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

Table 18: Environment variables used by catremote

specifies the configuration file to be used. The configuration file defines the list of catalogues which are currently available to catremote. Specifying the configuration file is described in Section 25.3, below.
is the maximum number of objects which the returned table is allowed to contain. The default is 1000.

25.3 Specifying the list of remote catalogues

The list of all the remote catalogues which are currently accessible is defined in a so-called configuration file. This file is not usually a file on your local computer (though in some cases it can be; see below), but rather it is located on a remote machine. The remote catalogues which you can access are not necessarily on the same remote machine as the configuration file, though sometimes they will be. catremote accesses the configuration file via the Hyper-Text Transfer Protocol (HTTP) developed for the World Wide Web. You specify the configuration file to be used by setting the Unix shell environment variable CATREM_CONFIG to the URL (Uniform Resource Locator) for the file. This process is exactly analogous to specifying the URL of a Web page when using a Web browser. The default configuration file used by CURSA is:


To specify a given configuration file you simply set environment variable CATREM_CONFIG to the required URL prior to running catremote or xcatview. For example, to specify a copy of the original ESO configuration file type:

  % setenv  CATREM_CONFIG  http://archive.eso.org/skycat/skycat2.0.cfg
25.3.1 Creating your own configuration file

You can create your own configuration file. Such a file might contain, for example, only the catalogues which you use regularly. However, I recommend that you only try to create your own configuration file if you really understand what you are doing. Configuration files are documented in SSN/75[9].

25.4 How remote access works

This section outlines how the remote access mechanism works. It is not strictly necessary to follow it in order to use catremote, though it may help you to appreciate some of the reasons behind some of catremote’s behaviour. The configuration file used by catremote is no more than its name implies. It simply defines a list of remote catalogues and provides some details for each: its computer network address, the sorts of query that it will accept, a short description etc.

For every remote catalogue listed in the configuration file there must be a server running on a remote machine. This server will accept queries sent from catremote, interrogate the relevant catalogue to select the objects which satisfy the query and return the selected objects to catremote.

There is a standard protocol for both the queries and the returned results which allows catremote and the various servers to communicate. This protocol is a subset of a proposed general format for exchanging information between remote astronomical information services which is being developed at the Centre de Données astronomiques de Strasbourg (CDS) and elsewhere. The proposal is described in the working document Astronomical Server URL by M. Albrecht et al.[1]. It is important to realise that this protocol is general, and allows not just catremote, but also various other clients, such as GAIA[12] and SkyCat22, to communicate with various different servers for differing purposes. Thus, it is not optimised for catremote, resulting in some peculiarities in the catalogues of selected objects written by catremote (see Section 25.5, below).

The Astronomical Server URL protocol, as its name implies, uses the Hyper-Text Transfer Protocol (HTTP) developed for the World Wide Web. Thus, in order for catremote to work successfully your local computer must be configured for running Web clients (such as netscape). Of course, most Starlink nodes (and, indeed, most networked computers) will be so configured. One way of thinking of catremote is that it is functioning as a very specialised Web browser. Similarly, the remote servers are, strictly speaking, ‘gateways’ using the Common Gateway Interface (CGI).

There are various types of remote servers: catalogues, name servers, data archives and image servers. All are ‘catalogues’ in the sense of returning a table of values. A catalogue server returns traditional columns such as position, magnitude, colours, spectral type etc. A name server primarily returns columns containing celestial coordinates and alternative names for the object. A data archive will return a normal catalogue of values but at least one column will list URLs pointing to images or ‘bulk data’ files for the objects tabulated. It is important to realise that though catremote can return these special columns CURSA contains no facilities for interpreting them. When catremote displays the list of accessible catalogues it includes the type of each (catalogue, data archive, name server or image server) immediately after the name and before the description.

25.5 Peculiarities and shortcomings

You may notice the following peculiarities and shortcomings with selections extracted from remote catalogues.

The selection does not contain all the columns which you expected to be present in the catalogue. Sometimes the remote versions of catalogues contain only some of the columns present in the full catalogue (as published, or as available from the CDS). Obviously, the decision about which columns to include in the on-line catalogue rests entirely with the institution which is providing it and is entirely outwith the control of Starlink. The catalogues available from Leicester usually seem to contain most of the columns available in the corresponding originals.
If the remote catalogue is a ‘data archive’ then usually the returned selection will contain at least one ‘odd’ column comprising a list of URLs (see Section 25.4, above). This column is intended to to give access to an image or other ‘bulk’ data for each object. CURSA contains no facilities to process these columns and access the bulk data.
The protocol used to return the catalogue of selected objects is rather deficient in metadata (see Section 4). In particular, the only information returned for each column is its name; the units, data type and external format are not specified. The Right Ascension and Declination are exceptions in that they are returned with known units.

25.6 Local or remote access?

This section considers whether it is better to access a given catalogue remotely or to obtain a copy of the complete catalogue (for example, as described in Section 2) and to access it on your local computer.

The advantages of remote access are that it is very quick and easy. Also the Right Ascension and Declination are automatically returned in a form which is fully compatible with CURSA. However, the catalogue may contain only some of the columns and most of the metadata (see Section 4) will be missing. Finally only ‘circular area’ selections are possible.

The advantages of local access are that the entire catalogue, including all its columns and metadata, is available and a variety of different sorts of selection can be made on it. The disadvantages are that more effort is involved in obtaining a copy and creating a version with coordinates which are fully compatible with CURSA.

As a rough guide, you should probably use remote access if you just want to make a quick ‘circular area’ selection and simply list or plot the results. However, if you are intending to make extensive use of a catalogue it is probably better to have a local copy.

19Technically xcatview is a ‘front-end’ graphical user interface which invokes catremote to access the remote catalogue, though as a user you will not normally be concerned with these details. Note, however, that the command line catalogue browser, catview, cannot access remote catalogues.

20This catalogue is a version of the Catalogue of Positions and Proper Motions (PPM)[232].

21Unlike other CURSA applications catremote will only write catalogues in the TST format. This restriction is not important because all the other CURSA applications can read catalogues in this format. If you want to convert the catalogue to another format (for example, in order to input it into some other program) then simply use catcopy, as described in Section 14.