>  Docs Center  >  Libraries  >  Coyote  >  NCDF_FILE__DEFINE






      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.


      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


File I/o

Calling Sequence

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


      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
      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".
    The following programs are required from the Coyote Library. And it is always a
    good idea to make sure you have the latest version of the Coyote Library code,
    as updates are irregular and frequent.
    These files may be (almost certainly are!) dependent on other Coyote Library files.


    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


    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')


      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.

© 2022 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us