Unidata

6.6 Define Chunking Parameters for a Variable: nc_def_var_chunking

The function nc_def_var_chunking sets the chunking parameters for a variable in a netCDF-4 file.

This function must be called after the variable is defined, but before nc_enddef is called. Once the chunking parameters are set, they cannot be changed.

Note that this does not work for scalar variables. Only non-scalar variables can have chunking.

Usage

     int nc_def_var_chunking(int ncid, int varid, int contiguous, int *chunksizesp);

ncid

NetCDF ID, from a previous call to nc_open or nc_create.

varid

Variable ID.

contiguous

If non-zero, 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.

*chunksizes

A pointer to an array list of chunk sizes. The array must have the one chunksize for each dimension in the variable. If the contiguous parameter is set, then the chunksizes parameter is ignored.

Errors

nc_def_var_chunking returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error.

Possible return codes include:

NC_NOERR

No error.

NC_BADID

Bad ncid.

NC_ENOTNC4

Not a netCDF-4 file.

NC_ENOTVAR

Can't find this variable.

NC_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 chunking for a variable.

NC_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 NC_STRICT_NC3 flag. (see nc_create).

NC_ESTRICTNC3

Trying to create a var some place other than the root group in a netCDF file with NC_STRICT_NC3 turned on.

NC_EPERM

Attempt to create object in read-only file.

Example

In this example from libsrc4/tst_vars2.c, chunksizes are set with nc_var_def_chunking, and checked with nc_var_inq_chunking.

        printf("**** testing chunking...");
        {
     #define NDIMS5 1
     #define DIM5_NAME "D5"
     #define VAR_NAME5 "V5"
     #define DIM5_LEN 1000
     
           int dimids[NDIMS5], dimids_in[NDIMS5];
           int varid;
           int ndims, nvars, natts, unlimdimid;
           nc_type xtype_in;
           char name_in[NC_MAX_NAME + 1];
           int data[DIM5_LEN], data_in[DIM5_LEN];
           int chunksize[NDIMS5] = {5};
           int chunksize_in[NDIMS5];
           int contiguous_in;
           int i, d;
     
           for (i = 0; i < DIM5_LEN; i++)
              data[i] = i;
     
           /* Create a netcdf-4 file with one dim and one var. */
           if (nc_create(FILE_NAME, NC_NETCDF4, &ncid)) ERR;
           if (nc_def_dim(ncid, DIM5_NAME, DIM5_LEN, &dimids[0])) ERR;
           if (dimids[0] != 0) ERR;
           if (nc_def_var(ncid, VAR_NAME5, NC_INT, NDIMS5, dimids, &varid)) ERR;
           if (nc_def_var_chunking(ncid, varid, 0, chunksize)) ERR;
           if (nc_put_var_int(ncid, varid, data)) ERR;
     
           /* Check stuff. */
           if (nc_inq_var_chunking(ncid, 0, &contiguous_in, chunksize_in)) ERR;
           for (d = 0; d < NDIMS5; d++)
              if (chunksize[d] != chunksize_in[d]) ERR;
           if (contiguous_in != 0) ERR;