Previous: NF90_ABORT, Up: Datasets


2.13 NF90_SET_FILL

This function is intended for advanced usage, to optimize writes under some circumstances described below. The function NF90_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 NF90_FILL or NF90_NOFILL. The default behavior corresponding to NF90_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. See Fill Values, for more information on the use of fill values. See Attribute Conventions, for information about how to define your own fill values.

The behavior corresponding to NF90_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 NF90_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 NF90_SET_FILL again to explicitly set the fill mode to NF90_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 NF90_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 NF90_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

      function nf90_set_fill(ncid, fillmode, old_mode)
        integer, intent( in) :: ncid, fillmode
        integer, intent(out) :: old_mode
        integer              :: nf90_set_fill
ncid
NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.
fillmode
Desired fill mode for the dataset, either NF90_NOFILL or NF90_FILL.
old_mode
Returned current fill mode of the dataset before this call, either NF90_NOFILL or NF90_FILL.

Errors

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

Example

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

      use netcdf
      implicit none
      integer :: ncid, status, oldMode
      ...
      status = nf90_open("foo.nc", nf90_write, ncid)
      if (status /= nf90_noerr) call handle_err(status)
      ...
      ! Write data with prefilling behavior
      ...
      status = nf90_set_fill(ncid, nf90_nofill, oldMode)
      if (status /= nf90_noerr) call handle_err(status)
      ...
      !  Write data with no prefilling
      ...