source: trunk/SRC/ReadWrite/idl-NetCDF/ncdf_quickread/ncdf_quickread_helper.pro @ 325

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;
; ncdf_quickread_helper.pro - This file contains IDL functions to read netCDF
;                             data files into IDL variables.
;
; Adapted from CDF2IDL.pro
;
;  This file contains the following functions and procedures:
;     functions:
;        ncdf_quickread_getfile - strips the directory and optionally) any
;                                 suffixes from the path+file
;        ncdf_quickread_getdir - returns the directory from the full path+file
;        ncdf_quickread_validatename - validates the name that will be used
;                                      as a netCDF variable
;     procedures:
;        ncdf_quickread_helper1 - construct commands which when executed at
;                                 the top level will read netCDF variables
;                                 into IDL
;
;  History:
;  Date       Name          Action
;  ---------  ------------  ----------------------------------------------
;  06 Jun 97  S. Rupert     Created.
;  09 Jun 97  S. Rupert     Fully tested.
;  10 Jun 97  S. Rupert     Modified keyword usage.
;  03 Feb 98  S. Rupert     Added additional error checking, and warning to
;                           output script.
;  17 Feb 98  S. Rupert     Corrected validation routine to handle instance
;                           of name strating with a number and containing a
;                           dash.
;  05 Jul 00  A.M.Iwi       Added keyword PREFIX= on CDF2IDL.  Supplied string
;                           gets prepended to all variable names.
;  19 Jun 01  A.M.Iwi       Added keyword REFORM on CDF2IDL.  REFORM function
;                           is used to remove dimensions of size 1.
;  02 Oct 03  A.M.Iwi       Change into helper routine for ncdf_quickread
;  11 Aug 04  A.M.Iwi       Add "fields" option to read only certain fields.
;                           Also, only stringify attributes of type CHAR.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;+
; @file_comments
; This function returns the filename name from the full path.
;
; @categories
;
;
; @param FULLPATH
; full directory+file path
;
; @keyword SUFFIX
; include input suffix in output file name
;
; @returns
; file - filename
;
; @restrictions
;
;
; @examples
; Call: file = ncdf_quickread_getfile(fullpath)
;
; @history
;
;
; @version
; $Id$
;-
function ncdf_quickread_getfile, fullpath, suffix=suffix
on_error,2
compile_opt hidden
; Retrieve the position at which the first '/' character occurs from
; the end of the string.
dirlen = rstrpos(fullpath, '/')

; Retrieve the full length of the original string.
len = strlen(fullpath)

; Retrieve the filename.
fullfile = strmid(fullpath, dirlen+1, len)

; Retrieve the position at which the first '.' character occurs from
; the end of the string.
len = -1
if not(keyword_set(suffix)) then len = rstrpos(fullfile, '.')
if (len EQ -1) then len = strlen(fullfile)

; Retrieve the file.
file = strmid(fullfile, 0, len)

; Return the file name.
return, file

; End function.
end

;+
; @file_comments
; This function returns the directory name from the full path.
;
; @categories
;
;
; @param FULLPATH
; full directory+file path
;
; @returns
; directory path
;
; @restrictions
;
;
; @examples
; Call: dir = ncdf_quickread_getdir(fullpath)
;
; @history
;
;
; @version
; $Id$
;-
function ncdf_quickread_getdir, fullpath
on_error,2
compile_opt hidden
; Retrieve the position at which the first '/' character occurs from
; the end of the string.
len = rstrpos(fullpath, '/')

; Retrieve the filename.
if (len EQ -1) then dir = "./" $
else dir = strmid(fullpath, 0, len+1)

; Return the file name.
return, dir

; End function.
end

;+
; @file_comments
; This routine ensures that the given name does not start with a number,
; nor contain a dash.  IDL cannot accept a variable starting with a
; number or containing a dash.  If the name starts with a number, an
; underscore is prepended to the name, and if it contains a dash, the
; dash is replaced with an underscore.
;
; @categories
;
;
; @param VARNAME
; The name of the variable to be read
;
;
; @returns
;
;
; @restrictions
;
;
; @examples
;
;
; @history
;
;
; @version
; $Id$
;-
function ncdf_quickread_validatename, varname
on_error,2
compile_opt hidden

; Initialize the name.
name = varname

; If the name starts with a number, prepend it with an underscore.
if (strpos(varname, '0') EQ 0) then name = strcompress("_"+varname)
if (strpos(varname, '1') EQ 0) then name = strcompress("_"+varname)
if (strpos(varname, '2') EQ 0) then name = strcompress("_"+varname)
if (strpos(varname, '3') EQ 0) then name = strcompress("_"+varname)
if (strpos(varname, '4') EQ 0) then name = strcompress("_"+varname)
if (strpos(varname, '5') EQ 0) then name = strcompress("_"+varname)
if (strpos(varname, '6') EQ 0) then name = strcompress("_"+varname)
if (strpos(varname, '7') EQ 0) then name = strcompress("_"+varname)
if (strpos(varname, '8') EQ 0) then name = strcompress("_"+varname)
if (strpos(varname, '9') EQ 0) then name = strcompress("_"+varname)

; If the name contains a dash replace it with an underscore.
if (strpos(name, '-') NE -1) then begin
   pieces = str_sep(name, '-')
   n_pieces = n_elements(pieces)
   name = pieces(0)
   for i=1,n_pieces-1 do begin
      name = strcompress(name+"_"+pieces(i))
   endfor
endif

; Return the file name.
return, name

; End function.
end
;+
; @file_comments
; This procedure creates a script to read the data in a given netCDF
; file into IDL.  The default output file is the name of the netCDF
; file with idl replacing any existing suffix.  The default output is
; variable data only.
;
; @categories
;
;
; @param INFILE
; full path to netCDF file of interest
;
; @keyword VERBOSE
; Set this keyword to return an error message in case of an error.
;
; @keyword PREFIX
; see changelog above.
;
; @keyword FIELDS
;
;
; @keyword REFORM
; see changelog above
;
; @returns
; array of commands to run at top level
;
; @restrictions
;
;
; @examples
;
;
; @history
;
;
; @version
; $Id$
;
;-
function ncdf_quickread_helper, infile, verbose=verbose,  $
                                prefix=prefix, fields=fields, $
                                reform=reform
on_error,2
compile_opt hidden
;
;

; Ensure that the netCDF format is supported on the current platform.
if not(ncdf_exists()) then message, $
  "The Network Common Data Format is not supported on this platform."

; Open the netcdf file for reading.
ncid = NCDF_OPEN(strcompress(infile, /remove_all))
if (ncid EQ -1) then message,$
  "The file "+infile+" could not be opened, please check the path."

; Retrieve general information about this netCDF file.
ncidinfo = NCDF_INQUIRE(ncid)

; command to write file header
commands="__ncid = NCDF_OPEN('"+infile+"')"

subset=0
if n_elements(fields) ne 0 then begin
  if (fields ne '') then begin
      subset=1
      subfields=strsplit(fields,/extract)
  endif
endif

; Place the desired variables in local arrays.
for i=0, ncidinfo.Nvars-1 do begin
   vardata = NCDF_VARINQ(ncid, i)
   if not subset then begin
       wanted=1
   endif else begin
       match = where(subfields eq vardata.Name, nmatch)
       wanted=(nmatch ne 0)
   endelse
   if wanted then begin
       varname = ncdf_quickread_validatename(vardata.Name)
       if keyword_set(prefix) then varname=prefix+varname
       commands=$
                [commands,"NCDF_VARGET, __ncid, "+strcompress(string(i))+", "+varname]
       if keyword_set(reform) and vardata.ndims ge 2 $
         then commands=[commands,varname+'=reform('+varname+')']
       if (keyword_set(verbose)) then begin
           for j=0, vardata.Natts-1 do begin
               att = NCDF_ATTNAME(ncid, i, j)
               attname = strcompress(varname+"_"+strcompress(att,/REMOVE_ALL))
               commands=$
                        [commands,"NCDF_ATTGET, __ncid, "+strcompress(string(i))+$
                         ", '"+att+"', "+attname]
               attinfo = ncdf_attinq(ncid, i, att)
               if attinfo.datatype eq 'CHAR' then $
                 commands=[commands,attname+" = STRING("+attname+")"]
           endfor
       endif
   endif
endfor

if (keyword_set(verbose)) then begin
  for i=0, ncidinfo.Ngatts-1 do begin
     name = NCDF_ATTNAME(ncid, /GLOBAL, i)
     attname = ncdf_quickread_validatename(name)
     if keyword_set(prefix) then attname=prefix+attname
     commands=$
       [commands,"NCDF_ATTGET, __ncid, /GLOBAL, '"+name+"', "+attname]
     attinfo = ncdf_attinq(ncid, /global, name)
     if attinfo.datatype eq 'CHAR' then $
       commands=[commands,attname+" = STRING("+attname+")"]
  endfor
endif

ncdf_close,ncid
commands=[commands,"NCDF_CLOSE, __ncid"]

; Return commands to the caller.
return,commands

; End procedure.
end