function grd_read_l1a_soh, pds_dir
;
; GRD_READ_L1A_SOH reads the GRaND L1A PDS SOH data within a 
; directory into an array of structures, representing a time series,
; for visualization and analysis.  This function was written to 
; illustrate how PDS L1A data are read using IDL and is not used
; for production of the L1B data.
;
; Input:
;   pds_dir  - target directory containing the PDS data
;              (string) - refer to the example.
;
; Output:
;   result   - an array of structures providing a time series
;              of reduced data (see structure definition 
;              comments below)
;
; Detector index pattern: [0: pz, 1:my, 2:py, 3:mz]
;
; Routines:
;   get_pds_value (function)
;   
; Example usage (PC):
;   path='F:\PDS\GRD_L0\ICO\07290_grd\'
;   directory=path+'GRD-L1A-071017-071018_090702\'
;   soh_data=GRD_READ_L1A_SOH(directory)
;
; Version 1.0, 18-May-2009:
;   Developed for the Dawn Data Workshop in Tennesee to
;   demonstrate the L1A data products from EMC and MGA. 
;
; Written by
;   T. H. Prettyman
;   Planetary Science institute

; 
; Structure definition
soh_data = { scet_utc    : 'yyyy-mm-ddThr:mn:sc'      ,  $ ; UTC spacecraft event time (SCET)
             sclk        : 0L                         ,  $ ; SCLK
             scaler      : ulonarr(23)                ,  $ ; Scaler data
             t_bgo       : 0.                            } ; BGO_sensor temperature


; Default result
result=-1


; Find the data set prefix and do some checking
pos=strpos(pds_dir,'GRD-')
if (pos eq -1) then begin
 print, ' ERROR: The directory does not exist. PDS_DIR = ', pds_dir
 return, result
endif
check=strlen(pds_dir)-1-pos
if (check ne 28) then begin
 print, ' ERROR: The PDS file name does not have the right length. '
 return, result
endif
prefix=strmid(pds_dir,pos,28)
search_pattern=prefix+'*'
files=file_search(pds_dir,search_pattern)
if (n_elements(files) ne 34) then begin   ; 34 files (TBL, DAT, LBL) are expected.
 print, ' ERROR: The archive is not complete. '
 return, result
endif
; From here on out there will be less error checking (hope for the best!)

; Find out how many records are in the time series...
file=pds_dir+'LEVEL1A_AUX\'+prefix+'-SOH-SCL.LBL'
val=get_pds_value(file,'FILE_RECORDS')
if (val eq -1) then begin
 print, ' ERROR: FILE_RECORDS not found by get_pds_value.'
 return, result
endif
reads, val, n_records, format='(i11)'
n_records=long(n_records)

; Create an array of structures
result=replicate(soh_data,n_records)

; Read the scaler data
FORMAT_STRING='(a19,i11,23(i6))'
scet_utc=' '
sclk=0L
scaler=ulonarr(23)
file=pds_dir+'LEVEL1A_AUX\'+prefix+'-SOH-SCL.TAB'
openr, lun, file, /get_lun, error=err
if (err ne 0) then begin
 print, ' ERROR: Problem opening -SOH-SCL.TBL '
 return, result
endif
line=' '
for i=0,n_records-1 do begin
 readf, lun, scet_utc, sclk, scaler, format=FORMAT_STRING
 result[i].scet_utc=scet_utc
 result[i].sclk=sclk
 result[i].scaler=scaler
endfor
free_lun, lun

; Read the readings data
FORMAT_STRING='(a19,i11,16(f9.2))'
scet_utc=' '
sclk=0L
hvps=fltarr(7)
temperatures=fltarr(9)
file=pds_dir+'LEVEL1A_AUX\'+prefix+'-RDG.TAB'
openr, lun, file, /get_lun, error=err
if (err ne 0) then begin
 print, ' ERROR: Problem opening -RDG.TBL '
 return, result
endif
line=' '
for i=0,n_records-1 do begin
 readf, lun, scet_utc, sclk, hvps, temperatures, format=FORMAT_STRING
 result[i].t_bgo=temperatures[6]
endfor
free_lun, lun



return, result

end