Go to the previous, next section.

Write a Single Data Value

The function ncvarput1 (or NCVPT1 or NCVP1C for FORTRAN) puts a single data value into a variable of an open netCDF file that is in data mode. Inputs are the netCDF ID, the variable ID, a multidimensional index that specifies which value to add or alter, and the data value.

In case of an error, ncvarput1 returns -1; NCVPT1 returns a nonzero value in rcode. Possible causes of errors include:

• The variable ID is invalid for the specified netCDF file.

• The specified indices were out of range for the dimensionality of the specified variable. For example, a negative index or an index that is larger than the corresponding dimension size will cause an error.

• The specified netCDF is in define mode rather than data mode.

• The specified netCDF ID does not refer to an open netCDF file.

ncvarput1: C Interface

int ncvarput1(int ncid, int varid, const long mindex[], const void *value);

ncid

NetCDF ID, returned from a previous call to ncopen or nccreate.

varid

Variable ID, returned from a previous call to ncvardef or ncvarid.

mindex

The multidimensional index of the the data value to be written. The indices are relative to 0, so for example, the first data value of a two-dimensional variable would have index (0,0). The elements of mindex must correspond to the variable's dimensions. Hence, if the variable is a record variable, the first index would correspond to the record number.

value

Pointer to the data value to be written. The pointer is declared to be of type void * because it can point to data of any of the basic netCDF types. The data should be of the appropriate type for the netCDF variable. Warning: neither the compiler nor the netCDF software can detect whether the wrong type of data is used.

Here is an example using ncvarput1 to set the (1,2,3) element 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, so we want to set the value of rh that corresponds to the second time value, the third lat value, and the fourth lon value:

#include "netcdf.h"
   ...
int  ncid;                         /* netCDF ID */
int  rh_id;                        /* variable ID */
static long rh_index[] = {1, 2, 3}; /* where to put value */
static double rh_val = 0.5;        /* value to put */
   ...
ncid = ncopen("foo.nc", NC_WRITE);
   ...
rh_id = ncvarid (ncid, "rh");
   ...
ncvarput1(ncid, rh_id, rh_index, (void *) &rh_val);

NCVPT1: FORTRAN Interface

      SUBROUTINE NCVPT1 (INTEGER NCID, INTEGER VARID,
     +                   INTEGER MINDEX(*), type VALUE,
     +                   INTEGER RCODE)

      SUBROUTINE NCVP1C (INTEGER NCID, INTEGER VARID,
     +                   INTEGER MINDEX(*), CHARACTER CHVAL,
     +                   INTEGER RCODE)

There are two FORTRAN subroutines, NCVPT1 and NCVP1C, for putting a single value in a variable. The first puts a numeric value in a variable of numeric type, and the second puts a character value in a variable of character type.

NCID

NetCDF ID, returned from a previous call to NCOPN or NCCRE.

VARID

Variable ID, returned from a previous call to NCVDEF or NCVID.

MINDEX

The multidimensional index of the the data value to be written. The indices are relative to 1, so for example, the first data value of a two-dimensional variable would have index (1,1). The elements of mindex must correspond to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the record number.

VALUE

For NCVPT1, the data value to be written. The data may be of a type corresponding to any of the netCDF types NCSHORT, NCLONG, NCFLOAT, or NCDOUBLE, but must be appropriate for the type of the netCDF variable. Warning: neither the compiler nor the netCDF software can detect whether the wrong type of data is used.

CHVAL

For NCVP1C, the data value to be written. The data should be of a type character, corresponding to the netCDF types NCCHAR or NCBYTE.

RCODE

Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCVPT1 to set the (4,3,2) element 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 lon, lat, and time, so we want to set the value of rh that corresponds to the fourth lon value, the third lat value, and the second time value:

      INCLUDE 'netcdf.inc'
         ...
      INTEGER  NCID, RCODE
      INTEGER  RHID               ! variable ID
      INTEGER  RHINDX(3)          ! where to put value
      DATA RHINDX /4, 3, 2/
         ...
      NCID = NCOPN ('foo.nc', NCWRITE, RCODE)
         ...
      RHID = NCVID (NCID, 'rh', RCODE)  ! get ID
      CALL NCVPT1 (NCID, RHID, RHINDX, 0.5, RCODE)

Go to the previous, next section.