Next: , Previous: , Up: Variables   [Index]


4.17 Read an Entire Variable ncmpi_get_var_<type>

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.

Data types

<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

Operational Mode

These API must be called while the file is in data mode.

Collective I/O

The corresponding collective APIs have the suffix name "_all" and must be called in collective data mode.

Usage

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.

Return Error Codes

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:

Example

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: , Previous: , Up: Variables   [Index]