Next: , Previous: nc_get_vara_ type, Up: Variables


6.29 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.

The functions for types ubyte, ushort, uint, longlong, ulonglong, and string are only available for netCDF-4/HDF5 files.

The nc_get_vars() function will read a variable of any type, including user defined type. For this function, the type of the data in memory must match the type of the variable - no data conversion is done.

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)
     int nc_get_vars_ubyte (int ncid, int varid, const size_t *startp,
                            const size_t *countp, const ptrdiff_t *stridep,
                            unsigned char *ip);
     int nc_get_vars_ushort(int ncid, int varid, const size_t *startp,
                            const size_t *countp, const ptrdiff_t *stridep,
                            unsigned short *ip);
     int nc_get_vars_uint  (int ncid, int varid, const size_t *startp,
                            const size_t *countp, const ptrdiff_t *stridep,
                            unsigned int *ip);
     int nc_get_vars_longlong (int ncid, int varid, const size_t *startp,
                               const size_t *countp, const ptrdiff_t *stridep,
                               long long *ip);
     int nc_get_vars_ulonglong(int ncid, int varid, const size_t *startp,
                               const size_t *countp, const ptrdiff_t *stridep,
                               unsigned long long *ip);
     int nc_get_vars_string(int ncid, int varid, const size_t *startp,
                            const size_t *countp, const ptrdiff_t *stridep,
                            char **ip);
     int nc_get_vars       (int ncid, int varid,  const size_t *startp,
                            const size_t *countp, const ptrdiff_t *stridep,
                            void *ip);
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.

Note: setting any element of the count array to zero causes the function to exit without error, and without doing anything.

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.

Return Codes

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);
      ...