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


4.12 Write a Subsampled Array of Values: ncmpi_put_vars_<type>

Each member of the family of functions ncmpi_put_vars_<type> writes a subsampled (strided) array section of values into a netCDF variable of an opened netCDF file. The subsampled array section is specified by giving a corner, a vector of counts, and a stride vector.

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_put_vars_<type>     (int                  ncid,
                                int                 varid,
                                const MPI_Offset    start[],
                                const MPI_Offset    count[],
                                const MPI_Offset    stride[],
                                const <C type>     *buf);

int ncmpi_put_vars             (int                 ncid,
                                int                 varid,
                                const MPI_Offset    start[],
                                const MPI_Offset    count[],
                                const MPI_Offset    stride[],
                                const void         *buf,
                                MPI_Offset          bufcount,
                                MPI_Datatype        buftype);

int ncmpi_put_vars_<type>_all (int                  ncid,
                                int                 varid,
                                const MPI_Offset    start[],
                                const MPI_Offset    count[],
                                const MPI_Offset    stride[],
                                const <C type>     *buf);

int ncmpi_put_vars_all         (int                 ncid,
                                int                 varid,
                                const MPI_Offset    start[],
                                const MPI_Offset    count[],
                                const MPI_Offset    stride[],
                                const 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.

start

A vector of MPI_Offset integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 0, so for example, the first data value of a variable would have index (0, 0, ... , 0). The elements of start correspond, in order, to the variable’s dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for writing the data values.

count

A vector of MPI_Offset integers specifying the number of indices selected along each dimension. To write a single value, for example, specify count as (1, 1, ... , 1). 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 write.

stride

A vector of MPI_Offset integers that specifies the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable’s dimensions (stride[0] gives the sampling interval along the most slowly varying dimension of the netCDF variable). Sampling intervals are specified in type-independent units of elements (a value of 1 selects consecutive elements of the netCDF variable along the corresponding dimension, a value of 2 selects every other element, etc.). A NULL stride argument is treated as (1, 1, ... , 1).

buf

Pointer to a block of data values to be written. The order in which the data will be written to the netCDF variable is with the last dimension of the specified variable varying fastest. If the type of data values 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 written to 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.

Layout Illustration for Write Buffer in Memory and Data Written in File

put_vars mapping

Return Error Codes

ncmpi_put_vars_<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 of using ncmpi_put_vars_float_all to write every other point of a netCDF variable named rh in parallel which is described by the C declaration float rh[4][6] (note the size of the dimensions). In this example, we assume there are 4 MPI processes running. The parallel write fills the entire 4x6 array.

#include <pnetcdf.h>
   ... 
#define NDIM 2                    /* rank of netCDF variable */
int ncid;                         /* netCDF ID */
int status;                       /* error status */
int rhid;                         /* variable ID */
MPI_Offset start[NDIM];           /* netCDF variable start point: first element */
MPI_Offset count[NDIM] = {2, 3};  /* size of internal array: entire (subsampled) netCDF variable */
MPI_Offset stride[NDIM] = {2, 2}; /* variable subsampling intervals: access every other netCDF element */
float rh[2][3];                   /* note subsampled sizes for netCDF variable dimensions */
   ... 
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_WRITE, MPI_INFO_NULL,  &ncid);
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
   ... 
/* set the starting indices and write lengths for this process */
MPI_Comm_rank(MPI_COMM_WORLD, &rank);
if (rank == 0) {
    start[0] = 0;
    start[1] = 0;                 /* write locations by process rank IDs:
} else if (rank == 1) {              0 1 0 1 0 1
    start[0] = 0;                    2 3 2 3 2 3
    start[1] = 1;                    0 1 0 1 0 1
} else if (rank == 2) {              2 3 2 3 2 3
    start[0] = 1;                  */
    start[1] = 0;
} else if (rank == 3) {
    start[0] = 1;
    start[1] = 1;
}
   ... 
status = ncmpi_put_vars_float_all(ncid, rhid, start, count, stride, rh);
if (status != NC_NOERR) handle_error(status);

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