1/** \file
2Functions to write attributes.
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/** \name Writing Attributes
12
13Functions to write attributes. */
14/*! \{ */
15
16/*!
17\ingroup attributes
18Write a string attribute.
19
20The function nc_put_att_string adds or changes a variable attribute or
21global attribute of an open netCDF dataset. The string type is only
22available in netCDF-4/HDF5 files, when ::NC_CLASSIC_MODEL has not been
23used in nc_create().
24
25\param ncid NetCDF or group ID, from a previous call to nc_open(),
26nc_create(), nc_def_grp(), or associated inquiry functions such as
27nc_inq_ncid().
28
29\param varid Variable ID of the variable to which the attribute will
30be assigned or ::NC_GLOBAL for a global or group attribute.
31
32\param name Attribute \ref object_name. \ref attribute_conventions may
33apply.
34
35\param len Number of values provided for the attribute.
36
37\param value Pointer to one or more values.
38
39\returns ::NC_NOERR No error.
40\returns ::NC_EINVAL More than one value for _FillValue or trying to set global _FillValue.
41\returns ::NC_ENOTVAR Couldn't find varid.
42\returns ::NC_EBADTYPE Fill value and var must be same type.
43\returns ::NC_ENOMEM Out of memory
44\returns ::NC_ELATEFILL Fill values must be written while the file
45is still in initial define mode.
46*/
47
48
49int
50nc_put_att_string(int ncid, int varid, const char *name,
51   size_t len, const char** value)
52{
53    NCncp;
54    int stat = NC_check_id(ncid, &ncp);
55    if(stat != NC_NOERR) return stat;
56    return ncp->dispatch->put_att(ncidvaridnameNC_STRING,
57   len, (void*)valueNC_STRING);
58}
59
60/*!
61\ingroup attributes
62Write a text attribute.
63
64Add or change a text attribute. If this attribute is new,
65or if the space required to store the attribute is greater than
66before, the netCDF dataset must be in define mode.
67
68Although it's possible to create attributes of all types, text and
69double attributes are adequate for most purposes.
70
71Use the nc_put_att function to create attributes of any type,
72including user-defined types. We recommend using the type safe
73versions of this function whenever possible.
74
75\param ncid NetCDF or group ID, from a previous call to nc_open(),
76nc_create(), nc_def_grp(), or associated inquiry functions such as
77nc_inq_ncid().
78
79\param varid Variable ID of the variable to which the attribute will
80be assigned or ::NC_GLOBAL for a global attribute.
81
82\param name Attribute \ref object_name. \ref attribute_conventions may
83apply.
84
85\param len Number of values provided for the attribute.
86
87\param value Pointer to one or more values.
88
89\returns ::NC_NOERR No error.
90\returns ::NC_EINVAL More than one value for _FillValue or trying to set global _FillValue.
91\returns ::NC_ENOTVAR Couldn't find varid.
92\returns ::NC_EBADTYPE Fill value and var must be same type.
93\returns ::NC_ENOMEM Out of memory
94\returns ::NC_ELATEFILL Fill values must be written while the file
95is still in initial define mode.
96
97\note With netCDF-4 files, nc_put_att will notice if you are writing a
98_Fill_Value_ attribute, and will tell the HDF5 layer to use the
99specified fill value for that variable.
100
101\section nc_put_att_text_example Example
102
103Here is an example using nc_put_att_double() to add a variable
104attribute named valid_range for a netCDF variable named rh and
105nc_put_att_text() to add a global attribute named title to an existing
106netCDF dataset named foo.nc:
107
108\code
109     #include <netcdf.h>
110        ...
111     int  status;
112     int  ncid;
113     int  rh_id;
114     static double rh_range[] = {0.0, 100.0};
115     static char title[] = "example netCDF dataset";
116        ...
117     status = nc_open("foo.nc", NC_WRITE, &ncid);
118     if (status != NC_NOERR) handle_error(status);
119        ...
120     status = nc_redef(ncid);
121     if (status != NC_NOERR) handle_error(status);
122     status = nc_inq_varid (ncid, "rh", &rh_id);
123     if (status != NC_NOERR) handle_error(status);
124        ...
125     status = nc_put_att_double (ncid, rh_id, "valid_range",
126                                 NC_DOUBLE, 2, rh_range);
127     if (status != NC_NOERR) handle_error(status);
128     status = nc_put_att_text (ncid, NC_GLOBAL, "title",
129                               strlen(title), title)
130     if (status != NC_NOERR) handle_error(status);
131        ...
132     status = nc_enddef(ncid);
133     if (status != NC_NOERR) handle_error(status);
134\endcode
135*/
136
137
138int nc_put_att_text(int ncid, int varid, const char *name,
139 size_t len, const char *value)
140{
141   NCncp;
142   int stat = NC_check_id(ncid, &ncp);
143   if(stat != NC_NOERR) return stat;
144   return ncp->dispatch->put_att(ncidvaridnameNC_CHARlen,
145  (void *)valueNC_CHAR);
146}
147
148/*! \} */
149/*!
150\ingroup attributes
151Write an attribute.
152
153The function nc_put_att_ type adds or changes a variable attribute or
154global attribute of an open netCDF dataset. If this attribute is new,
155or if the space required to store the attribute is greater than
156before, the netCDF dataset must be in define mode.
157
158With netCDF-4 files, nc_put_att will notice if you are writing a
159_FillValue attribute, and will tell the HDF5 layer to use the
160specified fill value for that variable.  With either classic or
161netCDF-4 files, a _FillValue attribute will be checked for validity,
162to make sure it has only one value and that its type matches the type
163of the associated variable.
164
165Although it's possible to create attributes of all types, text and
166double attributes are adequate for most purposes.
167
168\param ncid NetCDF or group ID, from a previous call to nc_open(),
169nc_create(), nc_def_grp(), or associated inquiry functions such as
170nc_inq_ncid().
171
172\param varid Variable ID of the variable to which the attribute will
173be assigned or ::NC_GLOBAL for a global or group attribute.
174
175\param name Attribute \ref object_name. \ref attribute_conventions may
176apply.
177
178\param xtype \ref data_type of the attribute.
179
180\param len Number of values provided for the attribute.
181
182\param value Pointer to one or more values.
183
184\returns ::NC_NOERR No error.
185\returns ::NC_EINVAL More than one value for _FillValue or trying to set global _FillValue.
186\returns ::NC_ENOTVAR Couldn't find varid.
187\returns ::NC_EBADTYPE Fill value and var must be same type.
188\returns ::NC_ENOMEM Out of memory
189\returns ::NC_ELATEFILL Fill values must be written while the file
190is still in initial define mode.
191
192\section nc_put_att_double_example Example
193
194Here is an example using nc_put_att_double() to add a variable
195attribute named valid_range for a netCDF variable named rh and
196nc_put_att_text() to add a global attribute named title to an existing
197netCDF dataset named foo.nc:
198
199\code
200     #include <netcdf.h>
201        ...
202     int  status;
203     int  ncid;
204     int  rh_id;
205     static double rh_range[] = {0.0, 100.0};
206     static char title[] = "example netCDF dataset";
207        ...
208     status = nc_open("foo.nc", NC_WRITE, &ncid);
209     if (status != NC_NOERR) handle_error(status);
210        ...
211     status = nc_redef(ncid);
212     if (status != NC_NOERR) handle_error(status);
213     status = nc_inq_varid (ncid, "rh", &rh_id);
214     if (status != NC_NOERR) handle_error(status);
215        ...
216     status = nc_put_att_double (ncid, rh_id, "valid_range",
217                                 NC_DOUBLE, 2, rh_range);
218     if (status != NC_NOERR) handle_error(status);
219     status = nc_put_att_text (ncid, NC_GLOBAL, "title",
220                               strlen(title), title)
221     if (status != NC_NOERR) handle_error(status);
222        ...
223     status = nc_enddef(ncid);
224     if (status != NC_NOERR) handle_error(status);
225\endcode
226*/
227/*! \{*/
228int
229nc_put_att(int ncid, int varid, const char *namenc_type xtype,
230    size_t len, const void *value)
231{
232   NCncp;
233   int stat = NC_check_id(ncid, &ncp);
234   if(stat != NC_NOERR) return stat;
235   return ncp->dispatch->put_att(ncidvaridnamextypelen,
236  valuextype);
237}
238
239int
240nc_put_att_schar(int ncid, int varid, const char *name,
241  nc_type xtype, size_t len, const signed char *value)
242{
243   NC *ncp;
244   int stat = NC_check_id(ncid, &ncp);
245   if(stat != NC_NOERR) return stat;
246   return ncp->dispatch->put_att(ncidvaridnamextypelen,
247  (void *)valueNC_BYTE);
248}
249
250int
251nc_put_att_uchar(int ncid, int varid, const char *name,
252  nc_type xtype, size_t len, const unsigned char *value)
253{
254   NCncp;
255   int stat = NC_check_id(ncid, &ncp);
256   if(stat != NC_NOERR) return stat;
257   return ncp->dispatch->put_att(ncidvaridnamextypelen,
258  (void *)valueNC_UBYTE);
259}
260
261int
262nc_put_att_short(int ncid, int varid, const char *name,
263  nc_type xtype, size_t len, const short *value)
264{
265   NCncp;
266   int stat = NC_check_id(ncid, &ncp);
267   if(stat != NC_NOERR) return stat;
268   return ncp->dispatch->put_att(ncidvaridnamextypelen,
269  (void *)valueNC_SHORT);
270}
271
272int
273nc_put_att_int(int ncid, int varid, const char *name,
274        nc_type xtype, size_t len, const int *value)
275{
276   NCncp;
277   int stat = NC_check_id(ncid, &ncp);
278   if(stat != NC_NOERR) return stat;
279   return ncp->dispatch->put_att(ncidvaridnamextypelen,
280  (void *)valueNC_INT);
281}
282
283int
284nc_put_att_long(int ncid, int varid, const char *name,
285 nc_type xtype, size_t len, const long *value)
286{
287   NCncp;
288   int stat = NC_check_id(ncid, &ncp);
289   if(stat != NC_NOERR) return stat;
290   return ncp->dispatch->put_att(ncidvaridnamextypelen,
291  (void *)valuelongtype);
292}
293
294int
295nc_put_att_float(int ncid, int varid, const char *name,
296  nc_type xtype, size_t len, const float *value)
297{
298   NCncp;
299   int stat = NC_check_id(ncid, &ncp);
300   if(stat != NC_NOERR) return stat;
301   return ncp->dispatch->put_att(ncidvaridnamextypelen,
302  (void *)valueNC_FLOAT);
303}
304
305int
306nc_put_att_double(int ncid, int varid, const char *name,
307   nc_type xtype, size_t len, const double *value)
308{
309   NCncp;
310   int stat = NC_check_id(ncid, &ncp);
311   if(stat != NC_NOERR) return stat;
312   return ncp->dispatch->put_att(ncidvaridnamextypelen,
313  (void *)valueNC_DOUBLE);
314}
315
316int
317nc_put_att_ubyte(int ncid, int varid, const char *name,
318  nc_type xtype, size_t len, const unsigned char *value)
319{
320   NCncp;
321   int stat = NC_check_id(ncid, &ncp);
322   if(stat != NC_NOERR) return stat;
323   return ncp->dispatch->put_att(ncidvaridnamextypelen,
324  (void *)valueNC_UBYTE);
325}
326
327int
328nc_put_att_ushort(int ncid, int varid, const char *name,
329   nc_type xtype, size_t len, const unsigned short *value)
330{
331   NCncp;
332   int stat = NC_check_id(ncid, &ncp);
333   if(stat != NC_NOERR) return stat;
334   return ncp->dispatch->put_att(ncidvaridnamextypelen,
335  (void *)valueNC_USHORT);
336}
337
338int
339nc_put_att_uint(int ncid, int varid, const char *name,
340 nc_type xtype, size_t len, const unsigned int *value)
341{
342   NCncp;
343   int stat = NC_check_id(ncid, &ncp);
344   if(stat != NC_NOERR) return stat;
345   return ncp->dispatch->put_att(ncidvaridnamextypelen,
346  (void *)valueNC_UINT);
347}
348
349int
350nc_put_att_longlong(int ncid, int varid, const char *name,
351     nc_type xtype, size_t len,
352     const long long *value)
353{
354   NCncp;
355   int stat = NC_check_id(ncid, &ncp);
356   if(stat != NC_NOERR) return stat;
357   return ncp->dispatch->put_att(ncidvaridnamextypelen,
358  (void *)valueNC_INT64);
359}
360
361int
362nc_put_att_ulonglong(int ncid, int varid, const char *name,
363      nc_type xtype, size_t len,
364      const unsigned long long *value)
365{
366   NCncp;
367   int stat = NC_check_id(ncid, &ncp);
368   if(stat != NC_NOERR) return stat;
369   return ncp->dispatch->put_att(ncidvaridnamextypelen,
370  (void *)valueNC_UINT64);
371}


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