NetCDF User's Guide - ncvarputg NCVPTG and NCVPGC

Go to the previous, next section.

Write a Generalized Hyperslab of Values

The function ncvarputg (or NCVPTG or NCVPGC for FORTRAN) writes a generalized hyperslab of values into a netCDF variable of an open netCDF file. The generalized hyperslab is specified by giving a corner, a vector of edge lengths, a stride vector, and an index mapping vector. No assumptions are made about the ordering or size of the dimensions of the data array. The netCDF file must be in data mode.

In case of an error, ncvarputg returns -1; NCVPTG and NCVPGC return a nonzero value in rcode. Possible causes of errors include:

The variable ID is invalid for the specified netCDF file.
The specified corner 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 edge lengths and strides added to the specified corner would have referenced data out of range for the dimensionality of the specified variable. For example, an edge length that is larger than the corresponding dimension size minus the corner index will cause an error, as will accessing two or more points using a stride that is greater than the size of the netCDF variable in the corresponding dimension.
A non-positive stride.
The specified netCDF is in define mode rather than data mode.
The specified netCDF ID does not refer to an open netCDF file.

ncvarputg: C Interface

int ncvarputg(int ncid, int varid, const long start[], const long count[],
              const long stride[], const long imap[], const void *values);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
varid: Variable ID, returned from a previous call to ncvardef or ncvarid.
start: A vector of long integers specifying the multidimensional index of the corner of the hyperslab 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 long integers specifying the multidimensional edge lengths from the corner of the hyperslab where the first of the data values will be written. To write a single value, for example, specify count as (1, 1, ..., 1). The size 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.
stride: A vector of long integers specifying, for each dimension, the interval between the accessed values of a netCDF variable. The size of the vector shall be at least the number of dimensions of the associated netCDF variable and its elements shall correspond, in order, to the variable's dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. A NULL stride argument obtains the default behavior in which adjacent values are accessed along each dimension.
imap: A vector of long integers specifying, for each dimension, how data values associated with a netCDF variable are arranged in memory. The offset, in bytes, from the memory location pointed to by the value argument to a particular datum is given by the inner product of the index mapping vector with the coordinates of the datum. (The inner product of two vectors [x0, x1, ..., xn] and [y0, y1, ..., yn] is just x0*y0 + x1*y1 + ... + xn*yn.) The vector may contain negative values if the value argument is appropriately specified. A NULL argument obtains the default behavior in which the memory-resident values are assumed to have the same structure as the associated netCDF variable.
value: 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 generalized hyperslab varying fastest. The pointer is declared to be of the 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 ncvarputg to add or change every other value in each dimension of the variable named rh to 0.5 in an existing netCDF file named `foo.nc'. Values are taken, using the same dimensional strides, from points in a 3-dimensional array of structures whose dimensions are the reverse of the netCDF variable. 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  ncid;                         /* netCDF ID */
int  rh_id;                        /* variable ID */
static long start[] = {0, 0, 0};   /* start at first value */
static long count[] = {TIMES, LATS, LONS};
static long stride[] = {2, 2, 2};  /* every other value */
long imap[3];                      /* set to reverse of variable */
struct datum {
    int    dummy;                  /* to illustrate mapping vector */
    double rh_val;                 /* actual value to be written */
}      data[LONS][LATS][TIMES];    /* reversed array to hold values. */
int itime, ilat, ilon;
   ...
ncid = ncopen("foo.nc", NC_WRITE);
   ...
rh_id = ncvarid (ncid, "rh");
   ...
for (ilon = 0; ilon < LONS; ilon += stride[2])
    for (ilat = 0; ilat < LATS; ilat += stride[1])
        for (itime = 0; itime < TIMES; itime += stride[0])
            data[ilon][ilat][itime].rh_val = 0.5;
/* access every `stride' in-memory value using reversed dimensions */
imap[0] = stride[2]*sizeof(struct datum);
imap[1] = stride[1]*(1+(LONS-1)/stride[0])*imap[0];
imap[2] = stride[0]*(1+(LATS-1)/stride[1])*imap[1];
/* write generalized hyperslab of values into netCDF variable */
ncvarputg(ncid, rh_id, start, count, stride, imap, (void*)&data[0][0][0].rh_val);

NCVPTG, NCVPGC: FORTRAN Interface

      SUBROUTINE NCVPTG (INTEGER NCID, INTEGER VARID,
     +                   INTEGER START(*), INTEGER COUNT(*),
     +                   INTEGER STRIDE(*), INTEGER IMAP(*),
     +                   type VALUES, INTEGER RCODE)

      SUBROUTINE NCVPGC (INTEGER NCID, INTEGER VARID,
     +                   INTEGER START(*), INTEGER COUNT(*),
     +                   INTEGER STRIDE(*), INTEGER IMAP(*),
     +                   CHARACTER*(*) STRING, INTEGER RCODE)

There are two FORTRAN subroutines, NCVPTG and NCVPGC, for writing a generalized hyperslab of values into a netCDF variable. The first writes numeric values into a variable of numeric type, and the second writes character values into 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.
START: A vector of integers specifying the multidimensional index of the corner of the hyperslab where the first of the data values will be written. The indices are relative to 1, so for example, the first data value of a variable would have index (1, 1, ..., 1). 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 last index would correspond to the starting record number for writing the data values.
COUNT: A vector of integers specifying the multidimensional edge lengths from the corner of the hyperslab where the first of the data values will be written. To write a single value, for example, specify COUNT as (1, 1, ..., 1). The size 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 last element of COUNT corresponds to a count of the number of records to write.
STRIDE: A vector of integers specifying, for each dimension, the interval between the accessed values of a netCDF variable or the value 0. The size of the vector shall be at least the number of dimensions of the associated netCDF variable and its elements shall correspond, in order, to the variable's dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. An 0 argument obtains the default behavior in which adjacent values are accessed along each dimension.
IMAP: A vector of long integers specifying, for each dimension, how data values associated with a netCDF variable are arranged in memory or the value 0. The offset, in bytes, from the memory location pointed to by the value argument to a particular datum is given by the inner product of the index mapping vector with the (origin-0) coordinates of the datum. (The inner product of two vectors [x1, x2, ..., xn] and [y1, y2, ..., yn] is just x1*y1 + x2*y2 + ... + xn*yn.) The vector may contain negative values if the value argument is appropriately specified. A 0 argument obtains the default behavior in which the memory-resident values are assumed to have the same structure as the associated netCDF variable.
VALUES: For NCVPTG, the block of data values to be written. The order in which the data will be written from the specified hyperslab is with the first dimension of the generalized hyperslab varying fastest (like the ordinary FORTRAN convention). 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.
STRING: For NCVPGC, the characters to be written. The order in which the characters will be written to the netCDF variable is with the first dimension of the generalized hyperslab varying fastest (like the FORTRAN convention). The data may be of a type corresponding to the netCDF types NCCHAR or NCBYTE.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCVPTG to add or change every other value in each dimension of the variable named rh to 0.5 in an existing netCDF file named `foo.nc'. Values are taken, using the same dimensional strides, from a 2-parameter array whose dimensions are the reverse of the netCDF variable. For simplicity in this example, we assume that we know that rh is dimensioned with lon, lat, and time, and that there are ten lon values, five lat values, and three time values.

      INCLUDE 'netcdf.inc'
         ...
      PARAMETER (NDIMS=3)         ! number of dimensions
      PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension sizes
      INTEGER  NCID, RCODE
      INTEGER  RHID               ! variable ID
      INTEGER  START(NDIMS), COUNT(NDIMS),
     +         STRIDE(NDIMS), IMAP(NDIMS)  ! generalized hyperslab
      DOUBLE DATA(2, TIMES, LATS, LONS)    ! rh is second parameter
      DATA START /1, 1, 1/        ! start at first value
      DATA COUNT /LONS, LATS, TIMES/
      DATA STRIDE /2, 2, 2/
         ...
      NCID = NCOPN ('foo.nc', NCWRITE, RCODE)
         ...
      RHID = NCVID (NCID, 'rh', RCODE)   ! get ID
      DO 10 ILON = 1, LONGS, STRIDE(1)
         DO 10 ILAT = 1, LATS, STRIDE(2)
            DO 10 ITIME = 1, TIMES, STRIDE(3)
               DATA(2, ITIME, ILAT, ILON) = 0.5
   10 CONTINUE
      IMAP(3) = 8*2*2   ! every other point of vector of 2-doubles
      IMAP(2) = IMAP(3)*(1+(TIMES-1)/STRIDE(3))*2
      IMAP(1) = IMAP(2)*(1+(LATS-1)/STRIDE(2))*2
      CALL NCVPTG (NCID, RHID, START, COUNT, STRIDE, IMAP, 
     +             DATA(2,1,1,1), RCODE)

Go to the previous, next section.