4.30 Nonblocking Buffered Write a Subarray: ncmpi_bput_<kind>_<type>

The ncmpi_bput_var<kind>_<type> family of functions is the buffered version of the nonblocking write functions ncmpi_iput_var<kind>_<type>.

The write data is buffered (cached) internally by PnetCDF and will be flushed to the file at the time of calling ncmpi_wait() or ncmpi_wait_all(). Unlike ncmpi_iput_var<kind>_<type>, once the call to this API returns, the caller is free to change the contents of write buffer.

<kind>: <none>, ’1’, ’a’, ’s’, or ’m’.

Data types

Operational Mode

Prior to version 1.7.0, nonblocking APIs must be called while the netCDF file is in data mode. Starting from 1.7.0, nonblocking APIs can be called in either define or data mode. This API family can be called in either collective or independent data mode.

Usage

int ncmpi_buffer_attach    (int         ncid,
                            MPI_Offset  bufsize);
                                       
int ncmpi_buffer_detach    (int ncid);

int ncmpi_bput_var_<type>  (int               ncid,
                            int                varid,
                            const <C type>   *buf,
                            int               *request);

int ncmpi_bput_var1_<type> (int               ncid,
                            int                varid,
                            const MPI_Offset   start[],
                            const <C type>   *buf,
                            int               *request);

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

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

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

Flexible APIs:

int ncmpi_bput_var  (int                ncid,
                     int                varid,
                     const void        *buf,
                     MPI_Offset         bufcount,
                     MPI_Datatype       buftype,
                     int               *request);

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

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

int ncmpi_bput_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               *request);

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

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).

imap

A vector of MPI_Offset integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. The elements of the index mapping vector correspond, in order, to the netCDF variable’s dimensions (imap[0] gives the distance between elements of the internal array corresponding to the most slowly varying dimension of the netCDF variable). Distances between elements are specified in type-independent units of elements (the distance between internal elements that occupy adjacent memory locations is 1 and not the element’s byte-length as in netCDF 2). A NULL argument means the memory-resident values have the same structure as the associated netCDF variable.

buf

Pointer to the location used for computing where the data values will be found; the data should be of the type appropriate for the function called. 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.

request

The nonblocking request ID returned by PnetCDF. It is to be used in a successive call to ncmpi_wait_all() or ncmpi_wait() for the completion of the nonblocking operation.

bufsize

The size of buffer users allow PnetCDF to allocate and use internally. The internal buffer will be used to aggregate multiple nonblocking buffered requests for better performance. The value can be different across processes.

Return Error Codes

ncmpi_bput_var<kind>_<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_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 ncmpi_get_var() and ncmpi_get_var_all()). Note NC_ERANGE is not a fatal error. The nonblocking request will be still added to the queue when NC_ERANGE is returned. Users are responsible to ensure no pending request exists when closing the file.
• NC_ECHAR: Attempt to convert numerical values to or from text data.
• NC_ENOMEM: Out of memory.
• NC_ENULLSTART: It is illegal for argument starts being a NULL.
• NC_EINSUFFBUF: The attached buffer ran out of space.
• 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: This API for NetCDF-4 files is not yet supported.

Example

Here is an example using ncmpi_bput_vara_double to add or change all the values of the variable named rh to 0.5 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, and that there are three time values, five lat values, and ten lon values.

#include <pnetcdf.h>
   ...
#define TIMES 0
#define LATS  5
#define LONS  10
int  status;                       /* error status */
int  ncid;                         /* netCDF ID */
int  rh_id;                        /* variable ID */
int  request[2];                   /* nonblocking request ID */
int  st[2];                        /* nonblocking request status */
MPI_Offset start[3] = {0, 0, 0};    /* start at first value */
MPI_Offset count[3] = {TIMES, LATS/2, LONS/2};
double rh_vals[LATS/2*LONS/2];   /* array to hold values */
int i;
   ...
status = ncmpi_create(MPI_COMM_WORLD, "foo.nc", NC_CLOBBER | NC_64BIT_DATA, MPI_INFO_NULL, &ncid);
if (status != NC_NOERR) handle_error(status);
   ...
/* define dimensions and variable */
   ...

/* attach buffer */
status = ncmpi_buffer_attach(ncid, LATS*LONS*sizeof(double));
if (status != NC_NOERR) handle_error(status);

/* write values into netCDF variable */
status = ncmpi_bput_vara_double(ncid, rh_id, start, count, rh_vals, &request[0]);
if (status != NC_NOERR) handle_error(status);

start[1] = LATS/2;
start[2] = LONS/2;
count[1] = LATS - LATS/2;
count[2] = LONS - LONS/2;
/* change contents of rh_vals[] */
status = ncmpi_bput_vara_double(ncid, rh_id, start, count, rh_vals, &request[1]);
if (status != NC_NOERR) handle_error(status);

status = ncmpi_wait_all(ncid, 2, request, st);
if (status != NC_NOERR) handle_error(status);

status = ncmpi_buffer_detach(ncid);
if (status != NC_NOERR) handle_error(status);

Full example C program

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