Next: ncmpi_get_vara_<type>, Previous: ncmpi_get_var1_<type>, Up: Variables [Index]
The members of the ncmpi_get_var_<type> family of functions read all the values from a netCDF variable of an opened netCDF file. This is the simplest interface to use for reading the value of a scalar variable or when all the values of a multidimensional variable can be read at once. The values are read into consecutive locations with the last dimension varying fastest.
Take care when using the simplest forms of this interface with record variables when you don’t specify how many records are to be read. If you try to read all the values of a record variable into an array but there are more records in the file than you assume, more data will be read than you expect, which may cause a segmentation violation.
<type > for API names | <C type> for API arguments |
text | char |
schar | signed char |
short | short |
int | int |
float | float |
double | double |
uchar | unsigned char |
ushort | unsigned short |
uint | unsigned int |
longlong | long long |
ulonglong | unsigned longlong |
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_var_<type> (int ncid, int varid, <C type> *buf); int ncmpi_get_var (int ncid, int varid, void *buf, MPI_Offset bufcount, MPI_Datatype buftype); int ncmpi_get_var_<type>_all (int ncid, int varid, <C type> *buf); int ncmpi_get_var_all (int ncid, int varid, void *buf, MPI_Offset bufcount, MPI_Datatype buftype);
ncid
NetCDF ID, from a previous call to ncmpi_open or ncmpi_create.
varid
Variable ID. Different MPI processes may use different variable IDs.
buf
Pointer to a block of contiguous locations in memory into which the data values are read. If the type of data value differs from the netCDF variable type, type conversion will occur.
bufcount
An integer indicates the number of MPI derived data type elements in the buf to be read from the file.
buftype
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_var_<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_var_double_all to read all the values of the variable named rh in parallel from an existing netCDF file 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 <pnetcdf.h> ... #define TIMES 3 #define LATS 5 #define LONS 10 int status; /* error status */ int ncid; /* netCDF ID */ int rh_id; /* variable ID */ double rh_vals[TIMES*LATS*LONS]; /* array to hold values */ ... /* 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); ... /* obtain variable ID */ status = ncmpi_inq_varid(ncid, "rh", &rh_id); if (status != NC_NOERR) handle_error(status); ... /* all processes read the whole variable in parallel (collectively) */ status = cmpi_get_var_double_all(ncid, rh_id, rh_vals); if (status != NC_NOERR) handle_error(status);
Next: ncmpi_get_vara_<type>, Previous: ncmpi_get_var1_<type>, Up: Variables [Index]