1.4 Adding New Dimensions, Variables, Attributes

An existing netCDF file 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 file:

    ncmpi_open             /* open existing netCDF file */
      ... 
    ncmpi_redef            /* put it into define mode */
        ... 
      ncmpi_def_dim        /* define additional dimensions (if any) */
        ... 
      ncmpi_def_var        /* define additional variables (if any) */
        ... 
      ncmpi_put_att        /* define additional attributes (if any) */
        ... 
    ncmpi_enddef           /* check definitions, leave define mode */
        ... 
      ncmpi_put_var        /* provide values for new variables */
        ... 
    ncmpi_close            /* close netCDF file */

A netCDF file is first opened by the ncmpi_open call. This call puts the opened file 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 ncmpi_redef. In define mode, call ncmpi_def_dim to define new dimensions, ncmpi_def_var to define new variables, and a member of the ncmpi_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 ncmpi_enddef. If you do not wish to reenter data mode, just call ncmpi_close, which will have the effect of first calling ncmpi_enddef.

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