Initial commit

1 files changed, 144 insertions, 0 deletions

diff --git a/vo/votools/doc/getcat.hlp b/vo/votools/doc/getcat.hlp
new file mode 100644
index 00000000..b8ee9cd8
--- /dev/null
+++ b/vo/votools/doc/getcat.hlp
@@ -0,0 +1,144 @@
+.help getcat Mar12 votools
+.ih
+NAME
+getcat -- Query catalog data services in the VO
+.ih
+USAGE
+getcat resource fields
+.ih
+PARAMETERS
+.ls resource
+List of the VO data services to query.  
+.le
+.ls fields
+List of objects or images used to specify the position of the query.  An
+object name will be resolved to a position using the \fISESAME\fR service
+and the \fIsize\fR parameter will determine the query size.  If an image
+name is given, the center position and image corners will be used to
+determine the query position and size.
+.le
+.ls pos = ""
+A string specifying the position of the query.  Positions are specified as
+J2000 RA and Dec in decimal degrees separate by a comma.
+.le
+.ls size = 0.25
+Query size in decimal degrees.
+.le
+.ls samp = no
+If enabled, each result table is broadcast as a SAMP message to other 
+VO applications.
+.le
+.ls plot = no
+Plot the result table to the standard graphics stream? 
+The \fIplot\fR parameter is ignored when using multiple resources or fields.
+.le
+.ls display = no
+If enabled, an image of the \fIfield\fR will be displayed.  If the
+\fIfield\fR is an object name, a DSS image of the field will be displayed,
+if the \fIfield\fR is an image then the image will be displayed.  The
+\fIdisplay\fR parameter is ignored when using multiple resources or fields.
+.le
+.ls overplot = no
+If enabled, the objects in the result table will be overlayed on the
+image display.  The \fIoverplot\fR parameter is ignored when using multiple
+resources or fields.
+.le
+.ls output = "STDOUT"
+Output filename.  If the \fIoutput\fR parameter is "STDOUT" the result table
+will be written to the standard output stream.  If the output name is a 
+null string, no result table will be printed or saved.
+.le
+.ls format = "ascii"
+Format of the result table.  Allowed values are
+.ls vot | xml
+A new VOTable.
+.le
+.ls asv
+Ascii separated values.
+.le
+.ls bsv
+Bar separated values.
+.le
+.ls csv
+Comma separated values.
+.le
+.ls tsv
+Tab separated values.
+.le
+.ls html
+Standalone HTML document.
+.le
+.ls shtml
+Single HTML <table> element.  This format may be used to generate the <table>
+code for inclusion in another HTML document.
+.le
+.ls fits
+FITS binary table
+.le
+.le
+.ls status = 0
+Return status code.  A non-zero value indicates an error in the query.
+.le
+
+.ih
+DESCRIPTION
+The \fIGETCAT\fR task is used to retrieve data from one or more VO 
+catalog services.  An individual \fIresource\fR name may be 
+specified as a user-defined alias, a VO \fIShortName\fR, a VO \fIivorn\fR
+identifier string, or as a base service URL.  If specified as a service URL, 
+additional parameters to specify the position and size will be determined
+from the \fIfields\fR, \fIpos\fR and \fIsize\fR parameters.  Multiple 
+resources may be specified as a comma-delimited string or as an \fI@file\fR.
+
+The position to be queried may be specified by the \fIfields\fR parameter
+as either a list of object names that are resolved to equatorial coordinates
+automatically, or as a list of images where the WCS footprint of the image is
+used to determine the center and size.  For object names, the \fIsize\fR
+parameter is specified in decimal degrees as the radius around the position
+to query.  The \fIpos\fR parameter may be specified as a comma-separated
+set of RA/Dec values given in decimal degrees.
+
+Result tables may be broadcast to other VO applications using SAMP messaging
+by enabling the \fIsamp\fR parameter.  If the \fIdisplay\fR parameter is
+enabled then images used as input will be displayed, if object names are
+used a DSS image of the field will be displayed.  The \fIoverplot\fR parameter
+may be set to overplot the result catalog on the image display automatically.
+The \fIdisplay\fR and \fIoverplot\fR parameters are only used for 
+single-resource and single-object queries.
+
+Results may be saved to disk in a format specified by the \fIformat\fR 
+parameter (described above).  If the \fIoutput\fR parameter is the null
+string then no local results will be saved or printed, the value "STDOUT"
+may be used to print the result table to the standard output stream (except
+in the case of FITS bintable output).
+
+.ih
+EXAMPLES
+1. Find the GSC2.3 catalog sources within 0.1 degrees of 3c273.  Display
+the field and overplot the catalog positions on the image display, but do
+not print the results.  Then do the same but plot a graph instead of
+overlay the display.
+
+.nf
+  votools> getcat gsc2.3 3c273 size=0.1 display+ overplot+ output=""
+  votools> getcat gsc2.3 3c273 size=0.1 plot+ output=""
+.fi
+
+2. Find the 2MASS point-source catalog objects in each extension of a
+NEWFIRM mosaic image:
+
+.nf
+  votools> getcat 2mass-psc @newfirm.fits format="fits" output="nf"
+.fi
+
+The result tables are saved as FITS bintables with the root name 'nf'
+followed by a running number indicating the extension.
+
+
+.ih
+REVISIONS
+.le
+.ih
+SEE ALSO
+getimg, vodata, votpos
+.endhelp