4.8 Write an Array of Values: NF_PUT_VARA_ type

The function NF_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 first dimension of the netCDF variable varies fastest in the FORTRAN interface. The netCDF dataset must be in data mode.

Usage

     INTEGER FUNCTION NF_PUT_VARA_TEXT(INTEGER NCID, INTEGER VARID,
                                       INTEGER START(*), INTEGER COUNT(*),
                                       CHARACTER*(*) TEXT)
     INTEGER FUNCTION NF_PUT_VARA_INT1(INTEGER NCID, INTEGER VARID,
                                       INTEGER START(*), INTEGER COUNT(*),
                                       INTEGER*1 I1VALS(*))
     INTEGER FUNCTION NF_PUT_VARA_INT2(INTEGER NCID, INTEGER VARID,
                                       INTEGER START(*), INTEGER COUNT(*),
                                       INTEGER*2 I2VALS(*))
     INTEGER FUNCTION NF_PUT_VARA_INT (INTEGER NCID, INTEGER VARID,
                                       INTEGER START(*), INTEGER COUNT(*),
                                       INTEGER IVALS(*))
     INTEGER FUNCTION NF_PUT_VARA_REAL(INTEGER NCID, INTEGER VARID,
                                       INTEGER START(*), INTEGER COUNT(*),
                                       REAL RVALS(*))
     INTEGER FUNCTION NF_PUT_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
                                       INTEGER START(*), INTEGER COUNT(*),
                                       DOUBLE DVALS(*))

NCID

NetCDF ID, from a previous call to NF_OPEN or NF_CREATE.

VARID

Variable ID.

START

A vector of integers specifying the index in the variable 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 length 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 edge lengths along each dimension of the block of data values to 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 last element of COUNT corresponds to a count of the number of records to write.

TEXT

I1VALS

I2VALS

IVALS

RVALS

DVALS

The block of data values to be written. The data should be of the type appropriate for the function called. You cannot put CHARACTER data into a numeric variable or numeric data into a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Type Conversion).

Errors

NF_PUT_VARA_ type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

• The variable ID is invalid for the specified netCDF dataset.
• The specified corner indices were out of range for the rank of the specified variable. For example, a negative index, or an index that is larger than the corresponding dimension length will cause an error.
• The specified edge lengths added to the specified corner would have referenced data out of range for the rank of the specified variable. For example, an edge length that is larger than the corresponding dimension length minus the corner index will cause an error.
• One or more of the specified values are out of the range of values representable by the external data type of the variable.
• The specified netCDF dataset is in define mode rather than data mode.
• The specified netCDF ID does not refer to an open netCDF dataset.

Example

Here is an example using NF_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.inc'
        ...
     PARAMETER (NDIMS=3)         ! number of dimensions
     PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
     INTEGER  STATUS, NCID, TIMES
     INTEGER  RHID               ! variable ID
     INTEGER  START(NDIMS), COUNT(NDIMS)
     DOUBLE RHVALS(LONS, LATS, TIMES)
     DATA START /1, 1, 1/        ! start at first value
     DATA COUNT /LONS, LATS, TIMES/
        ...
     STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
     IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
        ...
     STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
     IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
     DO 10 ILON = 1, LONS
        DO 10 ILAT = 1, LATS
           DO 10 ITIME = 1, TIMES
              RHVALS(ILON, ILAT, ITIME) = 0.5
     10 CONTINUE
     STATUS = NF_PUT_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
     IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)