mirror of
https://github.com/Unidata/netcdf-c.git
synced 2024-11-27 07:30:33 +08:00
11a259ad86
This consists of a persistent attribute named _NCProperties plus two computed attributes _IsNetcdf4 and _SuperblockVersion. See the 'Provenance Attributes' section of docs/attribute_conventions.md for details.
170 lines
5.3 KiB
C
170 lines
5.3 KiB
C
/** \file
|
|
Attribute functions
|
|
|
|
These functions read and write attributes.
|
|
|
|
Copyright 2010 University Corporation for Atmospheric
|
|
Research/Unidata. See \ref copyright file for more info. */
|
|
|
|
#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
|
|
*/
|
|
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
|
|
*/
|
|
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. */
|