4.11 Write an Array of Values: ncmpi_put_vara_<type>

The function ncmpi_put_vara_<type> writes values into a netCDF variable of an opened netCDF file. The part of the netCDF variable to write is specified by giving a corner and a vector of edge lengths that refer to an array section of the netCDF variable. The values to be written are associated with the netCDF variable by assuming that the last dimension of the netCDF variable varies fastest in the C interface.

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

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

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

int ncmpi_put_vara_all         (int                 ncid,
                                int                 varid,
                                const MPI_Offset    start[],
                                const MPI_Offset    count[],
                                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 size of start must be the same as the number of dimensions of the specified variable. The elements of start must correspond to the variable’s dimensions in order. Hence, if the variable is a record variable, the first index would correspond to the starting record number for writing the data values.

count

A vector of MPI_Offset integers specifying the edge lengths along each dimension of the block of data values to be written. To write a single value, for example, specify count as (1, 1, ... , 1). The length of count is the number of dimensions of the specified variable. The elements of count correspond 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.

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

Return Error Codes

ncmpi_put_vara_<type> returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

• NC_EBADID: Bad ncid. The specified netCDF ID does not refer to an opened netCDF file.
• NC_EPERM: Attempt write operations in read-only 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 of the specified values are out of the range of values representable by the external data type of the variable. (Does not apply to the nc_put_vara() function).
• 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_EBADTYPE: Bad type.
• 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) mismatches the one calculated from count. 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_put_vara_double_all to write (or overwrite) the whole third record of the variable named rh in parallel in an existing netCDF file named foo.nc. For simplicity in this example, we assume that the number of total MPI processes running is 4 and we know that rh is dimensioned with time, lat, and lon, and that there are three time values, five lat values, and 4*10 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 */
MPI_Offset start[3]                /* start indices of array */
MPI_Offset count[3];               /* write lengths along each dimension */
double rh_vals[TIMES*LATS*LONS];   /* local write buffer */
int i;
   ... 
/* open file in writeable mode */
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_WRITE, 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);
   ... 
/* set the starting indices and write lengths for this process */
MPI_Comm_rank(MPI_COMM_WORLD, &rank);
start[0] = 3;
start[1] = 0;
start[2] = LONS * rank;
count[0] = 1;
count[1] = LATS;
count[2] = LONS;
   ... 
/* set the write contents */
for (i=0; i<TIMES*LATS*LONS; i++)
    rh_vals[i] = 0.5 + rank;

/* collectively write a record into variable "rh" */
status = ncmpi_put_vara_double_all(ncid, rh_id, start, count, rh_vals);
if (status != NC_NOERR) handle_error(status);

Full example C program

• put_vara.c
• block_cyclic.c
• collective_write.c
• column_wise.c
• flexible_api.c
• hints.c
• The above programs are available in all PnetCDF releases under directory examples/C.