ncmpi_set_fill (PnetCDF C Interface Guide)

This function is intended for advanced usage, to optimize writes under some circumstances described below. The function ncmpi_set_fill sets the fill mode for a netCDF file 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 mode of PnetCDF is NC_NOFILL. Note that this is opposite to netCDF whose default mode is NC_FILL. The 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 at the time ncmpi_enddef is called. 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.

NC_NOFILL can be used to enhance performance, because it avoids the duplicate writes that occur when the PnetCDF library writes fill values that are later overwritten with data.

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

When in the default NC_NOFILL mode for an opened netCDF file, you must be certain to write valid data in all the positions that will later be read. Note that fill mode is only a transient property of a netCDF file 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 ncmpi_set_fill again to explicitly set the fill mode to NC_NOFILL.

ncmpi_set_fill() will change the fill mode for all variables defined so far at the time this API is called. In other words, it overwrites the fill mode for all variables previously defined. This will also change the default fill mode for new variables defined following this call. To set the fill mode for individual variables, readers are referred to ncmpi_def_var_fill.

In PnetCDF, this API only affects non-record variables. In addition, it can only be called while in the define mode. All non-record variables will be filled with fill values (either default or user-defined) at the time ncmpi_enddef() is called.

For record variables, users must call ncmpi_fill_var_rec() to fill one record of a variable at a time. If fill mode is desired, users should call ncmpi_fill_var_rec() first followed by the regular put APIs.

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

As stated in netCDF document, the use of this feature may not be available (or even needed) in future releases. Programmers are cautioned against heavy reliance upon this feature.

Operational Mode

This API is a collective subroutine and must be called in define mode, contrary to netCDF where nc_set_fill() can also be called in data mode. The reason of PnetCDF enforcing this requirement is because PnetCDF only fills fixed-size variables at ncmpi_enddef(). Record variables are only filled in ncmpi_fill_var_rec().

Usage

int ncmpi_set_fill(int  ncid,
                   int  fillmode,
                   int *old_modep);

Return Error Codes

ncmpi_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 ncmpi_set_fill to set nofill mode for subsequent writes of a netCDF file named foo.nc:

#include <pnetcdf.h>
   ... 
int ncid, status, old_fill_mode;
   ... 
status = ncmpi_create(MPI_COMM_WORLD, "foo.nc", NC_WRITE, info, &ncid);
if (status != NC_NOERR) handle_error(status);

   ...       /* create dimensions, variables, attributes */
   ...       /* finish definitions of all variables */

status = ncmpi_set_fill(ncid, NC_FILL, &old_fill_mode); /* set to fill */
if (status != NC_NOERR) handle_error(status);

status = ncmpi_enddef(ncid);
if (status != NC_NOERR) handle_error(status);

   ...           /* write data */

2.16 Set Fill Mode for Writes: ncmpi_set_fill

Operational Mode

Usage

Return Error Codes

Example

Full example C program