Next: nc_set_default_format, Previous: nc_abort, Up: Datasets
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:
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.
int nc_set_fill (int ncid, int fillmode, int *old_modep);
ncid
fillmode
old_modep
nc_set_fill returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
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 */