6.5 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.
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. If the file is a NetCDF-4/HDF5 file,
the additional types NC_UBYTE, NC_USHORT, NC_UINT, NC_INT64,
NC_UINT64, and NC_STRING may be used, as well as a user defined type
ID.
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. For classic model netCDF files, if the ID of the unlimited
dimension is included, it must be first. This argument is ignored if
ndims is 0. For expanded model netCDF4/HDF5 files, there may be any
number of unlimited dimensions, and they may be used in any element of
the dimids array.
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:
NC_NOERR
- No error.
NC_BADID
- Bad ncid.
NC_ENOTINDEFINE
- Not in define mode. This is returned for netCDF classic or 64-bit
offset files, or for netCDF-4 files, when they were been created with
NC_STRICT_NC3 flag. (see nc_create).
NC_ESTRICTNC3
- Trying to create a var some place other than the root group in a
netCDF file with NC_STRICT_NC3 turned on.
NC_MAX_VARS
- Max number of variables exceeded in a classic or 64-bit offset file,
or an netCDF-4 file with NC_STRICT_NC3 on.
NC_EBADTYPE
- Bad type.
NC_EINVAL
- Number of dimensions to large.
NC_ENAMEINUSE
- Name already in use.
NC_EPERM
- Attempt to create object in read-only file.
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);