1 | /** \file |
---|
2 | Attribute inquiry functions |
---|
3 | |
---|
4 | These functions find out about attributes. |
---|
5 | |
---|
6 | Copyright 2011 University Corporation for Atmospheric |
---|
7 | Research/Unidata. See \ref copyright file for more info. */ |
---|
8 | |
---|
9 | #include "ncdispatch.h" |
---|
10 | |
---|
11 | /** \name Learning about Attributes |
---|
12 | |
---|
13 | Functions to learn about the attributes in a file. */ |
---|
14 | /*! \{ */ /* All these functions are part of this named group... */ |
---|
15 | |
---|
16 | /** |
---|
17 | \ingroup attributes |
---|
18 | Return information about a netCDF attribute. |
---|
19 | |
---|
20 | The function nc_inq_att returns the attribute's type and length. |
---|
21 | |
---|
22 | \param ncid NetCDF or group ID, from a previous call to nc_open(), |
---|
23 | nc_create(), nc_def_grp(), or associated inquiry functions such as |
---|
24 | nc_inq_ncid(). |
---|
25 | |
---|
26 | \param varid Variable ID of the attribute's variable, or ::NC_GLOBAL |
---|
27 | for a global attribute. |
---|
28 | |
---|
29 | \param name Pointer to the location for the returned attribute \ref |
---|
30 | object_name. \ref ignored_if_null. |
---|
31 | |
---|
32 | \param xtypep Pointer to location for returned attribute \ref |
---|
33 | data_type. \ref ignored_if_null. |
---|
34 | |
---|
35 | \param lenp Pointer to location for returned number of values |
---|
36 | currently stored in the attribute. For attributes of type ::NC_CHAR, |
---|
37 | you should not assume that this includes a trailing zero byte; it |
---|
38 | doesn't if the attribute was stored without a trailing zero byte, for |
---|
39 | example from a FORTRAN program. Before using the value as a C string, |
---|
40 | make sure it is null-terminated. \ref ignored_if_null. |
---|
41 | |
---|
42 | \section Example |
---|
43 | |
---|
44 | Here is an example using nc_inq_att() to find out the type and length of |
---|
45 | a variable attribute named valid_range for a netCDF variable named rh |
---|
46 | and a global attribute named title in an existing netCDF dataset named |
---|
47 | foo.nc: |
---|
48 | |
---|
49 | \code |
---|
50 | #include <netcdf.h> |
---|
51 | ... |
---|
52 | int status; |
---|
53 | int ncid; |
---|
54 | int rh_id; |
---|
55 | nc_type vr_type, t_type; |
---|
56 | size_t vr_len, t_len; |
---|
57 | |
---|
58 | ... |
---|
59 | status = nc_open("foo.nc", NC_NOWRITE, &ncid); |
---|
60 | if (status != NC_NOERR) handle_error(status); |
---|
61 | ... |
---|
62 | status = nc_inq_varid (ncid, "rh", &rh_id); |
---|
63 | if (status != NC_NOERR) handle_error(status); |
---|
64 | ... |
---|
65 | status = nc_inq_att (ncid, rh_id, "valid_range", &vr_type, &vr_len); |
---|
66 | if (status != NC_NOERR) handle_error(status); |
---|
67 | status = nc_inq_att (ncid, NC_GLOBAL, "title", &t_type, &t_len); |
---|
68 | if (status != NC_NOERR) handle_error(status); |
---|
69 | \endcode |
---|
70 | */ |
---|
71 | int |
---|
72 | nc_inq_att(int ncid, int varid, const char *name, nc_type *xtypep, |
---|
73 | size_t *lenp) |
---|
74 | { |
---|
75 | NC* ncp; |
---|
76 | int stat = NC_check_id(ncid, &ncp); |
---|
77 | if(stat != NC_NOERR) return stat; |
---|
78 | return ncp->dispatch->inq_att(ncid, varid, name, xtypep, lenp); |
---|
79 | } |
---|
80 | |
---|
81 | /** |
---|
82 | \ingroup attributes |
---|
83 | Find an attribute ID. |
---|
84 | |
---|
85 | \param ncid NetCDF or group ID, from a previous call to nc_open(), |
---|
86 | nc_create(), nc_def_grp(), or associated inquiry functions such as |
---|
87 | nc_inq_ncid(). |
---|
88 | |
---|
89 | \param varid Variable ID of the attribute's variable, or ::NC_GLOBAL for |
---|
90 | a global attribute. |
---|
91 | |
---|
92 | \param name Attribute \ref object_name. |
---|
93 | |
---|
94 | \param idp Pointer to location for returned attribute number that |
---|
95 | specifies which attribute this is for this variable (or which global |
---|
96 | attribute). If you already know the attribute name, knowing its number |
---|
97 | is not very useful, because accessing information about an attribute |
---|
98 | requires its name. |
---|
99 | */ |
---|
100 | int |
---|
101 | nc_inq_attid(int ncid, int varid, const char *name, int *idp) |
---|
102 | { |
---|
103 | NC* ncp; |
---|
104 | int stat = NC_check_id(ncid, &ncp); |
---|
105 | if(stat != NC_NOERR) return stat; |
---|
106 | return ncp->dispatch->inq_attid(ncid, varid, name, idp); |
---|
107 | } |
---|
108 | |
---|
109 | /** |
---|
110 | \ingroup attributes |
---|
111 | Find the name of an attribute. |
---|
112 | |
---|
113 | \param ncid NetCDF or group ID, from a previous call to nc_open(), |
---|
114 | nc_create(), nc_def_grp(), or associated inquiry functions such as |
---|
115 | nc_inq_ncid(). |
---|
116 | |
---|
117 | \param varid Variable ID of the attribute's variable, or ::NC_GLOBAL |
---|
118 | for a global attribute. |
---|
119 | |
---|
120 | \param attnum Attribute number. The attributes for each variable are |
---|
121 | numbered from 0 (the first attribute) to natts-1, where natts is the |
---|
122 | number of attributes for the variable, as returned from a call to |
---|
123 | nc_inq_varnatts(). |
---|
124 | |
---|
125 | \param name Pointer to the location for the returned attribute \ref |
---|
126 | object_name. |
---|
127 | */ |
---|
128 | int |
---|
129 | nc_inq_attname(int ncid, int varid, int attnum, char *name) |
---|
130 | { |
---|
131 | NC* ncp; |
---|
132 | int stat = NC_check_id(ncid, &ncp); |
---|
133 | if(stat != NC_NOERR) return stat; |
---|
134 | return ncp->dispatch->inq_attname(ncid, varid, attnum, name); |
---|
135 | } |
---|
136 | |
---|
137 | /** |
---|
138 | \ingroup attributes |
---|
139 | Find number of global or group attributes. |
---|
140 | |
---|
141 | \param ncid NetCDF or group ID, from a previous call to nc_open(), |
---|
142 | nc_create(), nc_def_grp(), or associated inquiry functions such as |
---|
143 | nc_inq_ncid(). |
---|
144 | |
---|
145 | \param nattsp Pointer where number of global or group attributes will be |
---|
146 | written. \ref ignored_if_null. |
---|
147 | */ |
---|
148 | int |
---|
149 | nc_inq_natts(int ncid, int *nattsp) |
---|
150 | { |
---|
151 | NC* ncp; |
---|
152 | int stat = NC_check_id(ncid, &ncp); |
---|
153 | if(stat != NC_NOERR) return stat; |
---|
154 | if(nattsp == NULL) return NC_NOERR; |
---|
155 | return ncp->dispatch->inq(ncid, NULL, NULL, nattsp, NULL); |
---|
156 | } |
---|
157 | |
---|
158 | /** |
---|
159 | \ingroup attributes |
---|
160 | Find the type of an attribute. |
---|
161 | |
---|
162 | \param ncid NetCDF or group ID, from a previous call to nc_open(), |
---|
163 | nc_create(), nc_def_grp(), or associated inquiry functions such as |
---|
164 | nc_inq_ncid(). |
---|
165 | |
---|
166 | \param varid Variable ID of the attribute's variable, or ::NC_GLOBAL |
---|
167 | for a global or group attribute. |
---|
168 | |
---|
169 | \param name Attribute \ref object_name. |
---|
170 | |
---|
171 | \param xtypep Pointer to location for returned attribute \ref data_type. |
---|
172 | */ |
---|
173 | int |
---|
174 | nc_inq_atttype(int ncid, int varid, const char *name, nc_type *xtypep) |
---|
175 | { |
---|
176 | NC* ncp; |
---|
177 | int stat = NC_check_id(ncid, &ncp); |
---|
178 | if(stat != NC_NOERR) return stat; |
---|
179 | return ncp->dispatch->inq_att(ncid, varid, name, xtypep, NULL); |
---|
180 | } |
---|
181 | |
---|
182 | /** |
---|
183 | \ingroup attributes |
---|
184 | Find the length of an attribute. |
---|
185 | |
---|
186 | \param ncid NetCDF or group ID, from a previous call to nc_open(), |
---|
187 | nc_create(), nc_def_grp(), or associated inquiry functions such as |
---|
188 | nc_inq_ncid(). |
---|
189 | |
---|
190 | \param varid Variable ID of the attribute's variable, or ::NC_GLOBAL |
---|
191 | for a global or group attribute. |
---|
192 | |
---|
193 | \param name Attribute \ref object_name. |
---|
194 | |
---|
195 | \param lenp Pointer to location for returned number of values |
---|
196 | currently stored in the attribute. Before using the value as a C |
---|
197 | string, make sure it is null-terminated. \ref ignored_if_null. |
---|
198 | */ |
---|
199 | int |
---|
200 | nc_inq_attlen(int ncid, int varid, const char *name, size_t *lenp) |
---|
201 | { |
---|
202 | NC* ncp; |
---|
203 | int stat = NC_check_id(ncid, &ncp); |
---|
204 | if(stat != NC_NOERR) return stat; |
---|
205 | return ncp->dispatch->inq_att(ncid, varid, name, NULL, lenp); |
---|
206 | } |
---|
207 | |
---|
208 | /*! \} */ /* End of named group ...*/ |
---|