Next: , Previous: Attributes Introduction, Up: Attributes


7.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

With netCDF-4 files, nc_put_att will notice if you are writing a _Fill_Value_ attribute, and will tell the HDF5 layer to use the specified fill value for that variable.

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

Use the nc_put_att function to create attributes of any type, including user-defined types. We recommend using the type safe versions of this function whenever possible.

     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);
     int nc_put_att_ubyte     (int ncid, int varid, const char *name, nc_type xtype,
                               size_t len, const unsigned char *op);
     int nc_put_att_ushort    (int ncid, int varid, const char *name, nc_type xtype,
                               size_t len, const unsigned short *op);
     int nc_put_att_uint      (int ncid, int varid, const char *name, nc_type xtype,
                               size_t len, const unsigned int *op);
     int nc_put_att_longlong  (int ncid, int varid, const char *name, nc_type xtype,
                               size_t len, const long long *op);
     int nc_put_att_ulonglong (int ncid, int varid, const char *name, nc_type xtype,
                               size_t len,
                               const unsigned long long *op);
     int nc_put_att_string    (int ncid, int varid, const char *name, size_t len,
                               const char **op);
     int nc_put_att           (int ncid, int varid, const char *name, nc_type xtype,
                               size_t len, const void *op);
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. 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:

Return Codes

NC_NOERR
No error.
NC_EINVAL
Trying to set global _FillValue. (NetCDF-4 files only).
NC_ENOTVAR
Couldn't find varid.
NC_EBADTYPE
Fill value must be same type as variable. (NetCDF-4 files only).
NC_ENOMEM
Out of memory
NC_EFILLVALUE
Fill values must be written while the file is still in initial define mode, that is, after the file is created, but before it leaves define mode for the first time. NC_EFILLVALUE is returned when the user attempts to set the fill value after it's too late.

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);