4.24 Fill Values

Prior to version 1.6.1, PnetCDF supports only NC_NOFILL mode. Starting from 1.6.1, PnetCDF supports fill mode in a slightly different way from netCDF.

What happens when you try to read a value that was never written in an opened netCDF file? You might expect that this should always be an error, and that you should get an error message or an error status returned. You do get an error if you try to read data from a netCDF file that is not open for reading, if the variable ID is invalid for the specified netCDF file, or if the specified indices are not properly within the range defined by the dimension lengths of the specified variable. Otherwise, reading a value that was not written returns a special fill value used to fill in any undefined values when a netCDF variable is first written.

You may ignore fill values and use the entire range of a netCDF external data type, but in this case you should make sure you write all data values before reading them. If you know you will be writing all the data before reading it, you can specify that no pre-filling of variables with fill values will occur by calling ncmpi_def_var_fill after defining a non-record variable.

Differences from NetCDF

• Default fill mode – PnetCDF’s default mode is NC_NOFILL, while netCDF’s is NC_FILL.
• Filling a record variable – In PnetCDF, filling a record variable must be requested by calling ncmpi_fill_var_rec explicitly in the data mode, prior to write a new record. This API will fill only one record of a record variable. It will overwrite the contents of the record if the contents are previously written.

The variable attribute _FillValue may be used to specify the fill value for a variable. Their are default fill values for each type, defined in the include file pnetcdf.h: NC_FILL_CHAR, NC_FILL_BYTE, NC_FILL_SHORT, NC_FILL_INT, NC_FILL_FLOAT, and NC_FILL_DOUBLE. For CDF-5 file format, more default fill values are available for additional data types: NC_FILL_UBYTE, NC_FILL_USHORT, NC_FILL_UINT, NC_FILL_INT64, and NC_FILL_UINT64.

The netCDF byte and character types have different default fill values. The default fill value for characters is the zero byte, a useful value for detecting the end of variable-length C character strings. If you need a fill value for a byte variable, it is recommended that you explicitly define an appropriate _FillValue attribute, as generic utilities such as ncmpidump/ncdump will not assume a default fill value for byte variables.

Type conversion for fill values is identical to type conversion for other values: attempting to convert a value from one type to another type that can’t represent the value results in a range error. Such errors may occur on writing or reading values from a larger type (such as double) to a smaller type (such as float), if the fill value for the larger type cannot be represented in the smaller type.