1.4 Adding New Dimensions, Variables, Attributes

An existing netCDF dataset can be extensively altered. New dimensions, variables, and attributes can be added or existing ones renamed, and existing attributes can be deleted. Existing dimensions, variables, and attributes can be renamed. The following code template lists a typical sequence of calls to add new netCDF components to an existing dataset:

         NF_OPEN             ! open existing netCDF dataset
           ...
         NF_REDEF            ! put it into define mode
             ...
           NF_DEF_DIM        ! define additional dimensions (if any)
             ...
           NF_DEF_VAR        ! define additional variables (if any)
             ...
           NF_PUT_ATT        ! define other attributes (if any)
             ...
         NF_ENDDEF           ! check definitions, leave define mode
             ...
           NF_PUT_VAR        ! provide new variable values
             ...
         NF_CLOSE            ! close netCDF dataset

A netCDF dataset is first opened by the NF_OPEN call. This call puts the open dataset in data mode, which means existing data values can be accessed and changed, existing attributes can be changed (so long as they do not grow), but nothing can be added. To add new netCDF dimensions, variables, or attributes you must enter define mode, by calling NF_REDEF.In define mode, call NF_DEF_DIM to define new dimensions, NF_DEF_VAR to define new variables, and a member of the NF_PUT_ATT family to assign new attributes to variables or enlarge old attributes.

You can leave define mode and reenter data mode, checking all the new definitions for consistency and committing the changes to disk, by calling NF_ENDDEF. If you do not wish to reenter data mode, just call NF_CLOSE, which will have the effect of first calling NF_ENDDEF.

Until the NF_ENDDEF call, you may back out of all the redefinitions made in define mode and restore the previous state of the netCDF dataset by calling NF_ABORT. You may also use the NF_ABORT call to restore the netCDF dataset to a consistent state if the call to NF_ENDDEF fails. If you have called NF_CLOSE from definition mode and the implied call to NF_ENDDEF fails, NF_ABORT will automatically be called to close the netCDF dataset and leave it in its previous consistent state (before you entered define mode).

At most one process should have a netCDF dataset open for writing at one time. The library is designed to provide limited support for multiple concurrent readers with one writer, via disciplined use of the NF_SYNC function and the NF_SHARE flag. If a writer makes changes in define mode, such as the addition of new variables, dimensions, or attributes, some means external to the library is necessary to prevent readers from making concurrent accesses and to inform readers to call NF_SYNC before the next access.