;
;+
; AUTHOR:
;   Mike Dorey
;
; DATE:
;    26 September 2003
;
; PURPOSE:
;    reads solar spectral irradiance data from an hdf5 file.
;
; INPUT PARAMETERS:
;    filename - name of a hdf5 file
;
; OUTPUT PARAMETERS:
;    status - returns as 0 on success.  Anything else indicates an error.
;
; RETURN VALUE:
;    returns the data read from the hdf5 file
;
; KEYWORD ARGUMENTS:
;    none
;
; VERSION:
;    $Revision: 3542 $ $Date: 2004-04-02 15:38:29 -0700 (Fri, 02 Apr 2004) $ 
;
; MODIFICATION HISTORY:
;    $Log$
;    Revision 1.2  2004/04/02 22:38:29  windnage
;    Adding comments
;
;    Revision 1.1  2004-04-02 22:36:17+00  windnage
;    Initial revision
;
;
; EXAMPLE USAGE:
;    ans = read_sorce_level3_ssi_hdf(FILENAME, status)
;       where FILENAME is the name of an HDF5 file (for more
;    For more info on HDF5 files go to:
;       - http://lasp.colorado.edu/sorce/data_access.html
;       - http://hdf.ncsa.uiuc.edu/HDF5/
;
; RCS id: $Id: read_sorce_level3_ssi_hdf.pro 3542 2004-04-02 22:38:29Z windnage $

;------------------------------------------------------------
;
; Return value
;    On success, returns a structure that holds the attributes
;    for the hdf5 id.
;
; Mike Dorey, 6 October 2003
;
; RCS id: $Id: read_sorce_level3_ssi_hdf.pro 3542 2004-04-02 22:38:29Z windnage $
;-

function get_attributes,loc_id, status

  ; Compile the functions in this procedure
  FORWARD_FUNCTION create_struct_from_name_value_pairs

  nattributes = h5a_get_num_attrs(loc_id)
  attr_names = strarr(nattributes)
  attr_values = strarr(nattributes)
  name = string(bytarr(256))
  value = string(bytarr(256))
  for i = 0L, nattributes - 1 do begin
    attr_id = h5a_open_idx(loc_id, i)
    name = h5a_get_name(attr_id)
    name = strjoin(strsplit(name, "'", /extract), "", /single) ; remove any apostrophes
    attr_names[i] = strtrim(name)
    value = h5a_read(attr_id)
    attr_values[i] = strtrim(value)
  endfor
  attr_struct = create_struct_from_name_value_pairs(nattributes,  attr_names, attr_values, status)
  if (status ne 0) then begin
    return, 0
  endif
  
  return, attr_struct
end 

; ------------------------------------------------------------
; create_struct_from_name_value_pairs.pro
;
; This function returns a structure that contains the attributes read from
; a hdf5 file.  
;
; Parameters
;    names - (IN) names of the hdf5 attributes
;    values - (IN) values of the hdf5 attributes
;    status - (OUT) returns as 0 on success, 1 on failure
;
; Return value
;    Returns a structure that contains the attributes
;
; Mike Dorey, 6 October 2003
;
; RCS id: $Id: read_sorce_level3_ssi_hdf.pro 3542 2004-04-02 22:38:29Z windnage $

function create_struct_from_name_value_pairs, nattributes, names, values, status
   
   one = 0

   ; create the initial structure with the first name/value pair
   cmd = string("one = create_struct(names[0], values[0])")
   if (execute(cmd) ne 1) then begin
      print, 'execute of create_struct failed'
      status = 1
      return, 0
   endif

   ; tack on the other name/value pairs to the structure
   for i = 1L, nattributes-1 do begin
      cmd = string("two = create_struct(one, names[i], values[i])")
      if (execute(cmd) ne 1) then begin
         print, 'execute of create_struct failed'
         status = 1
         return, 0
      endif
      one = two
   endfor
   
   ; success
   status = 0
   return, one
end

; ---------------------------------------------------------------------------
function read_sorce_level3_ssi_hdf, filename, status
  
  ; Print usage if user does not supply enough inputs
  if (n_params() lt 2) then begin
     doc_library, 'read_sorce_level3_ssi_hdf'
     return, -1
  endif

  ; Check IDL version
  if (!version.release lt 5.4) then begin
     print,'This procedure only works with IDL v5.4 or later!'
     return,-1
  endif

  ; Compile the functions in this procedure
  FORWARD_FUNCTION create_struct_from_name_value_pairs, get_attributes

  ; set up error handling
  catch, status
  if status ne 0 then begin
    print,'error occurred in read_sorce_level3_ssi_hdf'
    print,!error_state.msg
    status = 1
    return, 0
  endif
  
  file_id = h5f_open(filename)
  group_id = h5g_open(file_id, '/')
  
  attr_struct = get_attributes(group_id, status)
  ssi_struct = create_struct("general information", attr_struct)
  
  ; read the data from the datasets within the '/' group
  ndatasets = h5g_get_nmembers(group_id, '/')
  for idx = 0L, ndatasets - 1 do begin
    dataset_name = h5g_get_member_name(group_id, '/', idx)
    dataset_id = h5d_open(group_id, dataset_name)
    attr_struct = get_attributes(dataset_id, status)
    data_struct = h5d_read(dataset_id)
    dataset_struct = create_struct("metadata", attr_struct, "data", data_struct)
    ssi_struct = create_struct(ssi_struct, dataset_name, dataset_struct)
    h5d_close, dataset_id
  endfor
  
  h5g_close, group_id
  h5f_close, file_id
  
  catch, /cancel
  status = 0
  return, ssi_struct
end