5.5 Copy Attribute from One NetCDF to Another: ncmpi_copy_att

The function ncmpi_copy_att copies an attribute from one opened netCDF file to another. It can also be used to copy an attribute from one variable to another within the same netCDF.

Operational Mode

This API is a collective subroutine for processes that opened ncid_out.

This API can be called under the following condition.

• If the attribute does not exist in ncid_out, then this API must be called when ncid_out is in define mode.
• If the attribute does exist in ncid_out and the attribute in ncid_in is smaller than the one in ncid_out, then this API can be called when ncid_out is in either define or data mode.
• If the attribute does exist in ncid_out and the attribute in ncid_in is larger than the one in ncid_out, then this API must be called when ncid_out is in define mode.

Usage

int ncmpi_copy_att (int         ncid_in,
                    int         varid_in,
                    const char *name,
                    int         ncid_out,
                    int         varid_out);

ncid_in

The netCDF ID of an input netCDF file from which the attribute will be copied, from a previous call to ncmpi_open or ncmpi_create.

varid_in

ID of the variable in the input netCDF file from which the attribute will be copied, or NC_GLOBAL for a global attribute.

name

Name of the attribute in the input netCDF file to be copied.

ncid_out

The netCDF ID of the output netCDF file to which the attribute will be copied, from a previous call to ncmpi_open or ncmpi_create. It is permissible for the input and output netCDF IDs to be the same. The output netCDF file should be in define mode if the attribute to be copied does not already exist for the target variable, or if it would cause an existing target attribute to grow.

varid_out

ID of the variable in the output netCDF file to which the attribute will be copied, or NC_GLOBAL to copy to a global attribute.

Return Error Codes

ncmpi_copy_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 input or output netCDF ID does not refer to an opened netCDF file.
• NC_EPERM: Write permission to ncid_out is denied.
• NC_EMAXATTS: Maximum number of attributes exceeds the limit, NC_MAX_ATTRS.
• NC_ENOTVAR: The input or output variable ID is invalid for the specified netCDF file.
• NC_ENOTATT: The specified attribute does not exist in ncid_in.
• NC_ENOTINDEFINE: The output netCDF is not in define mode and the attribute is new for the output file is larger than the existing attribute.

Example

Here is an example using ncmpi_copy_att to copy the variable attribute units from the variable rh in an existing netCDF file named foo.nc to the variable avgrh in another existing netCDF file named bar.nc, assuming that the variable avgrh already exists, but does not yet have a units attribute:

#include <pnetcdf.h>
   ... 
int  status;               /* error status */
int  ncid1, ncid2;         /* netCDF IDs */
int  rh_id, avgrh_id;      /* variable IDs */
   ... 
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_NOWRITE, MPI_INFO_NULL, &ncid1);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_open(MPI_COMM_WORLD, "bar.nc", NC_WRITE, MPI_INFO_NULL, &ncid2);
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_inq_varid(ncid1, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_inq_varid(ncid2, "avgrh", &avgrh_id);
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_redef(ncid2);  /* enter define mode */
if (status != NC_NOERR) handle_error(status);
/* copy variable attribute from "rh" to "avgrh" */
status = ncmpi_copy_att(ncid1, rh_id, "units", ncid2, avgrh_id);
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_enddef(ncid2); /* leave define mode */
if (status != NC_NOERR) handle_error(status);