Next: , Previous: nc_def_var, Up: Variables


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. It can set the chunk sizes to get chunked storage, or it can set the contiguous flag to get contiguous storage.

Variables that make use of one or more unlimited dimensions, compression, or checksums must use chunking. Such variables are created with default chunk sizes of 1 for each unlimited dimension and the dimension length for other dimensions, except that if the resulting chunks are too large, the default chunk sizes for non-record dimensions are reduced.

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 nc_enddef is called. Once the chunking parameters are set for a variable, they cannot be changed. This function can be used to change the default chunking for record, compressed, or checksummed variables before nc_enddef is called.

Note that you cannot set chunking for scalar variables. Only non-scalar variables can have chunking.

Usage

     int nc_def_var_chunking(int ncid, int varid, int storage, size_t *chunksizesp);
ncid
NetCDF ID, from a previous call to nc_open or nc_create.
varid
Variable ID.
storage
If NC_CONTIGUOUS, then contiguous storage is used for this variable. Variables with chunking, compression, checksums, or one or more unlimited dimensions cannot use contiguous storage.

If NC_CHUNKED, then chunked storage is used for this variable. Chunk sizes may be specified with the chunksizes parameter or default sizes will be used if that parameter is NULL.

By default contiguous storage is used for fix-sized variables when conpression, chunking, and checksums are not used.

*chunksizes
A pointer to an array list of chunk sizes. The array must have one chunksize for each dimension of the variable.

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_EBADID
Bad ncid.
NC_EINVAL
Invalid input. This can occur if contiguous storage is set on a variable which uses compression, checksums, or one or more unlimited dimensions.
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 nc_enddef has been called after the nc_def_var call for a variable, it is impossible to set the chunking for that 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];
           size_t chunksize[NDIMS5] = {5};
           size_t chunksize_in[NDIMS5];
           int storage_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 (nc_def_var(ncid, VAR_NAME5, NC_INT, NDIMS5, dimids, &varid)) ERR;
           if (nc_def_var_chunking(ncid, varid, NC_CHUNKED, chunksize)) ERR;
           if (nc_put_var_int(ncid, varid, data)) ERR;
     
           /* Check stuff. */
           if (nc_inq_var_chunking(ncid, varid, &storage_in, chunksize_in)) ERR;
           for (d = 0; d < NDIMS5; d++)
              if (chunksize[d] != chunksize_in[d]) ERR;
           if (storage_in != NC_CHUNKED) ERR;