;+
; NAME:
;  oc_getline_tyc2
;
; PURPOSE: (one line)
;  Return the raw catalog line from TYC2 catalog for a given ID or IDs.
;
; DESCRIPTION:
;  Return the raw catalog line from TYC2 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.
;
;  Because the TYC2 catalog is quite long (2M entries, 200M bytes), it is
;  inefficient to read the whole thing in, or grep through it.  Instead, we
;  use associative arrays to read individual arbitrary lines.
;
; CATEGORY:
;  Star catalogs
;  
; CALLING SEQUENCE:
;  lines = oc_getline_tyc2( ids [, NSTARS=nstars] [, /VERBOSE])
;
; INPUTS:
;  IDs -- A list of TYC2 ID's.  Scalar or vector.  String.
;   IDs must be in standard TYC2 format.
;
; OPTIONAL INPUT PARAMETERS:
;  None
;  
; KEYWORD INPUT PARAMETERS:
;  None
;
; KEYWORD OUTPUT PARAMETERS:
;  NSTARS -- Returns the number of successfully-retrieved lines.
;  /VERBOSE -- If set, print diagnostics to screen.
;
; 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:
;  Tycho-2 catalog must be available at $WCS_CATDIR/tyc2/catalog.dat .
;
; EXAMPLE:
;  lines = oc_getline_tyc2(['9537 03881', '000100017', '1-22'], nstars=nstars)
;    [Reads in two valid stars and one invalid one, and sets NSTARS=2]
;
; MODIFICATION HISTORY:
;  Written   1-Nov-2005 by Henry Throop, SwRI
;  Modified 27-Feb-2006 by HBT. Improved documentation and formatting.
;  Modified  7-Mar-2006 by LAY. Changed getenv to be consistent with scat
;-
function oc_getline_tyc2, ids, NSTARS=nstars, VERBOSE=verbose

; First set up the catalog specifics 

;  catalog	= 'tyc2/catalog.dat'
;  path_catalog	= getenv('WCS_CATDIR')
  catalog	= 'data/catalog.dat'
  path_catalog	= getenv('TY2_PATH')

; Number of lines in catalog
  num_lines_tyc2	= 2539913d			
; Number of bytes per line (including CR)
  bytes_per_line_tyc2	= 207				
; Number of bytes that the ID takes
  bytes_per_id_tyc2	= 10				

  num_lines_cat		= num_lines_tyc2

; Open the catalog.  We use an associative array, rather than reading the
; entire catalog in.  oc_getstar_hd.pro used grep to get individual lines;
; that is inefficient here.

  openr, lun, path_catalog + '/' + catalog, /get_lun

; Assoc array is allowed to be of type byte, but not string

  lines	= assoc(lun, bytarr(bytes_per_line_tyc2))	

  num_ids	= sizex(ids)
  lines_out	= strarr(num_ids)

; Number of successfully found lines
  nstars		= 0					

; Process the ID numbers.  We convert them into a floating-point number which
; is the concatenation of the first and second components, and we ignore the
; third component.

  for i = 0, num_ids-1 do begin
    id		= ids[i]
    id		= oc_convertid_tyc2_float(ids[i])

; Set up parameters for the search

    done	= 0
    start 	= long(num_lines_cat/2d)	; Start in the middle
    j_min	= 0
    j_max	= num_lines_cat-1
    j		= start
    j_last1	= 0
    j_last2	= 0

; Now we do a search through the catalog.  We start in the middle.  If we're
; too high, we go earlier in the catalog by half, and vice/versa.  We do this
; until we have found the proper star.  We should be able to find any star
; within log_2(n_lines) steps, which is 22 steps for the TYC2 catalog.

    repeat begin

; Save the earlier locations

      j_last2	= j_last1
      j_last1	= j

      line	= string(lines[j])
      id_line	= long(strcompress(strmid(line, 0, 10), /remove))

      if (id eq id_line) then begin
        line_out	= line
        done 		= 1
	nstars = nstars + 1
      end

; Move to later in list

      if (id gt id_line) then begin
        j_min	= j
        j	= long((j + j_max)/2d + 0.5) 	
      end

; Move to earlier in list

      if (id lt id_line) then begin
        j_max	= j
        j = long((j + j_min)/2d) 		
      end

; Didn't find the star

      if (((j eq j_last1) or (j eq j_last2)) and (not done))  $
        or (j ge num_lines_cat) $
      then begin
	line_out	= ''
	done		= 1
	if (keyword_set(VERBOSE)) then print, $
	  'Error: star ' + ids[i] + ' not found in TYC2 catalog'
      end

    end until (done)

    lines_out[i]	= line_out

  end

; Close the file

  close, lun & free_lun, lun

; Return an array or a scalar, depending on what was passed in.

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

end