Go to the previous, next section.

Read a Single Data Value

The function ncvarget1 (or NCVGT1 or NCVG1C for FORTRAN) gets a single data value from a variable of an open netCDF file that is in data mode. Inputs are the netCDF ID, the variable ID, a multidimensional index that specifies which value to get, and the address of a location into which the data value will be read.

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

• The variable ID is invalid for the specified netCDF file.

• The specified 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 netCDF is in define mode rather than data mode.

• The specified netCDF ID does not refer to an open netCDF file.

ncvarget1: C Interface

int ncvarget1(int ncid, int varid, const long mindex[], void *value);

ncid

NetCDF ID, returned from a previous call to ncopen or nccreate.

varid

Variable ID, returned from a previous call to ncvardef or ncvarid.

mindex

The multidimensional index of the the data value to be read. The indices are relative to 0, so for example, the first data value of a two-dimensional variable would have index (0,0). The elements of mindex must correspond to the variable's dimensions. Hence, if the variable is a record variable, the first index is the record number.

value

Pointer to the location into which the data value is read. 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 for the data value is used.

Here is an example using ncvarget1 to get the (1,2,3) element of the variable named rh in 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, so we want to get the value of rh that corresponds to the second time value, the third lat value, and the fourth lon value:

#include "netcdf.h"
   ... 
int ncid;                              /* netCDF ID */ 
int rh_id;                             /* variable ID */ 
static long rh_index[] = {1, 2, 3};  /* where to get value from */ 
double rh_val;                         /* where to put it */
   ... 
ncid = ncopen("foo.nc", NC_NOWRITE);
   ...
rh_id = ncvarid (ncid, "rh");
   ...
ncvarget1(ncid, rh_id, rh_index, (void *) &rh_val);

NCVGT1: FORTRAN Interface

      SUBROUTINE NCVGT1 (INTEGER NCID, INTEGER VARID,
     + INTEGER MINDEX(*), type VALUE,
     + INTEGER RCODE)

      SUBROUTINE NCVG1C (INTEGER NCID, INTEGER VARID,
     + INTEGER MINDEX(*), CHARACTER CHVAL,
     + INTEGER RCODE)

There are two FORTRAN subroutines, NCVGT1 and NCVG1C, for reading a single value from a variable. The first reads a numeric value in a variable of numeric type, and the second reads a character value in 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.

MINDEX

The multidimensional index of the the data value to be read. The indices are relative to 1, so for example, the first data value of a two-dimensional variable has index (1,1). The elements of mindex correspond to the variable's dimensions. Hence, if the variable is a record variable, the last index is the record number.

VALUE

For NCVGT1, the location into which the data value will be read. 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.

CHVAL

For NCVG1C, the location into which the data value will be read. This should be of a type character, corresponding to the netCDF types NCCHAR or NCBYTE.

RCODE

Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCVGT1 to get the (4,3,2) element of the variable named rh in 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, so we want to get the value of rh that corresponds to the fourth lon value, the third lat value, and the second time value:

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID, RCODE
      INTEGER RHID ! variable ID
      INTEGER RHINDX(3) ! where to get value
      DOUBLE PRECISION RHVAL ! put it here
      DATA RHINDX /4, 3, 2/
         ...
      NCID = NCOPN ('foo.nc', NCNOWRIT, RCODE)
         ...
      RHID = NCVID (NCID, 'rh', RCODE)! get ID
      CALL NCVGT1 (NCID, RHID, RHINDX, RHVAL, RCODE)

Go to the previous, next section.