# E.S.O. - VLT project/ESO Archive
# $Id: astrocat.mann,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  25 Jan 98  Created
#

NAME
astrocat - Tcl interface to the catalog library

SYNOPSIS
astrocat $instName 
$instName subcommand ...

DESCRIPTION
The "astrocat" Tcl command is the Tcl interface to the catalog
library, in particular the AstroCatalog(3) class. This command can be
used to query catalogs and get configuration about the available
catalogs.  See the man page for AstroCatalog(3) for details that are
not described here.

The astrocat Tcl command creates a new Tcl command with the same name
as its argument ($instName) that provides the subcommands described
below. 

CATALOG DIRECTORIES
Catalogs may be organized in hierarchies, with catalog directories containing
other catalogs. Some subcommands accept an optional "directory" argument,
which may be either the name of the catalog directory, or a tcl list of
directories forming a catalog directory path. Note that only catalog
directories may be specified in this way, not the catalog names themselves.

SUBCOMMANDS $instName authorize $instName authorize username passwd
?realm server?
	If the previous HTTP GET returned an authorization error: (The
	HTML error text returned in Tcl contained the string:
	"Authorization Required"), the application can ask the user to
	enter a username and password to use to access the URL and
	then retry the GET after using this subcommand to set the
	authorization information to use.

	With no arguments, this command returns a list of the form

  		{needpasswd realm server}

	where:	
		needpasswd is nonzero if a password is required for
		the URL.

   		realm is the string taken from the HTTP header (Basic
   		realm=...).

   		server is the name of the target server that wants the
   		password.

	If arguments are specified, they should be the username and
	password and optionally the realm and server hostname. If the
	last 2 args are specified, the information is stored in a file
	for later lookup (see HTTP(3)).

$instName check $filename
	Check that the given filename is a valid local catalog
	(tab table format).

$instName checkrow $row
	Check that the given row (Tcl list of columns) is valid for a
	local catalog. The row should contain valid values for ra and
	dec, if we are using world coords, or x and y, if we are using
	image coords. The default columns are "id ra dec ...", but can
	be overridden in the catalog config file or header.

	This command generates an error if the position (ra, dec) or
	(x, y) is not found or is not in range.

$instName close
	Close the current catalog, if one was open.

$instName copyright
	Return the copyright string for this catalog from the catalog
	config file.

$instName dec_col
	Return the value of the dec_col keyword for this catalog from
	the catalog config file.

$instName delete
	Use the "$instName delete" subcommand to free the resources
	for this object and remove the Tcl command.
	
$instName entry get ?$name? ?$directory?
$instName entry set $$info ?$name? ?$directory?
$instName entry update $info ?$name? ?$directory?
$instName entry add $info ?$directory?
$instName entry remove $name
	"entry get" returns the catalog config entry for the currently
	open catalog or for the given catalog if one is specified.
	The format of the return value is a tcl list of {keyword
	value} pairs:
 
	{{key value} {key value} ...}

	for example:

	{{serv_type catalog} 
	 {long_name "Guide Star Catalog at ESO"}
	 {short_name gsc@eso}
	 {url http://archive.eso.org/...}
	 {symbol ...}
	 {id_col 0}
	 {ra_col 1}
	 {dec_col 2}
	...}

	If the "directory" argument is specified, the entry is searched for
	in the given catalog directory, otherwise it is searched for
	starting at the top level directory (the catalog entries are linked
	in a hierarchical list or directory structure). 

	"entry update" allows you to update fields in the catalog's config
	entry.  Some fields, such as the catalog name and URL can not be
	changed in this way, however the column positions id_col, ra_col,
	dec_col, etc... may be updated.  The format for the update info is the
	same as that returned by "entry get". The directory argument has the
	same meaning as with the "entry get" subcommand.

	Note: The "entry update" command is needed, for example, when a
	catalog query was run in a subprocess. The results of the query may
	include config info, such as the default plot symbol and the columns
	for id, ra and dec. This subcommand can be used to get this
	information back into the parent process catalog entry.

	"entry add" adds a new catalog entry to the internal list. The format
	of the argument is the same as that for update. The entry is added to the
	given directory or the top level if none is specified.

	"entry remove" removes the entry for the named catalog from the internal 
	default catalog list. 

$instName feedback $fileDesc
	Specifies a Tcl file descriptor to use to write feedback info
	during HTTP transfer of catalog data.  1 Arg: file descriptor.

$instName getcol
	Given a row of output from a query, return the value for the
	named column in Tcl.

	example: set preview [$cat getcol preview $row]

$instName getidpos
	Given a row of output from a query, return a list {id ra dec}
	(or {id x y} if we're not using wcs) for the given row. The
	positions of the 3 columns default to the first 3 columns: id,
	ra and dec, but might be specified differently in the catalog
	config entry or result header.

	example: lassign [$cat getidpos $row] id ra dec

$instName getimage -option value ...
	Request an image from the current image server and return the
	name of the FITS file holding the image.
	The options are the same as for the query subcommand.

$instName getpreview ?-url $url? ?-tmpfile $filename?
	Given a URL from a query output line, get the preview data and
	put it in a temp file.  The return value in Tcl is a list of
	{filename type}, where filename is the name of the file
	containing the preview data and type is either "image" for a
	decompressed FITS image or "table" for a tab table with data
	to be plotted in a graph.

	The temp file is re-used and deleted in the destructor.

	example: set preview [$cat getpreview -url "http://...." ?-tmpfile "/tmp/img..."?]

	-url specifies the URL to use.

	-tmpfile can be used to specify the image file name to use.


$instName hascol
	Return true if the catalog contains the given column name (in
	the config entry).

$instName headings
	Return a Tcl list of the column headings.

$instName help
	Return the help info for this catalog from the catalog config file.

$instName id_col
	Return the value of the id_col keyword for this catalog from
	the catalog config file.

$instName info $serv_type ?$directory?
	This command returns a list of catalogs from the catalog
	config file.  The "serv_type" argument determines which
	catalogs are listed (one of: catalog, namesvr, imagesvr,
	directory, local...).

	If $serv_type is an empty string, all entries are returned.

	If $directory is specified, the return list will be from the
	given catalog directory entry, retrieved via HTTP if
	needed. The default, if no $directory is given, is the top
	level list read from the default config file at startup.

$instName is_tcs ?$name? ?$newValue?
	With 0 or 1 arg, returns true if this catalog (or the given
	one) is a TCS catalog.

	If $newValue is specified, it sets the tcs flag for the given catalog.

$instName ispix
	Returns true if the catalog is based on image pixel coordinates.

$instName iswcs
	Returns true if the catalog is based on world coordinates.

$instName load $filename
	This command loads the named catalog config file, making the
	catalogs in it available to the application.

$instName longname ?name?
	Returns the long_name field from the catalog config file
	for the given long or short name, or for the current catalog.

$instName more
	Return true if there were more rows to fetch on the last query
	(i.e.: not all rows that were found were returned due to
	limits).

$instName open name ?directory?
	Open the named astromonical catalog and refer to it in future
	queries. If a directory argument is given, it may be either the
 	name of the catalog directory to search, or a tcl list forming 
        the path to the catalog directory.

$instName plot $graph $element $filename $xVector $yVector
	Plot the contents of the given tab table file in the given 
	BLT graph widget.

	element    is the BLT graph element name

	filename   is the local catalog file

	xVector    is the name of the BLT x vector

	yVector    is the name of the BLT y vector

	The data for the given element in the given graph will be set
	directly from here without going through tcl.

	The return value in Tcl is the number of rows (for the graph's
	x-axis)

$instName query ?-option $value ...?
	Pass a query to the current catalog and return the result as a
	Tcl list of rows, where each row is a Tcl list of values.
	
	Options and Values:
	
	 -id $id
	    Specify the catalog id of the object, (as returned from a
	    previous query). If this is specified, -pos, -name, -mag
	    and -radius should not be specified and will be ignored.
	
	 -pos {ra dec}
	 -pos {x y}
	 -pos {ra1 dec1 ra2 dec2}
	 -pos {x1 y1 x2 y2}
	    World {ra, dec} or image {x, y} coordinates of center
	    position, or list {ra1 dec1 ra2 dec2} or {x1 y1 x2 y2} of
	    2 points for an area.  World Coordinates are given as
	    {H:M:S[+-]D:M:S} in the given equinox.  If the catalog
	    config entry contains the keywords "x_col" and "y_col",
	    the coords are interpreted as image coords, otherwise
	    world coords.
	
	 -equinox $equinox
	    specify the quinox for position (default 2000).
	 
	 -width $w
	 -height $h
	    Dimensions of rectangle with pos at center (alternative to
	    specifying 2 positions) in arcmin for world coords or
	    pixel for image coords.
	
	 -mag $mag
	     Max or list {min max} magnitude of object
	
	 -radius $r
	    Max or list (min max} radius from position (in arcmin for
	    world coords or pixel for image coords).
	
	 -nameserver $ns
	    Name of nameserver catalog to use (simbad@eso,
	    ned@eso,...).
	
	 -name $name
	    Can be used instead of -pos. The name will be resolved
	    using the value of -nameserver (default: SIMBAD)
	
	 -columns {col1 col2 ...}
	    Specify a list of columns to return.
	
	 -searchcols {col1 col2 ...}
	     Specify a list of columns to search by. The -minvalues
	     and -maxvalues options supply the corresponding value
	     ranges and must have the same lengths.
	
	 -minvalues {v1 v2 ...}
	 -maxvalues {v1 v2 ...}
	     Specify a list of values corresponding to the columns
	     specified with the -searchcols option. The values may be
	     numeric or string format, but the lists must have the
	     same lengths as the one specified by the -searchcols
	     option.
	
	 -sort {col1 col2 ...}
	    Set the list of column names to sort by.
	
	 -sortorder increasing
	 -sortorder decreasing
	    Set the sort order.
	
	 -nrows $n
	    Set the max number of rows to return.
	
	Each option has one value, however, for a range or area query,
	some values can be a list, such as -radius "$rad1 $rad2" to
	give a radius range or -pos "$pos1 $pos2" to give an area.
	
	If -columns is not specified, all columns are assumed.
	Otherwise, if -columns is specified, the column names should
	be valid for the catalog and the result will be a list of rows
	with those columns.
	
	Note that not all catalogs will support sorting by all fields.
	
$instName querypos
	Return the world or image coordinate position arguments from
	the most recent query, posibly expanded by a name server such
	as SIMBAD. The result is a list of the form {ra dec equinox}
	for world coordinates or just {x y} for image coords.

$instName ra_col
	return the value of the ra_col field from the config file.

$instName reload
	This command reloads the default catalog config file and
	updates the internal catalog entries from it. This is meant to
	be used after the config file has been edited by hand to make
	the new data available to the application.

$instName remove $filename ?$data? ?$equinox? ?$headings?
	With 1 arg, remove the results of the previous query from the
	given file.

	If $data is specified, it should be a Tcl list of rows to be
	removed, in the format returned by the query command.

	If $equinox is specified, it is the equinox of ra and dec in
	$data (so that ra,dec can be converted to J2000 for
	comparison).

	If $headings is given, it is used as a Tcl list of column
	headings.  Otherwise the catalog headings are used, if there
	is a current catalog.

	The data rows are removed from the file, which should be in
	the form of a local catalog (tab table), such as that used by
	the starbase utilities.

$instName root
	This command returns the name of the root catalog directory.

$instName save $filename ?$iflag? ?$data? ?$equinox? ?$headings?
	With 1 arg, save the results of the previous query to the
	given file.

	If $iflag is true, the data is inserted in the file if it
	already exists and the file is sorted and duplicates removed.

	If $data is specified, it should be a Tcl list of rows to be
	saved, in the format returned by the query command.

	If $equinox is specified, it is the equinox of the ra and dec
	columns in the data (the first 3 columns are assumed to be id,
	ra and dec, unless otherwise defined in the catalog config
	entry or header).

	If $headings is given, it is used as a Tcl list of column
	headings.  Otherwise the catalog headings are used, if there
	is a current catalog.

	The data is saved to a file in the form of a local catalog
	(tab table) that can be loaded again or processed by starbase
	utilities.

$instName searchcols ?newValue?
	With no args, return the "search_cols" entry for this catalog.
	With one arg, specify a new value for the search_cols entry,
	which should be a list of the form:  

	{{colName minLabel maxLabel} ...}

$instName servtype ?name?
	Return the servtype for this catalog or for the given catalog.

$instName shortname ?name?
	Returns the short_name field from the catalog config file for
	the given long name, or for the current catalog.

$instName showcols ?newValue?
	With no args, return the "show_cols" entry for this catalog.
	With one arg, specify a new value for the show_cols entry,
	which should be a list of the form: {col1 col2 ...}.

$instName sortcols ?newValue?
	With no args, return the "sort_cols" entry for this catalog.
	With one arg, specify a new value for the sort_cols entry,
	which should be a list of the form: {col1 col2 ...}


$instName sortorder
	With no args, return the "sort_order" entry for this catalog.
	With one arg, specify a new value for the sort_order entry,
	which should be a list of the form:  {col1 col2 ...}

$instName symbol ?newValue?
	With no args, return the "symbol" entry for this catalog.
	With one arg, specify a new value for the symbol entry, which
	should be a list of the form:

	   {{colNames symbolExpr sizeExpr} ...}

	where colNames is a list of column names used, symbolExpr is
	one of the accepted symbol expressions, such as "circle
	?color?" and sizeExpr is an expression (or a list of {expr
	?units?}) giving the radius of an object. 

$instName url ?name?
	Return the url for this catalog or for the given catalog.

$instName x_col
	Return the value of the x_col keyword for this catalog from
	the catalog config file.

$instName y_col
	Return the value of the y_col keyword for this catalog from
	the catalog config file.

SEE ALSO
AstroCatalog(3)
----------------------------------------------------------------------

