diff options
Diffstat (limited to 'vendor/voclient/doc/voregistry.html')
| -rw-r--r-- | vendor/voclient/doc/voregistry.html | 476 |
1 files changed, 476 insertions, 0 deletions
diff --git a/vendor/voclient/doc/voregistry.html b/vendor/voclient/doc/voregistry.html new file mode 100644 index 00000000..b99bbfb6 --- /dev/null +++ b/vendor/voclient/doc/voregistry.html @@ -0,0 +1,476 @@ +Content-type: text/html + +<HTML><HEAD><TITLE>Manpage of VOREGISTRY</TITLE> +</HEAD><BODY> +<H1>VOREGISTRY</H1> +Section: User Commands (1)<BR>Updated: July 2007<BR><A HREF="#index">Index</A> +<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +voregistry - VO Registry search client +<P> +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<B>voregistry</B> [-<I><flags></I>] [ <I><keywords></I> | <<I>term</I>> ] [ ... ] +<P> +<A NAME="lbAD"> </A> +<H2>OPTIONS</H2> + +The <I>voregistry</I> task accepts the following options: +<DL COMPACT> +<DT><B>-h, --help</B> + +<DD> +Print a help summary to the terminal and exit. No processing is done +following this flag. +<DT><B>-v, --verbose</B> + +<DD> +Verbose output. The output will be more verbose than normal but exactly +what is printed depends on whether other flags are enabled to changed the +basic task behavior. +<DT><B>--vverbose</B> + +<DD> +Very-verbose output. Even more output. +<DT>The following flags control the major behavior of the task, i.e. the type<DD> +of output to present. +<DT><B>-c, --count</B> + +<DD> +Print a count of matching records. For each of the search terms, a simple +count of matching resources will be printed. A breakdown by service type +will be printed if the verbose flag is enabled. +<DT><B>-e, --exact</B> + +<DD> +Match exactly the search term (resolve mode only). The <I>term</I> in this +case will normally be an IVO identifier, this flag can be used to match the +identifier exactly rather than as a potential substring. This option will +return an empty string if no exact match is found. +<DT><B>-l, --list</B> + +<DD> +List the full resource record for each matching resource. For each matching +resource, all (well, most) of the information available about a resource +will be printed to the screen. Additional information may be available from +the Registry web interface. +<DT><B>-m, --meta</B> + +<DD> +List the metadata for the data services associated with the resource. For +each resource found, the table metadata (i.e. the column UCD values) +associated with the resource will be printed. Currently only those DAL +services supported by VOClient may be queried. +<DT><B>-r, --resolve</B> + +<DD> +<I>Resolve</I> the search term to a specified resource. In <I>resolve mode</I> +the search terms are assumed to be either the resource <I>ShortName</I> or +<I>Identifier</I> and the match will be done using only these two fields in +the Registry resource record. The default output is simply the +<I>ServiceURL</I> for all matching records (i.e. resources where the search +string is part of the <I>ShortName</I> or <I>Identifier</I> fields) unless +the <I>-f</I> flag is given to select other fields. +<DT>Shorthand Convenience Options:<DD> +<DT><B>-I, --id</B> + +<DD> +Print only the <I>Identifier</I> field for the resolved resource. +<DT><B>-L, --long </B> + +<DD> +Suppress the linebreaks imposed for output fields that would wrap around the +normal 80-character output and allow long lines. This allows tasks to parse +the output more predictably. +<DT><B>-R, --Resolve</B> + +<DD> +Print the <I>ShortName</I>, <I>ServiceType</I> and <I>Identifier</I> fields for +the resolved resource. +<DT><B>-S, --SName</B> + +<DD> +Print only the <I>ShortName</I> field for the resolved resource. +<DT><B>-T, --Title</B> + +<DD> +Print only the <I>Title</I> for the resolved resources. +<DT>Constraint Options:<DD> +</DL> +<P> + +The list of allowed constraint strings is generally specified in the +<I>Resource Metadata for the Virtual Observatory</I> document available on +the IVOA document repository. These flags provide a convenient method to +limit a result list to resources that explicitly specify a value for the +given constraint. +<DL COMPACT> +<DT><B>-b, --bandpass <bpass></B> + +<DD> +Constrain the search to the specified bandpass string. +The text argument following the -f flag +will be matched against the <I>SpectralCoverage</I> field of the resource +record. Registry resources allow a list of values, however only a single +argument may be used to constrain the search. Permitted values include: +"Radio", "Millimeter", "Infrared" (IR), "Optical", "Ultraviolet" (UV), +"X-Ray" (XRay), and "Gamma-Ray" (GR). The match is case insensitive, values +shown in parentheses may be given and will be substituted automatically. +<DT><B>-C, --clevel <content></B> + +<DD> +Constrain the search to the specified ContentLevel string. The Registry +may contain data for a variety of intended audiences; Most often this +constraint will be used to limit the results to 'Research' grade data. +<DT><B>-d, --dal</B> + +<DD> +Constrain the search to only standard DAL services. A general keyword search will +normally return all resources, including those referring to custom services or +non data-access entries. Use of the <I>-d</I> flag will restrict results to only +those resource records describing a standard VO data-access service. +<DT><B>-g, --group</B> + +<DD> +Group the search terms to form a single query. +<DT><B>-s, --subject <subject></B> + +<DD> +Constrain the search to the specified Subject string. Note that multi-word +subjects (e.g. "cool stars") must either be quoted or have the space escaped +for the subject to be queried correctly. A substring, case-insensitive search +of the Subject field is performed. +<DT><B>-t, --type <type></B> + +<DD> +Constrain the search to the specified ResourceType string. The Registry +records may contain any user-specified string, however unless you know +specifically how a specific resource is defined, this constraint should +use the values 'catalog' (for Cone services), 'image' (for SIAP +services), 'spectra' (for SSAP services), 'table' (for Vizier tables), +or a literal string which appears in the +resource record. Additional aliases will be added as new +data services are supported. +<DT><B>-N, --new <time></B> + +<DD> +Constrain the search to those resources that have been newly created during +the specified <time>. By default, <time> is an integer value assumed to be +a number of days, the last character may contain one of the qualifying +characters to change the time period: 'h' for hours, 'd' for days, + +refers to the last siz months. If no search term is given, all results +for that period will be returned, otherwise only those results that match +both the search terms and the time constraint will be listed. +<DT><B>-U, --updated <time></B> + +<DD> +Constrain the search to those resource records that have been updated during +the specified time period. +<DT>Output Control Options:<DD> +<DT><B>-a, --all</B> + +<DD> +Output all matching records (default). When used with the constraint flags +above, this flag will allow those constraint strings to be matched as a +substring, e.g. using "-t siap" will exactly match resources with type + +<DT><B>-f, --fields <fields></B> + +<DD> +Output the specified fields from the resource record (used in Resolve Mode +only). The list of available fields is given below, an 'INDEF' string is +printed for invalid field names or when no information is available. +<DT><B>-O, --or</B> + +<DD> +Logically OR the search terms. By default, all terms will be used when +matching resource records. +<DT><B>-n, --index <index></B> + +<DD> +Output only the results for the matchng <I>index</I>. Results are 1-indexed, +i.e. the first result is index 1 (one). +<DT><B>-o, --output <oname></B> + +<DD> +Save the results in VOTable format to the file name <I>oname</I>. The +verbose level of the query is increased when using this option. +<DT><B>-B, --samp</B> + +<DD> +Broadcast the results as a SAMP message using a <I>table.load.votable</I> +message type. +<DT><B>-V, --votable</B> + +<DD> +Write results in VOTable format. +<DT><B>-X, --xml</B> + +<DD> +Write results in VOTable format. +<P> +<P> +</DL> +<A NAME="lbAE"> </A> +<H2>DESCRIPTION</H2> + +The <I>voregistry</I> task provides a command-line interface to the <I>NVO +Registry</I> at STScI/JHU. The task also provides a basic search capability +for the Registry, as well as a "Resolve Mode" that can be used to lookup +resource records given some familiar name (e.g. 'USNO-B1'). Constraint +parameters allow the search to be restricted to resources declaring a +specific type (the <I>-t</I> flag), spectral coverage (the <I>-b</I> flag), or +content level (the <I>-C</I> flag). +<P> + +Search terms may be provided on the +command-line, in a filename specified on the commandline, or read from the +standard input (e.g. redirected from a file or other command). Advanced +users can submit a quoted ADQL string to access specific fields of a resource +record. This is similar to using the "Advanced Search" capability on the +NVO Registry web page. ADQL strings are required to be in double quotes +when given on the command line, the quotes are needed when query strings +come from a file. Standard SQL operators apply for comparison and boolean +operations, the 'like' operator is used to match strings (which must be in +single quotes), one or more '%' metacharacters may be used in the string +to indicate a wildcard match. +<P> + +In the default search mode, keywords given on the command line will all be +used to match resource records. The <I>-o</I> flag may be used to logically +OR the keyword terms, e.g. to allow a search of 'galaxy' or 'galaxies'. The +minimal output provides the resource title, type, subject and the 'ShortName' +that can be used in the resolve mode or be passed to other tasks such as +<A HREF="http://localhost/cgi-bin/man/man2html?1+vodata">vodata</A>(1). Additional output can be had with the <I>-v</I> or <I>-vv</I> +verbose flags. A simple count of the resources will be printed if the +<I>-c</I> flag is set (e.g. the command "voregistry -oc chandra spitzer" +will print a count of how many records match each term rather than display +them directly, without the -o flag a count of resources mentioning both +keywords will be printed). +<P> + +The "Resolve mode" is activated by the <I>-r</I> flag; In this mode the +keywords will only be matched against the Registry <I>ShortName</I> and +<I>Identifier</I> fields. The default output is simply the <I>ServiceURL</I>, +adding the verbose flags will instead print the ShortName, ResourceType and +Title (with "-v") or Description (with "-vv"). The user can select specific +fields to be printed using the <I>-f</I> flag followed by a comma-delimited +list of fields. The allowed fields are shown with the <I>-h</I> help flag. +<P> + +The <I>-list</I> flag implies Resolve Mode and will cause all fields of the +matching resource to be printed. Unless the <I>-a</I> flag is set, the +search term will be matched exactly, otherwise it will be considered to be +a substring of the ShortName or Identifier fields. For example, searching +with the term '2mass' will list only 2MASS image service, but using the +<I>-a</I> flag will list all services where '2mass' appears in the ShortName. +<P> + +The <I>-meta</I> flag likewise assumes the command line arg is a resource +ShortName to be resolved and will query the DAL service associated with it +using a <I>FORMAT=METADATA</I> query. The default position will be (0.0,0.0) +with a search size of 0.1 degrees, the response will be a list of the column +UCDs returned by the query (note that adding <I>-v</I> flags will likewise +increase the VERBOSE of the query and may return additional columns). +<P> +<A NAME="lbAF"> </A> +<H2>RETURN STATUS</H2> + +The task will exit with a status of 0 if at least one search term could +be successfully resolved, otherwise the status will be 1. +<P> +<A NAME="lbAG"> </A> +<H2>VOCLIENT DAEMON PROCESSING</H2> + +All VO-CLI tasks are built upon the VOClient interface an rely on a +separate <I>voclientd</I> process to provide the VO functionality. The +voclientd task is distributed as part of VO-CLI and will be started +automatically by each task if it is not already running. If problems +are encountered, you may want to manually start the voclientd in a separate +window before running the task so you can monitor the output for error +messages. +<P> +<A NAME="lbAH"> </A> +<H2>RESOURCE CACHING</H2> + +Registry resolution is a common activity of VO-CLI tasks and so results +will be cached in the $HOME/.voclient/cache/regResolver directory based +on the search term, service type and bandpass parameters. Defining the +<I>VOC_NO_CACHE</I> environment variable will cause the task to ignore the +cache. +<P> +<P> +<A NAME="lbAI"> </A> +<H2>EXAMPLES</H2> + +<P> +<DL COMPACT> +<DT>1)<DD> +Get a count of all the SIAP services available in the Registry, then +list more information about each one: +<PRE> + + % voregistry -count -t image + 142 + % voregistry -rv -t image + +</PRE> + +<DT>2)<DD> +Find all catalog (i.e. Cone) services using the search words 'radio' +and 'galaxies': +<PRE> + + % voregistry -t catalog radio galaxies + +</PRE> + +<DT>3)<DD> +Print the full resource record of the GSC2.2 catalog at STScI: +<PRE> + + % voregistry -list GSC2.2 + +</PRE> + +<DT>4)<DD> +Find all services with radio data of Abell clusters. Then print the +full description of the first record associated with one of the matching +Vizier tables: +<PRE> + + % voregistry -b radio abell + % voregistry -rvv -n 1 J/A+A/446/97/tab + +</PRE> + +<DT>5)<DD> +Find all image services that have WFPC data: +<PRE> + + % voregistry -v -t image wfpc + +</PRE> + +<DT>6)<DD> +Print a breakdown of VO services having Keck data: +<PRE> + + % voregistry -cv keck + keck 122 (Cat: 2 Tab: 117 SNode: 1 Other: 2) + +</PRE> + +<DT>7)<DD> +Print a count of services having all of Chandra, HST and Spitzer data, +then break it down by each mission: +<PRE> + + % voregistry -c chandra hst spitzer + chandra hst spitzer 3 + % voregistry -co chandra hst spitzer + chandra 323 + hst 443 + spitzer 31 + +</PRE> + +<DT>8)<DD> +Print the column metadata returned by the GSC2.2 service: +<PRE> + + % voregistry -meta gsc2.2 + +</PRE> + +<DT>9)<DD> +Use the ADQL query format to find services in which HST was the used, +and not simply a match of 'HST' in the resource record: +<PRE> + + % voregistry "Facility like 'HST'" + +</PRE> + +Note that use assumed knowledge of the Registry being queried, specifically +that there exists a 'Facility' field with this information and that the +syntax of the query requires the string to be in quotes. +<P> +<DT>10) Use the ADQL query format to find services in which 'Keck' appears in<DD> +the Title of the resource: +<PRE> + + % voregistry "Title like '%Keck%'" + + or + + % cat query.txt + Title like '%Keck%' + % cat query.txt | voregistry + +</PRE> + +Note that here we use the '%' operator around the string so that we perform +a substring match on the entire title. As before, the ADQL string itself +must be enclosed in double quotes. +<P> +<DT>11) Find all resources that are newly registered in the last 3 months, then<DD> +find only those resources dealing with "cool stars", and finally just print +a count of resources updated in the last year: +<PRE> + + % voregistry --new 3m + % voregistry --new 3m cool stars + % voregistry --updated 12m --count + +</PRE> + +<P> +</DL> +<A NAME="lbAJ"> </A> +<H2>BUGS</H2> + +Some services don't repond properly to the metadata query and will print +a "no attributes found" message. +<A NAME="lbAK"> </A> +<H2>Revision History</H2> + +June 2007 - This task is new. +<A NAME="lbAL"> </A> +<H2>Author</H2> + +Michael Fitzpatrick (<A HREF="mailto:fitz@noao.edu">fitz@noao.edu</A>), July 2007 +<A NAME="lbAM"> </A> +<H2>SEE ALSO</H2> + +<A HREF="http://localhost/cgi-bin/man/man2html?1+voclient">voclient</A>(1), <A HREF="http://localhost/cgi-bin/man/man2html?1+voclientd">voclientd</A>(1), <A HREF="http://localhost/cgi-bin/man/man2html?1+vosesame">vosesame</A>(1), <A HREF="http://localhost/cgi-bin/man/man2html?1+vodata">vodata</A>(1) +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">OPTIONS</A><DD> +<DT><A HREF="#lbAE">DESCRIPTION</A><DD> +<DT><A HREF="#lbAF">RETURN STATUS</A><DD> +<DT><A HREF="#lbAG">VOCLIENT DAEMON PROCESSING</A><DD> +<DT><A HREF="#lbAH">RESOURCE CACHING</A><DD> +<DT><A HREF="#lbAI">EXAMPLES</A><DD> +<DT><A HREF="#lbAJ">BUGS</A><DD> +<DT><A HREF="#lbAK">Revision History</A><DD> +<DT><A HREF="#lbAL">Author</A><DD> +<DT><A HREF="#lbAM">SEE ALSO</A><DD> +</DL> +<HR> +This document was created by +<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 05:13:24 GMT, April 14, 2013 +</BODY> +</HTML> |