Next: , Previous: NetCDF-4 Atomic Types, Up: Variables


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);