1 /*Copyright 2018 University Corporation for Atmospheric
2 Research/Unidata. See copyright file for more info. */
3 /**
4 * @file
5 *
6 * These functions in this file rename and delete attributes.
7 */
8 #include "ncdispatch.h"
9
10 /**
11 * @defgroup attributes Attributes
12 *
13 * Attributes hold metadata about data and files.
14 *
15 * @image html ncatts.png "Attributes store metadata."
16 *
17 * Attributes may be associated with a netCDF variable to specify such
18 * properties as units, special values, maximum and minimum valid
19 * values, scaling factors, and offsets.
20 *
21 * It is also possible to have attributes that are not associated with
22 * any variable. These are called global attributes and are identified
23 * by using ::NC_GLOBAL as a variable pseudo-ID. Global attributes are
24 * related to the netCDF dataset as a whole and may be used for
25 * purposes such as providing a title or processing history for a
26 * netCDF dataset. In netCDF-4/HDF5 files, global attributes are
27 * associated with a hierarchical group.
28 *
29 * An attribute is designated by its variable ID and name. When an
30 * attribute name is not known, it may be designated by its variable
31 * ID and number in order to determine its name, using the function
32 * nc_inq_attname().
33 *
34 * Operations supported on attributes are:
35 * - Create an attribute, given its variable ID, name, data type,
36 * length, and value.
37 * - Get attribute's data type and length from its variable ID and
38 name.
39 * - Get attribute's value from its variable ID and name.
40 * - Copy attribute from one netCDF variable to another.
41 * - Get name of attribute from its number.
42 * - Rename an attribute.
43 * - Delete an attribute.
44 */
45
46 /** @{*/
47
48 /**
49 * @name Deleting and Renaming Attributes
50 *
51 * Functions to delete or rename an attribute. */
52 /**@{*/ /* Start doxygen member group. */
53
54 /**
55 * Rename an attribute.
56 *
57 * The function nc_rename_att() changes the name of an attribute. In
58 * classic formats, if the new name is longer than the original name,
59 * the netCDF dataset must be in define mode. In netCDF-4/HDF5 files,
60 * attributes may be renamed at any time. You cannot rename an
61 * attribute to have the same name as another attribute of the same
62 * variable.
63 *
64 * @param ncid NetCDF or group ID, from a previous call to nc_open(),
65 * nc_create(), nc_def_grp(), or associated inquiry functions such as
66 * nc_inq_ncid().
67 * @param varid Variable ID of the attribute's variable, or
68 * ::NC_GLOBAL for a global attribute.
69 * @param name Attribute \ref object_name.
70 * @param newname The new attribute \ref object_name.
71 *
72 * <h1>Example</h1>
73 *
74 * Here is an example using nc_rename_att() to rename the variable
75 * attribute units to Units for a variable rh in an existing netCDF
76 * dataset named foo.nc:
77 *
78 @code
79 #include <netcdf.h>
80 ...
81 int status;
82 int ncid;
83 int rh_id;
84 ...
85 status = nc_open("foo.nc", NC_NOWRITE, &ncid);
86 if (status != NC_NOERR) handle_error(status);
87 ...
88 status = nc_inq_varid (ncid, "rh", &rh_id);
89 if (status != NC_NOERR) handle_error(status);
90 ...
91 status = nc_rename_att(ncid, rh_id, "units", "Units");
92 if (status != NC_NOERR) handle_error(status);
93 @endcode
94
95 * @return ::NC_NOERR No error.
96 * @return ::NC_EBADID Bad ncid.
97 * @return ::NC_ENOTVAR Bad varid.
98 * @return ::NC_EBADNAME Bad name.
99 * @return ::NC_EMAXNAME New name too long.
100 * @return ::NC_EINVAL Name or new name not provided.
101 * @return ::NC_ENAMEINUSE Name already in use.
102 * @return ::NC_EPERM File was opened read only.
103 * @return ::NC_ENOTINDEFINE File is not in define mode.
104 * @return ::NC_ENOTATT Attribute not found.
105 * @return ::NC_EHDFERR Failure at HDF5 layer.
106 * @return ::NC_ENOMEM Out of memory.
107 *
108 * @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
109 */
110 int
nc_rename_att(int ncid,int varid,const char * name,const char * newname)111 nc_rename_att(int ncid, int varid, const char *name, const char *newname)
112 {
113 NC* ncp;
114 int stat = NC_check_id(ncid, &ncp);
115 if(stat != NC_NOERR) return stat;
116 TRACE(nc_rename_att);
117 return ncp->dispatch->rename_att(ncid, varid, name, newname);
118 }
119
120 /**
121 * Delete an attribute.
122 *
123 * The function nc_del_att() deletes a netCDF attribute from an open
124 * netCDF dataset. For classic netCDF formats, the dataset must be in
125 * define mode to delete an attribute. In netCDF-4/HDF5 files,
126 * attributes may be deleted at any time.
127 *
128 * @param ncid NetCDF or group ID, from a previous call to nc_open(),
129 * nc_create(), nc_def_grp(), or associated inquiry functions such as
130 * nc_inq_ncid().
131 * @param varid Variable ID of the attribute's variable, or
132 * ::NC_GLOBAL for a global attribute.
133 * @param name Attribute name.
134 *
135 * <h1>Example</h1>
136 *
137 * Here is an example using nc_del_att() to delete the variable
138 * attribute Units for a variable rh in an existing netCDF dataset
139 * named foo.nc:
140
141 @code
142 #include <netcdf.h>
143 ...
144 int status;
145 int ncid;
146 int rh_id;
147 ...
148 status = nc_open("foo.nc", NC_WRITE, &ncid);
149 if (status != NC_NOERR) handle_error(status);
150 ...
151 status = nc_inq_varid (ncid, "rh", &rh_id);
152 if (status != NC_NOERR) handle_error(status);
153 ...
154 status = nc_redef(ncid);
155 if (status != NC_NOERR) handle_error(status);
156 status = nc_del_att(ncid, rh_id, "Units");
157 if (status != NC_NOERR) handle_error(status);
158 status = nc_enddef(ncid);
159 if (status != NC_NOERR) handle_error(status);
160 @endcode
161
162 * @return ::NC_NOERR No error.
163 * @return ::NC_EBADID Bad ncid.
164 * @return ::NC_ENOTVAR Bad varid.
165 * @return ::NC_EBADNAME Bad name.
166 * @return ::NC_EINVAL Name not provided.
167 * @return ::NC_EPERM File was opened read only.
168 * @return ::NC_ENOTINDEFINE File is not in define mode.
169 * @return ::NC_ENOTATT Attribute not found.
170 * @return ::NC_EATTMETA Failure at HDF5 layer.
171 *
172 * @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
173 */
174 int
nc_del_att(int ncid,int varid,const char * name)175 nc_del_att(int ncid, int varid, const char *name)
176 {
177 NC* ncp;
178 int stat = NC_check_id(ncid, &ncp);
179 if(stat != NC_NOERR) return stat;
180 TRACE(nc_del_att);
181 stat = ncp->dispatch->del_att(ncid, varid, name);
182 return stat;
183 }
184 /**@}*/ /* End doxygen member group. */
185
186 /**@}*/
187