Next: , Previous: Attributes Introduction, Up: Attributes


5.2 Create an Attribute: nc_put_att_ type

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

Usage

Although it's possible to create attributes of all types, text and double attributes are adequate for most purposes.

     int nc_put_att_text   (int ncid, int varid, const char *name,
                                           size_t len, const char *tp);
     int nc_put_att_uchar  (int ncid, int varid, const char *name,
                               nc_type xtype, size_t len, const unsigned char *up);
     int nc_put_att_schar  (int ncid, int varid, const char *name,
                               nc_type xtype, size_t len, const signed char *cp);
     int nc_put_att_short  (int ncid, int varid, const char *name,
                            nc_type xtype, size_t len, const short *sp);
     int nc_put_att_int    (int ncid, int varid, const char *name,
                            nc_type xtype, size_t len, const int *ip);
     int nc_put_att_long   (int ncid, int varid, const char *name,
                            nc_type xtype, size_t len, const long *lp);
     int nc_put_att_float  (int ncid, int varid, const char *name,
                            nc_type xtype, size_t len, const float *fp);
     int nc_put_att_double (int ncid, int varid, const char *name,
                            nc_type xtype, size_t len, const double *dp);
ncid
NetCDF ID, from a previous call to nc_open or nc_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 begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ('_'). Case is significant. 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.
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.
len
Number of values provided for the attribute.
tp, up, cp, sp, ip, lp, fp, or dp
Pointer to one or more values. If the type of values differs from the netCDF attribute type specified as xtype, type conversion will occur. See Type Conversion.

Errors

nc_put_att_ type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

Example

Here is an example using nc_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 dataset named foo.nc:

     #include <netcdf.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 dataset";
        ...
     status = nc_open("foo.nc", NC_WRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_redef(ncid);                /* enter define mode */
     if (status != NC_NOERR) handle_error(status);
     status = nc_inq_varid (ncid, "rh", &rh_id);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_put_att_double (ncid, rh_id, "valid_range",
                                 NC_DOUBLE, 2, rh_range);
     if (status != NC_NOERR) handle_error(status);
     status = nc_put_att_text (ncid, NC_GLOBAL, "title",
                               strlen(title), title)
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_enddef(ncid);               /* leave define mode */
     if (status != NC_NOERR) handle_error(status);