.\" @(#)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)