4.22 Read an Array of Values using filetype: ncmpi_get_vard

The function ncmpi_get_vard reads values from a netCDF variable of an opened netCDF file. The part of the netCDF variable to read is specified by an MPI derived data type whose flattened displacements are relative to the beginning file offset of the variable.

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_vard     (int           ncid,
                        int           varid,
                        MPI_Datatype  filetype,
                        void         *buf,
                        MPI_Offset    bufcount,
                        MPI_Datatype  buftype);

int ncmpi_get_vard_all (int           ncid,
                        int           varid,
                        MPI_Datatype  filetype,
                        void         *buf,
                        MPI_Offset    bufcount,
                        MPI_Datatype  buftype);

ncid

NetCDF ID, from a previous call to ncmpi_open or ncmpi_create.

varid

Variable ID. Starting from version 1.10.0, filetype argument may cover more than one variable. In this case, varid is the ID of the first variable. However, variables accessed by filetype must be either all fixed-size variables or all record variables. In addition, the variables accessed by filetype must be of the same external NC data type. Thie limitation allows the same data type conversion to perform on the entire read buffer. When calling the collective ncmpi_get_vard_all(), different MPI processes may use different variable IDs, ncid.

filetype

An MPI derived data type that describes the file access layout. The element datatype that is used to construct filetype must conformed with the external NC data type of the variable defined in the file, i.e. MPI_FLOAT being used to construct filetype vs. NC_FLOAT being the NC data type of the variable(s). Starting from version 1.10.0, filetype may cover more than one variable. In this case, all variables accessed by the filetype must be of the same NC data type. For record variables, accessing more than one record is possible. One might need the size of record block (i.e. the sum of single records of all record variables defined in the file) which can be obtained from a call to ncmpi_inq_recsize. In addition, filetype must meet the following MPI-IO requirement specified in MPI standard Chapter 13.3. File displacements of filetype must be non-negative and in a monotonically nondecreasing order. It is fine for filetype to be MPI_DATATYPE_NULL, which indicates a zero-length read request. For independent APIs, a zero-length request is returned immediately. For collective APIs, the process with a zero-length request will still proceed to participate the collective MPI operations inside the PnetCDF library.

buf

Pointer to the read buffer.

bufcount

An integer indicates the number of MPI derived data type elements in the buf to be read from the file. This argument is ignored if buftype is MPI_DATATYPE_NULL.

buftype

An MPI derived data type that describes the memory layout of buf. There can only be a single element data type contained in buftype. It is fine for buftype to be MPI_DATATYPE_NULL, which indicates the read buffer is contiguous and its amount is equal to the size of filetype. In this case, argument bufcount is ignored and users must ensure the memory space pointed by argument buf is at least of size of filetype.

Return Error Codes

ncmpi_get_vard 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_EINDEP: Attempt collective I/O operations in independent data mode.
• NC_ENOTINDEP: Attempt independent I/O operations in collective data mode.
• NC_EINDEFINE: Operation not allowed in define mode.
• NC_ENOTVAR: Bad varid, variable not found.
• NC_EGLOBAL: NC_GLOBAL is considered invalid for these APIs.
• NC_EMULTITYPES: Multiple different MPI element datatypes used in filetype or buftype.
• NC_ETYPE_MISMATCH: filetype’s element type mismatches the variable’s NC data type.
• NC_EIOMISMATCH: the number of element data types in filetype is not equal to (buftype * bufcount).
• NC_ENOTSUPPORT: This API for NetCDF-4 files is not yet supported.

Example

Here is an example using ncmpi_get_vard.

#include <pnetcdf.h>
   ... 
#define NY 2
#define NX 5

MPI_Offset start[2], count[2];
int array_of_sizes[2], array_of_subsizes[2], array_of_starts[2];
int buf[NY][NX];
MPI_Datatype filetype;
    ... 

MPI_Comm_size(MPI_COMM_WORLD, &nprocs);
MPI_Comm_rank(MPI_COMM_WORLD, &rank);

/* create an MPI derived data type */
array_of_sizes[0]    = 2;
array_of_sizes[1]    = NX*nprocs;
array_of_subsizes[0] = 2;
array_of_subsizes[1] = NX;
array_of_starts[0]   = 0;
array_of_starts[1]   = NX*rank;
MPI_Type_create_subarray(2, array_of_sizes, array_of_subsizes,
                         array_of_starts, MPI_ORDER_C,
                         MPI_INT, &filetype);
MPI_Type_commit(&filetype);

err = ncmpi_get_vard_all(ncid, varid, filetype, buf, 2*NX, MPI_INT);
if (err != NC_NOERR) handle_error(err);

Full example C program

• vard_int.c
• vard_mvars.c
• The above programs are available in all PnetCDF releases under directory examples/C.