4.3 Create a Variable: nc_def_var
The function 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.
Usage
int nc_def_var (int ncid, const char *name, nc_type xtype,
int ndims, const int dimids[], int *varidp);
ncid
- NetCDF ID, from a previous call to nc_open or nc_create.
name
- Variable name. Must begin with an alphabetic character, followed by
zero or more alphanumeric characters including the underscore
('_'). Case is significant.
xtype
- One of the set of predefined netCDF external data types. The type of
this parameter, nc_type, is defined in the netCDF header file. The
valid netCDF external data types are NC_BYTE, NC_CHAR, NC_SHORT,
NC_INT, NC_FLOAT, and NC_DOUBLE.
ndims
- Number of dimensions for the variable. For example, 2 specifies a
matrix, 1 specifies a vector, and 0 means the variable is a scalar
with no dimensions. Must not be negative or greater than the
predefined constant NC_MAX_VAR_DIMS.
dimids
- Vector of ndims dimension IDs corresponding to the variable
dimensions. If the ID of the unlimited dimension is included, it must
be first. This argument is ignored if ndims is 0.
varidp
- Pointer to location for the returned variable ID.
Errors
nc_def_var returns the value NC_NOERR if no errors
occurred. Otherwise, the returned status indicates an error. Possible
causes of errors include:
- The netCDF dataset is not in define mode.
- The specified variable name is the name of another existing variable.
- The specified type is not a valid netCDF type.
- The specified number of dimensions is negative or more than the
constant NC_MAX_VAR_DIMS, the maximum number of dimensions permitted
for a netCDF variable.
- One or more of the dimension IDs in the list of dimensions is not a
valid dimension ID for the netCDF dataset.
- The number of variables would exceed the constant NC_MAX_VARS, the
maximum number of variables permitted in a netCDF dataset.
- The specified netCDF ID does not refer to an open netCDF dataset.
Example
Here is an example using 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);