•         advanced

6.6 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).

NC_DEF_VAR_DEFLATE must be called after the variable is defined, but before NC_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 NC_ENDDEF call. In netCDF-4 files NC_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, 0, chunks)
           if (retval .ne. nf_noerr) call handle_err(retval)
     
     C     Turn on deflate, fletcher32.
           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, 1)
           if (retval .ne. nf_noerr) call handle_err(retval)
     

Contact Us   •   Site Map   •   Search   •   Terms and Conditions   •   Privacy Policy   •   Participation Policy

Unidata is a member of the UCAR Office of Programs, is managed by the University Corporation for Atmospheric Research, and is sponsored by the National Science Foundation. P.O. Box 3000   •   Boulder, CO 80307-3000 USA   •   Tel: 303-497-8643   •   Fax: 303-497-8690