path: root/vo/doc/registry.hlp

.help registry Aug06 nvo
.ih
NAME
registry -- Browse the NVO Registry of data and services
.ih
USAGE
registry query
.ih
PARAMETERS
.ls query
A space separated list of keywords used to query the Registry.  The query
requires that all keywords in the list be present in Title, Subject or
Description fields of the resource record.
.le
.ls svc_type = ""
Constrain the results to this particular service type.  The value may 
be any string (or substring) found in the 'ServiceType' field of a resource.
.le
.ls bandpass = ""
Constrain the results to this particular bandpass coverage.  The value may 
be any string (or substring) found in the 'CoverageSpectral' field of a
resource.  
.le
.ls content = ""
Constrain the results to this particular content level description.  The
value may be any string (or substring) found in the 'ContentLevel' field of a
resource.  
.le
.ls sql = ""
An optional sql predicate string that will be combined with any keyword
query formed by the \fBquery\fR parameter.  Defining this predicate allows
the user to constrain the results based on a specified field in the resource.
.le
.ls fields = "Title,Subject,CoverageSpectral"
The list of fields to be returned with all records in a verbose result.
.le
.ls header = yes
Print a header summarizing the query and constraints?
.le
.ls verbose = no
Print verbose output?  In all cases each result will contain the record number,
the ShortName field, the ServiceType field and the Identifier field of the
resource record.   If the verbose parameter is set, the fields listed by the
\fBfields\fR parameter will also be listed for each record.
.le
.ls interactive = no
Drop into an interactive command loop once the query has finished?  This 
command loop allows the user to repeatedly return to the result table, 
browsing individual records in greater detail and summarizing the entire
result again before moving on.
.le
.ls record = -1
Print the full resource record for this record number.  If less than zero
the query is performed and all results are printed.  If equal to zero, the
results obtained from the most recent query are printed using the result
handled saved int he \fBqres\fR parameter.  Values greater than zero will
print the entire record for that resource.
.le
.ls metadata = no
If enabled, this will cause the task to list the metadata field available
in the Registry and quit.
.le

.ls qres = 0
The saved query response handle passed back by the VO Client from the most
recent query.  Within a given CL-VOClient pairing this object should remain
valid and can be either passed to another application for use or will be 
used internally when re-requesting a specific record from a new invocation
of the task.
.le
.ls qcount = 0
The saved number of results from the query.
.le
.ls qstring = ""
The saved keyword query string.
.le
.ls qbandpass = ""
The saved spectral coverage constraint string.
.le
.ls qcontent = ""
The saved content level constraint string.
.le
.ls qsvc = ""
The saved service-type constraint string.
.le
.ls qsql = ""
The saved sql predicate constraint string.
.le
.ls status = ""
Status return code of the web service (output).
.le

.ih
DESCRIPTION

The \fBREGISTRY\fR task provides a simple command-line based browser of 
the NVO Registry of data and services.  It is a script task built around
new VO-CL builtin functions for doing simple Registry queries.

The default query is based on a keyword search of the whitespace-delimited
words in the \fBquery\fR parameter.  Results may be further constrained by
defining the \fBsvc_type\fR, \fBbandpass\fR, \fBcontent\fR and \fBsql\fR
parameters described above.  If the \fBverbose\fR parameter is set the 
the metadata fields listed in the \fBfields\fR parameter will follow the
one-line summary of each resource found.  This summary contains a record
number, the 'ShortName', 'ServiceType', and 'Identifier' metadata fields
of each resource.

Calling the task a second time with a null search term and the \fBrecord\fR
parameter will print all available information on that record.  A record
number of zero will reprint the summary table of results.  A list of the
available metadata fields is printed by setting the \fBmetadata\fR parameter.
If the \fBinteractiv\fR parameter is set the task will drop into a command
loop following the query, a summary of the available commands may be found
below.

.ih
REGISTRY METADATA FIELDS

The \fBREGISTRY\fR task is presently implemented such that it is somewhat
specific to the NVO Registry hosted at JHU/STScI 
(http://nvo.stsci.edu/VORegistry/index.aspx or 
http://voservices.net/registry/index.aspx)  An upgrade to the standard
IVOA Registry interface is planned, however despite interface differences
the contents of the Registry will be largely the same.  We mention this 
since the metadata fields described here are likely to change in future 
versions.

The current Registry interface may be queried for the following columns 
to be returned when part of the \fBfields\fR parameter:

.nf
  String-Valued Fields:

     Title                Resource title (long version)
     Name                 (alias for Title)

     Description          Text description of resource
     Facility             Facility used to create the data
     Identifier           Standard ivo identifier of resource
     ContentLevel         Content Level (Research, educational, etc)
     Contributor          Entity responsible for creating service
     CoverageSpatial      Spatial coverage (STC)
     CoverageSpectral     Spectral coverage (csv list of bandpasses)
     ContentLevel         Content level (research, EPO, etc -- csv list)
     CoverageTemporal     Temporal coverage of data
     Creator              Entity responsible for creating the data
     Instrument           Instrument used to collect the data
     ReferenceURL         URL to reference about Resource
     ResourceType         Type of Service (Cone, Siap, etc)
     ServiceType          (alias for ResourceType)
     ServiceURL           Service URL (if appropriate)
     ShortName            Short name of Resource
     Subject              Subject keywords
     Type                 Resource Type (catalog, survey, etc)
     Version              Data Version

  Real-Valued Fields:

     MaxSR                Maximum search radius

  Integer-Valued Fields:

     MaxRecords           Maximum records returned by the service
.fi


.ih
SQL PREDICATES

The \fBsql\fR parameter may contain a valid sql predicate to be used as 
part of the search.  Unlike the \fBfields\fR parameter, this string is
specific to the Registry being queried and queries are formed using the
actual table column names and not the more abstract metadata fields described
above.

A full list of the column names supported by the JHU/STScI Registry is 
available at

.nf
	http://nvo.stsci.edu/voregistry/ListColumns.aspx
or	http://voservices.net/Registry/ListColumns.aspx

.fi

Sql predicates can be used to search by columns not constrained by this
particular task interface, or to further constrain a search.  For example,
to search for all resources who'd Creator is 'Smith' the task may be called
as

.nf
    cl> registry "" sql="CurationCreatorName like '%Smith%'"
.fi

In this case we do not specify a keyword query and rely on the sql string
completely.  The 'CurationCreatorName' is the column name we found from the
above URL, the '%' metacharacter matches all characters meaning we don't
need an explicit match.


.ih
COMMAND SUMMARY

If the \fBinterfactive\fR parameter is enabled the task will perform the 
requested query and then drop into a command loop supporting the following
keystroke commands:

.nf
	?	Print a usage summary
	r	Print detailed record (recnum will be prompted for)
	s	Print a summary list of results
	v	Enable the verbose flag
	q	Quit the command loop
.fi

.ih
ALTERNATIVE CL REGISTRY ACCESS

A programmatic interface to the Registry is also available in the CL
in the form of new builtin functions to the VO-CL.  (The \fBREGISTRY\fR
task itself is a CL script using this interface.)

The new functions will either directly return to the query result (high-level
access), or will return a "handle" that must be passed to other routines
to access that same result again in the VO Client (low-level access).  In
some cases the functions are overloaded and will accept more than one form 
of argument list (see below).

.nf

  High-Level Registry Query:

        str = regResolver (idstring [, svctype [, attr [, index]]])
         N = regNResolved ()

  Low-Level Registry Query:

     resource = regSearch (sql)
     resource = regSearch (keywords, orValues)
     resource = regSearch (sql, keywords, orValues)

  resource = regSvcSearch (svcType, searchTerm, orValues)

      count = regResCount (resource)
           str = regValue (resource, attr_list, resIndex)
.fi

.ls str = regResolver (idstring [, svctype [, attr [, index]]])

Resolve the given \fBidstring\fR to the attribute named by the \fBattr\fR
argument.  The \fBidstring\fR may be either the ShortName or Identifier
field of a resource record and is not required to be an exact match.  In
the case of multiple results, an exact match will be returned if found 
otherwise the first match found in the record is used.

The query may be refined further by defining a \fBsvctype\fR 2nd argument.
This argument is not required and is allowed to be a null string.

Unless otherwise specified, the default \fBattr\fR attribute returned is
the ServiceURL.  The \fBattr\fR may be a comma-delimited list of metadata
fields in which case the returned string will contain all requested attributes.

If no \fBindex\fR is specified, the first matching record will be returned.
In the case of multiple results, the index may be used to loop through the
results but note that each time regResolver is called a new query is generated.
When looping through multiple results, use of the low-level interface is
preferred since the query will only be done once on the Registry, subsequent
calls are made only to the VO Client interface.  A negative index will cause
the routine to return all matching records in the result string, one record
per line.
.le
.ls count = regNResolved ()

Return the number of records resolved by the last regResolver() query.  Will
return -1 if an error occurred, 0 if no records found, 1 for a unique 
resolution, otherwise >1 if multiple records were found.
.le

.ls resource = regSearch (sql)

Perform a registry query using the given sql predicate string.

Return a \fBresource\fR handle needed by other routines for accessing the
query result.
.le
.ls resource = regSearch (keywords, orValues)

Perform a registry query using a whitespace-delimited list of keywords.
The \fBorValues\fR boolean value is used to determine
whether all or only one of the given keywords are required for a match.

Return a \fBresource\fR handle needed by other routines for accessing the
query result.
.le
.ls resource = regSearch (sql, keyword, orValues)

Perform a registry query using an sql predicate string AND a
 whitespace-delimited list of keywords.
The \fBorValues\fR boolean value is used to determine
whether all or only one of the given keywords are required for a match.

Return a \fBresource\fR handle needed by other routines for accessing the
query result.
.le
.ls resource = regSvcSearch (svc, searchTerm, orValues)

Do a Registry query constrained to the type of service defined by the 
\fBsvc\fR argument (e.g. 'cone', 'siap', etc).  The \fBsearchTerm\fR may be
either a whitespace-delimited list of keywords or an SQL predicate.  In the
case of a keyword list the \fBorValues\fR boolean value is used to determine
whether all or only one of the given keywords are required for a match.

Return a \fBresource\fR handle needed by other routines for accessing the
query result.
.le
.ls resource = regResCount (resource)

Returns a count of the number of records in the \fBresource\fR handle.
.le
.ls str = regValue (resource, attr_list, resIndex)

Return a string containing the requested metadata fields in the \fBattr_list\fR
argument from the query \fBresource\fR at record number \fBresIndex\fR (zero
indexed).  A negative \fBresIndex\fR value will return all results, one per
line.
.le

Examples using this interface are given below.


.ih
EXAMPLES
1.  Find all Cone services registered as offering X-Ray catalogs, include
the Title and Subject of each resource printed:

.nf
    cl> registry "" svc=cone bandpass=x-ray verb+
.fi

Following the previous query:

.nf
    cl> registry rec=170 		    # details of record #170
    cl> registry rec=0 | page		    # to page the summary list
    cl> registry rec=0 header- | sort col=2 # to sort by ShortName 
.fi


2.  Find all resources containing the object NGC188 in the resource entry:

.nf
    cl> registry "ngc 188"
    cl> registry "ngc 188" svc=tabular		# for VizieR tables only
.fi

3.  Find all resources about "active galaxies":

.nf
    cl> registry "active galaxies"		# 186 results
    cl> registry "active galaxy"		#  55 results
.fi

Note we get a different number of results depending on whether the plural is
used.  Keyword queries are assumed to be substrings and so the phrase
"active galax" would match both 'galaxy' and 'galaxies' in the record.


4.  Use the CL interface to find all GSC2.2 catalog services:

.nf
    cl> print (regResolver("GSC2.2","","ServiceType,Identifier",-1))
    CONE    ivo://archive.stsci.edu/gsc/gsc2.2
    CONE    http://vizier.u-strasbg.fr/GSC2

    Since there is more than one cone service, call it by resolving the 
    identifier for the desired service on the fly:

    cl> cone regResolver("ivo://archive.stsci.edu/gsc/gsc2.2") \
    >>>       12:34:56.7 76:54:32.1 0.10

    Because we resolved the identifier, we didn't need to further 
    constraint the query.  The default gives us the ServiceURL we
    wished to pass to the CONECALLER task.
.fi


5.  Find all 2MASS catalog services currently registered:

.nf
    cl> registry 2mass
    #
    #  Found 7 records
    #
    #  Registry Query Constraints:
    #         Query Term: '2mass'
    #        ServiceType:  cone
    #
    #No  ShortName      SvcType  Identifier
    #--  ---------      -------  ----------
    #
      1  2MASS-PSC(CDS) CONE     http://vizier.u-strasbg.fr/2MASS
      2  NOMAD          CONE     ivo://fs.usno/cat/nomad
      3  BMWHRICAT      CONE     ivo://nasa.heasarc/bmwhricat
      4  NED(sources)   CONE     ivo://ned.ipac/Basic_Data_Near_Pos...
      5  2MASS-XSC      CONE     ivo://irsa.ipac/2MASS-XSC
      6  2MASS-PSC      CONE     ivo://irsa.ipac/2MASS-PSC
      7  BHRFSCID       CONE     ivo://nasa.heasarc/bhrfscid
.fi

Note that the ShortName is not guaranteed to be unique, here we have 
'2MASS-PSC(CDS)' and '2MASS-PSC' as mirrors of the same data source.  If 
we use the regResolver() CL builtin to find the ServiceUrl using only the
string '2MASS-PSC' we would actually get the CDS service since it appears
first in the list.  When a specific service is desired it is best to use
the Identifier string when resolving to a ServiceURL.  One common use of
the REGISTRY task will be in quickly locating data of a particular type
(e.g. HST image services), and using the ShortName/Identifier to call the
data access services with a specific query.

.ih
REVISIONS

.ih
SEE ALSO
voclient, conecaller, siapcaller, vizier
.endhelp