Next: ncmpi_put_vara_<type>, Previous: ncmpi_put_var1_<type>, Up: Variables [Index]
The ncmpi_put_var_<type> family of functions write all the values of a variable into a netCDF variable of an opened netCDF file. This is the simplest interface to use for writing a value in a scalar variable or whenever all the values of a multidimensional variable can all be written at once. 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. The values are converted to the external data type of the variable, if necessary.
Take care when using the simplest forms of this interface with record variables when you don’t specify how many records are to be written. If you try to write all the values of a record variable into a netCDF file that has no record data yet (hence has 0 records), nothing will be written. Similarly, if you try to write all of a record variable but there are more records in the file than you assume, more data may be written to the file than you supply, which may result in a segmentation violation.
Caution when using the same varid! Since this API writes the entire variable in the file, when there are multiple MPI processes making this call, collectively or independently, they will concurrently write to the same file space. If the contents of write buffers are different among processes, then the outcomes in file contents are undefined (data may come from any process).
<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 |
These API must be called while the file is in data mode.
The corresponding collective APIs have the suffix name "_all" and must be called in collective data mode. Users are recommended to avoid calling these collective APIs for the same varid, due to the possible conflicts in file contents. See the above note.
int ncmpi_put_var_<type> (int ncid, int varid, const <C type> *buf); int ncmpi_put_var (int ncid, int varid, const void *buf, MPI_Offset bufcount, MPI_Datatype buftype); int ncmpi_put_var_<type>_all (int ncid, int varid, const <C type> *buf); int ncmpi_put_var_all (int ncid, int varid, 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.
buf
Pointer to the data value to be written. 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.
ncmpi_put_var_<type> returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
Here is an example using ncmpi_put_var_double to 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 3 #define LATS 5 #define LONS 10 int status; /* error status */ int ncid; /* netCDF ID */ int rh_id; /* variable ID */ double rh_vals[TIMES*LATS*LONS]; /* array to hold values */ int i; ... /* open the 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); ... /* enter independent data mode */ status = ncmpi_begin_indep_data(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); ... for (i = 0; i < TIMES*LATS*LONS; i++) rh_vals[i] = 0.5; MPI_Comm_rank(MPI_COMM_WORLD, &rank); if (rank == 0) { /* MPI process rank 0 writes the whole variable */ status = ncmpi_put_var_double(ncid, rh_id, rh_vals); if (status != NC_NOERR) handle_error(status); } ... /* exit independent data mode */ status = ncmpi_end_indep_data(ncid); if (status != NC_NOERR) handle_error(status);
Next: ncmpi_put_vara_<type>, Previous: ncmpi_put_var1_<type>, Up: Variables [Index]