# coyote: NCDF_FILE__DEFINE

- coyote/FileIO
- [Source code]

NAME

      NCDF_FILE

PURPOSE

      The pupose of this NCDF_File object is three-fold. (1) Allow the user to easily
      determine what information is inside a netCDF file and allow easy access
      to such information. (2) Allow the user to easily create a netCDF file from
      scratch. (3) Allow the user to easily copy information from one netCDF
      file to another.

AUTHOR

      FANNING SOFTWARE CONSULTING
      David Fanning, Ph.D.
      1645 Sheely Drive
      Fort Collins, CO 80526 USA
      Phone: 970-221-0438
      E-mail: david@idlcoyote.com
      Coyote's Guide to IDL Programming: http://www.idlcoyote.com

CATEGORY

      File I/O

CALLING SEQUENCE

      IDL> nCDFObject = Obj_New('NCDF_FILE', filename)

ARGUMENTS

      filename:  The name of a netCDF file to read, write to, or browse.

KEYWORD PARAMETERS

      ALERT:     Set this keyword if you wish to have alert from the object's error logger.
                 Input. Default is 1.
      BROWSE:    If this keyword is set, the Browse Window is invoked as soon
                 as the object is initiated. Input. Default is 0.
      CLOBBER:   Set this keyword if you are opening a netCDF file that already exists and
                 you want to overwrite the existing file. Input. Default is 0.
      CREATE:    Set this keyword if you wish to create a new netCDF file to write
                 into. Input. Default is 0, which means the file will be opened as
                 "read-only".
      DELETE_ON_DESTROY:  Set this keyword if you wish to delete the error log file when
                 the ErrorLogger object is destroyed. This will only happen if the ErrorLogger
                 object is not in an error state. Input. Default is 1.
      MODIFY:    Set this keyword if you wish to modify (write to) a file you are opening.
                 If not set, the file will be opened as "read-only".

METHODS

      The following methods are available. Each is documented in front of the method.
      ncdfObject -> Browse
      ncdfObject -> CopyVarAttrTo, varName, attrName, destObj
      ncdfObject -> CopyVarDataTo, varName, destObj, COUNT=count, OFFSET=offset, STRIDE=stride
      ncdfObject -> CopyVarDefTo, varName, destObj
      ncdfObject -> CopyGlobalAttrTo, attrName, destObj
      ncdfObject -> CopyDimTo, dimName, destObj
      dimNames = ncdfObject -> GetDimNames(COUNT=dimCount)
      dimValue = ncdfObject -> GetDimValue(dimName)
      fileID = ncdfObject -> GetFileID()
      globalAttrNames = ncdfObject -> GetGlobalAttrNames(COUNT=attrCount)
      attrValue = ncdfObject -> GetGlobalAttrValue(attrName, DATATYPE=datatype)
      ncdfObject -> GetProperty, ....
      property = ncdfObject -> GetProperty(thisProperty)
      varAttrNames = ncdfObject -> GetVarAttrNames(varName, COUNT=attrCount)
      varAttrValue = ncdfObject -> GetVarAttrValue(varName, varAttrName, COUNT=attrCount)
      varNames = ncdfObject -> GetVarNames(COUNT=varCount)
      varData = ncdfObject -> GetVarData(varName, COUNT=count, OFFSET=offset, STRIDE=stride)
      answer = ncdfObject -> HasGlobalAttr(attrName, OBJECT=object)
      answer = ncdfObject -> HasDim(dimName, OBJECT=object)
      answer = ncdfObject -> HasVar(varName, OBJECT=object)
      answer = ncdfObject -> HasVarAttr(varName, attrName, OBJECT=object)
      ncdfObject -> PrintFileInfo
      ncdfObject -> ParseFile
      ncdfObject -> SetMode, DEFINE=define, DATA=data
      ncdfObject -> WriteVarData, varName, data, COUNT=count, OFFSET=offset, STRIDE=stride
      ncdfObject -> WriteVarDef, varName, dimNames, DATATYPE=datatype, VAROBJ=varObj
      ncdfObject -> WriteDim, dimName, dimSize, UNLIMITED=unlimited
      ncdfObject -> WriteGlobalAttr, attrName, attrValue, DATATYPE=datatype
      ncdfObject -> WriteVarAttr, attrName, attrValue, varObj, DATATYPE=datatype

NOTES

      Note that all variable, attribute, and dimension names in a netCDF file are CASE SENSITIIVE!!
      Thus, it is a good idea to use the methods provided in this object to obtain and examine
      information in the file, as these names are handled in a case sensitive manner.
      Whenever you are creating a new netCDF file, you should try to create the file in
      the following way.
         1. Create your global attributes.
         2. Create the dimensions you will be using to describe the variables.
         3. Define the variables. To do this correctly, dimensions MUST be defined.
         4. Define variable attributes.
         5. Load your variables with data.
         Note that the data type of the _FillValue variable attribute MUST match the
         data type of the variable data. Otherwise, you will have MANY problems! This
         is a common source of error.
         Note that in almost all cases where you see the names "varName", "dimName", or
         "attrName" used as input variables, you can substitute the proper object
         reference in place of the actual name. In other words, you could get the value
         of a variable attribute by doing something like this:
             check = ncdfObject -> HasAttr('history', OBJECT=attrObj)
             IF check THEN attrValue = ncdfObject -> GetGlobalAttrValue(attrObj)
          as opposed to this:
             IF check THEN attrValue = ncdfObject -> GetGlobalAttrValue('history')

EXAMPLE

      IDL> filename = 'example.nc'
      IDL> ncdfObj = Obj_New('NCDF_FILE', filename)
      IDL> ncdfObj -> Browse
      IDL> Obj_Destroy, ncdfObj

MODIFICATION HISTORY

      Written by:  David W. Fanning, 3 Feb 2010, using (stealing, really) plenty of ideas
         from Mark Hadfield's Motley Library. Mark's mghncfile object is terrific, but it
         had a number of limitations for my particular application, which I have attemped
         to correct in my version of the software. But I wouldn't have even attempted this
         had Mark not blazed the trail and Matt Savoie not insisted that I look at Mark's
         wonderful library.
      Changes in the way dimensions with a zero length are handled. 11 Feb 2010, DWF.
      Added GetVarInfo method. 20 March 2010. DWF.
      Added MISSINGINIDCES and FILLVALUE output keywords to GetVarData method. 20 March 2010. DWF.
      Added output keywords SCALE_FACTOR, ADD_OFFSET, and DATATYPE to GetVarData method
          so that these values can be obtained with the data. 29 Apr 2010. DWF.
      I changed "missingValue" to "fillValue" some time ago, but I missed one in
          the GetVarData method. Fixed. 7 June 2010. DWF.
      Used the undefine procedure OBJ_DELETE, rather than OBJ_DESTROY. Sheesh! 18 June 2010. DWF.
      Added NETCDF4_FORMAT keyword. 13 Feb 2012. DWF.
      Added a bunch of new IDL 8.0 and 8.1 keyword to the WriteVarDef method to allow
          access to these keywords in NCDF_VarDef. Also modified the NETCDF4_FORMAT keyword
          to apply only in IDL versions 8.0 and higher. 21 Feb 2012. DWF.
      Small typo fixed in setting CHAR datatype for IDL 8.1 and higher. 22 May 2013. DWF.
      Typo (CONTINUOUS->CONTIGUOUS) fixed in WriteDefVar method. 30 July 2013. DWF.
      Modified CopyVarDefTo method to allow new NCDF4 keywords. 30 July 2013. DWF.
      Added DelGlobalAttr method to allow deletion of global attributes. 11 Jan 2014. DWF.
      Found typo in UBYTE variable code, which I fixed. 12 Fef 2016. DWF.