;+
; NAME:
;  oc_scat
;
; PURPOSE: (one line)
;  call scat (Doug Mink) using spawn and report results
;
; DESCRIPTION:
;  call scat (Doug Mink) using spawn and report results
;
; CATEGORY:
;  Star catalogs.
;  
; CALLING SEQUENCE: 
;  ids = oc_scat(RA, DEC, RADIUS, NSTARS, catalog [, /VERBOSE] )
;
; INPUTS:
;  RA     -- Right ascension of center of search position.  Radians, J2000.
;  DEC    -- Declination     of center of search position.  Radians, J2000.
;  RADIUS -- Search radius.  Radians. 
;  NAME_CATALOG -- string.  Name of the catalog (as expected by scat)
;                   act, gsc, ua2, usa2, or local file
;
;  Inputs are single values, not arrays.
;
; OPTIONAL INPUT PARAMETERS:
;  None
;
; KEYWORD INPUT PARAMETERS:
;  /VERBOSE -- If set, print error messages to screen.
;
; OUTPUTS:
;  ids -- Array of star ids found by scat (strings)
;  NSTARS -- Number of stars found
;  
; KEYWORD OUTPUT PARAMETERS:
;  command -- the command called by spawn (string)
;  scat -- the lines returned by scat (array of strings)
;  
;
; COMMON BLOCKS:
;  None
;
; SIDE EFFECTS:
;  None
;
; RESTRICTIONS:
;  
;  This calls scat using spawn. Therefore, this 
;  (1) only runs on unix operating systems and
;  (2) must have scat installed.  
;     http://tdc-www.harvard.edu/software/wcstools/index.html
;  (3) The proper environment variable must be set for the catalog called.
;     $TY2_PATH   -- For Tycho-2 catalog
;     $WCS_CATDIR -- For HD and other WCS-based catalogs
;     $UCAC2_PATH -- For UCAC2 catalog
;     $TMC_PATH -- For 2MASS catalog
;     This can be done prior to the call with (eg)
;     setenv,'TY2_PATH=/Users/layoung/reference/stellar_cat/TYCHO2'
;
; EXAMPLE:
;  print, getenv('WCS_CATDIR')
;  ids = oc_scat(0.5, 0.5, 0.01, 'hd/catalog.wcs.dat', nstars)
;  help, ids, nstars
;  print, ids
;  
; 
; MODIFICATION HISTORY:
;  Written  02-Jul-2006 by Leslie Young, SwRI, based on oc_search_pos_fullcat
;-

function oc_scat, ra, dec, radius, name_catalog, nstars, VERBOSE=verbose, $
                  command = command, scat=scat, nstars_max = nstars_max

;    d2r		= 2.*!dpi / 360d
;    r2d		= 1./d2r
;    d2as	= 60d*60d
    
    deg = !dpi/180.
    arcsec = deg/3600.d

    if not keyword_set(nstars_max) then $
	    nstars_max	= 10L       ; Maximum number of stars

    ; Loop through calls to oc_scat, increasing the 
    ; number of nstars_max until the number returned is
    ; less than the number asked for.

    repeat begin

        nstars_max = nstars_max * 100L

; Construct the command

        command	= 'scat ' + $ 
; Catalog name
        ' -c ' + name_catalog + $			
; Search radius in arcsec
        ' -r ' + string(radius/arcsec,format='(F20.5)') + $	
; Output in Degrees (not hms)
        ' -d' + $				
; Tab-delimited columns (also adds 11 lines of header info)
        ' -t' + $				
; J2000
        ' -j' + $				
; Max number returned
        ' -n ' + st(nstars_max) + $		
		  ' '    + string(ra/deg,format='(F19.12)') + $
          ' ' + string(dec/deg,format='(F19.12)') + ' j2000'
        
        
                                ; Execute the command and return output to array 'scat'

        if keyword_set(VERBOSE) then print, 'Executing command: ' + command
        spawn, command, scat

; Figure out how many stars, and how many header lines we have here We do this
; by counting back from the '---' marker on scat's output.  This works for TY2
; and HD catalogs with -t flag, but should be verified for new catalogs!  Scat
; does not directly return the number of stars -- it must be inferred from the
; output.
;
; If there is an error (as opposed to no stars found), there will be
; no '---', where(grep()) will return -1, and lines_header = 0.
; In this case, there are no good lines, and lines_header should equal
; the total number of lines

        lines_header	= max(where(grep(scat, '---'))) + 1
        if lines_header eq 0 then lines_header = n_elements(scat)

; Figure out how many header lines we have 
        nstars	= n_elements(scat) - lines_header

        if keyword_set(VERBOSE) then print, $
          'Found ' + st(nstars) + ' matching stars'

    endrep until nstars lt nstars_max

; If none found, then return

  if (nstars le 0) then return, -1

; If stars found, then prepare to read them in

  scat_chop	= scat[lines_header:*]


; Parse and store the scat output
; Scat will not return output with fixed column locations; therefore, IDL's
; FORMAT= routines do not work.  We therefore use tab-delimited output, and
; split on tabs, which prevents problems with ID's containing spaces.

  char_tab	= string(9B)

  ids		= strarr(nstars)

  for i = 0L, nstars-1 do begin
    ids[i]	= (ht_str_split(scat_chop[i], char=char_tab))[0]
  end

  return, ids

end