4.3 Create a Variable: ncmpi_def_var

The function ncmpi_def_var adds a new variable to an opened netCDF file 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.

Operational Mode

This API is a collective subroutine.

This API must be called while the file is in define mode.

Usage

int ncmpi_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 ncmpi_open or ncmpi_create.

name

Variable name. Must be a legal netCDF identifier. For CDF-1, a legal identifier is any sequence of one or more alphabetic characters, digits, and the following special characters: ’_’, ’.’, ’-’, ’@’, and ’+’. The identifier must, however, start with an alphabetic character or underscore. Case is significant and names commencing with underscore are reserved for system use. Starting from CDF-2, more characters are allowed. Please refer to CDF-2 file format specification and CDF-5 file format specification.

xtype

One of the predefined netCDF external data types. The type of this parameter, nc_type, is defined in the PnetCDF header file, pnetcdf.h. The valid netCDF external data types are NC_BYTE, NC_CHAR, NC_SHORT, NC_INT, NC_FLOAT, and NC_DOUBLE. For CDF-5 file format, the following additional data types are supported: NC_UBYTE, NC_USHORT, NC_UINT, NC_INT64, and NC_UINT64.

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.

Return Error Codes

ncmpi_def_var returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

• NC_EBADID: Bad ncid. The specified netCDF ID does not refer to an opened netCDF file.
• NC_ENOTINDEFINE: Operation not allowed in data mode.
• NC_EBADNAME: Name contains illegal characters.
• NC_EMAXNAME: NC_MAX_NAME exceeded.
• NC_EBADTYPE: Not a valid NC data type used in argument xtype.
• NC_ESTRICTCDF2: Attempting CDF-5 operation on strict CDF or CDF-2 file (the NC data type specified in xtype is only valid in CDF-5 files).
• NC_EBADDIM: One or more of the dimension IDs in the list of dimensions is not a valid dimension ID for the netCDF file.
• NC_EINVAL: Number of dimensions too large, or negative.
• NC_EMAXVARS: The number of variables would exceed the constant NC_MAX_VARS, the maximum number of variables permitted in a netCDF file.
• NC_ENAMEINUSE: Name already in use.
• NC_EUNLIMPOS: only the highest dimension can be unlimited.
• NC_ENOMEM: run out of memory.
• NC_EVARSIZE: The size of variable exceeds the size constraints for whichever variant of the file format is in use.

Example

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

#include <pnetcdf.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 = ncmpi_create(MPI_COMM_WORLD, "foo.nc", NC_NOCLOBBER, MPI_INFO_NULL, &ncid);
if (status != NC_NOERR) handle_error(status);
   ... 
                                   /* define dimensions */
status = ncmpi_def_dim(ncid, "lat", 5L, &lat_dim);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_def_dim(ncid, "lon", 10L, &lon_dim);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_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 = ncmpi_def_var(ncid, "rh", NC_DOUBLE, 3, rh_dimids, &rh_id);
if (status != NC_NOERR) handle_error(status);