From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- vendor/voclient/doc/voregistry.html | 476 ++++++++++++++++++++++++++++++++++++ 1 file changed, 476 insertions(+) create mode 100644 vendor/voclient/doc/voregistry.html (limited to 'vendor/voclient/doc/voregistry.html') 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 + +Manpage of VOREGISTRY + +

VOREGISTRY

+Section: User Commands (1)
Updated: July 2007
Index +Return to Main Contents

+ + +

NAME

+ +voregistry - VO Registry search client +

+ +

SYNOPSIS

+ +voregistry [-<flags>] [ <keywords> | <term> ] [ ... ] +

+ +

OPTIONS

+ +The voregistry task accepts the following options: +

-h, --help + +: +Print a help summary to the terminal and exit. No processing is done +following this flag. +
-v, --verbose + +: +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. +
--vverbose + +: +Very-verbose output. Even more output. +
The following flags control the major behavior of the task, i.e. the type: +of output to present. +
-c, --count + +: +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. +
-e, --exact + +: +Match exactly the search term (resolve mode only). The term 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. +
-l, --list + +: +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. +
-m, --meta + +: +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. +
-r, --resolve + +: +Resolve the search term to a specified resource. In resolve mode +the search terms are assumed to be either the resource ShortName or +Identifier and the match will be done using only these two fields in +the Registry resource record. The default output is simply the +ServiceURL for all matching records (i.e. resources where the search +string is part of the ShortName or Identifier fields) unless +the -f flag is given to select other fields. +
Shorthand Convenience Options:: +
-I, --id + +: +Print only the Identifier field for the resolved resource. +
-L, --long + +: +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. +
-R, --Resolve + +: +Print the ShortName, ServiceType and Identifier fields for +the resolved resource. +
-S, --SName + +: +Print only the ShortName field for the resolved resource. +
-T, --Title + +: +Print only the Title for the resolved resources. +
Constraint Options:: +

+ +The list of allowed constraint strings is generally specified in the +Resource Metadata for the Virtual Observatory 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. +

-b, --bandpass <bpass> + +

+Constrain the search to the specified bandpass string. +The text argument following the -f flag +will be matched against the SpectralCoverage 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. +

-C, --clevel <content> + +

+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. +

-d, --dal + +

+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 -d flag will restrict results to only +those resource records describing a standard VO data-access service. +

-g, --group + +

+Group the search terms to form a single query. +

-s, --subject <subject> + +

+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. +

-t, --type <type> + +

+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. +

-N, --new <time> + +

+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. +

-U, --updated <time> + +

+Constrain the search to those resource records that have been updated during +the specified time period. +

Output Control Options:

-a, --all + +

+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 + +

-f, --fields <fields> + +

+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. +

-O, --or + +

+Logically OR the search terms. By default, all terms will be used when +matching resource records. +

-n, --index <index> + +

+Output only the results for the matchng index. Results are 1-indexed, +i.e. the first result is index 1 (one). +

-o, --output <oname> + +

+Save the results in VOTable format to the file name oname. The +verbose level of the query is increased when using this option. +

-B, --samp + +

+Broadcast the results as a SAMP message using a table.load.votable +message type. +

-V, --votable + +

+Write results in VOTable format. +

-X, --xml + +

+Write results in VOTable format. +

+ +

DESCRIPTION

+ +The voregistry task provides a command-line interface to the NVO +Registry 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 -t flag), spectral coverage (the -b flag), or +content level (the -C flag). +

+ +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. +

+ +In the default search mode, keywords given on the command line will all be +used to match resource records. The -o 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 +vodata(1). Additional output can be had with the -v or -vv +verbose flags. A simple count of the resources will be printed if the +-c 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). +

+ +The "Resolve mode" is activated by the -r flag; In this mode the +keywords will only be matched against the Registry ShortName and +Identifier fields. The default output is simply the ServiceURL, +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 -f flag followed by a comma-delimited +list of fields. The allowed fields are shown with the -h help flag. +

+ +The -list flag implies Resolve Mode and will cause all fields of the +matching resource to be printed. Unless the -a 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 +-a flag will list all services where '2mass' appears in the ShortName. +

+ +The -meta 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 FORMAT=METADATA 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 -v flags will likewise +increase the VERBOSE of the query and may return additional columns). +

+ +

RETURN STATUS

+ +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. +

+ +

VOCLIENT DAEMON PROCESSING

+ +All VO-CLI tasks are built upon the VOClient interface an rely on a +separate voclientd 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. +

+ +

RESOURCE CACHING

+ +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 +VOC_NO_CACHE environment variable will cause the task to ignore the +cache. +

+ +

EXAMPLES

+ +

1)

+Get a count of all the SIAP services available in the Registry, then +list more information about each one: +

+
+        % voregistry -count -t image
+        142
+        % voregistry -rv -t image
+
+

+ +

2)

+Find all catalog (i.e. Cone) services using the search words 'radio' +and 'galaxies': +

+
+        % voregistry -t catalog radio galaxies
+
+

+ +

3)

+Print the full resource record of the GSC2.2 catalog at STScI: +

+
+        % voregistry -list GSC2.2
+
+

+ +

4)

+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: +

+
+        % voregistry -b radio abell
+        % voregistry -rvv -n 1 J/A+A/446/97/tab
+
+

+ +

5)

+Find all image services that have WFPC data: +

+
+        % voregistry -v -t image wfpc
+
+

+ +

6)

+Print a breakdown of VO services having Keck data: +

+
+        % voregistry -cv keck
+        keck           122   (Cat: 2  Tab: 117 SNode: 1  Other: 2)
+
+

+ +

7)

+Print a count of services having all of Chandra, HST and Spitzer data, +then break it down by each mission: +

+
+        % voregistry -c chandra hst spitzer
+        chandra hst spitzer         3
+        % voregistry -co chandra hst spitzer
+        chandra                   323
+        hst                       443
+        spitzer                    31
+
+

+ +

8)

+Print the column metadata returned by the GSC2.2 service: +

+
+        % voregistry -meta gsc2.2
+
+

+ +

9)

+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: +

+
+        % voregistry "Facility like 'HST'"
+
+

+ +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. +

10) Use the ADQL query format to find services in which 'Keck' appears in

+the Title of the resource: +

+
+        % voregistry "Title like '%Keck%'"
+
+                or
+
+        % cat query.txt
+        Title like '%Keck%'
+        % cat query.txt | voregistry
+
+

+ +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. +

11) Find all resources that are newly registered in the last 3 months, then

+find only those resources dealing with "cool stars", and finally just print +a count of resources updated in the last year: +

+
+        % voregistry --new 3m
+        % voregistry --new 3m cool stars
+        % voregistry --updated 12m --count
+
+

+ +

BUGS

+ +Some services don't repond properly to the metadata query and will print +a "no attributes found" message. + +

Revision History

+ +June 2007 - This task is new. + +

Author

+ +Michael Fitzpatrick (fitz@noao.edu), July 2007 + +

+This document was created by +man2html, +using the manual pages.
+Time: 05:13:24 GMT, April 14, 2013 + + -- cgit