diff options
Diffstat (limited to 'vo/doc/registry.hlp')
| -rw-r--r-- | vo/doc/registry.hlp | 426 |
1 files changed, 426 insertions, 0 deletions
diff --git a/vo/doc/registry.hlp b/vo/doc/registry.hlp new file mode 100644 index 00000000..ce246b54 --- /dev/null +++ b/vo/doc/registry.hlp @@ -0,0 +1,426 @@ +.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 |