6.23 Read a Single Data Value: nc_get_var1_ type
The functions nc_get_var1_ type get a single data value from a
variable of an open netCDF dataset 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. The value is converted from the external
data type of the variable, if necessary.
The functions for types ubyte, ushort, uint, longlong, ulonglong, and
string are only available for netCDF-4/HDF5 files.
The nc_get_var1() function will read a variable of any type,
including user defined type. For this function, the type of the data
in memory must match the type of the variable - no data conversion is
done.
Usage
int nc_get_var1_text (int ncid, int varid, const size_t index[],
char *tp);
int nc_get_var1_uchar (int ncid, int varid, const size_t index[],
unsigned char *up);
int nc_get_var1_schar (int ncid, int varid, const size_t index[],
signed char *cp);
int nc_get_var1_short (int ncid, int varid, const size_t index[],
short *sp);
int nc_get_var1_int (int ncid, int varid, const size_t index[],
int *ip);
int nc_get_var1_long (int ncid, int varid, const size_t index[],
long *lp);
int nc_get_var1_float (int ncid, int varid, const size_t index[],
float *fp);
int nc_get_var1_double(int ncid, int varid, const size_t index[],
double *dp);
int nc_get_var1_ubyte (int ncid, int varid, const size_t *indexp,
unsigned char *ip);
int nc_get_var1_ushort(int ncid, int varid, const size_t *indexp,
unsigned short *ip);
int nc_get_var1_uint (int ncid, int varid, const size_t *indexp,
unsigned int *ip);
int nc_get_var1_longlong (int ncid, int varid, const size_t *indexp,
long long *ip);
int nc_get_var1_ulonglong(int ncid, int varid, const size_t *indexp,
unsigned long long *ip);
int nc_get_var1_string(int ncid, int varid, const size_t *indexp,
char **ip);
int nc_get_var1 (int ncid, int varid, const size_t *indexp,
void *ip);
ncid- NetCDF ID, from a previous call to nc_open or nc_create.
varid- Variable ID.
index[]- The index of 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 index must correspond to the
variable's dimensions. Hence, if the variable is a record variable,
the first index is the record number.
tpupcpspiplpfpdp- Pointer to the location into which the data value is read. If the type
of data value differs from the netCDF variable type, type conversion
will occur. See Type Conversion (The NetCDF Users Guide).
Return Codes
- NC_NOERR
No error.
- NC_EHDFERR
Error reported by HDF5 layer.
- NC_ENOTVAR
The variable ID is invalid for the specified netCDF dataset.
- NC_EINVALCOORDS
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.
- NC_EEDGE
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.
- NC_ERANGE
One or more of the specified values are out of the range of values
representable by the external data type of the variable. (Does not
apply to the nc_put_vars() function).
- NC_EINDEFINE
The specified netCDF is in define mode rather than data mode.
- NC_EBADID
The specified netCDF ID does not refer to an open netCDF dataset.
- NC_ECHAR
Attempt to convert to or from char.
- NC_ENOMEM
Out of memory.
Example
Here is an example using nc_get_var1_double to get the (1,2,3) element
of the variable named rh in an existing netCDF dataset 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 status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
static size_t rh_index[] = {1, 2, 3}; /* where to get value from */
double rh_val; /* where to put it */
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
...
status = nc_get_var1_double(ncid, rh_id, rh_index, &rh_val);
if (status != NC_NOERR) handle_error(status);
