6.22 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).
texti1valsi2valsivalsrvalsdvals- 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 (The NetCDF Users Guide)).
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:
- The variable ID is invalid for the specified netCDF dataset.
- The specified start, count and stride generate an index which is out
of range.
- One or more of the values are out of the range of values representable
by the desired type.
- The specified netCDF 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_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)
