1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
/*Copyright 2018 University Corporation for Atmospheric
Research/Unidata. See copyright file for more info. */
/**
* @file
*
* These functions in this file rename and delete attributes.
*/
#include "config.h"
#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.
*
* 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
* 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. In netCDF-4/HDF5 files, global attributes are
* associated with a hierarchical group.
*
* 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().
*
* 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.
*/
/** @{*/
/**
* @name Deleting and Renaming Attributes
*
* Functions to delete or rename an attribute. */
/**@{*/ /* Start doxygen member group. */
/**
* Rename an attribute.
*
* The function nc_rename_att() changes the name of an attribute. In
* classic formats, if the new name is longer than the original name,
* the netCDF dataset must be in define mode. In netCDF-4/HDF5 files,
* attributes may be renamed at any time. 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
* @return ::NC_NOERR No error.
* @return ::NC_EBADID Bad ncid.
* @return ::NC_ENOTVAR Bad varid.
* @return ::NC_EBADNAME Bad name.
* @return ::NC_EMAXNAME New name too long.
* @return ::NC_EINVAL Name or new name not provided.
* @return ::NC_ENAMEINUSE Name already in use.
* @return ::NC_EPERM File was opened read only.
* @return ::NC_ENOTINDEFINE File is not in define mode.
* @return ::NC_ENOTATT Attribute not found.
* @return ::NC_EHDFERR Failure at HDF5 layer.
* @return ::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. For classic netCDF formats, the dataset must be in
* define mode to delete an attribute. In netCDF-4/HDF5 files,
* attributes may be deleted at any time.
*
* @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
* @return ::NC_NOERR No error.
* @return ::NC_EBADID Bad ncid.
* @return ::NC_ENOTVAR Bad varid.
* @return ::NC_EBADNAME Bad name.
* @return ::NC_EINVAL Name not provided.
* @return ::NC_EPERM File was opened read only.
* @return ::NC_ENOTINDEFINE File is not in define mode.
* @return ::NC_ENOTATT Attribute not found.
* @return ::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 doxygen member group. */
/**@}*/
|
