6.21 NF_GET_VARA_ type
The members of the NF_GET_VARA_ type family of functions read an array
of values from a netCDF variable of an open netCDF dataset. The array
is specified by giving a corner and a vector of edge lengths. The
values are read into consecutive locations with the first dimension
varying fastest. The netCDF dataset must be in data mode.
Usage
INTEGER FUNCTION NF_GET_VARA_TEXT(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
CHARACTER*(*) text)
INTEGER FUNCTION NF_GET_VARA_INT1(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER*1 i1vals(*))
INTEGER FUNCTION NF_GET_VARA_INT2(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER*2 i2vals(*))
INTEGER FUNCTION NF_GET_VARA_INT (INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
INTEGER ivals(*))
INTEGER FUNCTION NF_GET_VARA_REAL(INTEGER NCID, INTEGER VARID,
INTEGER START(*), INTEGER COUNT(*),
REAL rvals(*))
INTEGER FUNCTION NF_GET_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 read. 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
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 edge lengths along each dimension
of the block of data values to be read. To read 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, 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.
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_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 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_VARA_DOUBLE to read all the values of
the variable named rh from an existing netCDF dataset named
foo.nc. 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)
DOUBLE RHVALS(LONS, LATS, TIMES)
DATA START /1, 1, 1/ ! start at first value
DATA COUNT /LONS, LATS, TIMES/ ! get all the values
...
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_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
