From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001
From: Joe Hunkeler <jhunkeler@gmail.com>
Date: Tue, 11 Aug 2015 16:51:37 -0400
Subject: Repatch (from linux) of OSX IRAF

---
 vo/doc/registry.hlp | 426 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 426 insertions(+)
 create mode 100644 vo/doc/registry.hlp

(limited to 'vo/doc/registry.hlp')

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
-- 
cgit 

