NetCDF User's Guide for C
Ordinarily, the name, type, and shape are fixed when the variable is first defined. The name may be changed, but the type and shape of a variable cannot be changed. However, a variable defined in terms of the unlimited dimension can grow without bound in that dimension.
A netCDF variable in an open netCDF dataset is referred to by a small integer called a variable ID.
Variable IDs reflect the order in which variables were defined within a netCDF dataset. Variable IDs are 0, 1, 2,..., in the order in which the variables were defined. A function is available for getting the variable ID from the variable name and vice-versa.
Attributes (see Chapter 8 "Attributes," page 81) may be associated with a variable to specify such properties as units.
Operations supported on variables are:
| netCDF/CDL Data Type | C API Mnemonic | Bits |
|---|---|---|
byte | NC_BYTE | 8 |
char | NC_CHAR | 8 |
short | NC_SHORT | 16 |
int | NC_INT | 32 |
float | NC_FLOAT | 32 |
double | NC_DOUBLE | 64 |
The first column gives the netCDF external data type, which is the same as the CDL data type. The next column gives the corresponding C preprocessor macro for use in netCDF functions (the preprocessor macros are defined in the netCDF C header-file netcdf.h). The last column gives the number of bits used in the external representation of values of the corresponding type.
Note that there are no netCDF types corresponding to 64-bit integers or to characters wider than 8 bits in the current version of the netCDF library.
nc_def_var nc_def_var adds a new variable to an open netCDF dataset in define mode. It returns (as an argument) a variable ID, given the netCDF ID, the variable name, the variable type, the number of dimensions, and a list of the dimension IDs.
int nc_def_var (int ncid, const char *name, nc_type xtype,
int ndims, const int dimids[], int *varidp);
nc_def_var returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
NC_MAX_VAR_DIMS, the maximum number of dimensions permitted for a netCDF variable.
NC_MAX_VARS, the maximum number of variables permitted in a netCDF dataset.
nc_def_var to create a variable named rh of type double with three dimensions, time, lat, and lon in a new netCDF dataset named foo.nc:
#include <netcdf.h>
...
int status; /* error status */
int ncid; /* netCDF ID */
int lat_dim, lon_dim, time_dim; /* dimension IDs */
int rh_id; /* variable ID */
int rh_dimids[3]; /* variable shape */
...
status = nc_create("foo.nc", NC_NOCLOBBER, &ncid);
if (status != NC_NOERR) handle_error(status);
...
/* define dimensions */
status = nc_def_dim(ncid, "lat", 5L, &lat_dim);
if (status != NC_NOERR) handle_error(status);
status = nc_def_dim(ncid, "lon", 10L, &lon_dim);
if (status != NC_NOERR) handle_error(status);
status = nc_def_dim(ncid, "time", NC_UNLIMITED, &time_dim);
if (status != NC_NOERR) handle_error(status);
...
/* define variable */
rh_dimids[0] = time_dim;
rh_dimids[1] = lat_dim;
rh_dimids[2] = lon_dim;
status = nc_def_var (ncid, "rh", NC_DOUBLE, 3, rh_dimids, &rh_id);
if (status != NC_NOERR) handle_error(status);
nc_inq_varid nc_inq_varid returns the ID of a netCDF variable, given its name.int nc_inq_varid (int ncid, const char *name, int *varidp);
ncid | NetCDF ID, from a previous call to nc_open or nc_create. |
name | Variable name for which ID is desired. |
varidp | Pointer to location for returned variable ID. |
nc_inq_varid returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
nc_inq_varid to find out the ID of a variable named rh in an existing netCDF dataset named foo.nc:
#include <netcdf.h>
...
int status, ncid, rh_id;
...
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);
nc_inq_var
The function nc_inq_var returns all the information about a netCDF variable, given its ID. The other functions each return just one item of information about a variable.
These other functions include nc_inq_varname, nc_inq_vartype, nc_inq_varndims, nc_inq_vardimid, and nc_inq_varnatts.
int nc_inq_var (int ncid, int varid, char *name, nc_type *xtypep,
int *ndimsp, int dimids[], int *nattsp);
int nc_inq_varname (int ncid, int varid, char *name);
int nc_inq_vartype (int ncid, int varid, nc_type *xtypep);
int nc_inq_varndims (int ncid, int varid, int *ndimsp);
int nc_inq_vardimid (int ncid, int varid, int dimids[]);
int nc_inq_varnatts (int ncid, int varid, int *nattsp);
These functions return the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
nc_inq_var to find out about a variable named rh in an existing netCDF dataset named foo.nc:
#include <netcdf.h>
...
int status /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
nc_type rh_type; /* variable type */
int rh_ndims; /* number of dims */
int rh_dims[NC_MAX_VAR_DIMS]; /* variable shape */
int rh_natts /* number of attributes */
...
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);
/* we don't need name, since we already know it */
status = nc_inq_var (ncid, rh_id, 0, &rh_type, &rh_ndims, rh_dims,
&rh_natts);
if (status != NC_NOERR) handle_error(status);
nc_put_var1_type nc_put_var1_type put a single data value of the specified type into a variable of an open netCDF dataset that is in data mode. Inputs are the netCDF ID, the variable ID, an index that specifies which value to add or alter, and the data value. The value is converted to the external data type of the variable, if necessary.
int nc_put_var1_text (int ncid, int varid, const size_t index[],
const char *tp);
int nc_put_var1_uchar (int ncid, int varid, const size_t index[],
const unsigned char *up);
int nc_put_var1_schar (int ncid, int varid, const size_t index[],
const signed char *cp);
int nc_put_var1_short (int ncid, int varid, const size_t index[],
const short *sp);
int nc_put_var1_int (int ncid, int varid, const size_t index[],
const int *ip);
int nc_put_var1_long (int ncid, int varid, const size_t index[],
const long *lp);
int nc_put_var1_float (int ncid, int varid, const size_t index[],
const float *fp);
int nc_put_var1_double(int ncid, int varid, const size_t index[],
const double *dp);
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 written. 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 uses the unlimited dimension, the first index would correspond to the unlimited dimension. |
tp, up, cp, sp, ip, lp, fp, or dp | Pointer to the data value to be written. If the type of data values differs from the netCDF variable type, type conversion will occur. See Section 3.3 "Type Conversion," page 20, for details. |
nc_put_var1_type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
nc_put_var1_double to set the (1,2,3) element of the variable named rh to 0.5 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 set 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 put value */
static double rh_val = 0.5; /* value to put */
...
status = nc_open("foo.nc", NC_WRITE, &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_put_var1_double(ncid, rh_id, rh_index, &rh_val);
if (status != NC_NOERR) handle_error(status);
nc_put_var_typenc_put_var_type family of functions write all the values of a variable into a netCDF variable of an open netCDF dataset. This is the simplest interface to use for writing a value in a scalar variable or whenever all the values of a multidimensional variable can all be written at once. The values to be written are associated with the netCDF variable by assuming that the last dimension of the netCDF variable varies fastest in the C interface. The values are converted to the external data type of the variable, if necessary.int nc_put_var_text (int ncid, int varid, const char *tp); int nc_put_var_uchar (int ncid, int varid, const unsigned char *up); int nc_put_var_schar (int ncid, int varid, const signed char *cp); int nc_put_var_short (int ncid, int varid, const short *sp); int nc_put_var_int (int ncid, int varid, const int *ip); int nc_put_var_long (int ncid, int varid, const long *lp); int nc_put_var_float (int ncid, int varid, const float *fp); int nc_put_var_double(int ncid, int varid, const double *dp);
ncid | NetCDF ID, from a previous call to nc_open or nc_create. |
varid | Variable ID. |
tp, up, cp, sp, ip, lp, fp, or dp | Pointer to a block of data values to be written. The order in which the data will be written to the netCDF variable is with the last dimension of the specified variable varying fastest. If the type of data values differs from the netCDF variable type, type conversion will occur. See Section 3.3 "Type Conversion," page 20, for details. |
Members of the nc_put_var_type family return the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
nc_put_var_double to add or change all the values of the variable named rh to 0.5 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, 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 status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
double rh_vals[TIMES*LATS*LONS]; /* array to hold values */
int i;
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
...
for (i = 0; i < TIMES*LATS*LONS; i++)
rh_vals[i] = 0.5;
/* write values into netCDF variable */
status = nc_put_var_double(ncid, rh_id, rh_vals);
if (status != NC_NOERR) handle_error(status);
nc_put_vara_type nc_put_vara_type writes values into a netCDF variable of an open netCDF dataset. The part of the netCDF variable to write is specified by giving a corner and a vector of edge lengths that refer to an array section of the netCDF variable. The values to be written are associated with the netCDF variable by assuming that the last dimension of the netCDF variable varies fastest in the C interface. The netCDF dataset must be in data mode.
int nc_put_vara_type (int ncid, int varid, const size_t start[],
const size_t count[], const type *valuesp);
int nc_put_vara_text (int ncid, int varid, const size_t start[],
const size_t count[], const char *tp);
int nc_put_vara_uchar (int ncid, int varid, const size_t start[],
const size_t count[], const unsigned char *up);
int nc_put_vara_schar (int ncid, int varid, const size_t start[],
const size_t count[], const signed char *cp);
int nc_put_vara_short (int ncid, int varid, const size_t start[],
const size_t count[], const short *sp);
int nc_put_vara_int (int ncid, int varid, const size_t start[],
const size_t count[], const int *ip);
int nc_put_vara_long (int ncid, int varid, const size_t start[],
const size_t count[], const long *lp);
int nc_put_vara_float (int ncid, int varid, const size_t start[],
const size_t count[], const float *fp);
int nc_put_vara_double(int ncid, int varid, const size_t start[],
const size_t count[], const double *dp);
ncid | NetCDF ID, from a previous call to nc_open or nc_create. |
varid | Variable ID. |
start | A vector of size_t integers specifying the index in the variable where the first of the data values will be written. 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 writing the data values. |
count | A vector of size_t integers specifying the edge lengths along each dimension of the block of data values to be written. To write a single value, for example, specify count as (1, 1, ... , 1). The length 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 write. |
tp, up, cp, sp, ip, lp, fp, or dp | Pointer to a block of data values to be written. The order in which the data will be written to the netCDF variable is with the last dimension of the specified variable varying fastest. If the type of data values differs from the netCDF variable type, type conversion will occur. See Section 3.3 "Type Conversion," page 20, for details. |
nc_put_vara_type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
nc_put_vara_double to add or change all the values of the variable named rh to 0.5 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, 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 status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
static size_t start[] = {0, 0, 0}; /* start at first value */
static size_t count[] = {TIMES, LATS, LONS};
double rh_vals[TIMES*LATS*LONS]; /* array to hold values */
int i;
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
...
for (i = 0; i < TIMES*LATS*LONS; i++)
rh_vals[i] = 0.5;
/* write values into netCDF variable */
status = nc_put_vara_double(ncid, rh_id, start, count, rh_vals);
if (status != NC_NOERR) handle_error(status);
nc_put_vars_type nc_put_vars_type writes a subsampled (strided) array section of values into a netCDF variable of an open netCDF dataset. The subsampled array section is specified by giving a corner, a vector of counts, and a stride vector. The netCDF dataset must be in data mode.
int nc_put_vars_text (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const char *tp);
int nc_put_vars_uchar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const unsigned char *up);
int nc_put_vars_schar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const signed char *cp);
int nc_put_vars_short (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const short *sp);
int nc_put_vars_int (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const int *ip);
int nc_put_vars_long (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const long *lp);
int nc_put_vars_float (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const float *fp);
int nc_put_vars_double(int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const double *dp);
ncid | NetCDF ID, from a previous call to nc_open or nc_create. |
varid | Variable ID. |
start | A vector of size_t integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 0, so for example, the first data value of a variable would have index (0, 0, ... , 0). The elements of start correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for writing the data values. |
count | A vector of size_t integers specifying the number of indices selected along each dimension. To write 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 first element of count corresponds to a count of the number of records to write. |
stride | A vector of ptrdiff_t integers that specifies the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable's dimensions (stride[0] gives the sampling interval along the most slowly varying dimension of the netCDF variable). Sampling intervals are specified in type-independent units of elements (a value of 1 selects consecutive elements of the netCDF variable along the corresponding dimension, a value of 2 selects every other element, etc.). A NULL stride argument is treated as (1, 1, ... , 1). |
tp, up, cp, sp, ip, lp, fp, or dp | Pointer to a block of data values to be written. The order in which the data will be written to the netCDF variable is with the last dimension of the specified variable varying fastest. If the type of data values differs from the netCDF variable type, type conversion will occur. See Section 3.3 "Type Conversion," page 20, for details. |
nc_put_vars_type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
nc_put_vars_float to write -- from an internal array -- every other point of a netCDF variable named rh which is described by the C declaration float rh[4][6] (note the size of the dimensions):
#include <netcdf.h>
...
#define NDIM 2 /* rank of netCDF variable */
int ncid; /* netCDF ID */
int status; /* error status */
int rhid; /* variable ID */
static size_t start[NDIM] /* netCDF variable start point: */
= {0, 0}; /* first element */
static size_t count[NDIM] /* size of internal array: entire */
= {2, 3}; /* (subsampled) netCDF variable */
static ptrdiff_t stride[NDIM] /* variable subsampling intervals: */
= {2, 2}; /* access every other netCDF element */
float rh[2][3]; /* note subsampled sizes for */
/* netCDF variable dimensions */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_put_vars_float(ncid, rhid, start, count, stride, rh);
if (status != NC_NOERR) handle_error(status);
nc_put_varm_type nc_put_varm_type family of functions writes a mapped array section of values into a netCDF variable of an open netCDF dataset. The mapped array section is specified by giving a corner, a vector of counts, 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.
int nc_put_varm_text (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const char *tp);
int nc_put_varm_uchar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const unsigned char *up);
int nc_put_varm_schar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const signed char *cp);
int nc_put_varm_short (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const short *sp);
int nc_put_varm_int (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const int *ip);
int nc_put_varm_long (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const long *lp);
int nc_put_varm_float (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const float *fp);
int nc_put_varm_double(int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const double *dp);
ncid | NetCDF ID, from a previous call to nc_open or nc_create. |
varid | Variable ID. |
start | A vector of size_t integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 0, so for example, the first data value of a variable would have index (0, 0, ... , 0). The elements of start correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for writing the data values. |
count | A vector of size_t integers specifying the number of indices selected along each dimension. To write 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 first element of count corresponds to a count of the number of records to write. |
stride | A vector of ptrdiff_t integers that specifies the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable's dimensions (stride[0] gives the sampling interval along the most slowly varying dimension of the netCDF variable). Sampling intervals are specified in type-independent units of elements (a value of 1 selects consecutive elements of the netCDF variable along the corresponding dimension, a value of 2 selects every other element, etc.). A NULL stride argument is treated as (1, 1, ... , 1). |
imap | A vector of ptrdiff_t integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. The elements of the index mapping vector correspond, in order, to the netCDF variable's dimensions (imap[0] gives the distance between elements of the internal array corresponding to the most slowly varying dimension of the netCDF variable). Distances between elements are specified in type-independent 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). A NULL argument means the memory-resident values have the same structure as the associated netCDF variable. |
tp, up, cp, sp, ip, lp, fp, or dp | Pointer to the location used for computing where the data values will be found; the data should be of the type appropriate for the function called. If the type of data values differs from the netCDF variable type, type conversion will occur. See Section 3.3 "Type Conversion," page 20, for details. |
nc_put_varm_type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
start, count, and stride generate an index which is out of range. Note that no error checking is possible on the imap vector.
imap vector maps in the trivial way a 4x3x2 netCDF variable and an internal array of the same shape:
float a[4][3][2]; /* same shape as netCDF variable */
int imap[3] = {6, 2, 1};
/* netCDF dimension inter-element distance */
/* ---------------- ---------------------- */
/* most rapidly varying 1 */
/* intermediate 2 (=imap[2]*2) */
/* most slowly varying 6 (=imap[1]*3) */
Using the imap vector above with nc_put_varm_float obtains the same result as simply using nc_put_var_float.
Here is an example of using nc_put_varm_float to write -- from a transposed, internal array -- a netCDF variable named rh which is described by the C declaration float rh[6][4] (note the size and order of the dimensions):
#include <netcdf.h>
...
#define NDIM 2 /* rank of netCDF variable */
int ncid; /* netCDF ID */
int status; /* error status */
int rhid; /* variable ID */
static size_t start[NDIM] /* netCDF variable start point: */
= {0, 0}; /* first element */
static size_t count[NDIM] /* size of internal array: entire netCDF */
= {6, 4}; /* variable; order corresponds to netCDF */
/* variable -- not internal array */
static ptrdiff_t stride[NDIM]/* variable subsampling intervals: */
= {1, 1}; /* sample every netCDF element */
static ptrdiff_t imap[NDIM] /* internal array inter-element distances; */
= {1, 6}; /* would be {4, 1} if not transposing */
float rh[4][6]; /* note transposition of netCDF variable */
/* dimensions */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_put_varm_float(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);
Here is another example of using nc_put_varm_float to write -- from a transposed, internal array -- a subsample of the same netCDF variable, by writing every other point of the netCDF variable:
#include <netcdf.h>
...
#define NDIM 2 /* rank of netCDF variable */
int ncid; /* netCDF ID */
int status; /* error status */
int rhid; /* variable ID */
static size_t start[NDIM] /* netCDF variable start point: */
= {0, 0}; /* first element */
static size_t count[NDIM] /* size of internal array: entire */
= {3, 2}; /* (subsampled) netCDF variable; order of */
/* dimensions corresponds to netCDF */
/* variable -- not internal array */
static ptrdiff_t stride[NDIM] /* variable subsampling intervals: */
= {2, 2}; /* sample every other netCDF element */
static ptrdiff_t imap[NDIM] /* internal array inter-element distances; */
= {1, 3}; /* would be {2, 1} if not transposing */
float rh[2][3]; /* note transposition of (subsampled) */
/* netCDF variable dimensions */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_put_varm_float(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);
nc_get_var1_type 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.
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);
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. |
tp, up, cp, sp, ip, lp, fp, or, dp | 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 Section 3.3 "Type Conversion," page 20, for details. |
nc_get_var1_type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
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);
nc_get_var_type nc_get_var_type family of functions read all the values from a netCDF variable of an open netCDF dataset. This is the simplest interface to use for reading the value of a scalar variable or when all the values of a multidimensional variable can be read at once. The values are read into consecutive locations with the last dimension varying fastest. The netCDF dataset must be in data mode.int nc_get_var_text (int ncid, int varid, char *tp); int nc_get_var_uchar (int ncid, int varid, unsigned char *up); int nc_get_var_schar (int ncid, int varid, signed char *cp); int nc_get_var_short (int ncid, int varid, short *sp); int nc_get_var_int (int ncid, int varid, int *ip); int nc_get_var_long (int ncid, int varid, long *lp); int nc_get_var_float (int ncid, int varid, float *fp); int nc_get_var_double(int ncid, int varid, double *dp);
ncid | NetCDF ID, from a previous call to nc_open or nc_create. |
varid | Variable ID. |
tp, up, cp, sp, ip, lp, fp, or dp | 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 Section 3.3 "Type Conversion," page 20, for details. |
nc_get_var_type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
nc_get_var_double to read all the values of the variable named rh from 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, 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 status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
double rh_vals[TIMES*LATS*LONS]; /* array to hold values */
...
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);
...
/* read values from netCDF variable */
status = nc_get_var_double(ncid, rh_id, rh_vals);
if (status != NC_NOERR) handle_error(status);
nc_get_vara_type nc_get_vara_type family of functions read an array of values from a netCDF variable of an open netCDF dataset. The array is specified by giving a corner and a vector of edge lengths. The values are read into consecutive locations with the last dimension varying fastest. The netCDF dataset must be in data mode.
int nc_get_vara_text (int ncid, int varid, const size_t start[],
const size_t count[] char *tp);
int nc_get_vara_uchar (int ncid, int varid, const size_t start[],
const size_t count[] unsigned char *up);
int nc_get_vara_schar (int ncid, int varid, const size_t start[],
const size_t count[] signed char *cp);
int nc_get_vara_short (int ncid, int varid, const size_t start[],
const size_t count[] short *sp);
int nc_get_vara_int (int ncid, int varid, const size_t start[],
const size_t count[] int *ip);
int nc_get_vara_long (int ncid, int varid, const size_t start[],
const size_t count[] long *lp);
int nc_get_vara_float (int ncid, int varid, const size_t start[],
const size_t count[] float *fp);
int nc_get_vara_double(int ncid, int varid, const size_t start[],
const size_t count[] double *dp);
ncid | NetCDF ID, from a previous call to nc_open or nc_create. |
varid | Variable ID. |
start | A vector of size_t integers specifying the index in the variable where the first of the data values will be read. The indices are relative to 0, so for example, the first data value of a variable would have index (0, 0, ... , 0). The length of start must be the same as the number of dimensions of the specified variable. The elements of start correspond, in order, to the variable's dimensions. 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 size_t integers specifying the edge lengths along each dimension of the block of data values to be read. To read a single value, for example, specify count as (1, 1, ... , 1). The length of count is the number of dimensions of the specified variable. The elements of count correspond, in order, 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. |
tp, up, cp, sp, ip, lp, fp, or, dp | 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 Section 3.3 "Type Conversion," page 20, for details. |
nc_get_vara_type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
nc_get_vara_double to read all the values of the variable named rh from 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, 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 status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
static size_t start[] = {0, 0, 0}; /* start at first value */
static size_t count[] = {TIMES, LATS, LONS};
double rh_vals[TIMES*LATS*LONS]; /* array to hold values */
...
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);
...
/* read values from netCDF variable */
status = nc_get_vara_double(ncid, rh_id, start, count, rh_vals);
if (status != NC_NOERR) handle_error(status);
nc_get_vars_type nc_get_vars_type family of functions read a subsampled (strided) array section of values from a netCDF variable of an open netCDF dataset. The subsampled array section is specified by giving a corner, a vector of edge lengths, and a stride vector. The values are read with the last dimension of the netCDF variable varying fastest. The netCDF dataset must be in data mode.
int nc_get_vars_text (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
char *tp);
int nc_get_vars_uchar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
unsigned char *up);
int nc_get_vars_schar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
signed char *cp);
int nc_get_vars_short (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
short *sp);
int nc_get_vars_int (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
int *ip);
int nc_get_vars_long (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
long *lp);
int nc_get_vars_float (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
float *fp);
int nc_get_vars_double(int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
double *dp)
ncid | NetCDF ID, from a previous call to nc_open or nc_create. |
varid | Variable ID. |
start | A vector of size_t integers specifying the index in the variable where the first of the data values will be read. The indices are relative to 0, so for example, the first data value of a variable would have index (0, 0, ... , 0). The elements of start correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for reading the data values. |
count | A vector of size_t 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 first element of count corresponds to a count of the number of records to read. |
stride | A vector of ptrdiff_t integers specifying, for each dimension, the interval between selected indices. The elements of the stride 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 NULL stride argument is treated as (1, 1, ... , 1). |
tp, up, cp, sp, ip, lp, fp, or, dp | 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 Section 3.3 "Type Conversion," page 20, for details. |
nc_get_vars_type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
nc_get_vars_double to read every other value in each dimension of the variable named rh from 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, 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 status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
static size_t start[] = {0, 0, 0}; /* start at first value */
static size_t count[] = {TIMES, LATS, LONS};
static ptrdiff_t stride[] = {2, 2, 2};/* every other value */
double data[TIMES][LATS][LONS]; /* array to hold values */
...
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);
...
/* read subsampled values from netCDF variable into array */
status = nc_get_vars_double(ncid, rh_id, start, count, stride,
&data[0][0][0]);
if (status != NC_NOERR) handle_error(status);
...
nc_get_varm_type nc_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.
int nc_get_varm_text (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], char *tp);
int nc_get_varm_uchar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], unsigned char *up);
int nc_get_varm_schar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], signed char *cp);
int nc_get_varm_short (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], short *sp);
int nc_get_varm_int (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], int *ip);
int nc_get_varm_long (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], long *lp);
int nc_get_varm_float (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], float *fp);
int nc_get_varm_double(int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], double *dp);
ncid | NetCDF ID, from a previous call to nc_open or nc_create. |
varid | Variable ID. |
start | A vector of size_t integers specifying the index in the variable where the first of the data values will be read. The indices are relative to 0, so for example, the first data value of a variable would have index (0, 0, ... , 0). The elements of start correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for reading the data values. |
count | A vector of size_t 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 first element of count corresponds to a count of the number of records to read. |
stride | A vector of ptrdiff_t integers specifying, for each dimension, the interval between selected indices. The elements of the stride 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 NULL stride 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[0] gives the distance between elements of the internal array corresponding to the most slowly varying dimension of the netCDF variable. imap[n-1] (where n is the rank of the netCDF variable) gives the distance between elements of the internal array corresponding to the most rapidly 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 type-independent 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). |
tp, up, cp, sp, ip, lp, fp, or, dp | Pointer to the location used for computing where the data values are read; the data should be of the type appropriate for the function called. If the type of data value differs from the netCDF variable type, type conversion will occur. See Section 3.3 "Type Conversion," page 20, for details. |
nc_get_varm_type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
start, count, and stride generate an index which is out of range. Note that no error checking is possible on the imap vector.
imap vector maps in the trivial way a 4x3x2 netCDF variable and an internal array of the same shape:
float a[4][3][2]; /* same shape as netCDF variable */
size_t imap[3] = {6, 2, 1};
/* netCDF dimension inter-element distance */
/* ---------------- ---------------------- */
/* most rapidly varying 1 */
/* intermediate 2 (=imap[2]*2) */
/* most slowly varying 6 (=imap[1]*3) */
Using the imap vector above with nc_get_varm_float obtains the same result as simply using nc_get_var_float.
Here is an example of using nc_get_varm_float to transpose a netCDF variable named rh which is described by the C declaration float rh[6][4] (note the size and order of the dimensions):
#include <netcdf.h>
...
#define NDIM 2 /* rank of netCDF variable */
int ncid; /* netCDF ID */
int status; /* error status */
int rhid; /* variable ID */
static size_t start[NDIM] /* netCDF variable start point: */
= {0, 0}; /* first element */
static size_t count[NDIM] /* size of internal array: entire netCDF */
= {6, 4}; /* variable; order corresponds to netCDF */
/* variable -- not internal array */
static ptrdiff_t stride[NDIM] /* variable subsampling intervals: */
= {1, 1}; /* sample every netCDF element */
static ptrdiff_t imap[NDIM] /* internal array inter-element distances; */
= {1, 6}; /* would be {4, 1} if not transposing */
float rh[4][6]; /* note transposition of netCDF variable */
/* dimensions */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_get_varm_float(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);
Here is another example of using nc_get_varm_float to simultaneously transpose and subsample the same netCDF variable, by accessing every other point of the netCDF variable:
#include <netcdf.h>
...
#define NDIM 2 /* rank of netCDF variable */
int ncid; /* netCDF ID */
int status; /* error status */
int rhid; /* variable ID */
static size_t start[NDIM] /* netCDF variable start point: */
= {0, 0}; /* first element */
static size_t count[NDIM] /* size of internal array: entire */
= {3, 2}; /* (subsampled) netCDF variable; order of */
/* dimensions corresponds to netCDF */
/* variable -- not internal array */
static ptrdiff_t stride[NDIM]/* variable subsampling intervals: */
= {2, 2}; /* sample every other netCDF element */
static ptrdiff_t imap[NDIM] /* internal array inter-element distances; */
= {1, 3}; /* would be {2, 1} if not transposing */
float rh[2][3]; /* note transposition of (subsampled) */
/* netCDF variable dimensions */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_get_varm_float(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);
LEN function returns the static length of a character string, not its dynamic length). As a result, a character string cannot be written or read as a single object in the netCDF interface. Instead, a character string must be treated as an array of characters, and array access must be used to read and write character strings as variable data in netCDF datasets. Furthermore, variable-length strings are not supported by the netCDF interface except by convention; for example, you may treat a zero byte as terminating a character string, but you must explicitly specify the length of strings to be read from and written to netCDF variables. Character strings as attribute values are easier to use, since the strings are treated as a single unit for access. However, the value of a character-string attribute is still an array of characters with an explicit length that must be specified when the attribute is defined.
When you define a variable that will have character-string values, use a character-position dimension as the most quickly varying dimension for the variable (the last dimension for the variable in C). The length of the character-position dimension will be the maximum string length of any value to be stored in the character-string variable. Space for maximum-length strings will be allocated in the disk representation of character-string variables whether you use the space or not. If two or more variables have the same maximum length, the same character-position dimension may be used in defining the variable shapes.
To write a character-string value into a character-string variable, use either entire variable access or array access. The latter requires that you specify both a corner and a vector of edge lengths. The character-position dimension at the corner should be zero for C. If the length of the string to be written is n, then the vector of edge lengths will specify n in the character-position dimension, and one for all the other dimensions:(1, 1, ... , 1, n).
In C, fixed-length strings may be written to a netCDF dataset without the terminating zero byte, to save space. Variable-length strings should be written with a terminating zero byte so that the intended length of the string can be determined when it is later read.
Here is an example that defines a record variable, tx, for character strings and stores a character-string value into the third record using nc_put_vara_text. In this example, we assume the string variable and data are to be added to an existing netCDF dataset named foo.nc that already has an unlimited record dimension time.
#include <netcdf.h>
...
int ncid; /* netCDF ID */
int chid; /* dimension ID for char positions */
int timeid; /* dimension ID for record dimension */
int tx_id; /* variable ID */
#define TDIMS 2 /* rank of tx variable */
int tx_dims[TDIMS]; /* variable shape */
size_t tx_start[TDIMS];
size_t tx_count[TDIMS];
static char tx_val[] =
"example string"; /* string to be put */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
status = nc_redef(ncid); /* enter define mode */
if (status != NC_NOERR) handle_error(status);
...
/* define character-position dimension for strings of max length 40 */
status = nc_def_dim(ncid, "chid", 40L, &chid);
if (status != NC_NOERR) handle_error(status);
...
/* define a character-string variable */
tx_dims[0] = timeid;
tx_dims[1] = chid; /* character-position dimension last */
status = nc_def_var (ncid, "tx", NC_CHAR, TDIMS, tx_dims, &tx_id);
if (status != NC_NOERR) handle_error(status);
...
status = nc_enddef(ncid); /* leave define mode */
if (status != NC_NOERR) handle_error(status);
...
/* write tx_val into tx netCDF variable in record 3 */
tx_start[0] = 3; /* record number to write */
tx_start[1] = 0; /* start at beginning of variable */
tx_count[0] = 1; /* only write one record */
tx_count[1] = strlen(tx_val) + 1; /* number of chars to write */
status = nc_put_vara_text(ncid, tx_id, tx_start, tx_count, tx_val);
if (status != NC_NOERR) handle_error(status);
You may ignore fill values and use the entire range of a netCDF external data type, but in this case you should make sure you write all data values before reading them. If you know you will be writing all the data before reading it, you can specify that no prefilling of variables with fill values will occur by calling nc_set_fillbefore writing. This may provide a significant performance gain for netCDF writes.
The variable attribute _FillValue may be used to specify the fill value for a variable. Their are default fill values for each type, defined in the include file netcdf.h: NC_FILL_CHAR, NC_FILL_BYTE, NC_FILL_SHORT, NC_FILL_INT, NC_FILL_FLOAT, and NC_FILL_DOUBLE.
The netCDF byte and character types have different default fill values. The default fill value for characters is the zero byte, a useful value for detecting the end of variable-length C character strings. If you need a fill value for a byte variable, it is recommended that you explicitly define an appropriate _FillValue attribute, as generic utilities such as ncdump will not assume a default fill value for byte variables.
Type conversion for fill values is identical to type conversion for other values: attempting to convert a value from one type to another type that can't represent the value results in a range error. Such errors may occur on writing or reading values from a larger type (such as double) to a smaller type (such as float), if the fill value for the larger type cannot be represented in the smaller type.
nc_rename_var nc_rename_var changes the name of a netCDF variable in an open netCDF dataset. If the new name is longer than the old name, the netCDF dataset must be in define mode. You cannot rename a variable to have the name of any existing variable. int nc_rename_var(int ncid, int varid, const char* name);
ncid | NetCDF ID, from a previous call to nc_open or nc_create. |
varid | Variable ID. |
name | New name for the specified variable. |
nc_rename_var returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:
nc_rename_var to rename the variable rh to rel_hum in an existing netCDF dataset named foo.nc:
#include <netcdf.h>
...
int status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_redef(ncid); /* put in define mode to rename variable */
if (status != NC_NOERR) handle_error(status);
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
status = nc_rename_var (ncid, rh_id, "rel_hum");
if (status != NC_NOERR) handle_error(status);
status = nc_enddef(ncid); /* leave define mode */
if (status != NC_NOERR) handle_error(status);