•         advanced

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.

The total size the chunk must be less than 4 GiB. That is, the product of all chunksizes and the size of the data (or the size of nc_vlen_t for VLEN types) must be less than 4 GiB.

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

Contact Us   •   Site Map   •   Search   •   Terms and Conditions   •   Privacy Policy   •   Participation Policy

Unidata is a member of the UCAR Community Programs, is managed by the University Corporation for Atmospheric Research, and is sponsored by the National Science Foundation. P.O. Box 3000   •   Boulder, CO 80307-3000 USA   •   Tel: 303-497-8643   •   Fax: 303-497-8690