idlastro / Web Socket Procedures: QUERYVIZIER

[Source code]

NAME
QUERYVIZIER
PURPOSE
Query any catalog in the Vizier database by position
EXPLANATION
Uses the IDL SOCKET command to provide a positional query of any catalog 
in the the Vizier (http://vizier.u-strasbg.fr/) database over the Web and
return results in an IDL structure.    
CALLING SEQUENCE
info = QueryVizier(catalog, targetname_or_coords, [ dis
                   /ALLCOLUMNS, /CFA, CONSTRAINT= ,/VERBOSE ])
INPUTS
CATALOG - Scalar string giving the name of the VIZIER catalog to be
      searched.    The complete list of catalog names is available at
      http://vizier.u-strasbg.fr/vizier/cats/U.htx . 
      Popular VIZIER catalogs include 
      'II/328'- AllWISE Data Release (Cutri+ 2013)
      'V/139' - Sloan SDSS photometric catalog Release 9 (2012)
      '2MASS-PSC' - 2MASS point source catalog (2003)
      'GSC2.3' - Version 2.3.2 of the HST Guide Star Catalog (2006)
      'USNO-B1' - Verson B1 of the US Naval Observatory catalog (2003)
      'UCAC5'  - 5th U.S. Naval Observatory CCD Astrograph Catalog (2017)
      'B/DENIS/DENIS' - 2nd Deep Near Infrared Survey of southern Sky (2005)
      'I/337/gaia' - Gaia DR1 Data Release 1 (2016)
      'I/311/HIP2' - Hipparcos main catalog, new reduction (2007)
    Note that some names will prompt a search of multiple catalogs
    and QUERYVIZIER will only return the result of the first search.
    Thus, setting catalog to "HIP2" will search all catalogs 
    associated with the Hipparcos mission, and return results for the
    first catalog found.    To specifically search the Hipparcos or
    Tycho main catalogs use the VIZIER catalog names listed above
TARGETNAME_OR_COORDS - Either a scalar string giving a target name, 
    (with J2000 coordinates determined by SIMBAD), or a 2-element
    numeric vector giving the J2000 right ascension in *degrees* and 
    the target declination in degrees.
    If the targetname is set to 'NONE' then QUERYVIZIER will perform
    an all-sky search using the constraints given in the CONSTRAINT
    keyword.   
OPTIONAL INPUT
dis - scalar or 2-element vector.   If one value is supplied then this
      is the search radius in arcminutes.     If two values are supplied
      then this is the width (i.e., in longitude direction) and height
      of the search box.   Default is a radius search with radius of
      5 arcminutes
OUTPUTS
info - Anonymous IDL structure containing information on the catalog  
       sources within the specified distance of the specified center.  The 
       structure tag names are identical with the VIZIER  catalog column 
       names, with the exception of an occasional underscore
       addition, if necessary to convert the column name to a valid 
       structure tag.    The VIZIER Web  page should consulted for the 
       column names and their meaning for each particular catalog..
       If the tagname is numeric and the catalog field is blank then either
       NaN  (if floating) or -1 (if integer) is placed in the tag.
       If no sources are found within the specified radius, or an
       error occurs in the query then -1 is returned. 
OPTIONAL KEYWORDS
/ALLCOLUMNS - if set, then all columns for the catalog are returned
       The default is to return a smaller VIZIER default set. 
/CFA - By default, the query is sent to the main VIZIER site in
  Strasbourg, France.   If /CFA is set then the VIZIER site
  at the Harvard Center for Astrophysics (CFA) is used instead.
  Note that not all Vizier sites have the option to return
  tab-separated values (TSV) which is required by this program.
CONSTRAINT - string giving additional nonpositional numeric 
  constraints on the entries to be selected.     For example, when 
  in the GSC2.3  catalog, to only select sources with Rmag < 16 set 
  Constraint = 'Rmag<16'.    Multiple constraints can be 
  separated by commas.    Use '!=' for "not equal", '<=' for smaller
  or equal, ">=" for greater than or equal.  See the complete list
  of operators at  
       http://vizier.u-strasbg.fr/doc/asu.html#AnnexQual
  For this keyword only, **THE COLUMN NAME IS CASE SENSITIVE** and 
  must be written exactly as displayed on the VIZIER Web page.  
  Thus for the GSC2.3 catalog one must use 'Rmag' and not 'rmag' or
  'RMAG'.    In addition, *DO NOT INCLUDE ANY BLANK SPACE* unless it 
  is a necessary part of the query.
 /SILENT - If set, then no message will be displayed if no sources
      are found.    Error messages are still displayed.
 /VERBOSE - If set then the query sent to the VIZIER site is
     displayed, along with the returned title(s) of found catalog(s)
EXAMPLES
(1) Plot a histogram of the J magnitudes of all 2MASS point sources 
stars within 10 arcminutes of the center of the globular cluster M13 
IDL>  info = queryvizier('2MASS-PSC','m13',10)
IDL> plothist,info.jmag,xran=[10,20]
(2)  Find the brightest J mag GSC2.3 source within 3' of the 
     J2000 position ra = 10:12:34, dec = -23:34:35
IDL> str = queryvizier('GSC2.3',[ten(10,12,34)*15,ten(-23,34,35)],3)
IDL> print,min(str.jmag,/NAN)
(3) Find sources with V < 19 in the Magellanic Clouds Photometric 
    Survey (Zaritsky+, 2002) within 5 arc minutes of  the position 
    00:47:34 -73:06:27
    Checking the VIZIER Web page we find that this catalog is
IDL>  catname =  'J/AJ/123/855/table1'
IDL>  ra = ten(0,47,34)*15 & dec = ten(-73,6,27)
IDL> str = queryvizier(catname, [ra,dec], 5, constra='Vmag<19')
(4) Perform an all-sky search of the Tycho-2 catalog for stars with
    BTmag = 13+/-0.1
DL> str = queryvizier('I/259/TYC2','NONE',constrain='BTmag=13+/-0.1')
PROCEDURES USED
GETTOK(), REMCHAR, REPSTR(), STRCOMPRESS2(), ZPARCHECK
TO DO
(1) Allow specification of output sorting
MODIFICATION HISTORY
Written by W. Landsman  SSAI  October 2003
Added /SILENT keyword  W.L.  Jan 2009
Avoid error if output columns but not data returned W.L. Mar 2010
Ignore vector tags (e.g. SED spectra) W.L.   April 2011
Better checking when more than one catalog returned W.L. June 2012
Assume since IDL V6.4 W.L. Aug 2013
Update HTTP syntax for /CANADA    W. L.  Feb 2014
Add CFA keyword, remove /CANADA keyword  W.L. Oct 2014
Use IDLnetURL instead of Socket   W.L.    October 2014
Add Catch, fix problem with /AllColumns W.L. September 2016
Update Strasbourg Web address  W.L. April 2017