Next: , Previous: nc_put_var_ type, Up: Variables


6.23 Write an Array of Values: nc_put_vara_ type

The function nc_put_vara_ type writes values into a netCDF variable of an open netCDF dataset. 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. The netCDF dataset must be in data mode.

The functions for types ubyte, ushort, uint, longlong, ulonglong, and string are only available for netCDF-4/HDF5 files.

The nc_put_var() function will write a variable of any type, including user defined type. For this function, the type of the data in memory must match the type of the variable - no data conversion is done.

Usage

     int nc_put_vara_ type (int ncid, int varid, const size_t start[],
                            const size_t count[], const type *valuesp);
     int nc_put_vara_text  (int ncid, int varid, const size_t start[],
                            const size_t count[], const char *tp);
     int nc_put_vara_uchar (int ncid, int varid, const size_t start[],
                            const size_t count[], const unsigned char *up);
     int nc_put_vara_schar (int ncid, int varid, const size_t start[],
                            const size_t count[], const signed char *cp);
     int nc_put_vara_short (int ncid, int varid, const size_t start[],
                            const size_t count[], const short *sp);
     int nc_put_vara_int   (int ncid, int varid, const size_t start[],
                            const size_t count[], const int *ip);
     int nc_put_vara_long  (int ncid, int varid, const size_t start[],
                            const size_t count[], const long *lp);
     int nc_put_vara_float (int ncid, int varid, const size_t start[],
                            const size_t count[], const float *fp);
     int nc_put_vara_double(int ncid, int varid, const size_t start[],
                            const size_t count[], const double *dp);
     int nc_put_vara_ubyte (int ncid, int varid, const size_t *startp,
                            const size_t *countp, const unsigned char *op);
     int nc_put_vara_ushort(int ncid, int varid, const size_t *startp,
                            const size_t *countp, const unsigned short *op);
     int nc_put_vara_uint  (int ncid, int varid, const size_t *startp,
                            const size_t *countp, const unsigned int *op);
     int nc_put_vara_longlong (int ncid, int varid, const size_t *startp,
                               const size_t *countp, const long long *op);
     int nc_put_vara_ulonglong(int ncid, int varid, const size_t *startp,
                               const size_t *countp, const unsigned long long *op);
     int nc_put_vara_string(int ncid, int varid, const size_t *startp,
                            const size_t *countp, const char **op);
     int nc_put_vara       (int ncid, int varid,  const size_t *startp,
                            const size_t *countp, const void *op);
ncid
NetCDF ID, from a previous call to nc_open or nc_create.
varid
Variable ID.
start
A vector of size_t 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 size_t 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.

Note: setting any element of the count array to zero causes the function to exit without error, and without doing anything.

tp
up
cp
sp
ip
lp
fp
dp
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. See Type Conversion.

Return Codes

Example

Here is an example using nc_put_vara_double to add or change all the values of the variable named rh to 0.5 in an existing netCDF dataset 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 <netcdf.h>
        ...
     #define TIMES 3
     #define LATS  5
     #define LONS  10
     int  status;                       /* error status */
     int  ncid;                         /* netCDF ID */
     int  rh_id;                        /* variable ID */
     static size_t start[] = {0, 0, 0}; /* start at first value */
     static size_t count[] = {TIMES, LATS, LONS};
     double rh_vals[TIMES*LATS*LONS];   /* array to hold values */
     int i;
        ...
     status = nc_open("foo.nc", NC_WRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_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;
     /* write values into netCDF variable */
     status = nc_put_vara_double(ncid, rh_id, start, count, rh_vals);
     if (status != NC_NOERR) handle_error(status);