CATREMOTE - A simple script to query remote catalogues

Description:

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 saved as a local file written in the Tab-Separated Table (TST) format. It also provides a number of related auxiliary functions.

catremote has several different modes of usage, each providing a different function. The modes are:

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.

There is an introduction to using catremote in SUN/190 and it is comprehensively documented in SSN/76.

Usage:

Arguments for catremote can be specified on the command line. If arguments other than the first are omitted then they will usually be prompted for. The first argument is the mode of operation and its value determines the other arguments which are required. The arguments for the various modes are:

catremote list server-type

catremote details db-name

catremote query db-name alpha delta radius additional-condition

catremote name db-name object-name

catremote help

The individual arguments are described in the `Arguments' section. If the mode is omitted then 'help' mode is assumed.

In addition to the command-line arguments, catremote takes some input from Unix shell environment variables and these variables can be used to control its behaviour.

Examples:

catremote

catremote help

List the various modes in which catremote may be used.

catremote list

List all the catalogues and databases in the current configuration file.

catremote list namesvr

List all the name servers (that is, databases of server type 'namesvr') in the current configuration file.

catremote details usno@eso

Show details of the USNO PMM astrometric catalogue (whose name is 'usno@eso').

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

Find all the objects in the USNO PMM which lie within ten minutes of arc of Right Ascension 12:15:00.0 (sexagesimal hours) and Declination 30:30:00.0 (sexagesimal degrees, both J2000). The objects selected will be saved as a catalogue called usno_eso_121500_303000.tab created in your current directory. This catalogue will be written in the Tab-Separated Table (TST) format.

catremote query usno@eso 12:15:00 30:30:00 10 14,16

Find all the objects in the USNO PMM which lie within ten minutes of arc of Right Ascension 12:15:00.0 (sexagesimal hours) and Declination 30:30:00.0 (sexagesimal degrees, both J2000) which also lie in the magnitude range 14 to 16.

catremote name simbad_ns@eso ngc3379

Find the equatorial coordinates of the galaxy NGC 3379. The coordinates returned are for equinox J2000.

Environment Variables

CATREM_URLREADER (read) catremote uses a separate program to submit the URL constituting a query to the server and return the table of results. This environment variable specifies the program to be used. See SSN/76 for further details. (Mandatory.)

CATREM_CONFIG (read) This environment variable specifies the configuration file to be used. It should be set to either the URL (for a remote file) or the local file name, including a directory specification (for a local file). Configuration files mediate the interaction between catremote and the remote catalogue; see SSN/76 for further details. (Mandatory.)

CATREM_MAXOBJ (read) The maximum number of objects which the returned table is allowed to contain.

CATREM_ECHOURL (read) This environment controls whether the URL representing the query submitted to the remote catalogue is also displayed to the user. The default is 'no'; to see the URL set CATREM_ECHOURL to 'yes'. Seeing the URL is potentially useful when debugging configuration files and remote catalogue servers but is not usually required for normal operation.