The members of the ncmpi_get_vara_<type> family of functions read an array of values from a netCDF variable of an opened netCDF file. 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.
|<type > for API names||<C type> for API arguments|
These API must be called while the file is in data mode.
The corresponding collective APIs have the suffix name "_all" and must be called in collective data mode.
int ncmpi_get_vara_<type> (int ncid, int varid, const MPI_Offset start, const MPI_Offset count, <C type> *buf); int ncmpi_get_vara (int ncid, int varid, const MPI_Offset start, const MPI_Offset count, void *buf, MPI_Offset bufcount, MPI_Datatype buftype); int ncmpi_get_vara_<type>_all (int ncid, int varid, const MPI_Offset start, const MPI_Offset count, <C type> *buf); int ncmpi_get_vara_all (int ncid, int varid, const MPI_Offset start, const MPI_Offset count, void *buf, MPI_Offset bufcount, MPI_Datatype buftype);
NetCDF ID, from a previous call to ncmpi_open or ncmpi_create.
Variable ID. Different MPI processes may use different variable IDs.
A vector of MPI_Offset 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.
A vector of MPI_Offset 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.
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.
An integer indicates the number of MPI derived data type elements in the buf to be read from the file.
An MPI derived data type that describes the memory layout of buf. Starting from PnetCDF version 1.6.0, buftype can be MPI_DATATYPE_NULL. In this case, bufcount is ignored and the buf’s data type must match the type of the variable defined in the file - no data conversion will be done.
ncmpi_get_vara_<type> returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Here is an example using ncmpi_get_vara_double_all to read a whole record of the variable named rh in parallel from an existing netCDF file named foo.nc. For simplicity in this example, we assume that the number of total MPI processes running is 4 and we know that rh is dimensioned with time, lat, and lon, and that there are three time values, five lat values, and 4*10 lon values.
#include <pnetcdf.h> ... #define TIMES 3 #define LATS 5 #define LONS 10 int status; /* error status */ int ncid; /* netCDF ID */ int rh_id; /* variable ID */ MPI_Offset start; /* start at first value to be read */ MPI_Offset count; /* read lengths along each dimension */ double rh_vals[TIMES*LATS*LONS]; /* local buffer */ ... /* open the file in read-only mode */ status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_NOWRITE, MPI_INFO_NULL, &ncid); if (status != NC_NOERR) handle_error(status); ... /* inquire the variable ID */ status = ncmpi_inq_varid(ncid, "rh", &rh_id); if (status != NC_NOERR) handle_error(status); ... /* set the starting indices and read lengths for this process */ MPI_Comm_rank(MPI_COMM_WORLD, &rank); start = 3; start = 0; start = LONS * rank; count = 1; count = LATS; count = LONS; ... /* collectively read a record of variable "rh" */ status = ncmpi_get_vara_double_all(ncid, rh_id, start, count, rh_vals); if (status != NC_NOERR) handle_error(status);