# E.S.O. - VLT project/ESO Archive
# $Id: CatalogInfoEntry.man3,v 1.1.1.1 2009/03/31 14:11:52 cguirao Exp $
#
# This file is processed by the ESO/VLT docDoManPages command to
# produce a man page in nroff, TeX and MIF formats. 
# See docDoManPages(1) for a description of the input format.
# 
# who             when       what
# --------------  ---------  ----------------------------------------
# Allan Brighton  07 Nov 97  Created
#

NAME
CatalogInfoEntry - C++ class representing a catalog config file entry

SYNOPSIS
#include "CatalogInfo.h"

class CatalogInfoEntry {
...
public:
    CatalogInfoEntry();
    CatalogInfoEntry(const CatalogInfoEntry&);
    
    int operator=(const CatalogInfoEntry&);

    ~CatalogInfoEntry();
    
    char* check();

    void servType(const char* s);
    void longName(const char* s);
    void shortName(const char* s);
    void url(const char* s);
    void backup1(const char* s);
    void backup2(const char* s)
    void symbol(const char* s);
    void searchCols(const char* s);
    void sortCols(const char* s);
    void sortOrder(const char* s);
    void showCols(const char* s);
    void copyright(const char* s);
    void id_col(int i);
    void ra_col(int i);
    void dec_col(int i);
    void x_col(int i);
    void y_col(int i);
    void is_tcs(int i);
    void equinox(double d);

    const char* servType() const;
    const char* longName() const;
    const char* shortName() const;
    const char* url() const;
    const char* backup1() const;
    const char* backup2() const
    const char* symbol() const;
    const char* searchCols() const;
    const char* sortCols() const;
    const char* sortOrder() const;
    const char* showCols() const;
    const char* copyright() const;
    int id_col() const;
    int ra_col() const;
    int dec_col() const;
    int x_col() const;
    int y_col() const;
    int is_tcs() const;
    double equinox() const;
    
    int isWcs();

    CatalogInfoEntry* link() const;
    void link(CatalogInfoEntry*e);

    int append(CatalogInfoEntry* e);

    CatalogInfoEntry* next() const;
    void next(CatalogInfoEntry*e);

    friend ostream& operator<<(ostream&, const CatalogInfoEntry&);
};


DESCRIPTION
Objects of class CatalogInfoEntry are used to represent catalog config
file entries. The entries are linked together in the form of a
hierarchical list.  The next pointer points to the next catalog in the
list and the link pointer points to the next list in the hierarchy.

A config file entry contains the information necessary to access a
catalog. The syntax for each catalog entry is:

  serv_type:   service type, one of: catalog, namesvr, imagesvr
               directory, local... (see SERVICE TYPES below)

  long_name:   long name of service for displaying
  short_name:  short name of service
  url:         URL used to access catalog, %ra,%dec, etc. expanded 
               (see below)

  symbol:      the symbol to use to plot the given column value
               (see SYMBOLS below)

  copyright:   optional copyright notice to display in user interface

  search_cols: optional list of columns that can be searched by in the format
               col1 "col1 min label" "col1 max label" : ...
               example:
                  search_cols:    mag "Brightest (min)" "Faintest (max)"

  sort_cols:   optional list of columns to sort by {col1 col2 ...}
  sort_order:  optional: set to "increasing" or "decreasing"

  show_cols:   optional list of columns to display (default: all)

  id_col:      column containing id field
  ra_col:
  dec_col:     columns containing ra and dec (for catalogs supporting WCS)
 
  x_col:
  y_col:       columns containing x,y coords (for catalogs not supporting WCS)

  is_tcs:      flag: true if using TCS columns

SERVICE TYPES
The currently known service types are:

  catalog  - server returns a tab separated table of row/col values

  namesvr  - server returns a single line with id, ra and dec to resolve
             the given object name

  imagesvr - server returns an image file

  directory - the URL is a pointer to another catalog config file

  local - a local catalog

URL SYNTAX
The url field is used to build a URL to get the results via HTTP.
The syntax is like this:

      http://host:port/cgi-bin/server?arg1&arg2&...argn

If ":port" is missing, it defaults to 80.  

Substitutions are performed on the URL as follows:

  %ra, %dec        - coordinates of center point

  %w, %h           - width and height in arcmin

  %r1, %r2         - min and max radius (for circular query)
  %r               - use when server only accepts single radius value

  %m1, %m2         - min and max magnitude
  %m               - use when server only accepts single magnitude

  %n               - max number of rows to return

  %cols            - list of columns to return (col1,col2,...coln)

  %id              - ID field of item to return (if supported)

  %mime-type       - value for http mime-type field  

Name servers only need the %id field, which is set to the object name.

SYMBOLS
The syntax for the "symbol:" field is as follows:

    symbol:  colnames symbol expr : colnames symbol expr : ...

 where 
   colnames - is a list of column names used (in symbol or expr)

   symbol - is the symbol to use, one of: square, circle, triangle,
            cross, plus, diamond, ellipse.  The symbol may also be a
            list such as {circle yellow} and some symbols take extra
            args for ratio and angle (ellipse).

   expr - is an expression in terms of colnames above, used to
          determine the size of the symbol. It may also be a list
          {expr units}, where units is one of {"image" "deg J2000"
          "deg B1950}. The default is "image" pixel coordinates.  See
          the RTD documentation for details on the syntax of
          coordinates and units. The column names (colnames) can be
          used as variables in the expression using "$" (following Tcl
          syntax).

 example: 
    symbol: mag circle 15-$mag : xyz square (1-$xyz)*2.5
    symbol: {a/b pa mag} {ellipse yellow ${a/b} $pa} {15-$mag}
    symbol: "a/b pa mag" "ellipse yellow ${a/b} $pa" "15-$mag"

METHODS
CatalogInfoEntry()
	Default constructor, sets all fields to NULL or default
	values. Use methods to set individual values.

CatalogInfoEntry(entry)
	Copy constructor.
    
operator=(entry)
	Assignment operator.

~CatalogInfoEntry()
	Destructor.
    
check()
	Check that all required fields have been set and return 0 if
	all ok.

servType(s)
longName(s)
shortName(s)
url(s)
backup1(s)
backup2(s)
symbol(s)
searchCols(s)
sortCols(s)
sortOrder(s)
showCols(s)
copyright(s)
	Set string keyword values (copy is made internally).

id_col(i)
ra_col(i)
dec_col(i)
x_col(i)
y_col(i)
is_tcs(i)
	Set int keyword values.

equinox(d)
	Set the equinox for the entry.

servType()
longName()
shortName()
url()
backup1()
backup2()
symbol()
searchCols()
sortCols()
sortOrder()
showCols()
copyright()
	Get string keyword values.

id_col()
ra_col()
dec_col()
x_col()
y_col()
is_tcs()
	Get int keyword values.

equinox()
 	Get the equinox.
   
isWcs()
	Return true if the catalog uses word coordinates, that is, if
	ra_col and dec_col have valid values The default is to use
	World Coordinates with ra_col=1, dec_col=2.

link()
link(entry)
	Get or set the pointer to link entry. Link entries are for
	catalog directory entries, where the link points to the
	beginning of a new sublist of catalogs.

append(entry)
	Append the given entry to the end of this list.

next()
next(entry)
	Get or set the pointer to next entry in the list.

operator<<(ostream, entry)
	Output operator. The output format is like the config file
	format.

SEE ALSO
CatalogInfo, AstroCatalog(3C++)
----------------------------------------------------------------------

