Next: , Previous: NF_DEF_VAR, Up: Variables

6.4 Define Chunking Parameters for a Variable: NF_DEF_VAR_CHUNKING

The function NF_DEF_VAR_CHUNKING sets the storage parameters for a variable in a netCDF-4 file. It can set the chunk sizes to get chunked storage, or it can set the contiguous flag to get contiguous storage.

The total size of a chunk must be less than 4 GiB. That is, the product of all chunksizes and the size of the data (or the size of nc_vlen_t for VLEN types) must be less than 4 GiB.

This function may only be called after the variable is defined, but before nf_enddef is called. Once the chunking parameters are set for a variable, they cannot be changed.

Usage

     NF_DEF_VAR_CHUNKING(INTEGER NCID, INTEGER VARID, INTEGER STORAGE, INTEGER CHUNKSIZES)
ncid
NetCDF ID, from a previous call to NF_OPEN or NF_CREATE.
varid
Variable ID.
storage
If NF_CONTIGUOUS, then contiguous storage is used for this variable. Variables with one or more unlimited dimensions cannot use contiguous storage. If contiguous storage is turned on, the chunksizes parameter is ignored.

If NF_CHUNKED, then chunked storage is used for this variable. Chunk sizes may be specified with the chunksizes parameter. Default sizes will be used if chunking is required and this function is not called.

chunksizes
An array of chunk sizes. The array must have the one chunksize for each dimension in the variable. If contiguous storage is used, then the chunksizes parameter is ignored.

Errors

NF_DEF_VAR_CHUNKING 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 chunking 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_ESTRICTNC3
Trying to create a var some place other than the root group in a netCDF file with NF_STRICT_NC3 turned on.

Example

In this example from nf_test/ftst_vars.F, a file is created, two dimensions and a variable are defined, and the chunksizes of the data are set to the size of the data (that is, data will be written in one chunk). 

     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)