4.10 Write an Entire Variable: ncmpi_put_var_<type>

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.

Note on unexpected data in file when run in parallel:

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

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

Usage

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.

Return Error Codes

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:

• 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_EINDEFINE: Operation not allowed in define mode.
• NC_EGLOBAL: NC_GLOBAL is considered invalid for these APIs.
• NC_ENOTVAR: Bad variable ID.
• NC_ECHAR: Attempt to convert numerical values to or from text data.
• 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 variable size. 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_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);