Go to the previous, next section.

Create a Variable

The function ncvardef (or NCVDEF for FORTRAN) adds a new variable to an open netCDF file in define mode. It returns a variable ID, given the netCDF ID, the variable name, the variable type, the number of dimensions, and a list of the dimension IDs.

In case of an error, ncvardef returns -1; NCVDEF returns a nonzero value in rcode. Possible causes of errors include:

• The netCDF file 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 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 file.

• The specified netCDF ID does not refer to an open netCDF file.

ncvardef: C Interface

int ncvardef(int ncid, const char* name, nc_type datatype,
             int ndims, const int dimids[]);

ncid

NetCDF ID, returned from a previous call to ncopen or nccreate.

name

Variable name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore (`_'). Case is significant.

datatype

One of the set of predefined netCDF data types. The type of this parameter, nc_type, is defined in the netCDF header file. The valid netCDF data types are NC_BYTE, NC_CHAR, NC_SHORT, NC_LONG, 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 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.

Here is an example using ncvardef to create a variable named rh of type long with three dimensions, time, lat, and lon in a new netCDF file named `foo.nc':

#include "netcdf.h"
   ...
int  ncid;                         /* netCDF ID */
int  lat_dim, lon_dim, time_dim;   /* dimension IDs */
int  rh_id;                        /* variable ID */
int  rh_dimids[3];                 /* variable shape */
   ...
ncid = nccreate("foo.nc", NC_CLOBBER);
   ...
                                   /* define dimensions */
lat_dim = ncdimdef(ncid, "lat", 5L);
lon_dim = ncdimdef(ncid, "lon", 10L);
time_dim = ncdimdef(ncid, "time", NC_UNLIMITED);
   ...
                                  /* define variable */
rh_dimids[0] = time_dim;
rh_dimids[1] = lat_dim;
rh_dimids[2] = lon_dim;
rh_id = ncvardef (ncid, "rh", NC_DOUBLE, 3, rh_dimids);

NCVDEF: FORTRAN Interface

      INTEGER FUNCTION NCVDEF(INTEGER NCID, CHARACTER*(*) VARNAM,
     +                        INTEGER VARTYP, INTEGER NVDIMS,
     +                        INTEGER VDIMS(*), INTEGER RCODE)

NCID

NetCDF ID, returned from a previous call to NCOPN or NCCRE.

VARNAM

Variable name. Must begin with an alphabetic character, which is followed by zero or more alphanumeric characters including the underscore (`_'). Case is significant.

VARTYP

One of the set of predefined netCDF data types. The valid netCDF data types are NCBYTE, NCCHAR, NCSHORT, NCLONG, NCFLOAT, and NCDOUBLE.

NVDIMS

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 MAXVDIMS.

VDIMS

Vector of NVDIMS dimension IDs corresponding to the variable dimensions. If the ID of the unlimited dimension is included, it must be last.

RCODE

Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCVDEF to create a variable named rh of type long with three dimensions, time, lat, and lon in a new netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER  NCID, RCODE
      INTEGER  LATDIM, LONDIM, TIMDIM ! dimension IDs
      INTEGER  RHID                    ! variable ID
      INTEGER  RHDIMS(3)               ! variable shape
         ...
      NCID = NCCRE ('foo.nc', NC_CLOBBER, RCODE)
         ...
                                       ! define dimensions
      LATDIM = NCDDEF(NCID, 'lat', 5, RCODE)
      LONDIM = NCDDEF(NCID, 'lon', 10, RCODE)
      TIMDIM = NCDDEF(NCID, 'time', NCUNLIM, RCODE)
         ...
                                       ! define variable
      RHDIMS(1) = LONDIM
      RHDIMS(2) = LATDIM
      RHDIMS(3) = TIMDIM
      RHID = NCVDEF (NCID, 'rh', NCDOUBLE, 3, RHDIMS, RCODE)

Go to the previous, next section.