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.
$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 starting 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 Open the given astromonical catalog and refer to it in future queries. $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.
Please send questions or comments to abrighto@eso.org@eso.org.
Copyright © 1998 ESO - European Southern Observatory