1/*! \file
2Functions for netCDF-4 features.
3
4Copyright 2010 University Corporation for Atmospheric
5Research/Unidata. See \ref copyright file for more info. */
6
7#include "ncdispatch.h"
8
9/** \defgroup groups Groups
10
11NetCDF-4 added support for hierarchical groups within netCDF datasets.
12
13Groups are identified with a ncid, which identifies both the open
14file, and the group within that file. When a file is opened with
15nc_open or nc_create, the ncid for the root group of that file is
16provided. Using that as a starting point, users can add new groups, or
17list and navigate existing groups or rename a group.
18
19All netCDF calls take a ncid which determines where the call will take
20its action. For example, the nc_def_var function takes a ncid as its
21first parameter. It will create a variable in whichever group its ncid
22refers to. Use the root ncid provided by nc_create or nc_open to
23create a variable in the root group. Or use nc_def_grp to create a
24group and use its ncid to define a variable in the new group.
25
26Variable are only visible in the group in which they are defined. The
27same applies to attributes. “Global” attributes are associated with
28the group whose ncid is used.
29
30Dimensions are visible in their groups, and all child groups.
31
32Group operations are only permitted on netCDF-4 files - that is, files
33created with the HDF5 flag in nc_create(). Groups are not compatible
34with the netCDF classic data model, so files created with the
35::NC_CLASSIC_MODEL file cannot contain groups (except the root group).
36
37Encoding both the open file id and group id in a single integer
38currently limits the number of groups per netCDF-4 file to no more
39than 32767.  Similarly, the number of simultaneously open netCDF-4
40files in one program context is limited to 32767.
41
42 */
43
44/** \{*/ /* All these functions are part of the above defgroup... */
45
46/*! Return the group ID for a group given the name.
47
48
49  @param[in] ncid      A valid file or group ncid.
50  @param[in] name      The name of the group you are querying.
51  @param[out] grp_ncid Pointer to memory to hold the group ncid.
52
53  @returns Error code or ::NC_NOERR or no error.
54
55 */
56int nc_inq_ncid(int ncid, const char *name, int *grp_ncid)
57{
58    NCncp;
59    int stat = NC_check_id(ncid,&ncp);
60    if(stat != NC_NOERR) return stat;
61    return ncp->dispatch->inq_ncid(ncid,name,grp_ncid);
62}
63
64/*! Get a list of groups or subgroups from a file or groupID.
65
66  @param[in]  ncid    The ncid of the file or parent group.
67  @param[out] numgrps Pointer to memory to hold the number of groups.
68  @param[out] ncids   Pointer to memory to hold the ncid for each group.
69
70  @returns Error code or ::NC_NOERR for no error.
71
72 */
73int nc_inq_grps(int ncid, int *numgrps, int *ncids)
74{
75    NCncp;
76    int stat = NC_check_id(ncid,&ncp);
77    if(stat != NC_NOERR) return stat;
78    return ncp->dispatch->inq_grps(ncid,numgrps,ncids);
79}
80
81/*! Get the name of a group given an ID.
82
83  @param[in]  ncid The ncid of the file or parent group.
84  @param[out] name The name of the group associated with the id.
85
86  @returns Error code or ::NC_NOERR for no error.
87*/
88int nc_inq_grpname(int ncid, char *name)
89{
90    NCncp;
91    int stat = NC_check_id(ncid,&ncp);
92    if(stat != NC_NOERR) return stat;
93    return ncp->dispatch->inq_grpname(ncid,name);
94}
95
96/*! Get the full path/groupname of a group/subgroup given an ID.
97
98  @param[in]  ncid      The ncid of the file or parent group.
99  @param[out] lenp      Pointer to memory to hold the length of the full name.
100  @param[out] full_name Pointer to memory to hold the full name of the group including root/parent.
101
102  @returns Error code or ::NC_NOERR for no error.
103
104*/
105
106int nc_inq_grpname_full(int ncid, size_t *lenp, char *full_name)
107{
108    NCncp;
109    int stat = NC_check_id(ncid,&ncp);
110    if(stat != NC_NOERR) return stat;
111    return ncp->dispatch->inq_grpname_full(ncid,lenp,full_name);
112}
113
114/*! Get the length of a group name given an ID.
115
116  @param[in] ncid  The ncid of the group in question.
117  @param[out] lenp Pointer to memory to hold the length of the name of the group in question.
118
119  @returns Error code or ::NC_NOERR for no error.
120
121*/
122int nc_inq_grpname_len(int ncid, size_t *lenp)
123{
124    int stat = nc_inq_grpname_full(ncid,lenp,NULL);
125    return stat;
126}
127
128/*! Get the ID of the parent based on a group ID.
129
130  @param[in] ncid         The ncid of the group in question.
131  @param[out] parent_ncid Pointer to memory to hold the identifier of the parent of the group in question.
132
133  @returns Error code or ::NC_NOERR for no error.
134
135 */
136int nc_inq_grp_parent(int ncid, int *parent_ncid)
137{
138    NCncp;
139    int stat = NC_check_id(ncid,&ncp);
140    if(stat != NC_NOERR) return stat;
141    return ncp->dispatch->inq_grp_parent(ncid,parent_ncid);
142}
143
144/*! Get a group ncid given the group name.
145
146  @param[in] ncid      The ncid of the file.
147  @param[in] grp_name  The name of the group in question.
148  @param[out] grp_ncid Pointer to memory to hold the identifier of the group in question.
149
150  @returns Error code or ::NC_NOERR for no error.
151
152\note{This has same semantics as nc_inq_ncid}
153
154*/
155int nc_inq_grp_ncid(int ncid, const char *grp_name, int *grp_ncid)
156{
157    return nc_inq_ncid(ncid,grp_name,grp_ncid);
158}
159
160/*! Get the full ncid given a group name.
161
162  @param[in] ncid      The ncid of the file.
163  @param[in] full_name The full name of the group in question.
164  @param[out] grp_ncid Pointer to memory to hold the identifier of the full group in question.
165
166  @returns Error code or ::NC_NOERR for no error.
167
168 */
169int nc_inq_grp_full_ncid(int ncid, const char *full_name, int *grp_ncid)
170{
171    NCncp;
172    int stat = NC_check_id(ncid,&ncp);
173    if(stat != NC_NOERR) return stat;
174    return ncp->dispatch->inq_grp_full_ncid(ncid,full_name,grp_ncid);
175}
176
177
178/*! Get a list of varids associated with a group given a group ID.
179
180  @param[in] ncid    The ncid of the group in question.
181  @param[out] nvars  Pointer to memory to hold the number of variables in the group in question.
182  @param[out] varids Pointer to memory to hold the variable ids contained by the group in question.
183
184  @returns Error code or ::NC_NOERR for no error.
185
186*/
187int nc_inq_varids(int ncid, int *nvars, int *varids)
188{
189    NCncp;
190    int stat = NC_check_id(ncid,&ncp);
191    if(stat != NC_NOERR) return stat;
192    return ncp->dispatch->inq_varids(ncid,nvars,varids);
193}
194
195/*! Retrieve a list of dimension ids associated with a group.
196
197  @param[in] ncid    The ncid of the group in question.
198  @param[out] ndims  Pointer to memory to contain the number of dimids associated with the group.
199  @param[out] dimids Pointer to memory to contain the number of dimensions associated with the group.
200  @param[in] include_parents If non-zero, parent groups are also traversed.
201
202  @returns Error code or ::NC_NOERR for no error.
203
204 */
205int nc_inq_dimids(int ncid, int *ndims, int *dimids, int include_parents)
206{
207    NCncp;
208    int stat = NC_check_id(ncid,&ncp);
209    if(stat != NC_NOERR) return stat;
210    return ncp->dispatch->inq_dimids(ncid,ndims,dimids,include_parents);
211}
212
213/*! Retrieve a list of types associated with a group
214
215  @param[in] ncid     The ncid for the group in question.
216  @param[out] ntypes  Pointer to memory to hold the number of typeids contained by the group in question.
217  @param[out] typeids Pointer to memory to hold the typeids contained by the group in question.
218
219  @returns Error code or ::NC_NOERR for no error.
220
221*/
222
223int nc_inq_typeids(int ncid, int *ntypes, int *typeids)
224{
225    NCncp;
226    int stat = NC_check_id(ncid,&ncp);
227    if(stat != NC_NOERR) return stat;
228    return ncp->dispatch->inq_typeids(ncid,ntypes,typeids);
229}
230
231/*! Define a new group.
232
233  The function nc_def_grp() adds a new
234  group to an open netCDF dataset in define mode.  It returns (as an
235  argument) a group id, given the parent ncid and the name of the group.
236
237  A group may be a top-level group if it is passed the ncid of the file,
238  or a sub-group if passed the ncid of an existing group.
239
240  @param[in]  parent_ncid The ncid of the parent for the group.
241  @param[in]  name        Name of the new group.
242  @param[out] new_ncid    Pointer to memory to hold the new ncid.
243
244  @returns Error code or ::NC_NOERR for no error.
245
246  @retval ::NC_NOERR No error.
247  @retval ::NC_ENOTNC4 Not an nc4 file.
248  @retval ::NC_ENOTINDEFINE Not in define mode.
249  @retval ::NC_ESTRICTNC3 Not permissible in nc4 classic mode.
250  @retval ::NC_EPERM Write to read only.
251  @retval ::NC_ENOMEM Memory allocation (malloc) failure.
252  @retval ::NC_ENAMEINUSE String match to name in use.
253
254  \section nc_def_grp_example Example
255
256  Here is an example using nc_def_grp() to create a new group.
257
258  \code{.c}
259
260  #include <netcdf.h>
261  ...
262  int status, ncid, grpid, latid, recid;
263  ...
264
265  \endcode
266
267*/
268int nc_def_grp(int parent_ncid, const char *name, int *new_ncid)
269{
270    NCncp;
271    int stat = NC_check_id(parent_ncid,&ncp);
272    if(stat != NC_NOERR) return stat;
273    return ncp->dispatch->def_grp(parent_ncid,name,new_ncid);
274}
275
276/*! Rename a group.
277
278  @param[in] grpid The ID for the group in question.
279  @param[in] name  The new name for the group.
280
281  @returns Error code or ::NC_NOERR for no error.
282
283*/
284int nc_rename_grp(int grpid, const char *name)
285{
286    NCncp;
287    int stat = NC_check_id(grpid,&ncp);
288    if(stat != NC_NOERR) return stat;
289    return ncp->dispatch->rename_grp(grpid,name);
290}
291
292/*! Print the metadata for a file.
293
294  @param[in] ncid The ncid of an open file.
295
296  @returns Error code or ::NC_NOERR for no error.
297
298 */
299int nc_show_metadata(int ncid)
300{
301    NCncp;
302    int stat = NC_check_id(ncid,&ncp);
303    if(stat != NC_NOERR) return stat;
304    return ncp->dispatch->show_metadata(ncid);
305}
306
307/** \} */


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