4.16 Read a Single Data Value: ncmpi_get_var1_<type>

The functions ncmpi_get_var1_<type> get a single data value from a variable of an opened netCDF file that is in data mode. Inputs are the netCDF ID, the variable ID, a multidimensional index that specifies which value to get, and the address of a location into which the data value will be read. The value is converted from the external data type of the variable, if necessary.

Data types

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_var1_<type>     (int                  ncid,
                                int                 varid,
                                const MPI_Offset    index[],
                                <C type>           *buf);

int ncmpi_get_var1             (int                 ncid,
                                int                 varid,
                                const MPI_Offset    index[],
                                void               *buf,
                                MPI_Offset          bufcount,
                                MPI_Datatype        buftype);

int ncmpi_get_var1_<type>_all (int                  ncid,
                                int                 varid,
                                const MPI_Offset    index[],
                                <C type>           *buf);

int ncmpi_get_var1_all         (int                 ncid,
                                int                 varid,
                                const MPI_Offset    index[],
                                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.

index[]

The index of the data value to be read. The indices are relative to 0, so for example, the first data value of a two-dimensional variable would have index (0,0). The elements of index must correspond to the variable’s dimensions. Hence, if the variable is a record variable, the first index is the record number.

buf

Pointer to the location into which the data value is read. If the type of data values differs from the netCDF variable type, type conversion will

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_var1_<type> returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

• NC_EBADID: The specified netCDF ID does not refer to an opened netCDF file.
• NC_ENOTVAR: The variable ID is invalid for the specified netCDF file.
• NC_EGLOBAL: NC_GLOBAL is considered invalid for these APIs.
• NC_EINVALCOORDS: The specified corner indices were out of range for the rank of the specified variable. For example, a negative index, or an index that is larger than the corresponding dimension length will cause an error.
• NC_EEDGE: The specified edge lengths added to the specified corner would have referenced data out of range for the rank of the specified variable. For example, an edge length that is larger than the corresponding dimension length minus the corner index will cause an error.
• NC_ERANGE: One or more elements of the external variable are out of the range of values representable by the internal data type of read buffer, buf. (Does not apply to the ncmpi_get_var1() and ncmpi_get_var1_all()).
• NC_EINDEFINE: Operation not allowed in define mode.
• NC_ECHAR: Attempt to convert numerical values to or from text data.
• NC_ENOMEM: Out of memory.
• NC_EINDEP: Attempt collective I/O operations in independent data mode.
• NC_ENOTINDEP: Attempt independent I/O operations in collective data mode.
• NC_EIOMISMATCH: The number of variable elements requested in (bufcount, buftype) is not equal to one. This error may only occur for flexible APIs.
• NC_ENOTSUPPORT: Flexible APIs for NetCDF-4 files is not yet supported.

Example

Here is an example using ncmpi_get_var1_double_all to get the elements at starting indices (1+rank*10, 2+rank*10, 3+rank*10) of the variable named rh in parallel in 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. If run sequentially (i.e. one MPI process), this example is equivalent to to get the values of rh that corresponds to the second time value, the third lat value, and the fourth lon value:

#include <pnetcdf.h>
   ... 
int  status;                       /* error status */
int  rank;                         /* MPI process rank ID */
int  ncid;                         /* netCDF ID */
int  rh_id;                        /* variable ID */
MPI_Offset rh_index[] = {1, 2, 3}; /* where to get value from */
double rh_val;                     /* where to put it */
   ... 
/* Open 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 the variable ID */
status = ncmpi_inq_varid(ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
   ... 
/* Set the starting indices. Indices are different at each process */
MPI_Comm_rank(MPI_COMM_WORLD, &rank);
rh_index[0] += rank*10;
rh_index[1] += rank*10;
rh_index[2] += rank*10;

/* Each MPI process reads a single value from a different location of variable rh */
status = ncmpi_get_var1_double_all(ncid, rh_id, rh_index, &rh_val);
if (status != NC_NOERR) handle_error(status);