source: XIOS/dev/dev_cmip6_omp/extern/src_netcdf4/datt.c @ 1606

Last change on this file since 1606 was 409, checked in by ymipsl, 11 years ago

Add improved nectdf internal library src

YM

  • Property svn:eol-style set to native
File size: 5.2 KB
Line 
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   NC* ncp;
110   int stat = NC_check_id(ncid, &ncp);
111   if(stat != NC_NOERR) return stat;
112   return ncp->dispatch->rename_att(ncid, varid, name, newname);
113}
114
115/*!
116Delete an attribute.
117
118The function nc_del_att() deletes a netCDF attribute from an open
119netCDF dataset. The netCDF dataset must be in define mode.
120
121\param ncid NetCDF or group ID, from a previous call to nc_open(),
122nc_create(), nc_def_grp(), or associated inquiry functions such as
123nc_inq_ncid().
124
125\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
126for a global attribute.
127
128\param name Attribute name.
129
130<h1>Example</h1>
131
132Here is an example using nc_del_att() to delete the variable attribute
133Units for a variable rh in an existing netCDF dataset named foo.nc:
134
135\code
136     #include <netcdf.h>
137        ...
138     int  status;     
139     int  ncid;     
140     int  rh_id;     
141        ...
142     status = nc_open("foo.nc", NC_WRITE, &ncid);
143     if (status != NC_NOERR) handle_error(status);
144        ...
145     status = nc_inq_varid (ncid, "rh", &rh_id);
146     if (status != NC_NOERR) handle_error(status);
147        ...
148     status = nc_redef(ncid);
149     if (status != NC_NOERR) handle_error(status);
150     status = nc_del_att(ncid, rh_id, "Units");
151     if (status != NC_NOERR) handle_error(status);
152     status = nc_enddef(ncid);
153     if (status != NC_NOERR) handle_error(status);
154\endcode
155 */
156int
157nc_del_att(int ncid, int varid, const char *name)
158{
159   NC* ncp;
160   int stat = NC_check_id(ncid, &ncp);
161   if(stat != NC_NOERR) return stat;
162   return ncp->dispatch->del_att(ncid, varid, name);
163}
164/*! \} */  /* End of named group ...*/
165
166/*! \} */ /* End of defgroup. */
Note: See TracBrowser for help on using the repository browser.