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.

Usage

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

ncid

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

name

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.

len

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.

• For CDF-1 format, the maximum length of a dimension is (2^31 - 4) = 2147483644.
• For CDF-2 format, the maximum length of a dimension is (2^32 - 4) = 4294967292.
• For CDF-5 format, the maximum length of a dimension is (2^63 - 1) = 9223372036854775807 = NC_MAX_INT64 = INT64_MAX. Note this maximum is different from the NetCDF library’s (2^64-4).

dimidp

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:

• NC_EBADID: The specified netCDF ID does not refer to an opened netCDF file.
• NC_ENAMEINUSE: The new name is the name of another dimension.
• NC_EBADDIM: The dimension ID is invalid for the specified netCDF file.
• NC_ENOTINDEFINE: Operation not allowed in data mode.
• NC_EDIMSIZE: The specified length is negative or larger than the limits allowable by the file format.
• NC_EMAXDIMS: The number of dimensions exceeds the limit, NC_MAX_DIMS=1024.
• NC_EUNLIMIT: The specified length is unlimited, but there is already an unlimited length dimension defined for this netCDF file.
• NC_EMULTIDEFINE_DIM_NAME: Dimension name is inconsistent among processes.
• NC_EMULTIDEFINE_DIM_SIZE: Dimension size is inconsistent among processes.

Example

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 foo.nc:

#include <pnetcdf.h>
   ... 
int status, ncid, latid, recid;
MPI_Offset len = 18;
   ... 
status = ncmpi_create(MPI_COMM_WORLD, "foo.nc", 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);