4.25 Rename a Variable: ncmpi_rename_var

The function ncmpi_rename_var changes the name of a netCDF variable in an opened netCDF file. It is illegal to rename a variable to the name of any existing variable.

Operational Mode

This API is a collective subroutine, argument newname must be consistent among all calling processes.

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

Usage

int ncmpi_rename_var(int         ncid,
                     int         varid,
                     const char *newname);

ncid

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

varid

Variable ID. This value must be consistent across all calling MPI processes.

newname

New name for the specified variable.

Return Error Codes

ncmpi_rename_var 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 variable ID is invalid for the specified netCDF file.
• NC_EGLOBAL: NC_GLOBAL is considered invalid for this API.
• NC_EBADNAME: Name contains illegal characters.
• NC_ENAMEINUSE: The new name is in use as the name of another variable.
• NC_ENOTINDEFINE: Must in define mode when newname is longer.
• NC_EMAXNAME: NC_MAX_NAME exceeded.
• NC_EMULTIDEFINE_VAR_NAME: Variable name is inconsistent among processes.
• NC_EMULTIDEFINE_FNC_ARGS: Inconsistent function arguments used in collective API.

Example

Here is an example using ncmpi_rename_var to rename the variable rh to rel_hum 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_WRITE, MPI_INFO_NULL,  &ncid);
if (status != NC_NOERR) handle_error(status);
   ...
status = ncmpi_redef(ncid);  /* put in define mode to rename variable */
if (status != NC_NOERR) handle_error(status);
status = ncmpi_inq_varid(ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_rename_var(ncid, rh_id, "rel_hum");
if (status != NC_NOERR) handle_error(status);
status = ncmpi_enddef(ncid); /* leave define mode */
if (status != NC_NOERR) handle_error(status);