4.4 Set fill mode for a Variable: ncmpi_def_var_fill

The API ncmpi_def_var_fill sets the fill mode parameters for a variable. This API is only available in version 1.6.1 and later.

This API must be called after the variable is defined, but before ncmpi_enddef is called.

Operational Mode

This API is a collective subroutine.

This API must be called while the file is in define mode.

Usage

int ncmpi_def_var_fill(int         ncid,
                       int         varid,
                       int         no_fill,
                       const void *fill_value);

ncid

NetCDF ID, from a previous call to ncmpi_open or ncmpi_create.

varid

Variable ID. This value must be consistent across all calling MPI processes.

no_fill

Set no_fill mode for a variable. 1 for on (not to fill) and 0 for off (to fill). When this mode is on, fill values will not be written for the variable. This is helpful in high performance applications. The mode may only be changed after the variable is defined, but before it is committed to disk (i.e. before the first ncmpi_enddef after the ncmpi_def_var.)

fill_value

A pointer to a value which will be used as the fill value for the variable. Must be the same type as the variable. This will be written to a _FillValue attribute, created for this purpose. If NULL, this argument will be ignored and the default fill value is used.

Return Error Codes

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

• NC_EBADID: Bad ncid. The specified netCDF ID does not refer to an opened netCDF file.
• NC_EPERM: Attempt write operations in read-only file.
• NC_ENOTINDEFINE: Operation not allowed in data mode.
• NC_ENOTVAR: Cannot find this variable.
• NC_EGLOBAL: NC_GLOBAL is considered invalid variable ID for this API.
• NC_EMULTIDEFINE_VAR_FILL_MODE: Fill modes are inconsistent among all MPI processes.
• NC_EMULTIDEFINE_VAR_FILL_VALUE: Fill values are inconsistent among all MPI processes.

Example

Here is an example using ncmpi_def_var to create a variable named rh of type double with three dimensions and turn on the variable’s fill mode using the PnetCDF default fill value.

#include <pnetcdf.h>

/* create a file */
/* define dimensions */
    ...
status = ncmpi_def_var(ncid, "rh", NC_DOUBLE, 3, dimids, &varid);
if (status != NC_NOERR) handle_error(status);

/* set fill mode to yes and use the default fill values */
status = ncmpi_def_var_fill(ncid, varid, 0, NULL);
if (status != NC_NOERR) handle_error(status);

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

Full example C program

• fill_mode.c
• The above programs are available in all PnetCDF releases under directory examples/C.