Next: , Previous: NF_INQ_VAR_FILL, Up: Variables


6.10 Define Compression Parameters for a Variable: NF_DEF_VAR_DEFLATE

The function NF_DEF_VAR_DEFLATE sets the deflate parameters for a variable in a netCDF-4 file.

When using parallel I/O for writing data, deflate cannot be used. This is because the compression makes it impossible for the HDF5 library to exactly map the data to disk location.

(Deflated data can be read with parallel I/O).

NF_DEF_VAR_DEFLATE must be called after the variable is defined, but before NF_ENDDEF is called.

Usage

     NF_DEF_VAR_DEFLATE(INTEGER NCID, INTEGER VARID, INTEGER SHUFFLE, INTEGER DEFLATE,
                        INTEGER DEFLATE_LEVEL);
NCID
NetCDF ID, from a previous call to NF_OPEN or NF_CREATE.
VARID
Variable ID.
SHUFFLE
If non-zero, turn on the shuffle filter.
DEFLATE
If non-zero, turn on the deflate filter at the level specified by the deflate_level parameter.
DEFLATE_LEVEL
Must be between 0 (no deflate, the default) and 9 (slowest, but “best” deflate).

If set to zero, no deflation takes place and the def_var_deflate call is ignored. This is slightly different from HDF5 handing of 0 deflate, which turns on the filter but makes only trivial changes to the data.

Informal testing at NetCDF World Headquarters suggests that there is little to be gained (with the limited set of test data used here), in setting the deflate level above 2 or 3.

Errors

NF_DEF_VAR_DEFLATE returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error.

Possible return codes include:

NF_NOERR
No error.
NF_BADID
Bad ncid.
NF_ENOTNC4
Not a netCDF-4 file.
NF_ENOTVAR
Can't find this variable.
NF_ELATEDEF
This variable has already been the subject of a NF_ENDDEF call. In netCDF-4 files NF_ENDDEF will be called automatically for any data read or write. Once enddef has been called, it is impossible to set the deflate for a variable.
NF_ENOTINDEFINE
Not in define mode. This is returned for netCDF classic or 64-bit offset files, or for netCDF-4 files, when they were been created with NF_STRICT_NC3 flag. (see NF_CREATE).
NF_EPERM
Attempt to create object in read-only file.
NF_EINVAL
Invalid deflate_level. The deflate level must be between 0 and 9, inclusive.

Example

In this example from nf_test/ftst_vars.F, a file is created with two dimensions and one variable. Chunking, deflate, and the fletcher32 filter are turned on. The deflate level is set to 4 below.

     C     Create the netCDF file.
           retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
           if (retval .ne. nf_noerr) call handle_err(retval)
     
     C     Define the dimensions.
           retval = nf_def_dim(ncid, "x", NX, x_dimid)
           if (retval .ne. nf_noerr) call handle_err(retval)
           retval = nf_def_dim(ncid, "y", NY, y_dimid)
           if (retval .ne. nf_noerr) call handle_err(retval)
     
     C     Define the variable.
           dimids(1) = y_dimid
           dimids(2) = x_dimid
           retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
           if (retval .ne. nf_noerr) call handle_err(retval)
     
     C     Turn on chunking.
           chunks(1) = NY
           chunks(2) = NX
           retval = NF_DEF_VAR_CHUNKING(ncid, varid, NF_CHUNKED, chunks)
           if (retval .ne. nf_noerr) call handle_err(retval)
     
     C     Turn on deflate compression, fletcher32 checksum.
           retval = NF_DEF_VAR_deflate(ncid, varid, 0, 1, 4)
           if (retval .ne. nf_noerr) call handle_err(retval)
           retval = NF_DEF_VAR_FLETCHER32(ncid, varid, NF_FLETCHER32)
           if (retval .ne. nf_noerr) call handle_err(retval)