source: trunk/SRC/ToBeReviewed/LECTURE/ncdf_lec.pro @ 325

;+
;
; @file_comments
; Give informations on a file netcdf and allows to recuperate
; variables which are written in it.
;
; @categories
; Reading
;
; @param NOM {in}{required}
; Name of a file netcdf located in the directory stipulated by iodir.
;
; @keyword ATT
; 'global' or the name of a variable. Allows to see all attributes
; associated to variable
;
; @keyword DIM
; Give the list of dimensions.
;
; @keyword VAR
;       1) /var: Give the list of dimensions.
;       2) var='name_of_a_variable': in this case the function send back the variable.
;
; @keyword IODIR
; String containing the directory containing the file to be read
;
; @keyword _EXTRA
; Used to pass keywords defined by IDL to functions NETCDF (especially OFFSET
; and COUNT in <proidl>NCDF_VARGET</proidl>)
;
; @returns
; -1 (except if var='nom de variable', then the function send back the variable).
;
; @restrictions
; Variables's names of the program are similar to these used by the IDL manual
; 'scientific data formats'
;
; @history
; Sebastien Masson (smasson\@lodyc.jussieu.fr)
;                       4/1/98
;
; @version
; $Id$
;
;-
FUNCTION ncdf_lec,nom,ATT=att,DIM=dim,VAR=var, IODIR = iodir, _EXTRA = ex
;
  compile_opt idl2, strictarrsubs
;
   res = -1
;------------------------------------------------------------
   if NOT keyword_set(IODIR) then iodir = ''
   if not(keyword_set(att) or keyword_set(dim) or keyword_set(var)) then BEGIN
      att = 1
      dim = 1
      var = 1
;      commande='ncdump -c '+iodir+nom
;      spawn,commande
;      goto,fini
   endif
;------------------------------------------------------------
; opening of the file name.
;------------------------------------------------------------
   cdfid=ncdf_open(iodir+nom)
;------------------------------------------------------------
; What does the file contain??
;------------------------------------------------------------
   wathinside=ncdf_inquire(cdfid)
;   print,'in the file, ',iodir+nom,', there are:'
   if keyword_set(dim) then begin
      ras = report(['number of dimensions: ' + strtrim(wathinside.ndims,1), $
      'number of the dimension which value is infinite : ',strtrim(wathinside.recdim,1)])
   endif
   if keyword_set(var) then $
    if size(var, /type) NE 7 then ras = report('number of variables  :'+strtrim(wathinside.nvars,1))
   if keyword_set(att) then begin
      if strlowcase(att) ne 'global' then goto,nonglobal
      ras = report('number of global attributes :' + strtrim(wathinside.ngatts,1))
   endif
;------------------------------------------------------------
; Global attributes
;------------------------------------------------------------
   if keyword_set(att) then begin
      print, '----------------------------'
      print,'ATTRIBUTS GLOBAUX'
      for attiq=0,wathinside.ngatts-1 do begin
         name=ncdf_attname(cdfid,attiq,/global) ;attribute's name
         ncdf_attget,cdfid,name,value,/global ;attribute's value
         ras = report(name + ': ' + string(value))
      endfor
   endif
nonglobal:
;------------------------------------------------------------
; Display of different dimensions.
;------------------------------------------------------------
   if keyword_set(dim) then begin
      print, '----------------------------'
      print,'DIMENSIONS'
   endif
   nomdim   =strarr(wathinside.ndims)
   tailledim=lonarr(wathinside.ndims)
   for dimiq=0,wathinside.ndims-1 do begin
      ncdf_diminq,cdfid,dimiq,name,value ; dimension's name and value
      nomdim[dimiq]=name
      tailledim[dimiq]=value
      if keyword_set(dim) then begin
         ras = report('dimension number ' + strtrim(dimiq,1) + ', name: ' + $
               nomdim[dimiq] + ' value: ' + strtrim(tailledim[dimiq],1))
      endif
   endfor
;------------------------------------------------------------
; Display of different variables.
;------------------------------------------------------------
;
   if keyword_set(att) or keyword_set(var) then begin
; var's value? string or 1
   help, var, output = nature
   if (strpos(nature, 'STRING'))[0] NE -1 then nature = 'string' ELSE nature = '1'
; If we just have to read the variable.
   if nature EQ 'string' then begin
      ncdf_varget, cdfid, var, res, _extra = ex
      GOTO, sortie
   ENDIF
; If it is to have pieces of information.
   if not keyword_set(att) then att='rien'
      print, '----------------------------'
      for varid=0,wathinside.nvars-1 do begin
         varcontent=ncdf_varinq(cdfid,varid) ; What does variable contain??
         if strlowcase(att) eq strlowcase(varcontent.name) or keyword_set(var) $
          then begin
            ras = report('variable number: ' + strtrim(varid,1) + $
                  ', name:' + varcontent.name + $
                  ', type:' + varcontent.datatype + $
                  ', dimensions:' + nomdim[varcontent.dim])
            if strlowcase(att) eq strlowcase(varcontent.name) then begin
               for attiq=0,varcontent.natts-1 do begin
                  name=ncdf_attname(cdfid,varid,attiq)
                  ncdf_attget,cdfid,varid,name,value
                  ras = report('     ' + strtrim(attiq) + ' ' + $
                        ' name : ' + strtrim(string(value),1))
               endfor
               goto, sortie
            endif
         endif
      endfor
   endif
;------------------------------------------------------------
sortie:
   ncdf_close,cdfid
;------------------------------------------------------------
;------------------------------------------------------------
fini:

   return, res
end