Go to the previous, next section.
The function ncvargetg
(or NCVGTG
or NCVGGC
for
FORTRAN) reads a generalized hyperslab of values from a netCDF variable
of an open netCDF file. The generalized hyperslab is specified by
giving a corner, a vector of edge lengths, a stride vector, and an index
mapping vector. The values are read with the last (or first for
FORTRAN) dimension of the generalized hyperslab varying fastest. The
netCDF file must be in data mode.
In case of an error, ncvargetg
returns -1; NCVGTG
and
NCVGGC
return a nonzero value in rcode
. Possible causes
of errors include:
int ncvargetg(int ncid, int varid, const long start[], const long count[], const long stride[], const long imap[], void *values);
ncid
ncopen
or
nccreate
.
varid
ncvardef
or
ncvarid
.
start
(0, 0, ..., 0)
. The
size 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 first index would correspond to the starting record number
for reading the data values.
count
count
as
(1, 1, ..., 1)
. The size 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 first element of count
corresponds to a
count of the number of records to read.
stride
NULL
stride argument obtains the default behavior
in which adjacent values are accessed along each dimension.
imap
value
argument to a particular datum is given by the inner
product of the index mapping vector with the coordinates of the datum.
(The inner product of two vectors [x0, x1, ..., xn] and [y0,
y1, ..., yn] is just x0*y0 + x1*y1 + ... + xn*yn.) The vector
may contain negative values if the value
argument is
appropriately specified. A NULL
argument obtains the default
behavior in which the memory-resident values are assumed to have the
same structure as the associated netCDF variable.
value
void *
because it can
point to data of any of the basic netCDF types. The data should be of
the appropriate type for the netCDF variable. Warning: neither
the compiler nor the netCDF software can detect whether the wrong type
of data is used.
Here is an example using ncvargetg
to read every other value in
each dimension of the variable named rh
from an existing netCDF
file named `foo.nc'. Values are assigned, using the same
dimensional strides, to points in a 3-dimensional array of structures
whose dimensions are the reverse of the netCDF variable. 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.h" ... #define TIMES 3 #define LATS 5 #define LONS 10 int ncid; /* netCDF ID */ int rh_id; /* variable ID */ static long start[] = {0, 0, 0}; /* start at first value */ static long count[] = {TIMES, LATS, LONS}; static long stride[] = {2, 2, 2}; /* every other value */ long imap[3]; /* set to reverse of variable */ struct datum { int dummy; /* to illustrate mapping vector usage */ double rh_val; /* actual value to be read */ } data[TIMES][LATS][LONS]; /* array to hold values */ ... ncid = ncopen("foo.nc", NC_NOWRITE); ... rh_id = ncvarid (ncid, "rh"); ... /* access every `stride' in-memory value using reversed dimensions */ imap[0] = stride[2]*sizeof(struct datum); imap[1] = stride[1]*(1+(LONS-1)/stride[0])*imap[0]; imap[2] = stride[0]*(1+(LATS-1)/stride[1])*imap[1]; /* read generalized hyperslab of values from netCDF variable */ ncvargetg(ncid, rh_id, start, count, stride, imap, (void*)&data[0][0][0].rh_val); ...
SUBROUTINE NCVGTG (INTEGER NCID, INTEGER VARID, + INTEGER START(*), INTEGER COUNT(*), + INTEGER STRIDE(*), INTEGER IMAP(*), + type VALUES, INTEGER RCODE) SUBROUTINE NCVGGC (INTEGER NCID, INTEGER VARID, + INTEGER START(*), INTEGER COUNT(*), + INTEGER STRIDE(*), INTEGER IMAP(*), + CHARACTER*(*) STRING, INTEGER RCODE)
There are two FORTRAN subroutines, NCVGTG
and NCVGGC
, for
reading a generalized hyperslab of values from a netCDF variable. The
first reads numeric values from a variable of numeric type, and the
second reads character values from a variable of character type.
NCID
NCOPN
or
NCCRE
.
VARID
NCVDEF
or
NCVID
.
START
(1, 1, ..., 1)
. The size 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 reading the data values.
COUNT
COUNT
as
(1, 1, ..., 1)
. The size 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 read.
STRIDE
0
.
The size of the vector shall be at least the number of dimensions of the
associated netCDF variable and its elements shall 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. An 0
argument obtains the default behavior
in which adjacent values are accessed along each dimension.
IMAP
0
. The offset, in bytes, from the memory location pointed
to by the value
argument to a particular datum is given by the
inner product of the index mapping vector with the (origin-0)
coordinates of the datum. (The inner product of two vectors [x1,
x2, ..., xn] and [y1, y2, ..., yn] is just x1*y1 + x2*y2 +
... + xn*yn.) The vector may contain negative values if the
value
argument is appropriately specified. A 0
argument
obtains the default behavior in which the memory-resident values are
assumed to have the same structure as the associated netCDF variable.
VALUES
NCVGTG
, the locations into which the data values will be
read. The order in which the data will be read from the netCDF variable
is with the first dimension of the generalized hyperslab varying fastest
(like the ordinary FORTRAN convention). The data may be of a type
corresponding to any of the netCDF types NCSHORT
, NCLONG
,
NCFLOAT
, or NCDOUBLE
, but must be appropriate for the type
of the netCDF variable. Warning: neither the compiler nor the
netCDF software can detect whether the wrong type of data is used.
STRING
NCVGGC
, the character string into which the character data
will be read. The order in which the characters will be read from the
netCDF variable is with the first dimension of the generalized hyperslab
varying fastest (like the FORTRAN convention). The data may be of a
type corresponding to the netCDF types NCCHAR
or NCBYTE
.
RCODE
Here is an example using NCVGTG
to read every other value in each
dimension of the variable named rh
from an existing netCDF file
named `foo.nc'. Values are assigned, using the same dimensional
strides, to a 2-parameter array whose dimensions are the reverse of the
netCDF variable. 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 sizes INTEGER NCID, RCODE INTEGER RHID ! variable ID INTEGER START(NDIMS), COUNT(NDIMS) + STRIDE(NDIMS), IMAP(NDIMS) ! generalized hyperslab DOUBLE DATA(2, TIMES, LATS, LONS) ! rh is second parameter DATA START /1, 1, 1/ ! start at first value DATA COUNT /LONS, LATS, TIMES/ DATA STRIDE /2, 2, 2/ ... NCID = NCOPN ('foo.nc', NCNOWRIT, RCODE) ... RHID = NCVID (NCID, 'rh', RCODE)! get ID IMAP(3) = 8*2*2 ! every other point of vector of 2-doubles IMAP(2) = IMAP(3)*(1+(TIMES-1)/STRIDE(3))*2 IMAP(1) = IMAP(2)*(1+(LATS-1)/STRIDE(2))*2 CALL NCVGTG (NCID, RHID, START, COUNT, STRIDE, IMAP, + DATA(2,1,1,1), RCODE)
Go to the previous, next section.