5.6 Rename an Attribute: ncmpi_rename_att

The function ncmpi_rename_att changes the name of an attribute. It is illegal to rename an attribute to the same name as another attribute of the same variable.

Operational Mode

This API is a collective subroutine.

If the new name is longer than the original name, the netCDF file must be in define mode. Otherwise, the netCDF file can be in either define or data mode.

Usage

int ncmpi_rename_att(int         ncid,
                     int         varid,
                     const char *name,
                     const char *newname);

ncid

NetCDF ID, from a previous call to ncmpi_open or ncmpi_create

varid

ID of the attribute’s variable, or NC_GLOBAL for a global attribute

name

The current attribute name.

newname

The new name to be assigned to the specified attribute. If the new name is longer than the current name, the netCDF file must be in define mode.

Return Error Codes

ncmpi_rename_att 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: Attempt write operations in read-only file.
• NC_ENOTVAR: The input or output variable ID is invalid for the specified netCDF file.
• NC_EBADNAME: Name contains illegal characters.
• NC_ENOTATT: The specified attribute does not exist.
• NC_ENAMEINUSE: The new attribute name is already in use for another attribute of the specified variable.
• NC_ENOTINDEFINE: The specified netCDF file is in data mode and the new name is longer than the old name.
• NC_EMULTIDEFINE_ATTR_NAME: Attribute name is inconsistent among processes.
• NC_EMULTIDEFINE_FNC_ARGS: Inconsistent function arguments used in collective API.

Example

Here is an example using ncmpi_rename_att to rename the variable attribute units to Units for a variable rh in an existing netCDF file named foo.nc:

#include <pnetcdf.h>
   ...
int  status;      /* error status */
int  ncid;        /* netCDF ID */
int  rh_id;       /* variable id */
   ...
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_NOWRITE, MPI_INFO_NULL, &ncid);
if (status != NC_NOERR) handle_error(status);
   ...
status = ncmpi_inq_varid(ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
   ...
/* rename attribute */
status = ncmpi_rename_att(ncid, rh_id, "units", "Units");
if (status != NC_NOERR) handle_error(status);