Next: ncmpi_inq_att Family, Previous: Attributes Introduction, Up: Attributes [Index]
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.
<type > for API names | <C type> for API arguments |
text | char |
schar | signed char |
short | short |
int | int |
float | float |
double | double |
uchar | unsigned char |
ushort | unsigned short |
uint | unsigned int |
longlong | long long |
ulonglong | unsigned longlong |
These APIs are collective subroutines.
These APIs must be called while the file is in define mode.
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.
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:
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);
Next: ncmpi_inq_att Family, Previous: Attributes Introduction, Up: Attributes [Index]