Next: , Previous: , Up: Dimensions   [Index]

3.2 Create a Dimension: ncmpi_def_dim

The function ncmpi_def_dim adds a new dimension to an opened netCDF file in define mode. It returns (as an argument) a dimension ID, given the netCDF ID, the dimension name, and the dimension length. At most one unlimited length dimension, called the record dimension, may be defined for each netCDF file.

Operational Mode

This API is a collective routine. All processes must participate the call with the same values for arguments name and len.

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


int ncmpi_def_dim (int         ncid,
                   const char *name,
                   MPI_Offset  len,
                   int        *dimidp);

NetCDF ID, from a previous call to ncmpi_open or ncmpi_create.


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


Length of dimension; that is, number of values for this dimension as an index to variables that use it. This should be either a positive integer (of type MPI_Offset) or the predefined constant NC_UNLIMITED.


Pointer to location for returned dimension ID.

Return Error Codes

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


Here is an example using ncmpi_def_dim to create a dimension named lat of length 18 and a unlimited dimension named rec in a new netCDF file named

#include <pnetcdf.h>
int status, ncid, latid, recid;
MPI_Offset len = 18;
status = ncmpi_create(MPI_COMM_WORLD, "", NC_NOCLOBBER, MPI_INFO_NULL, &ncid);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_def_dim(ncid, "lat", len, &latid);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_def_dim(ncid, "rec", NC_UNLIMITED, &recid);
if (status != NC_NOERR) handle_error(status);

Next: , Previous: , Up: Dimensions   [Index]