Next: , Previous: nc_abort, Up: Datasets


2.15 Set Fill Mode for Writes: nc_set_fill

This function is intended for advanced usage, to optimize writes under some circumstances described below. The function nc_set_fill sets the fill mode for a netCDF dataset open for writing and returns the current fill mode in a return parameter. The fill mode can be specified as either NC_FILL or NC_NOFILL. The default behavior corresponding to NC_FILL is that data is pre-filled with fill values, that is fill values are written when you create non-record variables or when you write a value beyond data that has not yet been written. This makes it possible to detect attempts to read data before it was written. For more information on the use of fill values see Fill Values. For information about how to define your own fill values see Attribute Conventions.

The behavior corresponding to NC_NOFILL overrides the default behavior of prefilling data with fill values. This can be used to enhance performance, because it avoids the duplicate writes that occur when the netCDF library writes fill values that are later overwritten with data.

A value indicating which mode the netCDF dataset was already in is returned. You can use this value to temporarily change the fill mode of an open netCDF dataset and then restore it to the previous mode.

After you turn on NC_NOFILL mode for an open netCDF dataset, you must be certain to write valid data in all the positions that will later be read. Note that nofill mode is only a transient property of a netCDF dataset open for writing: if you close and reopen the dataset, it will revert to the default behavior. You can also revert to the default behavior by calling nc_set_fill again to explicitly set the fill mode to NC_FILL.

There are three situations where it is advantageous to set nofill mode:

  1. Creating and initializing a netCDF dataset. In this case, you should set nofill mode before calling nc_enddef and then write completely all non-record variables and the initial records of all the record variables you want to initialize.
  2. Extending an existing record-oriented netCDF dataset. Set nofill mode after opening the dataset for writing, then append the additional records to the dataset completely, leaving no intervening unwritten records.
  3. Adding new variables that you are going to initialize to an existing netCDF dataset. Set nofill mode before calling nc_enddef then write all the new variables completely.

If the netCDF dataset has an unlimited dimension and the last record was written while in nofill mode, then the dataset may be shorter than if nofill mode was not set, but this will be completely transparent if you access the data only through the netCDF interfaces.

The use of this feature may not be available (or even needed) in future releases. Programmers are cautioned against heavy reliance upon this feature.

Usage

     int nc_set_fill (int ncid, int fillmode, int *old_modep);
ncid
NetCDF ID, from a previous call to nc_open or nc_create.
fillmode
Desired fill mode for the dataset, either NC_NOFILL or NC_FILL.
old_modep
Pointer to location for returned current fill mode of the dataset before this call, either NC_NOFILL or NC_FILL.

Errors

nc_set_fill returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

Example

Here is an example using nc_set_fill to set nofill mode for subsequent writes of a netCDF dataset named foo.nc:

     #include <netcdf.h>
        ...
     int ncid, status, old_fill_mode;
        ...
     status = nc_open("foo.nc", NC_WRITE, &ncid);  /* open for writing */
     if (status != NC_NOERR) handle_error(status);
     
        ...           /* write data with default prefilling behavior */
     
     status = nc_set_fill(ncid, NC_NOFILL, &old_fill_mode); /* set nofill */
     if (status != NC_NOERR) handle_error(status);
     
        ...           /* write data with no prefilling */