source: trunk/SRC/ReadWrite/ncdf_getatt.pro @ 391

;+
;
; @file_comments
; Get variable attibutes from a NetCDF file
;
; @categories
; Read NetCDF file
;
; @param fileid {in}{required}{type=salar string or long}
; if fileid is a scalar string then it is the name of the file (with
; the full path) to be opened (in that case, the file will be opened
; and closed within ncdf_getatt).
; if fileid is a scalar long then it is the id of the file return by a call
; to ncdf_open outside of ncdf_getatt (in that case, the file will
; NOT be opened and closed within ncdf_getatt)
;
; @param varid {in}{required}{type=salar string or long}
; The netCDF variable ID, returned from a previous call to NCDF_VARDEF
; or NCDF_VARID, or the name of the variable.
;
; @keyword add_offset 
; Set this keyword to a named variable in which the value of
; add_offset attribute is returned. Return 0. if this attribute
; doesn't exist.
;
; @keyword scale_factor
; Set this keyword to a named variable in which the value of
; scale_factor attribute is returned. Return 0. if this attribute
; doesn't exist.
;
; @keyword missing_value
; Set this keyword to a named variable in which the value of
; missing_value or _fillvalue attribute is returned. Return the scalar
; 'no' if this attribute doesn't exist.
;
; @keyword units
; Set this keyword to a named variable in which the value of
; units attribute is returned. Return the empty string '' if this attribute
; doesn't exist.
;
; @keyword calendar
; Set this keyword to a named variable in which the value of
; calendar attribute is returned. Return the string 'greg' if this attribute
; doesn't exist.
;
; @keyword long_name
; Set this keyword to a named variable in which the value of
; long_name is returned. Return empty string if this attribute
; does not exist.
;
; @keyword DOUBLE {default=0} {type=1 or 0}
; activate to force double-precision floating-point value of
; add_offset and scale_factor
;
; @keyword standard_name
; Set this keyword to a named variable in which the value of
; standard_name (CF convention) is returned. Return empty string 
; if this attribute does not exist.
;
; @keyword _EXTRA
; defined only to be able to call <pro>ncdf_getatt</pro> with the 
; _EXTRA keyword
;
; @examples
;
;   IDL> ncdf_getatt, cdfid, 'sst', add_offset = add_offset, scale_factor = scale_factor, units = units
;
; @history
; August 2007: Sebastien Masson (smasson\@lodyc.jussieu.fr)
;
; @version
; $Id$
;
;-
PRO ncdf_getatt, fileid, varid, ADD_OFFSET = add_offset, SCALE_FACTOR = scale_factor $
                 , MISSING_VALUE = missing_value, UNITS = units, CALENDAR = calendar $
                 , LONG_NAME = long_name, STANDARD_NAME = standard_name, DOUBLE = double $
                 , _extra = ex
;
  compile_opt idl2, strictarrsubs
;
  @cm_general                      ;   needed for iodir
;
; should we open the file?
  IF size(fileid, /type) EQ 7 THEN $
     cdfid = ncdf_open(isafile(fileid, title = 'which file must be open by ncdf_getatt?', IODIRECTORY = iodir, _extra = ex)) $
  ELSE cdfid = fileid
; default definitions
  units = ''
  add_offset = 0.
  scale_factor = 1.
  missing_value = 'no'
  calendar = 'greg'
  long_name = ''
  standard_name = ''
; 
  varinq = ncdf_varinq(cdfid, varid)
  IF varinq.natts GT 0 THEN BEGIN
    FOR a = 0, varinq.natts-1 DO BEGIN
      attname = ncdf_attname(cdfid, varid, a)
      CASE strlowcase(attname) OF
        'units':BEGIN 
          ncdf_attget, cdfid, varid, attname, tmp
          units = strtrim(tmp, 2)
        END
        'calendar':BEGIN 
          ncdf_attget, cdfid, varid, attname, tmp
          tmp = strtrim(tmp, 2)
          CASE tmp OF
            'noleap':calendar = 'noleap'
            '360d':calendar = '360d'
            'greg':calendar = 'greg'
            '360_day':calendar = '360d'
            '365_day':calendar = 'noleap'
            'gregorian': calendar = 'greg'
            ELSE:notused = report('Unknown calendar: '+tmp+', we use greg calendar.')
          ENDCASE
        END
        'long_name':BEGIN
           ncdf_attget, cdfid, varid, attname, tmp
           long_name = strtrim(tmp, 2)           
        END
        'standard_name':BEGIN
           ncdf_attget, cdfid, varid, attname, tmp
           standard_name = strtrim(tmp, 2)           
        END
        'add_offset':ncdf_attget, cdfid, varid, attname, add_offset
        'scale_factor':ncdf_attget, cdfid, varid, attname, scale_factor
        '_fillvalue':ncdf_attget, cdfid, varid, attname, missing_value
        'missing_value':ncdf_attget, cdfid, varid, attname, missing_value
        ELSE:
      ENDCASE
    ENDFOR
  ENDIF
;
  IF size(missing_value, /type) EQ 1 THEN BEGIN
    missing_value = strlowcase(string(missing_value))
    IF strmid(missing_value, 0, 1, /reverse_offset) EQ 'f' THEN $
       missing_value = strmid(missing_value, 0, strlen(missing_value)-1)
    IF isnumber(string(missing_value), tmp) EQ 1 THEN BEGIN 
      missing_value = tmp
    ENDIF ELSE BEGIN
      ras = report('Warning: missing value is not a number: ' + missing_value)
      missing_value = 'no'
    ENDELSE
  ENDIF
;
  IF keyword_set(double) THEN BEGIN
    add_offset = double(add_offset)
    scale_factor = double(scale_factor)
  ENDIF ELSE BEGIN 
    add_offset = float(add_offset)
    scale_factor = float(scale_factor)
  ENDELSE
;
  IF size(fileid, /type) EQ 7 THEN ncdf_close, cdfid
  
  return
END