NetCDF User's Guide - ncvarget and NCVGT(C)

Go to the previous, next section.

Read a Hyperslab of Values

The function ncvarget (or NCVGT or NCVGTC for FORTRAN) reads a hyperslab of values from a netCDF variable of an open netCDF file. The hyperslab is specified by giving a corner and a vector of edge lengths. The values are read into consecutive locations with the last (or first for FORTRAN) dimension of the hyperslab varying fastest. The netCDF file must be in data mode.

In case of an error, ncvarget returns -1; NCVGT returns a nonzero value in rcode. Possible causes of errors include:

The variable ID is invalid for the specified netCDF file.
The specified corner indices were out of range for the dimensionality of the specified variable. For example, a negative index or an index that is larger than the corresponding dimension size will cause an error.
The specified edge lengths added to the specified corner would have referenced data out of range for the dimensionality of the specified variable. For example, an edge length that is larger than the corresponding dimension size minus the corner index will cause an error.
The specified netCDF is in define mode rather than data mode.
The specified netCDF ID does not refer to an open netCDF file.

ncvarget: C Interface

int ncvarget(int ncid, int varid, const long start[], const long count[],
             void *values);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
varid: Variable ID, returned from a previous call to ncvardef or ncvarid.
start: A vector of long integers specifying the multidimensional index of the corner of the hyperslab where the first of the data values will be read from. The indices are relative to 0, so for example, the first data value of a variable would have index (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: A vector of long integers specifying the multidimensional edge lengths from the corner of the hyperslab where the first of the data values will be read. To read a single value, for example, specify 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.
value: Pointer to the first of 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 last dimension of the specified hyperslab varying fastest. The pointer is declared to be of the type 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 ncvarget to read all the values of the variable named rh from an existing netCDF file named `foo.nc'. 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}; double rh_vals[TIMES*LATS*LONS]; /* array to hold values */
   ... ncid = ncopen("foo.nc", NC_NOWRITE);
   ... rh_id = ncvarid (ncid, "rh");
   ... /* read hyperslab of values from netCDF variable */
ncvarget(ncid, rh_id, start, count, (void *) rh_vals);

NCVGT, NCVGTC: FORTRAN Interface

      SUBROUTINE NCVGT (INTEGER NCID, INTEGER VARID,
     + INTEGER START(*), INTEGER COUNT(*),
     + type VALUES, INTEGER RCODE)

      SUBROUTINE NCVGTC(INTEGER NCID, INTEGER VARID,
     + INTEGER START(*), INTEGER COUNTS(*),
     + CHARACTER*(*) STRING, INTEGER LENSTR,
     + INTEGER RCODE)

There are two FORTRAN subroutines, NCVGT and NCVGTC, for reading a 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: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
VARID: Variable ID, returned from a previous call to NCVDEF or NCVID.
START: A vector of integers specifying the multidimensional index of the corner of the hyperslab 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 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: A vector of integers specifying the multidimensional edge lengths from the corner of the hyperslab where the first of the data values will be read. To read a single value, for example, specify 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.
VALUES: For NCVGT, 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 specified 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: For NCVGTC, 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 specified hyperslab varying fastest (like the FORTRAN convention). The data may be of a type corresponding to the netCDF types NCCHAR or NCBYTE.
LENSTR: For NCVGTC, the total declared length (in characters) of the STRING argument. This should be at least as large as the product of the elements of the COUNT vector. Note that this is not necessarily the same as the value returned by the FORTRAN LEN function, because an array argument may be provided. NCVGTC will check to make sure the requested data will fit in LENSTR characters.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCVGT to read all the values of the variable named rh from an existing netCDF file 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 sizes
      INTEGER NCID, RCODE
      INTEGER RHID ! variable ID
      INTEGER START(NDIMS), COUNT(NDIMS) ! hyperslab
      DOUBLE RHVALS(LONS, LATS, TIMES)
      DATA START /1, 1, 1/ ! start at first value
      DATA COUNT /LONS, LATS, TIMES/
         ...
      NCID = NCOPN ('foo.nc', NCNOWRIT, RCODE)
         ...
      RHID = NCVID (NCID, 'rh', RCODE)! get ID
      CALL NCVGT (NCID, RHID, START, COUNT, RHVALS, RCODE)

Go to the previous, next section.