5.2 Create an Attribute: ncmpi_put_att_<type>

The function ncmpi_put_att_<type> adds or changes a variable attribute or global attribute of an opened netCDF file. If this attribute is new, or if the space required to store the attribute is greater than before, the netCDF file must be in define mode.

Data types

Operational Mode

These APIs are collective subroutines.

These APIs must be called while the file is in define mode.

Usage

int ncmpi_put_att        (int              ncid,
                          int              varid,
                          const char      *name,
                          nc_type          xtype,
                          MPI_Offset       nelems,
                          const char      *buf);

int ncmpi_put_att_text   (int              ncid,
                          int              varid,
                          const char      *name,
                          MPI_Offset       nelems,
                          const char      *buf);

int ncmpi_put_att_<type>(int              ncid,
                          int              varid,
                          const char      *name,
                          nc_type          xtype,
                          MPI_Offset       nelems,
                          const <C type> *buf);

ncid

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

varid

Variable ID of the variable to which the attribute will be assigned or NC_GLOBAL for a global attribute.

name

Attribute 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. Attribute name conventions are assumed by some netCDF generic applications, e.g., units as the name for a string attribute that gives the units for a netCDF variable. For examples of attribute conventions see Attribute Conventions in The PnetCDF Users Guide.

xtype

One of the set of predefined netCDF external data types. The type of this parameter, nc_type, is defined in the netCDF header file. The valid netCDF external data types are NC_BYTE, NC_CHAR, NC_SHORT, NC_INT, NC_FLOAT, and NC_DOUBLE. Although it’s possible to create attributes of all types, NC_CHAR and NC_DOUBLE attributes are adequate for most purposes. For CDF-5 file format, the following data types are also supported: NC_UBYTE, NC _USHORT, NC_UINT, NC_INT64, and NC_UINT64.

nelems

Number of values provided for the attribute.

buf

Pointer to one or more values. If the type of values differs from the netCDF attribute type specified as xtype, type conversion will occur.

Return Error Codes

ncmpi_put_att_<type> 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_EGLOBAL: Using NC_GLOBAL is illegal in this context.
• NC_EINVAL: nelems < 0, or nelems > 0 when buf is NULL, or must be 1 for fill attribute.
• NC_EBADNAME: Name contains illegal characters.
• NC_EBADTYPE: Fill value must be of the same type.
• NC_ESTRICTCDF2: Attempting CDF-5 operation on strict CDF or CDF-2 file (the NC data type specified in xtype is only valid in CDF-5 files).
• NC_ECHAR: Attempt to convert numerical values to or from text data.
• NC_ENOTINDEFINE: The specified netCDF file is in data mode when adding a new attribute or the new name of an existing attribute is longer than the old name. NC_EMAXATTS: Maximum number of attributes exceeds the limit, NC_MAX_ATTRS.
• NC_EMULTIDEFINE_ATTR_NAME: Attribute name is inconsistent among processes.
• NC_EMULTIDEFINE_ATTR_LEN: Attribute length is inconsistent among processes.
• NC_EMULTIDEFINE_ATTR_TYPE: Attribute type is inconsistent among processes.
• NC_EMULTIDEFINE_ATTR_VAL: Attribute value is inconsistent among processes.
• NC_EMULTIDEFINE_FNC_ARGS: Inconsistent function arguments used in collective API.

Example

Here is an example using ncmpi_put_att_double to add a variable attribute named valid_range for a netCDF variable named rh and a global attribute named title to an existing netCDF file named foo.nc:

#include <pnetcdf.h>
   ... 
int  status;                            /* error status */
int  ncid;                              /* netCDF ID */
int  rh_id;                             /* variable ID */
static double rh_range[] = {0.0, 100.0};/* attribute vals */
static char title[] = "example netCDF file";
   ... 
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);                /* enter define mode */
if (status != NC_NOERR) handle_error(status);
status = ncmpi_inq_varid(ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_put_att_double(ncid, rh_id, "valid_range", NC_DOUBLE, 2, rh_range);
if (status != NC_NOERR) handle_error(status);
status = ncmpi_put_att_text(ncid, NC_GLOBAL, "title", strlen(title), title)
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_enddef(ncid);               /* leave define mode */
if (status != NC_NOERR) handle_error(status);

Full example C program

• global_attributes.c
• put_vara.c
• fill_mode.c
• The above programs are available in all PnetCDF releases under directory examples/C.