;
; BITVREAD
;
;   Accepts a set of ATDF byte-array data, and constructs IDL
;   structures for all of the requested quantities.
;
;   BB - 288xN byte array, where 288 is the length of one raw ATDF
;        record.
;
;   FORMAT - bit packed format, as described in BITSTRACT
;
;   ITEMS - desired items.  Pass FORMAT.ITEM if all columns are
;           desired.
;
;   RECORDS - upon output, filled with IDL structures.  Each of the
;             structure fields is named according to the field's
;             FORMAT.NAME value.  The type of each field is determined
;             from FORMAT.TYPE.
;
;   KEYWORD OFFSET - if set, describes how many records to skip,
;                    starting from the beginning.
;
;
;  $Id: bitvread.pro,v 1.2 2002/02/06 21:39:02 craigm Exp $
;
;  C. Markwardt 03 Feb 2002
;

pro bitvread, bb, format, items, records, offset=offset0

  if n_elements(offset0) NE 0 then offset = round(offset0(0)) $
  else offset = 0L

  for i = 0, n_elements(items)-1 do begin
      item = items(i)
      wh = where(format.item EQ item, ct)
      if ct GT 0 then begin
          fm = format(wh)
          proto = call_function(fm.type,0)
          
          if n_elements(template) EQ 0 then begin
              template = create_struct(fm.name, proto)
          endif else begin
              template = create_struct(template, fm.name, proto)
          endelse
      endif else begin
          message, 'ERROR: could not find item '+strtrim(item,2)
      endelse
  endfor

  ntags = n_tags(template)

  sz = size(bb)
  nrec = sz(2) - offset
  records = replicate(template, nrec)

  for i = 0, n_elements(items)-1 do begin
      item = items(i)
      bitstract, bb, format, item, data, offset=offset
      records.(i) = data
  endfor

  return
end