6 Running catremote

 6.1 list mode
 6.2 details mode
 6.3 query mode
 6.4 name mode
 6.5 help mode

catremote is invoked by simply typing:

  % catremote

Arguments may be supplied on the command line or prompted for. Obviously, if catremote is being invoked from a script the arguments will usually be supplied on the command line.

The first command-line argument is the mode of operation. The permitted values are listed in Table 2. The mode can only be specified on the command line. If it is omitted then ‘help’ mode is assumed.

The subsequent arguments required depend on the mode chosen and are summarised in Table 3. Command line arguments are identified by position. They may optionally be omitted, starting at the right. Omitted arguments will usually be prompted for. Exceptions are the server-type in list mode, any additional-condition in query mode and the mode itself (see below). For each mode the input required and output produced is described below.


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

Table 3: Arguments for the various modes of catremote

6.1 list mode

Input
list mode has a single optional argument, the server-type. The values permitted are listed in Table 4 (and SSN/75[3] gives more details of the individual types). catremote lists all the databases in the current configuration file which match the given server-type. If the argument is omitted then ‘all’ is assumed (that is, all the databases in the configuration file are listed).


Server type Description


all all types of server
catalog simple catalogue
archive archive
namesvr name server
imagesvr image server
local local file
directory link to another configuration file

Table 4: Types of server

Output
All the databases in the configuration file which match the specified server type are listed, one per line. Typical output might look something like:
  usno@eso  catalog  USNO at ESO
  gsc@lei  catalog  Guide Star Catalog at LEDAS
  simbad_ns@eso  namesvr  SIMBAD Names

For each database, the first item is its name, the second its server type and the rest of the line gives a short description.

6.2 details mode

Input
details mode has a single input argument, db-name; the name of the database for which the details are to be shown (see Section 2). This database must be included in the current configuration file.
Output
The following details are shown for the specified database, listed one per line:
short_name: name of the database
serv_type: server type of the database (see Table 4)
long_name: a short description of the database
url: URL of the database server
search_cols: columns on which range searches are supported
help: URL of help page for the database

See SSN/75[3] for a description of each item.

6.3 query mode

Input
query mode has the arguments described below. Any arguments which are omitted will be prompted for, with the exception of additional-condition. Thus, if an additional-condition is specified then all the arguments must be included on the command line.
db-name
Name of the database to be queried (see Section 2).
α
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
Radius of the query in minutes of arc.
additional-condition
Any additional condition applied to the query. Databases vary in which, if any, additional queries they support. Three forms of additional-condition are accepted. The first is:

column-name=minimum-value,maximum-value

and objects will only be selected if their value for column column-name lies between minimum-value and maximum-value. The second is:

minimum-magnitude,maximum-magnitude

here the range is assumed to be a magnitude and no column name is specified (remember that magnitudes increase the ‘wrong way round’ so that minimum-magnitude corresponds to the brightest object). The third is:

maximum-magnitude

which is again assumed to be a magnitude and only objects brighter than maximum-magnitude are selected. For completeness, the relationship between the forms of additional-condition and the ‘query tokens’ for the database specified in the configuration file (as described in SSN/75[3]) is that additional-condition replaces the tokens as follows:

Form replaces token



first: column-name=minimum-value,maximum-value %cond
second: minimum-magnitude,maximum-magnitude %m1, %m2
third: maximum-magnitude %m
Output
The objects selected are written as a catalogue in the Tab-Separated Table (TST) format in the current directory. The TST format is described in SSN/75[3]. The name of the catalogue file is derived automatically from the name of the database and the central Right Ascension and Declination. catremote displays a line showing the name of the file created, for example:
  !(Info.) Catalogue usno_eso_101500_303000.tab written successfully.

If the catalogue contained no objects which satisfied the query catremote will report:

  ! Failure: no objects found in the region specified.

6.4 name mode

Input
name mode has the following two arguments. If they are omitted then they will be prompted for.
db-name
The name of the name resolver database which is to be queried (see Section 2). The usual choice is simbad_ns@eso, the SIMBAD name resolver provided by ESO using the SIMBAD2 integrated database maintained by the Centre de Données astronomiques de Strasbourg (CDS).
object-name
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.
Output
If the name resolver resolves the given name, that is successfully looks it up and finds coordinates for it, then they are displayed, for example:
  Right Ascension: +10:47:50
  Declination: +12:34:57

The Right Ascension is in sexagesimal hours, the Declination in sexagesimal degrees and both are for equinox J2000. If the name could not be resolved then catremote reports:

  ! Failure: unable to resolve object name.

6.5 help mode

Input
No arguments are required.
Output
All the various modes are listed, with a one-line summary of each.

2http://simbad.u-strasbg.fr/Simbad