.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