1 | /*! \file |
---|
2 | Functions for netCDF-4 features. |
---|
3 | |
---|
4 | Copyright 2010 University Corporation for Atmospheric |
---|
5 | Research/Unidata. See \ref COPYRIGHT file for more info. */ |
---|
6 | |
---|
7 | #include "ncdispatch.h" |
---|
8 | |
---|
9 | /** \defgroup user_types User-Defined Types |
---|
10 | |
---|
11 | User defined types allow for more complex data structures. |
---|
12 | |
---|
13 | NetCDF-4 has added support for four different user defined data |
---|
14 | types. User defined type may only be used in files created with the |
---|
15 | ::NC_NETCDF4 and without ::NC_CLASSIC_MODEL. |
---|
16 | - compound type: like a C struct, a compound type is a collection of |
---|
17 | types, including other user defined types, in one package. |
---|
18 | - variable length array type: used to store ragged arrays. |
---|
19 | - opaque type: This type has only a size per element, and no other |
---|
20 | type information. |
---|
21 | - enum type: Like an enumeration in C, this type lets you assign text |
---|
22 | values to integer values, and store the integer values. |
---|
23 | |
---|
24 | Users may construct user defined type with the various nc_def_* |
---|
25 | functions described in this section. They may learn about user defined |
---|
26 | types by using the nc_inq_ functions defined in this section. |
---|
27 | |
---|
28 | Once types are constructed, define variables of the new type with |
---|
29 | nc_def_var (see nc_def_var). Write to them with nc_put_var1, |
---|
30 | nc_put_var, nc_put_vara, or nc_put_vars. Read data of user-defined |
---|
31 | type with nc_get_var1, nc_get_var, nc_get_vara, or nc_get_vars (see |
---|
32 | \ref variables). |
---|
33 | |
---|
34 | Create attributes of the new type with nc_put_att (see nc_put_att_ |
---|
35 | type). Read attributes of the new type with nc_get_att (see |
---|
36 | \ref attributes). |
---|
37 | */ |
---|
38 | /** \{ */ |
---|
39 | |
---|
40 | /** \} */ |
---|
41 | |
---|
42 | /** \defgroup groups Groups |
---|
43 | |
---|
44 | NetCDF-4 added support for hierarchical groups within netCDF datasets. |
---|
45 | |
---|
46 | Groups are identified with a ncid, which identifies both the open |
---|
47 | file, and the group within that file. When a file is opened with |
---|
48 | nc_open or nc_create, the ncid for the root group of that file is |
---|
49 | provided. Using that as a starting point, users can add new groups, or |
---|
50 | list and navigate existing groups. |
---|
51 | |
---|
52 | All netCDF calls take a ncid which determines where the call will take |
---|
53 | its action. For example, the nc_def_var function takes a ncid as its |
---|
54 | first parameter. It will create a variable in whichever group its ncid |
---|
55 | refers to. Use the root ncid provided by nc_create or nc_open to |
---|
56 | create a variable in the root group. Or use nc_def_grp to create a |
---|
57 | group and use its ncid to define a variable in the new group. |
---|
58 | |
---|
59 | Variable are only visible in the group in which they are defined. The |
---|
60 | same applies to attributes. âGlobalâ attributes are associated with |
---|
61 | the group whose ncid is used. |
---|
62 | |
---|
63 | Dimensions are visible in their groups, and all child groups. |
---|
64 | |
---|
65 | Group operations are only permitted on netCDF-4 files - that is, files |
---|
66 | created with the HDF5 flag in nc_create(). Groups are not compatible |
---|
67 | with the netCDF classic data model, so files created with the |
---|
68 | ::NC_CLASSIC_MODEL file cannot contain groups (except the root group). |
---|
69 | |
---|
70 | */ |
---|
71 | /** \{ */ |
---|
72 | int |
---|
73 | nc_inq_ncid(int ncid, const char *name, int *grp_ncid) |
---|
74 | { |
---|
75 | NC* ncp; |
---|
76 | int stat = NC_check_id(ncid,&ncp); |
---|
77 | if(stat != NC_NOERR) return stat; |
---|
78 | return ncp->dispatch->inq_ncid(ncid,name,grp_ncid); |
---|
79 | } |
---|
80 | |
---|
81 | int |
---|
82 | nc_inq_grps(int ncid, int *numgrps, int *ncids) |
---|
83 | { |
---|
84 | NC* ncp; |
---|
85 | int stat = NC_check_id(ncid,&ncp); |
---|
86 | if(stat != NC_NOERR) return stat; |
---|
87 | return ncp->dispatch->inq_grps(ncid,numgrps,ncids); |
---|
88 | } |
---|
89 | |
---|
90 | int |
---|
91 | nc_inq_grpname(int ncid, char *name) |
---|
92 | { |
---|
93 | NC* ncp; |
---|
94 | int stat = NC_check_id(ncid,&ncp); |
---|
95 | if(stat != NC_NOERR) return stat; |
---|
96 | return ncp->dispatch->inq_grpname(ncid,name); |
---|
97 | } |
---|
98 | |
---|
99 | int |
---|
100 | nc_inq_grpname_full(int ncid, size_t *lenp, char *full_name) |
---|
101 | { |
---|
102 | NC* ncp; |
---|
103 | int stat = NC_check_id(ncid,&ncp); |
---|
104 | if(stat != NC_NOERR) return stat; |
---|
105 | return ncp->dispatch->inq_grpname_full(ncid,lenp,full_name); |
---|
106 | } |
---|
107 | |
---|
108 | int |
---|
109 | nc_inq_grpname_len(int ncid, size_t *lenp) |
---|
110 | { |
---|
111 | int stat = nc_inq_grpname_full(ncid,lenp,NULL); |
---|
112 | return stat; |
---|
113 | } |
---|
114 | |
---|
115 | int |
---|
116 | nc_inq_grp_parent(int ncid, int *parent_ncid) |
---|
117 | { |
---|
118 | NC* ncp; |
---|
119 | int stat = NC_check_id(ncid,&ncp); |
---|
120 | if(stat != NC_NOERR) return stat; |
---|
121 | return ncp->dispatch->inq_grp_parent(ncid,parent_ncid); |
---|
122 | } |
---|
123 | |
---|
124 | /* This has same semantics as nc_inq_ncid */ |
---|
125 | int |
---|
126 | nc_inq_grp_ncid(int ncid, const char *grp_name, int *grp_ncid) |
---|
127 | { |
---|
128 | return nc_inq_ncid(ncid,grp_name,grp_ncid); |
---|
129 | } |
---|
130 | |
---|
131 | int |
---|
132 | nc_inq_grp_full_ncid(int ncid, const char *full_name, int *grp_ncid) |
---|
133 | { |
---|
134 | NC* ncp; |
---|
135 | int stat = NC_check_id(ncid,&ncp); |
---|
136 | if(stat != NC_NOERR) return stat; |
---|
137 | return ncp->dispatch->inq_grp_full_ncid(ncid,full_name,grp_ncid); |
---|
138 | } |
---|
139 | |
---|
140 | int |
---|
141 | nc_inq_varids(int ncid, int *nvars, int *varids) |
---|
142 | { |
---|
143 | NC* ncp; |
---|
144 | int stat = NC_check_id(ncid,&ncp); |
---|
145 | if(stat != NC_NOERR) return stat; |
---|
146 | return ncp->dispatch->inq_varids(ncid,nvars,varids); |
---|
147 | } |
---|
148 | |
---|
149 | int |
---|
150 | nc_inq_dimids(int ncid, int *ndims, int *dimids, int include_parents) |
---|
151 | { |
---|
152 | NC* ncp; |
---|
153 | int stat = NC_check_id(ncid,&ncp); |
---|
154 | if(stat != NC_NOERR) return stat; |
---|
155 | return ncp->dispatch->inq_dimids(ncid,ndims,dimids,include_parents); |
---|
156 | } |
---|
157 | |
---|
158 | int |
---|
159 | nc_inq_typeids(int ncid, int *ntypes, int *typeids) |
---|
160 | { |
---|
161 | NC* ncp; |
---|
162 | int stat = NC_check_id(ncid,&ncp); |
---|
163 | if(stat != NC_NOERR) return stat; |
---|
164 | return ncp->dispatch->inq_typeids(ncid,ntypes,typeids); |
---|
165 | } |
---|
166 | |
---|
167 | int |
---|
168 | nc_def_grp(int parent_ncid, const char *name, int *new_ncid) |
---|
169 | { |
---|
170 | NC* ncp; |
---|
171 | int stat = NC_check_id(parent_ncid,&ncp); |
---|
172 | if(stat != NC_NOERR) return stat; |
---|
173 | return ncp->dispatch->def_grp(parent_ncid,name,new_ncid); |
---|
174 | } |
---|
175 | |
---|
176 | |
---|
177 | |
---|
178 | int |
---|
179 | nc_show_metadata(int ncid) |
---|
180 | { |
---|
181 | NC* ncp; |
---|
182 | int stat = NC_check_id(ncid,&ncp); |
---|
183 | if(stat != NC_NOERR) return stat; |
---|
184 | return ncp->dispatch->show_metadata(ncid); |
---|
185 | } |
---|
186 | |
---|
187 | /** \} */ |
---|