Next: , Previous: nc_get_vara_ type, Up: Variables


4.14 Read a Subsampled Array of Values: nc_get_vars_ type

The nc_get_vars_ type family of functions read a subsampled (strided) array section of values from a netCDF variable of an open netCDF dataset. The subsampled array section is specified by giving a corner, a vector of edge lengths, and a stride vector. The values are read with the last dimension of the netCDF variable varying fastest. The netCDF dataset must be in data mode.

Usage

     int nc_get_vars_text  (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            char *tp);
     int nc_get_vars_uchar (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            unsigned char *up);
     int nc_get_vars_schar (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            signed char *cp);
     int nc_get_vars_short (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            short *sp);
     int nc_get_vars_int   (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            int *ip);
     int nc_get_vars_long  (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            long *lp);
     int nc_get_vars_float (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            float *fp);
     int nc_get_vars_double(int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            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 read. 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 reading the data values.
count
A vector of size_t integers specifying the number of indices selected along each dimension. To read 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 read.
stride
A vector of ptrdiff_t integers specifying, for each dimension, the interval between selected indices. The elements of the stride vector correspond, in order, to the variable's dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. A NULL stride argument is treated as (1, 1, ... , 1).
tp
up
cp
sp
ip
lp
fp
dp
Pointer to the location into which the data value is read. If the type of data value differs from the netCDF variable type, type conversion will occur. See Type Conversion.

Errors

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

Example

Here is an example that uses nc_get_vars_double to read every other value in each dimension of the variable named rh from an existing netCDF dataset named foo.nc. For simplicity in this example, we assume that we know that rh is dimensioned with time, lat, and lon, and that there are three time values, five lat values, and ten lon values.

     #include <netcdf.h>
        ...
     #define TIMES 3
     #define LATS  5
     #define LONS 10
     int  status;                          /* error status */
     int ncid;                             /* netCDF ID */
     int rh_id;                            /* variable ID */
     static size_t start[] = {0, 0, 0};    /* start at first value */
     static size_t count[] = {TIMES, LATS, LONS};
     static ptrdiff_t stride[] = {2, 2, 2};/* every other value */
     double data[TIMES][LATS][LONS];       /* array to hold values */
      ...
     status = nc_open("foo.nc", NC_NOWRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
      ...
     status = nc_inq_varid (ncid, "rh", &rh_id);
     if (status != NC_NOERR) handle_error(status);
      ...
     /* read subsampled values from netCDF variable into array */
     status = nc_get_vars_double(ncid, rh_id, start, count, stride,
                                 &data[0][0][0]);
     if (status != NC_NOERR) handle_error(status);
      ...