Next: , Previous: NF_GET_VARA_ type, Up: Variables


4.14 NF_GET_VARS_ type

The NF_GET_VARS_ type family of functions read a subsampled (strided) array section of values from a netCDF variable of an open netCDF dataset. The subsampled array section is specified by giving a corner, a vector of edge lengths, and a stride vector. The values are read with the first dimension of the netCDF variable varying fastest. The netCDF dataset must be in data mode.

Usage

     INTEGER FUNCTION NF_GET_VARS_TEXT  (INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*),CHARACTER*(*) text)
     INTEGER FUNCTION NF_GET_VARS_INT1  (INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*),INTEGER*1 i1vals(*))
     INTEGER FUNCTION NF_GET_VARS_INT2  (INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*),INTEGER*2 i2vals(*))
     INTEGER FUNCTION NF_GET_VARS_INT   (INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*), INTEGER ivals(*))
     INTEGER FUNCTION NF_GET_VARS_REAL  (INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*), REAL rvals(*))
     INTEGER FUNCTION NF_GET_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*), 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 from which the first of the data values will be read. The indices are relative to 1, so for example, the first data value of a variable would have index (1, 1, ..., 1). The elements of START correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the starting record number for reading the data values.
COUNT
A vector of integers specifying the number of indices selected along each dimension. To read a single value, for example, specify COUNT as (1, 1, ..., 1). The elements of COUNT correspond, in order, 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 read.
STRIDE
A vector of integers specifying, for each dimension, the interval between selected indices or the value 0. The elements of the vector 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 0 argument is treated as (1, 1, ..., 1).
text
i1vals
i2vals
ivals
rvals
dvals
The block of data values to be read. The data should be of the type appropriate for the function called. You cannot read CHARACTER data from a numeric variable or numeric data from 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_GET_VARS_ type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

Example

Here is an example using NF_GET_VARS_DOUBLE to read every other value in each dimension of the variable named rh from an existing netCDF dataset named foo.nc. Values are assigned, using the same dimensional strides, to a 2-parameter array. 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 lengths
     INTEGER STATUS, NCID
     INTEGER RHID ! variable ID
     INTEGER START(NDIMS), COUNT(NDIMS), STRIDE(NDIMS)
     DOUBLE DATA(LONS, LATS, TIMES)
     DATA START /1, 1, 1/                 ! start at first value
     DATA COUNT /LONS, LATS, TIMES/
     DATA STRIDE /2, 2, 2/
        ...
     STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, 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)
     STATUS = NF_GET_VARS_DOUBLE(NCID,RHID,START,COUNT,STRIDE,DATA(1,1,1))
     IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)