4.9 Write a Subsampled Array of Values: nc_put_vars_ type

Each member of the family of functions nc_put_vars_ type writes a subsampled (strided) array section of values into a netCDF variable of an open netCDF dataset. The subsampled array section is specified by giving a corner, a vector of counts, and a stride vector. The netCDF dataset must be in data mode.

Usage

     int nc_put_vars_text  (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const char *tp);
     int nc_put_vars_uchar (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const unsigned char *up);
     int nc_put_vars_schar (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const signed char *cp);
     int nc_put_vars_short (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const short *sp);
     int nc_put_vars_int   (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const int *ip);
     int nc_put_vars_long  (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const long *lp);
     int nc_put_vars_float (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const float *fp);
     int nc_put_vars_double(int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const double *dp);

ncid

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

varid

Variable ID.

start

A vector of size_t integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 0, so for example, the first data value of a variable would have index (0, 0, ... , 0). The elements of start correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for writing the data values.

count

A vector of size_t integers specifying the number of indices selected along each dimension. To write a single value, for example, specify count as (1, 1, ... , 1). The elements of count correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first element of count corresponds to a count of the number of records to write.

stride

A vector of ptrdiff_t integers that specifies the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable's dimensions (stride[0] gives the sampling interval along the most slowly varying dimension of the netCDF variable). Sampling intervals are specified in type-independent units of elements (a value of 1 selects consecutive elements of the netCDF variable along the corresponding dimension, a value of 2 selects every other element, etc.). A NULL stride argument is treated as (1, 1, ... , 1).

tp

up

cp

sp

ip

lp

fp

dp

Pointer to a block of data values to be written. The order in which the data will be written to the netCDF variable is with the last dimension of the specified variable varying fastest. If the type of data values differs from the netCDF variable type, type conversion will occur. See Type Conversion.

Errors

nc_put_vars_ type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

• The variable ID is invalid for the specified netCDF dataset.
• The specified start, count and stride generate an index which is out of range.
• One or more of the specified values are out of the range of values representable by the external data type of the variable.
• The specified netCDF is in define mode rather than data mode.
• The specified netCDF ID does not refer to an open netCDF dataset.

Example

Here is an example of using nc_put_vars_float to write – from an internal array – every other point of a netCDF variable named rh which is described by the C declaration float rh[4][6] (note the size of the dimensions):

     #include <netcdf.h>
        ...
     #define NDIM 2                /* rank of netCDF variable */
     int ncid;                     /* netCDF ID */
     int status;                   /* error status */
     int rhid;                     /* variable ID */
     static size_t start[NDIM]     /* netCDF variable start point: */
                      = {0, 0};    /* first element */
     static size_t count[NDIM]     /* size of internal array: entire */
                        = {2, 3};  /* (subsampled) netCDF variable */
     static ptrdiff_t stride[NDIM] /* variable subsampling intervals: */
                      = {2, 2};    /* access every other netCDF element */
     float rh[2][3];               /* note subsampled sizes for */
                                   /* netCDF variable dimensions */
        ...
     status = nc_open("foo.nc", NC_WRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_varid(ncid, "rh", &rhid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_put_vars_float(ncid, rhid, start, count, stride, rh);
     if (status != NC_NOERR) handle_error(status);