Next: ncmpi_iget_var<kind>_<type>, Previous: ncmpi_rename_var, Up: Variables [Index]
The ncmpi_iput_var<kind>_<type> family of functions is the nonblocking version of the write functions. The nonblocking APIs have an additional argument, request. It can be used later to query the status of the put operation or wait for the write to complete.
A nonblocking put call indicates that the PnetCDF may start using (possible altering the contents of) the put buffer. The caller should not access any part of the put buffer after a nonblocking put is called, until the put completes.
<kind>: <none>, ’1’, ’a’, ’s’, or ’m’.
<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 |
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.
int ncmpi_iput_var_<type> (int ncid, int varid, const <C type> *buf, int *request); int ncmpi_iput_var1_<type> (int ncid, int varid, const MPI_Offset start[], const <C type> *buf, int *request); int ncmpi_iput_vara_<type> (int ncid, int varid, const MPI_Offset start[], const MPI_Offset count[], const <C type> *buf, int *request); int ncmpi_iput_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_iput_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_iput_var (int ncid, int varid, const void *buf, MPI_Offset bufcount, MPI_Datatype buftype, int *request); int ncmpi_iput_var1 (int ncid, int varid, const MPI_Offset start[], const void *buf, MPI_Offset bufcount, MPI_Datatype buftype, int *request); int ncmpi_iput_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_iput_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_iput_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.
Starting from 1.7.0, the request argument can be NULL, meaning the caller does not intend to track the requests IDs. In this case, a call to ncmpi_wait_all/ncmpi_wait must use NC_REQ_ALL in its second argument "num" to flush all pending nonblocking requests.
ncmpi_iput_var<kind>_<type> returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Below is an example using ncmpi_iput_vara_double to write 10 variables. For simplicity in this example, we assume that the 10 variables have been defined.
#include <pnetcdf.h> ... int i; int ncid; /* netCDF ID */ int varid; /* variable ID */ int status; /* error status */ int request[10]; /* nonblocking request ID */ int statuses[10]; /* status for individual requests */ MPI_Offset start[10][2]; /* 10 sets of start indices */ MPI_Offset count[10][2]; /* 10 sets of count lengths */ double *buffers[10]; /* 10 write buffers */ ... status = ncmpi_create(MPI_COMM_WORLD, "foo.nc", NC_WRITE, MPI_INFO_NULL, &ncid); if (status != NC_NOERR) handle_error(status); ... /* define dimensions */ /* define variables */ /* set values for start and count */ /* allocate write buffers and assign their values */ ... for (i=0; i<10; i++) { /* post a nonblocking write request */ status = ncmpi_iput_vara_double(ncid, varid, start[i], count[i], buffers[i], &request[i]); if (status != NC_NOERR) handle_error(status); } /* write all 10 requests to the file at once */ status = ncmpi_wait_all(ncid, 10, request, statuses); if (status != NC_NOERR) handle_error(status); for (i=0; i<10; i++) /* check status for each request */ if (statuses[i] != NC_NOERR) handle_error(statuses[i]);
Next: ncmpi_iget_var<kind>_<type>, Previous: ncmpi_rename_var, Up: Variables [Index]