3.5 Rename a Dimension: ncmpi_rename_dim

The function ncmpi_rename_dim renames an existing dimension in a netCDF file open for writing. It is illegal to rename a dimension to the same name as another dimension.

Operational Mode

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

This API can be called in either define or data mode in the following conditions.

• If the new name is longer than the old name, then the netCDF file must be in define mode.
• If the new name is shorter than the old name, then the netCDF file can be in either define or data mode.

Usage

int ncmpi_rename_dim(int         ncid,
                     int         dimid,
                     const char *name);

ncid

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

dimid

Dimension ID, from a previous call to ncmpi_inq_dimid or ncmpi_def_dim.

name

New dimension name.

Return Error Codes

ncmpi_rename_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_EPERM: The specified netCDF ID refers to a file open for read-only access.
• 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: The new name is longer than the old name and the netCDF file is not in define mode.
• NC_EMULTIDEFINE_DIM_NAME: The new dimension name is inconsistent among processes.

Example

Here is an example using ncmpi_rename_dim to rename the dimension lat to latitude in an existing netCDF file named foo.nc:

#include <pnetcdf.h>
   ...
int status, ncid, latid;
   ...
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_WRITE, MPI_INFO_NULL, &ncid);  /* open for writing */
if (status != NC_NOERR) handle_error(status);
   ...
status = ncmpi_redef(ncid);  /* put in define mode to rename dimension */
if (status != NC_NOERR) handle_error(status);
status = ncmpi_inq_dimid(ncid, "lat", &latid);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_rename_dim(ncid, latid, "latitude");
if (status != NC_NOERR) handle_error(status);
status = ncmpi_enddef(ncid); /* leave define mode */
if (status != NC_NOERR) handle_error(status);