netcdf-c/libdispatch/datt.c

/** \file
Copyright 2010 University Corporation for Atmospheric
Research/Unidata. See \ref copyright file for more info.  

These functions read and write attributes.
*/

#include "ncdispatch.h"

/** \defgroup attributes Attributes

Attributes hold metadata about data and files.

\image html ncatts.png "Attributes store metadata."

Attributes may be associated with a netCDF variable to specify such
properties as units, special values, maximum and minimum valid values,
scaling factors, and offsets.

Attributes for a netCDF dataset are defined when the dataset is first
created, while the netCDF dataset is in define mode. Additional
attributes may be added later by reentering define mode.

A netCDF attribute has a netCDF variable to which it is assigned, a
name, a type, a length, and a sequence of one or more values. 

An attribute is designated by its variable ID and name. When an
attribute name is not known, it may be designated by its variable ID
and number in order to determine its name, using the function
nc_inq_attname().

The attributes associated with a variable are typically defined
immediately after the variable is created, while still in define
mode. The data type, length, and value of an attribute may be changed
even when in data mode, as long as the changed attribute requires no
more space than the attribute as originally defined.

It is also possible to have attributes that are not associated with
any variable. These are called global attributes and are identified by
using ::NC_GLOBAL as a variable pseudo-ID. Global attributes are
usually related to the netCDF dataset as a whole and may be used for
purposes such as providing a title or processing history for a netCDF
dataset.

Operations supported on attributes are:
- Create an attribute, given its variable ID, name, data type, length,
  and value.
- Get attribute's data type and length from its variable ID and name.
- Get attribute's value from its variable ID and name.
- Copy attribute from one netCDF variable to another.
- Get name of attribute from its number.
- Rename an attribute.
- Delete an attribute. 
*/

/*! \{*/ /* All these functions are part of the above defgroup... */


/** \name Deleting and Renaming Attributes

Functions to delete or rename an attribute. */
/*! \{ */ /* All these functions are part of this named group... */

/*!
Rename an attribute.

The function nc_rename_att() changes the name of an attribute. If the
new name is longer than the original name, the netCDF dataset must be
in define mode. You cannot rename an attribute to have the same name
as another attribute of the same variable.

\param ncid NetCDF or group ID, from a previous call to nc_open(), 
nc_create(), nc_def_grp(), or associated inquiry functions such as 
nc_inq_ncid().

\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL for
a global attribute.

\param name Attribute \ref object_name. 

\param newname The new attribute \ref object_name. 

<h1>Example</h1>

Here is an example using nc_rename_att() to rename the variable
attribute units to Units for a variable rh in an existing netCDF
dataset named foo.nc:

\code
     #include <netcdf.h>
        ...
     int  status;
     int  ncid;  
     int  rh_id; 
        ...
     status = nc_open("foo.nc", NC_NOWRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_varid (ncid, "rh", &rh_id);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_rename_att(ncid, rh_id, "units", "Units");
     if (status != NC_NOERR) handle_error(status);
\endcode

\returns NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Bad varid.
\returns ::NC_EBADNAME Bad name.
\returns ::NC_EMAXNAME New name too long.
\returns ::NC_EINVAL Name or new name not provided.
\returns ::NC_ENAMEINUSE Name already in use.
\returns ::NC_EPERM File was opened read only.
\returns ::NC_ENOTINDEFINE File is not in define mode.
\returns ::NC_ENOTATT Attribute not found.
\returns ::NC_EHDFERR Failure at HDF5 layer.
\returns ::NC_ENOMEM Out of memory.
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
 */
int
nc_rename_att(int ncid, int varid, const char *name, const char *newname)
{
   NC* ncp;
   int stat = NC_check_id(ncid, &ncp);
   if(stat != NC_NOERR) return stat;
   TRACE(nc_rename_att);
   return ncp->dispatch->rename_att(ncid, varid, name, newname);
}

/*!
Delete an attribute.

The function nc_del_att() deletes a netCDF attribute from an open
netCDF dataset. The netCDF dataset must be in define mode.

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as 
nc_inq_ncid().

\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
for a global attribute.

\param name Attribute name. 

<h1>Example</h1>

Here is an example using nc_del_att() to delete the variable attribute
Units for a variable rh in an existing netCDF dataset named foo.nc:

\code
     #include <netcdf.h>
        ...
     int  status;     
     int  ncid;      
     int  rh_id;     
        ...
     status = nc_open("foo.nc", NC_WRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_varid (ncid, "rh", &rh_id);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_redef(ncid); 
     if (status != NC_NOERR) handle_error(status);
     status = nc_del_att(ncid, rh_id, "Units");
     if (status != NC_NOERR) handle_error(status);
     status = nc_enddef(ncid);
     if (status != NC_NOERR) handle_error(status);
\endcode

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Bad varid.
\returns ::NC_EBADNAME Bad name.
\returns ::NC_EINVAL Name not provided.
\returns ::NC_EPERM File was opened read only.
\returns ::NC_ENOTINDEFINE File is not in define mode.
\returns ::NC_ENOTATT Attribute not found.
\returns ::NC_EATTMETA Failure at HDF5 layer.
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
 */
int
nc_del_att(int ncid, int varid, const char *name)
{
   NC* ncp;
   int stat = NC_check_id(ncid, &ncp);
   if(stat != NC_NOERR) return stat;
   TRACE(nc_del_att);
   stat = ncp->dispatch->del_att(ncid, varid, name);
   return stat;
}
/*! \} */  /* End of named group ...*/

/*! \} */ /* End of defgroup. */