Working with Catalogs in Tcl

The following code creates an astrocat object named cat, opens the GSC catalog and prints out the headings followed by the rows retrieved from the catalog:

 
astrocat cat 
cat open "gsc@eso" 
puts "catalog headings: [cat headings]" 
foreach i [cat query -pos {3:19:48 +41:30:39} -radius 10 -nrows 10] { 
    puts $i 
} 
cat close

The astrocat command creates a new Tcl command with the same name as its argument. The new command can be used to perform operations on catalogs. A new catalog is opened with the open subcommand, which takes the name of the catalog as an argument. The headings subcommand returns a Tcl list of the catalog's column names, which can be used to display query results in a table. The query subcommand is used to perform the catalog queries. It takes a number of option/value pairs as arguments and returns a Tcl list of astronomical objects as the result. The format of the query subcommand is:

 
<catObject> query -option value -option value ...

The available options are listed below:

Option	Value
-pos	Center position as a list of {ra dec} for World Coordinates or {x, y} for pixel coordinates. May also be 2 positions, indicating an area, in the format {ra1 dec1 ra2 dec2} or {x1 y1 x2 y2}.
-equinox	Equinox for the position (default 2000.0).
-id	Object Id, returned from a previous query.
-nameserver	Name server to use for resolving object names (for example simbad@eso or ned@eso - default is simbad@eso).
-name	Astronomical object name to be resolved by a name server.
-radius	Max radius from position/name (or list of min and max radius) in arcmin.
-width -height	Specify the width and height of the area in arcmin, centered at the given center point.
-nrows	Max number of rows to return.
-mag	Max magnitude of object (or list with min and max magnitude).
-columns	List of columns to return, default: all columns returned by server.
-sort	List of columns to sort by.
-sortorder	Specify the sort order as "increasing" or "decreasing"
-searchcols, -minvalues, -maxvalues	The argument for -`searchcols` is a list of columns to search by. The -`minvalues` and -`maxvalues` options supply the corresponding value ranges and must have the same lengths.

Some of the query options will take a Tcl list of two items as an argument, in which case a range search will be made. For example, the command:

 
cat query -pos {3:19:48 +41:30:39} -radius {10.5 20.2} -mag {2.3 4.5}

returns a Tcl list of objects between radius 10.5 and 20.2 from the given position and with a magnitude between 2.3 and 4.5.

The table below summarizes the astrocat subcommands. See the man pages for a detailed description.

Subcommand	Description
`check`	Check that the given filename is a valid local catalog (tab table format).
`checkrow`	Check that the given row (tcl list of column values) is valid for the catalog (use before inserting a new row).
`close`	Close the current catalog.
`copyright`	Return the copyright field from teh catalog config entry.
`id_col, ra_col, dec_col, x_col, y_col`	These subcommands return the column index for the id, ra, dec, x or y column, from the catalog config entry.
`entry`	This subcommand is used to manipulate (get, set, update) catalog config entries.
`feedback`	Specifies a Tcl file descriptor to use to write feedback info during HTTP transfer of catalog data.
`getcol`	Given a row of output from a query, return the value for the named column in Tcl
`getidpos`	Given a row of output from a query, return a list {id ra dec} , or {id x y} if we're not using World Coordinates, for the given row.
`getimage`	Get an image from the image server, based on the given options, put it in a temp file and return the name of the file.
`getpreview`	Given a URL from a query output line, get the preview data and put it in a temp file and return a list of {filename type}, where filename is the name of the file containing the preview data and type is either "`image` " for a FITS image or "`table` " for a tab table with data to be plotted in a graph.
`hascol`	Return true if the catalog has the given column.
`headings`	Return a Tcl list of catalog column headings.
`info`	Returns a list of catalogs of a given type and/or under a given catalog directory/
`is_tcs`	Returns true if the catalog is a TCS catalog (flag set in config entry).
`iswcs` `ispix`	iswcs returns true if the catalog supports World Coordinates, ispix returns true if image pixel coordinates are supported. If both of these return false, no coordinates are supported. By default, catalogs are assumed to support World Coordinates.
`load`	Loads the named catalog config file, making the catalogs in it available to the application.
`longname`	Return the long name of the current or given catalog.
`more`	Return true if there were more than `nrows` rows available.
`open`	Open the named catalog.
`plot`	Plot the contents of the given tab table file in the given BLT graph widget.
`query`	Query the catalog and return a Tcl list of result rows.
`querypos`	Return the world or image coordinate position arguments from the most recent query, posibly expanded by a name server such as SIMBAD.
`reload`	Reloads the default catalog config file and updates the internal catalog entries from it.
`remove`	Remove specified objects from a local catalog file.
`root`	Returns the name of the root catalog directory.
`save`	Save query results to a file as a local catalog or insert into existing local catalog.
`searchcols`	Set or get the list of search columns in the catalog config entry.
`servtype`	Return the serv_type field from the catalog config file, or "local" for local catalogs.
`shortname`	Return the short name of the catalog.
`showcols`	Set or get the list of columns to display in the catalog config entry.
`sortcols`	Set or get the list of sort columns in the catalog config entry.
`sortorder`	Set or get the sort order in the catalog config entry.
`symbol`	Return the name of symbol used to plot the catalog objects.
`url`	Return the URL for the current or given catalog.

See teh man page astrocat(n) for more details.