;+
; NAME:
;  oc_getline_ucac2
;   
; PURPOSE: (one line)
;  Retrieve the raw binary UCAC2 catalog line for a given ID or IDs.
;
; DESCRIPTION:
;  This function retrieves the raw binary UCAC2 catalog line for a given ID or
;  IDs.  The catalog line is a 44-byte sequence and is not human-readable.
;  Therefore, this routine will not usually be called by an end-user.
;
; CATEGORY:
;  Star catalogs.
;  
; CALLING SEQUENCE:
;  result = oc_getline_ucac2( IDs [,NSTARS=nstars] [,/VERBOSE] )
;
; INPUTS:
;  IDs -- A list of UCAC2 ID's.  Must be string or array of strings.
;   IDs can be in UCAC2 or SCAT format -- e.g., '004321897' or '216.212'.
;   They must all be in the same format.
;
; OPTIONAL INPUT PARAMETERS:
;  None
;  
; KEYWORD INPUT PARAMETERS:
;  None
;
; KEYWORD OUTPUT PARAMETERS:
;  NSTARS -- Returns the number of successfully-retrieved lines.
;
; OUTPUTS:
;  If input is a scalar, then output is byte array of size [44].
;  If input is a vector, then output is byte array of size [num_ids, 44].
;  If a star is not found, elements of that array are set to zero.
;
; COMMON BLOCKS:
;  UCAC2ID_COMMON -- Used to store catalog index file.
;
; SIDE EFFECTS:
;  None
;
; RESTRICTIONS:
;  UCAC2 catalog must be available on local filesystem, 
;  in files $UCAC2_PATH/u2/{z001 .. z288}
;
; EXAMPLE:
;  print, oc_getline_ucac2(['1.0', '1.1'], /VERBOSE)
; 
; MODIFICATION HISTORY:
;  Written  10-Jan-2006 by Henry Throop, SwRI
;  Modified 23-Feb-2006 by HBT. Improved documentation and formatting.
;  Modified 26-Feb-2006 by LAY. Added '/' before 'u2/' (see scat code
;                               usage)
;  Modified 27-Feb-2006 by HBT.  Changed keyword COUNT -> NSTARS.
;  Modified 14-Apr-2006 by Leslie Young. Made loop index long.
;  Modified 29-Jun-2006 by Leslie Young. Close open files on exit
;-

forward_function oc_convertid_ucac2
function oc_getline_ucac2, ids_in, NSTARS=nstars, VERBOSE=verbose

common ucac2id_common, ucac2_index_loaded, ucac2_ninbin, ucac2_ninbin_cum

; Set up the common block so we can read in the index file

  path_catalog	= getenv('UCAC2_PATH') + '/u2/'

; Bytes per line.  There is no CR, LF, etc. btwn fields

  bytes_per_line_ucac2= 44					

; Parse the list of id's into a list of catalogs, and a list of indices within
; these catalogs.
;
; NB: To debug this, use od to look at files, such as: od --width=44 -tu1 z001
; | more

; Load the conversion matrices, if they haven't been loaded, and place them in
; the common block.

  junk	= oc_convertid_ucac2(SCAT=['1.1'])

; Convert the ID type into scat-formatted, if we have to

; If at least one star is in SCAT form, then ok
  if (total(grep(string(ids_in), '\.')) ge 1) then begin		
    ids	= string(ids_in)
  end $ 
; Otherwise, convert from UCAC2 form to SCAT form	
  else begin
    ids	= string(oc_convertid_ucac2(ucac2=ids_in))		
  end

  num_ids	= sizex(ids)

  catalogs	= dblarr(num_ids)	; '200' part of '200.077191'
  indices	= dblarr(num_ids)	; '077191' part of '200.077191'
  lines		= bytarr(num_ids, bytes_per_line_ucac2)	; Binary catalog entry

  for i = 0L, num_ids-1 do begin
    if (ids[i] ne 'none') then begin
      split		= ht_str_split(ids[i], char='.')
      catalogs[i]	= split[0]
      indices[i]	= split[1]
    end
  end

; Now go through and open each catalog
; We use an associative array, rather than reading the entire catalog in.

; Indicates whether file 'file' is currently open, or not

  file_open		= 0			
  for i = 0L, num_ids-1 do begin
    if (ids[i] eq 'none') then begin
      lines[i,*] = ''
    end $
    else begin

      file = path_catalog + 'z' + $
        str_replace(string(catalogs[i], format='(I3)'), ' ', '0', /all)
      if file_exists(file) then begin
        if not(file_open) then begin
          openr, lun, file, /get_lun
          file_open = 1
; Assoc array is allowed to be of type byte, but not string
          arr		= assoc(lun, bytarr(bytes_per_line_ucac2))	
        end

; Check the pre-loaded list of UCAC file arrays to check that this star is
; indeed a valid ID

; In file, star '1.1' is the 0th star, so correct for this

        index	= indices[i]-1				
	if (index ge 0) and (index+1 le ucac2_ninbin[catalogs[i]]) then begin
          lines[i,*]	= byte(arr[index])
	end $ 
	else begin
	  lines[i,*]	= 0
          if keyword_set(VERBOSE) then print, $
	    'Error: oc_getline_ucac2: star ' + ids[i] + ' not valid ID.'
	end

; If the next catalog is the same as this one, just keep it open rather than
; close it.

        if (i lt (num_ids-1)) then begin
          if (catalogs[i] ne catalogs[i+1]) then begin
            close, lun & free_lun, lun
  	    file_open	= 0
          end 
        end
      end $
      else begin
        if keyword_set(VERBOSE) then print, $
	  'Error: oc_getline_ucac2: can''t open ' + file + '.'
        stop
        lines[i,*]	= 0
      end
    end
  end

; Put the number of stars into NSTARS

  nstars	= sizex(ids)

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

  if file_open then begin
      close, lun & free_lun, lun 
  end

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

end

;;;;;;;;;;

;; Code below here is intended for development purposes and not end-user

pro other
  uc = oc_getline_ucac2(['001.00000', '001.00002', '200.077191', '200.077191', '200.077191', 'none'])
end