diff options
Diffstat (limited to 'vendor/voclient/doc/voregistry.man')
| -rw-r--r-- | vendor/voclient/doc/voregistry.man | 384 |
1 files changed, 384 insertions, 0 deletions
diff --git a/vendor/voclient/doc/voregistry.man b/vendor/voclient/doc/voregistry.man new file mode 100644 index 00000000..e4a16de2 --- /dev/null +++ b/vendor/voclient/doc/voregistry.man @@ -0,0 +1,384 @@ +.\" @(#)voregistry.1 1.0 June-07 MJF +.TH VOREGISTRY 1 "July 2007" "VOClient Project" +.SH NAME +voregistry \- VO Registry search client + +.SH SYNOPSIS +\fBvoregistry\fP [\-\fI<flags>\fP] [ \fI<keywords>\fP | <\fIterm\fP> ] [ ... ] + +.SH OPTIONS +The \fIvoregistry\fP task accepts the following options: +.TP 8 +.B \-h, --help +Print a help summary to the terminal and exit. No processing is done +following this flag. +.TP 8 +.B \-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. +.TP 8 +.B \--vverbose +Very-verbose output. Even more output. +.TP 0 +The following flags control the major behavior of the task, i.e. the type +of output to present. +.TP 8 +.B \-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. +.TP 8 +.B \-e, --exact +Match exactly the search term (resolve mode only). The \fIterm\fP 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. +.TP 8 +.B \-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. +.TP 8 +.B \-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. +.TP 8 +.B \-r, --resolve +\fIResolve\fP the search term to a specified resource. In \fIresolve mode\fP +the search terms are assumed to be either the resource \fIShortName\fP or +\fIIdentifier\fP and the match will be done using only these two fields in +the Registry resource record. The default output is simply the +\fIServiceURL\fP for all matching records (i.e. resources where the search +string is part of the \fIShortName\fP or \fIIdentifier\fP fields) unless +the \fI-f\fP flag is given to select other fields. +.TP 0 +Shorthand Convenience Options: +.TP 8 +.B \-I, --id +Print only the \fIIdentifier\fP field for the resolved resource. +.TP 8 +.B \-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. +.TP 8 +.B \-R, --Resolve +Print the \fIShortName\fP, \fIServiceType\fP and \fIIdentifier\fP fields for +the resolved resource. +.TP 8 +.B \-S, --SName +Print only the \fIShortName\fP field for the resolved resource. +.TP 8 +.B \-T, --Title +Print only the \fITitle\fP for the resolved resources. +.TP 0 +Constraint Options: +.PP +The list of allowed constraint strings is generally specified in the +\fIResource Metadata for the Virtual Observatory\fP 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. +.TP 8 +.B \-b, --bandpass <bpass> +Constrain the search to the specified bandpass string. +The text argument following the -f flag +will be matched against the \fISpectralCoverage\fP 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. +.TP 8 +.B \-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. +.TP 8 +.B \-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 \fI-d\fP flag will restrict results to only +those resource records describing a standard VO data-access service. +.TP 8 +.B \-g, --group +Group the search terms to form a single query. +.TP 8 +.B \-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. +.TP 8 +.B \-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. +.TP 8 +.B \-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, +'w' for weeks, and 'm' for months. For example, the <time> string "6m" +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. +.TP 8 +.B \-U, --updated <time> +Constrain the search to those resource records that have been updated during +the specified time period. +.TP 0 +Output Control Options: +.TP 8 +.B \-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 +'siap', but using "-a -t siap" will also match 'siap/cutout' services. +.TP 8 +.B \-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. +.TP 8 +.B \-O, --or +Logically OR the search terms. By default, all terms will be used when +matching resource records. +.TP 8 +.B \-n, --index <index> +Output only the results for the matchng \fIindex\fP. Results are 1-indexed, +i.e. the first result is index 1 (one). +.TP 8 +.B \-o, --output <oname> +Save the results in VOTable format to the file name \fIoname\fP. The +verbose level of the query is increased when using this option. +.TP 8 +.B \-B, --samp +Broadcast the results as a SAMP message using a \fItable.load.votable\fP +message type. +.TP 8 +.B \-V, --votable +Write results in VOTable format. +.TP 8 +.B \-X, --xml +Write results in VOTable format. + + +.SH DESCRIPTION +The \fIvoregistry\fP task provides a command-line interface to the \fINVO +Registry\fP 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 \fI-t\fP flag), spectral coverage (the \fI-b\fP flag), or +content level (the \fI-C\fP flag). +.PP +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. +.PP +In the default search mode, keywords given on the command line will all be +used to match resource records. The \fI-o\fR 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 \fI-v\fR or \fI-vv\fP +verbose flags. A simple count of the resources will be printed if the +\fI-c\fP 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). +.PP +The "Resolve mode" is activated by the \fI-r\fR flag; In this mode the +keywords will only be matched against the Registry \fIShortName\fP and +\fIIdentifier\fR fields. The default output is simply the \fIServiceURL\fR, +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 \fI-f\fP flag followed by a comma-delimited +list of fields. The allowed fields are shown with the \fI-h\fP help flag. +.PP +The \fI-list\fP flag implies Resolve Mode and will cause all fields of the +matching resource to be printed. Unless the \fI-a\fP 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 +\fI-a\fP flag will list all services where '2mass' appears in the ShortName. +.PP +The \fI-meta\fP 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 \fIFORMAT=METADATA\fP 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 \fI-v\fP flags will likewise +increase the VERBOSE of the query and may return additional columns). + +.SH 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. + +.SH VOCLIENT DAEMON PROCESSING +All VO-CLI tasks are built upon the VOClient interface an rely on a +separate \fIvoclientd\fP 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. + +.SH 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 +\fIVOC_NO_CACHE\fP environment variable will cause the task to ignore the +cache. + + +.SH EXAMPLES + +.TP 4 +1) +Get a count of all the SIAP services available in the Registry, then +list more information about each one: +.nf + + % voregistry --count -t image + 142 + % voregistry -rv -t image + +.fi +.TP 4 +2) +Find all catalog (i.e. Cone) services using the search words 'radio' +and 'galaxies': +.nf + + % voregistry -t catalog radio galaxies + +.fi +.TP 4 +3) +Print the full resource record of the GSC2.2 catalog at STScI: +.nf + + % voregistry --list GSC2.2 + +.fi +.TP 4 +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: +.nf + + % voregistry -b radio abell + % voregistry -rvv -n 1 J/A+A/446/97/tab + +.fi +.TP 4 +5) +Find all image services that have WFPC data: +.nf + + % voregistry -v -t image wfpc + +.fi +.TP 4 +6) +Print a breakdown of VO services having Keck data: +.nf + + % voregistry -cv keck + keck 122 (Cat: 2 Tab: 117 SNode: 1 Other: 2) + +.fi +.TP 4 +7) +Print a count of services having all of Chandra, HST and Spitzer data, +then break it down by each mission: +.nf + + % voregistry -c chandra hst spitzer + chandra hst spitzer 3 + % voregistry -co chandra hst spitzer + chandra 323 + hst 443 + spitzer 31 + +.fi +.TP 4 +8) +Print the column metadata returned by the GSC2.2 service: +.nf + + % voregistry --meta gsc2.2 + +.fi +.TP 4 +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: +.nf + + % voregistry "Facility like 'HST'" + +.fi +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. + +.TP 4 +10) Use the ADQL query format to find services in which 'Keck' appears in +the Title of the resource: +.nf + + % voregistry "Title like '%Keck%'" + + or + + % cat query.txt + Title like '%Keck%' + % cat query.txt | voregistry + +.fi +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. + +.TP 4 +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: +.nf + + % voregistry --new 3m + % voregistry --new 3m cool stars + % voregistry --updated 12m --count + +.fi + +.SH BUGS +Some services don't repond properly to the metadata query and will print +a "no attributes found" message. +.SH Revision History +June 2007 - This task is new. +.SH Author +Michael Fitzpatrick (fitz@noao.edu), July 2007 +.SH "SEE ALSO" +voclient(1), voclientd(1), vosesame(1), vodata(1) |