;-------------------------------------------------------------
;+
; NAME:
;        GTE_READBIN
;
; PURPOSE:
;        Read a binary GTE data set. This is a caller to
;        READ_BDT0001 which also extracts LOD information
;        that is stored as negative JDAY values in the
;        data array.
;
; CATEGORY:
;        GTE tools
;
; CALLING SEQUENCE:
;        GTE_READBIN,FILENAME,DATA,VARDESC,FILEDESC
;
; INPUTS:
;        FILENAME -> A filename or template. If filename is a
;            named variable, it will contain the actually
;            seelcted filename.
;
; KEYWORD PARAMETERS:
;        EXPERIMENT_NAME -> A named variable that will contain
;            the name of the experiment if it was stored in the file.
;
;        EXPERIMENT_NUMBER -> number of the experiment or flight number
;            if stored in the file.
;
;        EXPERIMENT_DATE -> date of experiment
;
;        ORIGINAL_FILE -> filename of original ASCII file
;
;        REVISION_DATE -> data revision date as contained in the
;            file descriptor of a GTE ASCII file -- if it was stored.
;
;        COMMENTS -> A string (array) with comments stored in the
;            file. The return values for the above four keywords are
;            extracted from the first comment line, which will then
;            be deleted.
;
;        TIME -> returns a vector with GMT seconds for easier use of
;            the data.
;
;        _EXTRA -> All keywords are passed on to READ_BDT0001
;            (E.g. DEFAULTMASK, /PICKFILE, /NO_PICKFILE)
;
; OUTPUTS:
;        DATA ->will return the data array without the extra LOD
;            information
;
;        VARDESC -> will return a list of variable descriptors (see
;            GTE_VARDESC) that contains LOD information if found in
;            DATA.
;
;        FILEDESC -> will return a GTE file descriptor (albeit not complete)
;            that contains the experiment and variable information
;
; SUBROUTINES:
;
; REQUIREMENTS:
;        Uses READ_BDT0001
;
; NOTES:
;
; EXAMPLE:
;        GTE_READBIN,'~/data/*.bdt',data,vardesc
;
; MODIFICATION HISTORY:
;        mgs, 28 Aug 1998: VERSION 1.00
;        mgs, 22 Mar 1999: - added TIME keyword
;
;-
; Copyright (C) 1998, Martin Schultz, Harvard University
; This software is provided as is without any warranty
; whatsoever. It may be freely used, copied or distributed
; for non-commercial purposes. This copyright notice must be
; kept with any copy of this software. If this software shall
; be used commercially or sold as part of a larger package,
; please contact the author to arrange payment.
; Bugs and comments should be directed to mgs@io.harvard.edu
; with subject "IDL routine gte_readbin"
;-------------------------------------------------------------


pro gte_readbin,filename,data,vardesc,filedesc,  $
         experiment_name=experiment_name,  $
        experiment_number=experiment_number,  $
        experiment_date=experiment_date,  $
        original_file=original_file,revision_date=revision_date, $
        comments=comments, time=time, $
        _EXTRA=e


    ; Initialize experiment information
    experiment_name = ''
    experiment_number = 0
    experiment_date = ''
    original_file = ''
    revision_date = ''
    filedesc = gte_filedesc()
    if (n_elements(filename) eq 0) then filename = ''
    if (filename eq '') then filename='c:/data/gte/pem-tb/dc8/binary/*.bdt'


    ; Read binary file
    read_bdt0001,filename,data,vardesc,comments=comments,_EXTRA=e
    filedesc.pvardesc = ptr_new(vardesc)
    filedesc.filename = filename


    ; was it successful ?
    if (n_elements(data) lt 2) then return
    test =  ( vardesc[0].name eq 'JDAY' AND $
              vardesc[1].name eq 'STARTHOUR' AND $
              vardesc[2].name eq 'STARTSEC' AND $
              vardesc[3].name eq 'STOPSEC' )
    if (not test) then begin
       message,'WARNING! Not a valid GTE data set!',/INFO,/NONAME
       return
    endif


    ; extract lod information from data array and store it in
    ; variable descriptor

    col0 = data[*,0]
    indt = where(abs(col0+1.) lt 1.0E-6)
    indv = where(abs(col0+2.) lt 1.0E-6)
    if (indt[0] ge 0 AND indv[0] ge 0) then begin
       vardesc.lodtype = reform( data[indt[0],*] )
       vardesc.llodval = reform( data[indv[0],*] )
       ; set lodtype for JDAY to 0
       vardesc[0].lodtype = 0
       *filedesc.pvardesc = vardesc
    endif


    ; Keep only data with positive JDAY values
    ind = where(col0 ge 0.)
    if (ind[0] ge 0) then data = temporary(data[ind,*])



    ; Try to extract experiment information from 1st comment line
    if (n_elements(comments) gt 0) then begin
       com0 = str_sep(comments[0],'|')
       if (n_elements(com0) gt 2 AND n_elements(com0) lt 9) then $
          message,'Cannot extract experiment information from comments!', $
          /INFO   $
       else begin
          experiment_name = com0[2]
          experiment_number = long(com0[3])
          experiment_date = com0[4]
          original_file = com0[5]
          revision_date = com0[6]
          ; delete first comment line
          if (n_elements(comments) gt 1) then $
             comments = comments[1:*]  $
          else  $
             comments = ''

          filedesc.experiment_name = experiment_name
          filedesc.experiment_number = experiment_number
          filedesc.experiment_date = experiment_date
          if (original_file ne '') then filedesc.filename = original_file
          filedesc.revision_date = revision_date
       endelse
    endif

    if (n_elements(comments) gt 0) then $
       if (comments[0] ne '') then $
          filedesc.pcomments = ptr_new(comments)

    ; create a vector with mid-times if requested
    if (arg_present(time)) then begin
       time = 3600.*data[*,1] + (data[*,2]+data[*,3])/2.
    endif


    return

end