Next: , Previous: NF_GET_VARS_ type, Up: Variables


4.15 NF_GET_VARM_ type

The NF_GET_VARM_ type family of functions reads a mapped array section of values from a netCDF variable of an open netCDF dataset. The mapped array section is specified by giving a corner, a vector of edge lengths, a stride vector, and an index mapping vector. The index mapping vector is a vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. No assumptions are made about the ordering or length of the dimensions of the data array. The netCDF dataset must be in data mode.

Usage

     INTEGER FUNCTION NF_GET_VARM_TEXT  (INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*), INTEGER IMAP(*),
                                 CHARACTER*(*) text)
     INTEGER FUNCTION NF_GET_VARM_INT1  (INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*), INTEGER IMAP(*),
                                 INTEGER*1 i1vals(*))
     INTEGER FUNCTION NF_GET_VARM_INT2  (INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*), INTEGER IMAP(*),
                                 INTEGER*2 i2vals(*))
     INTEGER FUNCTION NF_GET_VARM_INT   (INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*), INTEGER IMAP(*),
                                 INTEGER ivals(*))
     INTEGER FUNCTION NF_GET_VARM_REAL  (INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*), INTEGER IMAP(*),
                                 REAL rvals(*))
     INTEGER FUNCTION NF_GET_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
                                 INTEGER START(*), INTEGER COUNT(*),
                                 INTEGER STRIDE(*), INTEGER IMAP(*),
                                 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).
IMAP
A vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. IMAP(1) gives the distance between elements of the internal array corresponding to the most rapidly varying dimension of the netCDF variable. IMAP(N) (where N is the rank of the netCDF variable) gives the distance between elements of the internal array corresponding to the most slowly varying dimension of the netCDF variable. Intervening IMAP elements correspond to other dimensions of the netCDF variable in the obvious way. Distances between elements are specified in units of elements (the distance between internal elements that occupy adjacent memory locations is 1 and not the element's byte-length as in netCDF 2).
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_VARM_ type returns the value NF_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

Example

The following IMAP vector maps in the trivial way a 2x3x4 netCDF variable and an internal array of the same shape:

     REAL A(2,3,4)       ! same shape as netCDF variable
     INTEGER IMAP(3)
     DATA IMAP /1, 2, 6/ ! netCDF dimension       inter-element distance
                         ! ----------------       ----------------------
                         ! most rapidly varying       1
                         ! intermediate               2 (=IMAP(1)*2)
                         ! most slowly varying        6 (=IMAP(2)*3)

Using the IMAP vector above with NF_GET_VARM_REAL obtains the same result as simply using NF_GET_VAR_REAL.

Here is an example of using NF_GET_VARM_REAL to transpose a netCDF variable named rh which is described by the FORTRAN declaration REAL RH(4,6) (note the size and order of the dimensions):

     INCLUDE 'netcdf.inc'
        ...
     PARAMETER (NDIM=2)   ! rank of netCDF variable
     INTEGER NCID         ! netCDF dataset ID
     INTEGER STATUS       ! return code
     INTEGER RHID         ! variable ID
     INTEGER START(NDIM)  ! netCDF variable start point
     INTEGER COUNT(NDIM)  ! size of internal array
     INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
     INTEGER IMAP(NDIM)   ! internal array inter-element distances
     REAL    RH(6,4)      ! note transposition of netCDF variable dimensions
     DATA START   /1, 1/  ! start at first netCDF variable element
     DATA COUNT   /4, 6/  ! entire netCDF variable; order corresponds
                          ! to netCDF variable -- not internal array
     DATA STRIDE /1, 1/   ! sample every netCDF element
     DATA IMAP   /6, 1/   ! would be /1, 4/ if not transposing
        ...
     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_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
     IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)

Here is another example of using NF_GET_VARM_REAL to simultaneously transpose and subsample the same netCDF variable, by accessing every other point of the netCDF variable:

     INCLUDE 'netcdf.inc'
        ...
     PARAMETER (NDIM=2)   ! rank of netCDF variable
     INTEGER NCID         ! netCDF dataset ID
     INTEGER STATUS       ! return code
     INTEGER RHID         ! variable ID
     INTEGER START(NDIM)  ! netCDF variable start point
     INTEGER COUNT(NDIM)  ! size of internal array
     INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
     INTEGER IMAP(NDIM)   ! internal array inter-element distances
     REAL    RH(3,2)      ! note transposition of (subsampled) dimensions
     DATA START   /1, 1/  ! start at first netCDF variable value
     DATA COUNT   /2, 3/  ! order of (subsampled) dimensions corresponds
                          ! to netCDF variable -- not internal array
     DATA STRIDE /2, 2/   ! sample every other netCDF element
     DATA IMAP   /3, 1/   ! would be `1, 2' if not transposing
        ...
     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_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
     IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)