;+
; NAME:
;  oc_getline_sao
;
; PURPOSE: (one line)
;  Return the raw catalog line from SAO catalog for a given ID or IDs.
;
; DESCRIPTION:
;  Return the raw catalog line from SAO catalog for a given ID or IDs.
;  The catalog line is a single line of text which is human-readable,
;  although it must be carefully interpreted.
;
; This routine searches through the catalog using grep.  For small catalogs
; like this, grep is fast enough.
; 
;
; CATEGORY:
;  Star catalogs
;  
; CALLING SEQUENCE:
;  lines = oc_getline_sao( ids [, NSTARS=nstars] [, /VERBOSE])
;
; INPUTS:
;  IDs -- A list of SAO ID's.  Scalar or vector.
;   IDs must be in SAO format and are recommended to be strings, rather
;   than numerical values, due to precision and wraparound.
;
; OPTIONAL INPUT PARAMETERS:
;  None
;  
; KEYWORD INPUT PARAMETERS:
;  /VERBOSE -- If set, print diagnostics to screen.
;
; KEYWORD OUTPUT PARAMETERS:
;  NSTARS -- Returns the number of successfully-retrieved lines.
;
; OUTPUTS:
;  If input is a scalar, then output is a single string.
;  If input is a vector, then output is an array of strings.
;  If a star is not found, returned value is ''.
;  
; COMMON BLOCKS:
;  None
;
; SIDE EFFECTS:
;  None
;
; RESTRICTIONS:
;  SAO catalog must be available at $WCS_CATDIR/sao/catalog.dat .
;
; EXAMPLE:
;  print, oc_getline_sao(['430', '1000'])
; 
; MODIFICATION HISTORY:
;  Written   2-Nov-2005 by Henry Throop, SwRI
;  Modified 27-Feb-2006 by HBT. Improved documentation and formatting.
;  Modified 05-Mar-2006 by LAY. Change nstars to count (consistent
;                               with oc_getline_ucac2)
;  Modified 15-Mar-2006 by HBT. Undid LAY's nstars change (hah!), 
;                               as it already was consistent w/ ucac2.
;
;-
function oc_getline_sao, ids, NSTARS=nstars, VERBOSE=verbose

  catalog	= 'sao/sao.dat'
  path_catalog	= getenv('WCS_CATDIR')

  nstars	= 0
  num_ids 	= sizex(ids)
  lines		= strarr(num_ids)

  linelen = 205L  ; characters per line
  nlines = 258997L

  openr, lun, path_catalog + '/' + catalog, /get_lun
  allines = assoc(lun, bytarr(linelen))

  ; convert all the ids to long
  type = datatype(ids[0])
  case type of
      'INT': id_long = long(ids)
      'BYT': id_long = long(ids)
      'LON': id_long = ids
      'UIN': id_long = long(ids)
      'ULO': id_long = long(ids)
      'L64': id_long = long(ids)
      'U64': id_long = long(ids)

      'FLO': id_long = floor(ids)
      'DOU': id_long = floor(ids)
      'COM': id_long = floor(float(ids))

      'STR': begin
          id_long = replicate(-1L, num_ids)
          for i=0L,num_ids-1 do begin
              if strnumber(ids[i]) then id_long[i] = long(ids[i])
          end
      end
      else: begin
          id_long = replicate(-1L, num_ids)
          if (keyword_set(VERBOSE)) then begin
              print, 'oc_getline_sao: ids must be numbers or strings'
          endif
      endelse
  endcase

  for i = 0L, num_ids-1 do begin
      id = id_long[i]
    
      if (id gt nlines or id lt 1) then begin
          if (keyword_set(VERBOSE)) then begin
              print, 'oc_getline_sao: star ', ids[i], $
                ' not found in SAO catalog'
              line	= ''
          endif
      endif else begin
        
; If line is found, incrememnt coounter
          
          nstars = nstars + 1
          lines[i]	= string(allines[id - 1])
      endelse
  endfor
; Return argument in the same form as passed in

  if     is_array(ids)  then return, lines
  if not(is_array(ids)) then return, lines[0]

end