1/** \file
2Attribute functions
3
4These functions read and write attributes.
5
6Copyright 2010 University Corporation for Atmospheric
7Research/Unidata. See \ref copyright file for more info.  */
8
9#include "ncdispatch.h"
10
11/** \defgroup attributes Attributes
12
13Attributes hold metadata about data and files.
14
15\image html ncatts.png "Attributes store metadata."
16
17Attributes may be associated with a netCDF variable to specify such
18properties as units, special values, maximum and minimum valid values,
19scaling factors, and offsets.
20
21Attributes for a netCDF dataset are defined when the dataset is first
22created, while the netCDF dataset is in define mode. Additional
23attributes may be added later by reentering define mode.
24
25A netCDF attribute has a netCDF variable to which it is assigned, a
26name, a type, a length, and a sequence of one or more values.
27
28An attribute is designated by its variable ID and name. When an
29attribute name is not known, it may be designated by its variable ID
30and number in order to determine its name, using the function
31nc_inq_attname().
32
33The attributes associated with a variable are typically defined
34immediately after the variable is created, while still in define
35mode. The data type, length, and value of an attribute may be changed
36even when in data mode, as long as the changed attribute requires no
37more space than the attribute as originally defined.
38
39It is also possible to have attributes that are not associated with
40any variable. These are called global attributes and are identified by
41using ::NC_GLOBAL as a variable pseudo-ID. Global attributes are usually
42related to the netCDF dataset as a whole and may be used for purposes
43such as providing a title or processing history for a netCDF dataset.
44
45Operations supported on attributes are:
46- Create an attribute, given its variable ID, name, data type, length,
47  and value.
48- Get attribute's data type and length from its variable ID and name.
49- Get attribute's value from its variable ID and name.
50- Copy attribute from one netCDF variable to another.
51- Get name of attribute from its number.
52- Rename an attribute.
53- Delete an attribute.
54*/
55
56/*! \{*/ /* All these functions are part of the above defgroup... */
57
58
59/** \name Deleting and Renaming Attributes
60
61Functions to delete or rename an attribute. */
62/*! \{ */ /* All these functions are part of this named group... */
63
64/*!
65Rename an attribute.
66
67The function nc_rename_att() changes the name of an attribute. If the
68new name is longer than the original name, the netCDF dataset must be
69in define mode. You cannot rename an attribute to have the same name
70as another attribute of the same variable.
71
72\param ncid NetCDF or group ID, from a previous call to nc_open(),
73nc_create(), nc_def_grp(), or associated inquiry functions such as
74nc_inq_ncid().
75
76\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL for
77a global attribute.
78
79\param name Attribute \ref object_name.
80
81\param newname The new attribute \ref object_name.
82
83<h1>Example</h1>
84
85Here is an example using nc_rename_att() to rename the variable
86attribute units to Units for a variable rh in an existing netCDF
87dataset named foo.nc:
88
89\code
90     #include <netcdf.h>
91        ...
92     int  status;
93     int  ncid;
94     int  rh_id;
95        ...
96     status = nc_open("foo.nc", NC_NOWRITE, &ncid);
97     if (status != NC_NOERR) handle_error(status);
98        ...
99     status = nc_inq_varid (ncid, "rh", &rh_id);
100     if (status != NC_NOERR) handle_error(status);
101        ...
102     status = nc_rename_att(ncid, rh_id, "units", "Units");
103     if (status != NC_NOERR) handle_error(status);
104\endcode
105 */
106int
107nc_rename_att(int ncid, int varid, const char *name, const char *newname)
108{
109   NCncp;
110   int stat = NC_check_id(ncid, &ncp);
111   if(stat != NC_NOERR) return stat;
112   TRACE(nc_rename_att);
113   return ncp->dispatch->rename_att(ncidvaridnamenewname);
114}
115
116/*!
117Delete an attribute.
118
119The function nc_del_att() deletes a netCDF attribute from an open
120netCDF dataset. The netCDF dataset must be in define mode.
121
122\param ncid NetCDF or group ID, from a previous call to nc_open(),
123nc_create(), nc_def_grp(), or associated inquiry functions such as
124nc_inq_ncid().
125
126\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
127for a global attribute.
128
129\param name Attribute name.
130
131<h1>Example</h1>
132
133Here is an example using nc_del_att() to delete the variable attribute
134Units for a variable rh in an existing netCDF dataset named foo.nc:
135
136\code
137     #include <netcdf.h>
138        ...
139     int  status;
140     int  ncid;
141     int  rh_id;
142        ...
143     status = nc_open("foo.nc", NC_WRITE, &ncid);
144     if (status != NC_NOERR) handle_error(status);
145        ...
146     status = nc_inq_varid (ncid, "rh", &rh_id);
147     if (status != NC_NOERR) handle_error(status);
148        ...
149     status = nc_redef(ncid);
150     if (status != NC_NOERR) handle_error(status);
151     status = nc_del_att(ncid, rh_id, "Units");
152     if (status != NC_NOERR) handle_error(status);
153     status = nc_enddef(ncid);
154     if (status != NC_NOERR) handle_error(status);
155\endcode
156 */
157int
158nc_del_att(int ncid, int varid, const char *name)
159{
160   NCncp;
161   int stat = NC_check_id(ncid, &ncp);
162   if(stat != NC_NOERR) return stat;
163   TRACE(nc_del_att);
164   stat = ncp->dispatch->del_att(ncidvaridname);
165   return stat;
166}
167/*! \} */  /* End of named group ...*/
168
169/*! \} */ /* End of defgroup. */


HyperKWIC - Version 7.20DA executed at 11:37 on 27 Oct 2017 | Polyhedron Solutions - INTERNAL USE | COMMERCIAL (Any O/S) SN 4AKIed