idlastro / Web Socket Procedures: QUERY_IRSA_CAT

[Source code]

NAME
QUERY_IRSA_CAT
PURPOSE
Query a catalog in the NASA/IPAC Infrared Science Archive (IRSA)
database by position or resolvable target name.
EXPLANATION
Uses the IDL SOCKET command to provide a query of a catalog 
in the IRSA (http://irsa.ipac.caltech.edu/) database over the Web and
return results in an IDL structure.  If outfile is set, it saves
the query as an IPAC table file.  This can be slow for large query
results, so only write a file if needed.    
CALLING SEQUENCE
info = query_irsa_cat(targetname_or_coords, [catalog=catalog,
radius=radius, radunits=radunits, outfile=outfile,
change_null=change_null, /DEBUG])
INPUTS
TARGETNAME_OR_COORDS - Either a string giving a resolvable target
       name (with J2000 coordinates determined by NED or SIMBAD), or a 
       2-element numeric vector giving the J2000 right ascension 
       and declination, both in degrees.
OPTIONAL INPUT
CATALOG - string giving the identifier of the IRSA catalog to be
       searched.  The complete list of catalogs and identifier strings is available in
       XML format at:
         http://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-scan?mode=xml
       or as an IPAC Table (ascii) at:
         http://irsa.ipac.caltech.edu/cgi-bin/Gator/nph-scan?mode=ascii
       In the table, the identifier string is in the "catname" column.
       If this keyword is omitted, the program will query the 2MASS point
       source catalog.
       Examples of current IRSA catalogs include:  
          'wise_allsky_4band_p3as_psd' - WISE All-Sky Source Catalog
          'fp_psc' - 2MASS Point Source Catalog
          'iraspsc' - IRAS Point Source Catalog v2.1 (PSC)
          'irasfsc' - IRAS Faint Source Catalog v2.0
          'cosmos_ib_phot' - COSMOS Intermediate and Broad Band Photometry Catalog 2008
          'akari_irc' - Akari/IRC Point Source Catalogue
RADIUS - scalar input of the radius of the search.  By default it
         has a value of 60 arcsec. IRSA
       catalogs have maximum allowable search radii.  These are listed on the corresponding
       web interface page for the catalog search, or in the nph-scan return table in the
       "coneradius" column.
RADUNITS - string giving the units of the radius.  By default it is 'arcsec'.
OUTFILE - if present, the search results are written to a file with this name.
 CHANGE_NULL - a numeric value (input as integer) to put in the structure if the table uses a string for nulls.  Default is -9999.
DEBUG - /DEBUG provides some additional output.
OUTPUTS
info - Anonymous IDL structure containing information on the catalog.  The structure
       tag names are taken from the catalog column names.  If no objects were found in 
       the catalog, the structure values will be empty or zero.  If any input parameter
       (e.g. catalog name) is invalid, the structure will have no
       content fields other than info.CREATED.
       If the query fails or is invalid, the function returns a value of -1.  
EXAMPLES
(1) Plot a histogram of the J magnitudes of all 2MASS
    point sources within 10 arcminutes of the center of the
    globular cluster M13.  Save the IPAC table. 
  IDL> info = query_irsa_cat('m13',radius=10,radunits='arcmin',outfile='save.tbl')
  IDL> help,/struct,info
  IDL> plothist,info.j_m,xran=[10,20]
(2) Find the position of the faintest IRAS 60 micron
    source within 1 degree of central position of the
    COSMOS survey (10h00m28.6s +02d12m21.0s in J2000)
  IDL> info = query_irsa_cat([150.11917,2.205833], catalog='irasfsc', radius=1, radunits='deg')
  IDL> help,/struct,info
  IDL> idx = where(info.fnu_60 eq min(info.fnu_60))
  IDL> print, (info.ra)[idx], (info.dec)[idx]
PROCEDURES USED
READ_IPAC_VAR  comes with query_irsa_cat.pro
WEBGET(), VALID_NUM  from IDLastro
NOTES
The program writes an output IPAC table file only if the
OUTFILE keyword is set.
MODIFICATION HISTORY
Adapted from queryvizier.pro - H. Teplitz, IPAC  September 2010
Removed requirement of writing/reading IPAC table file -
  T. Brooke, IPAC May 2011
Longer timeout for webget, added change_null - TYB June 2013