idlastro / Web Socket Procedures: QUERYGSC

[Source code]

NAME
QUERYGSC
PURPOSE
Query the Guide Star Catalog (GSC V2.3.2) at STScI by position
EXPLANATION
Uses the IDL SOCKET command to query the GSC 2.3.2 database over the Web.
The number and names of the structure tags was changed in April 2014    
Alternatively, (and more reliably) one can query the GSC 2.3.2 catalog using
queryvizier.pro and the VIZIER database, e.g.  
  IDL> st = queryvizier('GSC2.3',[23,35],10,/all)
GSC2.3 is an all-sky export of calibrated photographic survey plate 
source parameters from the COMPASS database.  The number of unique
objects is approximately 945,592,683.   All sources are 
from the second-generation plate-processing pipeline with the exception
of Tycho-2 and Skymap sources in the case of very bright objects. The 
Skymap sources are exported when there is no matching GSC or Tycho 
sources.  Each GSC 2.3 entry contains only one position and one 
magnitude per bandpass for each unique sky object
CALLING SEQUENCE
info = QueryGSC(targetname_or_coords, [ dis, /HOURS] )
INPUTS
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* (or 
    hours if /HOURS is set) and the target declination in degrees.
OPTIONAL INPUT
dis - Numeric scalar giving search radius in arcminutes to search around 
      specified target    Default is 5 arcminutes
OPTIONAL INPUT KEYWORDS
/BOX - if set, then radius gives  a box width in arcminutes
/HOURS - If set, then the right ascension is both input and output (in
         the info .ra tag) in hours instead of degrees
/VERBOSE - If set, then the CGI command to the Webserver will be displayed
OUTPUTS
info - IDL structure containing information on the GSC stars within the 
       specified distance of the specified center.   There are (currently)
       48 tags in this structure  -- for further information see
       http://gsss.stsci.edu/Catalogs/GSC/GSC2/gsc23/gsc23_release_notes.htm
       .HSTID - GSC 2.3 name for HST operations
       .RA,.DEC - Position in degrees (double precision).   RA is given in
                hours if the /HOURS keyword is set.
       .GSC1ID - GSC1 name
       .RAERR, .DECERR - uncertainty (in arcseconds) in the RA and Dec
       .EPOCH - mean epoch of the observation
       .FPGMAG, .FPGERR, .FPGMAGCODE - mag, error, code in photographic F
       .JPGMAG, .JPGERR, .JPGMAGCODE - mag, error code, photographic J
       .VPGMAG, .VPGERR, .VPGMAGCODE - V mag, error, code
       .NPGMAG, .NPGERR, .NPGMAGCODE - mag, error, code
       .UMAG, .UERR, .UMAGCODE - magnitude, error, code
       .BMAG, .BERR, .BMAGCODE - magnitude, error, code
       .VMAG, .VERR, .VMAGCODE - magnitude, error, code
       .RMAG, .RERR, .RMAGCODE - magnitude, error, code
       .IMAG, .IERR, .IMAGCODE - magnitude, error, code
       .JMAG, .JERR, .JMAGCODE - magnitude, error, code
       .HMAG, .HERR, .HMAGCODE - magnitude, error, code
       .KMAG, .KERR, .KMAGCODE - magnitude, error, code
       .CLASS - classification (0-5): 0-star, 1-galaxy, 2-blend, 
                      3-nonstar, 4-unclassified, 5-defect
       .SOURCESTATUS -10 digit field  used to encode more detailed information 
           about the properties of the catalog object.   For more info, see
ttp//www-gsss.stsci.edu/Catalogs/GSC/GSC2/gsc23/gsc23_release_notes.htm#ClassificationCodes
.SEMIMAJORAXIS - semi-major axis in pixels
.POSITIONANGLE - Position angle of extended objects in degrees
.ECCENTRICITY - eccentricity of extended objects
.STATUS -10 digit field  used to encode more detailed information 
    about the properties of the catalog object.   For more info, see
ttp//www-gsss.stsci.edu/Catalogs/GSC/GSC2/gsc23/gsc23_release_notes.htm#ClassificationCodes
.VARIABLEFLAG, MULTIPLEFLAG - Variability andd multiplicity flags
.DISTANCE - Distance to search center in arcminutes
EXAMPLE
Plot a histogram of the photographic J magnitudes of all GSC 2.3.2 
stars within 10 arcminutes of the center of the globular cluster M13 
IDL> info = querygsc('M13',10)
IDL> plothist,info.jpgmag,xran=[10,20]
PROCEDURES USED
QUERYSIMBAD, RADEC, WEBGET()
MODIFICATION HISTORY
Written by W. Landsman  SSAI  August 2002
Fixed parsing of RA and Dec  W. Landsman September 2002
Major rewrite to use new STScI Web server, remove magrange
  keyword   W. Landsman Dec 2007
Update server name, added /BOX,/ VERBOSE keywords W.L 19 Dec 2007
Web server now also returns infrared data  W.L. Feb 2010
Fixed case where dec neg. and deg or min 0 Pat Fry Jul 2010
Updated for new server format W. Landsman  April 2014