Next: , Previous: nc_get_var_ type, Up: Variables


4.13 Read an Array of Values: nc_get_vara_ type

The members of the nc_get_vara_ type family of functions read an array of values from a netCDF variable of an open netCDF dataset. The array is specified by giving a corner and a vector of edge lengths. The values are read into consecutive locations with the last dimension varying fastest. The netCDF dataset must be in data mode.

Usage

     int nc_get_vara_text  (int ncid, int varid, const size_t start[],
                            const size_t count[] char *tp);
     int nc_get_vara_uchar (int ncid, int varid, const size_t start[],
                            const size_t count[] unsigned char *up);
     int nc_get_vara_schar (int ncid, int varid, const size_t start[],
                            const size_t count[] signed char *cp);
     int nc_get_vara_short (int ncid, int varid, const size_t start[],
                            const size_t count[] short *sp);
     int nc_get_vara_int   (int ncid, int varid, const size_t start[],
                            const size_t count[] int *ip);
     int nc_get_vara_long  (int ncid, int varid, const size_t start[],
                            const size_t count[] long *lp);
     int nc_get_vara_float (int ncid, int varid, const size_t start[],
                            const size_t count[] float *fp);
     int nc_get_vara_double(int ncid, int varid, const size_t start[],
                            const size_t count[] 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 length of start must be the same as the number of dimensions of the specified variable. The elements of start correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index would correspond to the starting record number for reading the data values.
count
A vector of size_t integers specifying the edge lengths along each dimension of the block of data values to be read. To read a single value, for example, specify count as (1, 1, ... , 1). The length of count is the number of dimensions of the specified variable. 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.
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_vara_ 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 using nc_get_vara_double to read all the values 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};
     double rh_vals[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 values from netCDF variable */
     status = nc_get_vara_double(ncid, rh_id, start, count, rh_vals);
     if (status != NC_NOERR) handle_error(status);