;+
; NAME:
;  oc_getline_tyc2_hd
;
; PURPOSE: (one line)
;  Return raw catalog line from TYC2<->HD conversion catalog. 
;
; DESCRIPTION:
;  Return raw catalog line from TYC2<->HD conversion catalog, given 
;  TYC2 or HD ID(s).
;
;  This routine does not do the matching; it only retrieves 
;  raw lines from the conversion catalog.  It is called by
;  oc_getrec_tyc2_hd.pro, which is the end-user routine.
; 
;  The catalog is Vizier IV/25, Fabricius et al 2002.
;
; CATEGORY:
;  Category
;  
; CALLING SEQUENCE:
;  lines = oc_getline_tyc2_hd( {HD=hd | TYC2=tyc2} [, NTH=nth], $
;                               [, NSTARS=nstars]  [, /VERBOSE]
;
; INPUTS:
;  HD   = hd    -- Either HD= *or* TYC2= must be passed.  Each is an ID 
;  TYC2 = tyc2     or array of ID's, in the standard format for that catalog.
;
; OPTIONAL INPUT PARAMETERS:
;  NTH -- Return the nth possible match for each star, if possible; if not,
;         return a lower match.  E.g., there may be 2 TYC2 stars for 1 HD ID.
;         Setting NTH=0 will return the first match for this star and
;         NTH=1 with return the second match to the star.  For stars
;         on which there is only one match, it will return the single
;         match.
;  
;  /VERBOSE -- If set, print diagnostics to screen.
;
; KEYWORD INPUT PARAMETERS:
;  None
;
; KEYWORD OUTPUT PARAMETERS:
;  NSTARS -- Returns the number of successfully-retrieved lines.
;
; OUTPUTS:
;  String or array of strings.  Same dimensions as input ID, regardless of
;  multiple matches or non-matches.
;
;  If HD=   is passed for input, returned values are for Tycho-2 stars.
;  If TYC2= is passed for input, returned values are for HD stars.
;
;  If a star has no match, an empty string is returned for that element.
;  
; COMMON BLOCKS:
;  None
;
; SIDE EFFECTS:
;  None
;
; RESTRICTIONS:
;  Tycho2-HD catalog must exist at $WCS_CATDIR/tyc2_hd/tyc2_hd.dat .
;
; EXAMPLE:
;  print, oc_getline_tyc2_hd(HD=[0,1,10,100,1000,10000d], nstars=nstars, /VER)
;   [Returns 5 matches and one non-match, setting nstars=5]
; 
; MODIFICATION HISTORY:
;  Written   3-Nov-2005 by Henry Throop, SwRI.
;  Modified  7-Dec-2005 by HBT.  Improved multiple- and non-match handling.
;  Modified 27-Feb-2006 by HBT.  Improved documentation and formatting.
;  Modified  7-Mar-2006 by LAY.  Fixed bug in indexing line for nth>lines-1
;                                and changed documentation to reflect nth=0..lines-1
;  Modified 14-Apr-2006 by Leslie Young. Made loop index long.
;-

function oc_getline_tyc2_hd, HD=hd, TYC2=tyc2, NSTARS=nstars, $
  VERBOSE=verbose, NTH=nth

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

; Default to returning the 0th matching star if multiple stars match

  if not(keyword_exists(NTH)) then nth = 0

; First check that we have exactly one catalog name passed

  if (keyword_set(HD) + keyword_set(TYC2)) ne 1 then begin
    print, 'Error: oc_getline_tyc2_hd(): Must supply either TYC2 or HD ID''s'
    stop
  end

;;;;;; If HD is set, look up the TYC2 stars which match this HD

  if keyword_set(HD) then begin
    nstars	= 0
    ids		= hd
    num_ids	= sizex(ids)
    lines	= strarr(num_ids)

    for i = 0L, num_ids-1 do begin
  
      id	= ids[i]
      id_string	= '^..............' + string(id, format='(I6)')
      spawn, /NOSHELL, ['grep', id_string, path_catalog + '/' + catalog], line

; If a line matches, then process it

      if (line[0] ne '') then begin			 		
        nstars = nstars + 1

; Number of tyc2 stars for this HD

	n_tyc	= strmid(line[0], 27,1)					
	if (n_tyc eq 1) then line = line[0]

; Return only one matching star, not more

	if (n_tyc gt 1) then line = line[nth < (sizex(line)-1)]		
        if (n_tyc gt 1) and (keyword_set(VERBOSE)) then print, $
	 'Warning: HD ' + st(id) + ' has multiple matches in tyc2_hd catalog.'
      end
      if (line eq '') and (keyword_set(VERBOSE)) then print, $
         'Error: HD ' + st(id) + ' not found in tyc2_hd catalog'
      lines[i]	= line
    end
  end

;;;;;; If TYC2 is set, look up the HD stars which match this TYC2

  if keyword_set(TYC2) then begin
    nstars	= 0
    ids		= tyc2
    num_ids	= sizex(ids)
    lines	= strarr(num_ids)

    for i = 0L, num_ids-1 do begin

      id	= ids[i]
      id	= oc_convertid_float_tyc2(oc_convertid_tyc2_float(id,$
        VERBOSE=verbose), char=' ', /SHORT, VERBOSE=verbose)
      id_string	= '^' + id
      spawn, /NOSHELL, ['grep', id_string, path_catalog + '/' + catalog], $
        line
      if (line[0] ne '') then begin
        nstars = nstars + 1

; Number of HD stars for this tyc2

	n_hd	= strmid(line[0], 25,1)					
	if (n_hd eq 1) then line = line[0]

; Return only one matching star, not more

	if (n_hd gt 1) then line = line[nth < (sizex(line)-1)]		
        if (n_hd gt 1) and (keyword_set(VERBOSE)) then print, $
	  'Warning: TYC2 ' + id + ' has multiple matches in tyc2_hd catalog.'
      end
      if (line eq '') and (keyword_set(VERBOSE)) then print, $
          'Error: TYC2 ' + id + ' not found in tyc2_hd catalog'
      lines[i]	= line
    end
  end

; 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]

  return, lines
end