1/*! \file
2  Functions for Compound Types
3
4  Copyright 2011 University Corporation for Atmospheric
5  Research/Unidata. See \ref copyright file for more info. */
6
7#include "ncdispatch.h"
8
9/** \name Compound Types
10    Functions to create and learn about compound types. */
11/*! \{ */ /* All these functions are part of this named group... */
12
13
14/** \ingroup user_types
15
16Create a compound type. Provide an ncid, a name, and a total size (in
17bytes) of one element of the completed compound type.
18
19After calling this function, fill out the type with repeated calls to
20nc_insert_compound(). Call nc_insert_compound() once for each field
21you wish to insert into the compound type.
22
23\param ncid \ref ncid
24\param size The size, in bytes, of the compound type.
25\param name \ref object_name of the created type.
26\param typeidp The type ID of the new type is copied here.
27
28\returns ::NC_NOERR No error.
29\returns ::NC_EBADID Bad \ref ncid.
30\returns ::NC_EBADTYPE Bad type id.
31\returns ::NC_ENAMEINUSE That name is in use.
32\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
33\returns ::NC_EBADNAME Name contains illegal characters.
34\returns ::NC_ESTRICTNC3 Attempting a netCDF-4 operation on a netCDF-3 file.
35\returns ::NC_ENOTNC4 This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see nc_open).
36\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
37\returns ::NC_EPERM Attempt to write to a read-only file.
38\returns ::NC_ENOTINDEFINE Not in define mode.
39
40\section nc_def_compound_example Example
41
42\code
43struct s1
44{
45int i1;
46int i2;
47};
48struct s1 data[DIM_LEN], data_in[DIM_LEN];
49
50if (nc_create(FILE_NAME, NC_NETCDF4, &ncid)) ERR;
51if (nc_def_compound(ncid, sizeof(struct s1), SVC_REC, &typeid)) ERR;
52if (nc_insert_compound(ncid, typeid, BATTLES_WITH_KLINGONS,
53HOFFSET(struct s1, i1), NC_INT)) ERR;
54if (nc_insert_compound(ncid, typeid, DATES_WITH_ALIENS,
55HOFFSET(struct s1, i2), NC_INT)) ERR;
56if (nc_def_dim(ncid, STARDATE, DIM_LEN, &dimid)) ERR;
57if (nc_def_var(ncid, SERVICE_RECORD, typeid, 1, dimids, &varid)) ERR;
58if (nc_put_var(ncid, varid, data)) ERR;
59if (nc_close(ncid)) ERR;
60\endcode
61*/
62int
63nc_def_compound(int ncid, size_t size, const char *name,
64 nc_type *typeidp)
65{
66   NCncp;
67   int stat = NC_check_id(ncid,&ncp);
68   if(stat != NC_NOERR) return stat;
69   return ncp->dispatch->def_compound(ncid,size,name,typeidp);
70}
71
72/** \ingroup user_types
73Insert a named field into a compound type.
74
75\param ncid \ref ncid
76
77\param xtype The typeid for this compound type, as returned by
78nc_def_compound(), or nc_inq_var().
79
80\param name The \ref object_name of the new field.
81
82\param offset Offset in byte from the beginning of the compound type
83for this field.
84
85\param field_typeid The type of the field to be inserted.
86
87\returns ::NC_NOERR No error.
88\returns ::NC_EBADID Bad \ref ncid.
89\returns ::NC_EBADTYPE Bad type id.
90\returns ::NC_ENAMEINUSE That name is in use.
91\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
92\returns ::NC_EBADNAME Name contains illegal characters.
93\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
94\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
95\returns ::NC_EPERM Attempt to write to a read-only file.
96\returns ::NC_ENOTINDEFINE Not in define mode.
97*/
98int
99nc_insert_compound(int ncidnc_type xtype, const char *name,
100    size_t offsetnc_type field_typeid)
101{
102   NC *ncp;
103   int stat = NC_check_id(ncid, &ncp);
104   if(stat != NC_NOERR) return stat;
105   return ncp->dispatch->insert_compound(ncidxtypename,
106  offsetfield_typeid);
107}
108
109/** \ingroup user_types
110Insert a named array field into a compound type.
111
112\param ncid \ref ncid
113
114\param xtype The typeid for this compound type, as returned by
115nc_def_compound(), or nc_inq_var().
116
117\param name The \ref object_name of the new field.
118
119\param offset Offset in byte from the beginning of the compound type
120for this field.
121
122\param field_typeid The type of the field to be inserted.
123
124 \param ndims Number of dimensions in array.
125
126 \param dim_sizes Array of dimension sizes.
127
128\returns ::NC_NOERR No error.
129\returns ::NC_EBADID Bad \ref ncid.
130\returns ::NC_EBADTYPE Bad type id.
131\returns ::NC_ENAMEINUSE That name is in use.
132\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
133\returns ::NC_EBADNAME Name contains illegal characters.
134\returns ::NC_ESTRICTNC3 Attempting a netCDF-4 operation on a netCDF-3 file.
135\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
136\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
137\returns ::NC_EPERM Attempt to write to a read-only file.
138\returns ::NC_ENOTINDEFINE Not in define mode.
139*/
140int
141nc_insert_array_compound(int ncidnc_type xtype, const char *name,
142  size_t offsetnc_type field_typeid,
143  int ndims, const int *dim_sizes)
144{
145   NCncp;
146   int stat = NC_check_id(ncid,&ncp);
147   if(stat != NC_NOERR) return stat;
148   return ncp->dispatch->insert_array_compound(ncid,xtype,name,offset,field_typeid,ndims,dim_sizes);
149}
150
151/**  \ingroup user_types
152Learn about a compound type. Get the number of fields, len, and
153name of a compound type.
154
155\param ncid \ref ncid
156
157\param xtype The typeid for this compound type, as returned by
158nc_def_compound(), or nc_inq_var().
159
160\param name Returned \ref object_name of compound type. \ref
161ignored_if_null.
162
163\param sizep Returned size of compound type in bytes. \ref ignored_if_null.
164
165\param nfieldsp The number of fields in the compound type will be
166placed here. \ref ignored_if_null.
167
168\returns ::NC_NOERR No error.
169\returns ::NC_EBADID Bad \ref ncid.
170\returns ::NC_EBADTYPE Bad type id.
171\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
172\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
173 */
174int
175nc_inq_compound(int ncidnc_type xtype, char *name,
176 size_t *sizep, size_t *nfieldsp)
177{
178   int class = 0;
179   int stat = nc_inq_user_type(ncid,xtype,name,sizep,NULL,nfieldsp,&class);
180   if(stat != NC_NOERR) return stat;
181   if(class != NC_COMPOUNDstat = NC_EBADTYPE;
182   return stat;
183}
184
185/**  \ingroup user_types
186Learn the name of a compound type.
187
188\param ncid \ref ncid
189
190\param xtype The typeid for this compound type, as returned by
191nc_def_compound(), or nc_inq_var().
192
193\param name Returned \ref object_name of compound type. \ref
194ignored_if_null.
195
196\returns ::NC_NOERR No error.
197\returns ::NC_EBADID Bad \ref ncid.
198\returns ::NC_EBADTYPE Bad type id.
199\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
200\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
201 */
202int
203nc_inq_compound_name(int ncidnc_type xtype, char *name)
204{
205   return nc_inq_compound(ncid,xtype,name,NULL,NULL);
206}
207
208/**  \ingroup user_types
209Learn the size of a compound type.
210
211\param ncid \ref ncid
212
213\param xtype The typeid for this compound type, as returned by
214nc_def_compound(), or nc_inq_var().
215
216\param sizep Returned size of compound type in bytes. \ref
217ignored_if_null.
218
219\returns ::NC_NOERR No error.
220\returns ::NC_EBADID Bad \ref ncid.
221\returns ::NC_EBADTYPE Bad type id.
222\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
223\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
224 */
225int
226nc_inq_compound_size(int ncidnc_type xtype, size_t *sizep)
227{
228   return nc_inq_compound(ncid,xtype,NULL,sizep,NULL);
229}
230
231/**  \ingroup user_types
232Learn the number of fields in a compound type.
233
234\param ncid \ref ncid
235
236\param xtype The typeid for this compound type, as returned by
237nc_def_compound(), or nc_inq_var().
238
239\param nfieldsp The number of fields in the compound type will be
240placed here. \ref ignored_if_null.
241
242\returns ::NC_NOERR No error.
243\returns ::NC_EBADID Bad \ref ncid.
244\returns ::NC_EBADTYPE Bad type id.
245\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
246\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
247 */
248int
249nc_inq_compound_nfields(int ncidnc_type xtype, size_t *nfieldsp)
250{
251   return nc_inq_compound(ncid,xtype,NULL,NULL,nfieldsp);
252}
253
254/**  \ingroup user_types
255Get information about one of the fields of a compound type.
256
257\param ncid \ref ncid
258
259\param xtype The typeid for this compound type, as returned by
260nc_def_compound(), or nc_inq_var().
261
262\param fieldid A zero-based index number specifying a field in the
263compound type.
264
265\param name Returned \ref object_name of the field. \ref
266ignored_if_null.
267
268\param offsetp A pointer which will get the offset of the field. \ref
269ignored_if_null.
270
271\param field_typeidp A pointer which will get the typeid of the
272field. \ref ignored_if_null.
273
274\param ndimsp A pointer which will get the number of dimensions of the
275field. \ref ignored_if_null.
276
277\param dim_sizesp A pointer which will get the dimension sizes of the
278field. \ref ignored_if_null.
279
280\returns ::NC_NOERR No error.
281\returns ::NC_EBADID Bad \ref ncid.
282\returns ::NC_EBADTYPE Bad type id.
283\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
284\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
285 */
286int
287nc_inq_compound_field(int ncidnc_type xtype, int fieldid,
288       char *name, size_t *offsetp,
289       nc_type *field_typeidp, int *ndimsp,
290       int *dim_sizesp)
291{
292   NCncp;
293   int stat = NC_check_id(ncid,&ncp);
294   if(stat != NC_NOERR) return stat;
295   return ncp->dispatch->inq_compound_field(ncidxtypefieldid,
296     nameoffsetpfield_typeidp,
297     ndimspdim_sizesp);
298}
299
300/**  \ingroup user_types
301Get information about one of the fields of a compound type.
302
303\param ncid \ref ncid
304
305\param xtype The typeid for this compound type, as returned by
306nc_def_compound(), or nc_inq_var().
307
308\param fieldid A zero-based index number specifying a field in the
309compound type.
310
311\param name Returned \ref object_name of the field. \ref
312ignored_if_null.
313
314\returns ::NC_NOERR No error.
315\returns ::NC_EBADID Bad \ref ncid.
316\returns ::NC_EBADTYPE Bad type id.
317\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
318\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
319 */
320int
321nc_inq_compound_fieldname(int ncidnc_type xtype, int fieldid,
322   char *name)
323{
324   NCncp;
325   int stat = NC_check_id(ncid,&ncp);
326   if(stat != NC_NOERR) return stat;
327   return ncp->dispatch->inq_compound_field(ncidxtypefieldid,
328     nameNULLNULLNULL,
329     NULL);
330}
331
332/**  \ingroup user_types
333Get information about one of the fields of a compound type.
334
335\param ncid \ref ncid
336
337\param xtype The typeid for this compound type, as returned by
338nc_def_compound(), or nc_inq_var().
339
340\param fieldid A zero-based index number specifying a field in the
341compound type.
342
343\param offsetp A pointer which will get the offset of the field. \ref
344ignored_if_null.
345
346\returns ::NC_NOERR No error.
347\returns ::NC_EBADID Bad \ref ncid.
348\returns ::NC_EBADTYPE Bad type id.
349\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
350\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
351 */
352int
353nc_inq_compound_fieldoffset(int ncidnc_type xtype, int fieldid,
354     size_t *offsetp)
355{
356   NCncp;
357   int stat = NC_check_id(ncid,&ncp);
358   if(stat != NC_NOERR) return stat;
359   return ncp->dispatch->inq_compound_field(ncid,xtype,fieldid,NULL,offsetp,NULL,NULL,NULL);
360}
361
362/**  \ingroup user_types
363Get information about one of the fields of a compound type.
364
365\param ncid \ref ncid
366
367\param xtype The typeid for this compound type, as returned by
368nc_def_compound(), or nc_inq_var().
369
370\param fieldid A zero-based index number specifying a field in the
371compound type.
372
373\param field_typeidp A pointer which will get the typeid of the
374field. \ref ignored_if_null.
375
376\returns ::NC_NOERR No error.
377\returns ::NC_EBADID Bad \ref ncid.
378\returns ::NC_EBADTYPE Bad type id.
379\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
380\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
381 */
382int
383nc_inq_compound_fieldtype(int ncidnc_type xtype, int fieldid,
384   nc_type *field_typeidp)
385{
386   NCncp;
387   int stat = NC_check_id(ncid,&ncp);
388   if(stat != NC_NOERR) return stat;
389   return ncp->dispatch->inq_compound_field(ncid,xtype,fieldid,NULL,NULL,field_typeidp,NULL,NULL);
390}
391
392/**  \ingroup user_types
393Get information about one of the fields of a compound type.
394
395\param ncid \ref ncid
396
397\param xtype The typeid for this compound type, as returned by
398nc_def_compound(), or nc_inq_var().
399
400\param fieldid A zero-based index number specifying a field in the
401compound type.
402
403\param ndimsp A pointer which will get the number of dimensions of the
404field. \ref ignored_if_null.
405
406\returns ::NC_NOERR No error.
407\returns ::NC_EBADID Bad \ref ncid.
408\returns ::NC_EBADTYPE Bad type id.
409\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
410\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
411 */
412int
413nc_inq_compound_fieldndims(int ncidnc_type xtype, int fieldid,
414    int *ndimsp)
415{
416   NCncp;
417   int stat = NC_check_id(ncid,&ncp);
418   if(stat != NC_NOERR) return stat;
419   return ncp->dispatch->inq_compound_field(ncid,xtype,fieldid,NULL,NULL,NULL,ndimsp,NULL);
420}
421
422/**  \ingroup user_types
423Get information about one of the fields of a compound type.
424
425\param ncid \ref ncid
426
427\param xtype The typeid for this compound type, as returned by
428nc_def_compound(), or nc_inq_var().
429
430\param fieldid A zero-based index number specifying a field in the
431compound type.
432
433\param dim_sizesp A pointer which will get the dimension sizes of the
434field. \ref ignored_if_null.
435
436\returns ::NC_NOERR No error.
437\returns ::NC_EBADID Bad \ref ncid.
438\returns ::NC_EBADTYPE Bad type id.
439\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
440\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
441 */
442int
443nc_inq_compound_fielddim_sizes(int ncidnc_type xtype, int fieldid,
444        int *dim_sizesp)
445{
446   NC *ncp;
447   int stat = NC_check_id(ncid, &ncp);
448   if(stat != NC_NOERR) return stat;
449   return ncp->dispatch->inq_compound_field(ncidxtypefieldid,
450     NULLNULLNULLNULL,
451     dim_sizesp);
452}
453
454/**  \ingroup user_types
455Learn the Index of a Named Field in a Compound Type. Get the index
456 * of a field in a compound type from the name.
457
458\param ncid \ref ncid
459
460\param xtype The typeid for this compound type, as returned by
461nc_def_compound(), or nc_inq_var().
462
463\param name \ref object_name of the field. \ref ignored_if_null.
464
465\param fieldidp A pointer which will get the index of the named
466field. \ref ignored_if_null.
467
468\returns ::NC_NOERR No error.
469\returns ::NC_EBADID Bad \ref ncid.
470\returns ::NC_EBADTYPE Bad type id.
471\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
472\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
473 */
474int
475nc_inq_compound_fieldindex(int ncidnc_type xtype, const char *name,
476    int *fieldidp)
477{
478   NCncp;
479   int stat = NC_check_id(ncid,&ncp);
480   if(stat != NC_NOERR) return stat;
481   return ncp->dispatch->inq_compound_fieldindex(ncid,xtype,name,fieldidp);
482}
483/*! \} */  /* End of named group ...*/
484
485
486
487
488
489


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