1/*! \file
2  Functions for User-Defined 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/** \defgroup user_types User-Defined Types
10
11User defined types allow for more complex data structures.
12
13NetCDF-4 has added support for four different user defined data
14types. 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
17types, 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
24Users may construct user defined type with the various nc_def_*
25functions described in this section. They may learn about user defined
26types by using the nc_inq_ functions defined in this section.
27
28Once types are constructed, define variables of the new type with
29nc_def_var (see nc_def_var). Write to them with nc_put_var1,
30nc_put_var, nc_put_vara, or nc_put_vars. Read data of user-defined
31type with nc_get_var1, nc_get_var, nc_get_vara, or nc_get_vars (see
32\ref variables).
33
34Create attributes of the new type with nc_put_att (see nc_put_att_
35type). Read attributes of the new type with nc_get_att (see
36\ref attributes).
37*/
38
39/** \{ */
40
41
42/** \internal
43\ingroup user_types
44Learn if two types are equal
45
46\param ncid1 \ref ncid of first typeid.
47\param typeid1 First typeid.
48\param ncid2 \ref ncid of second typeid.
49\param typeid2 Second typeid.
50\param equal Pointer to int. A non-zero value will be copied here if
51the two types are equal, a zero if they are not equal.
52
53\returns ::NC_NOERR No error.
54\returns ::NC_EBADID Bad \ref ncid.
55\returns ::NC_EBADTYPE Bad type id.
56\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
57\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
58 */
59int
60nc_inq_type_equal(int ncid1nc_type typeid1, int ncid2,
61   nc_type typeid2, int *equal)
62{
63    NCncp1;
64    int stat = NC_check_id(ncid1,&ncp1);
65    if(stat != NC_NOERR) return stat;
66    return ncp1->dispatch->inq_type_equal(ncid1,typeid1,ncid2,typeid2,equal);
67}
68
69/** \name Learning about User-Defined Types
70
71    Functions to learn about any kind of user-defined type. */
72/*! \{ */ /* All these functions are part of this named group... */
73
74/** \ingroup user_types
75
76Find a type by name. Given a group ID and a type name, find the ID of
77the type. If the type is not found in the group, then the parents are
78searched. If still not found, the entire file is searched.
79
80\param ncid \ref ncid
81\param name \ref object_name of type to search for.
82\param typeidp Typeid of named type will be copied here, if it is
83found.
84
85\returns ::NC_NOERR No error.
86\returns ::NC_EBADID Bad \ref ncid.
87\returns ::NC_EBADTYPE Bad type id.
88\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
89\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
90 */
91int
92nc_inq_typeid(int ncid, const char *namenc_type *typeidp)
93{
94    NCncp;
95    int stat = NC_check_id(ncid,&ncp);
96    if(stat != NC_NOERR) return stat;
97    return ncp->dispatch->inq_typeid(ncid,name,typeidp);
98}
99
100/** \ingroup user_types
101Learn about a user defined type.
102
103Given an ncid and a typeid, get the information about a user defined
104type. This function will work on any user defined type, whether
105compound, opaque, enumeration, or variable length array.
106
107\param ncid \ref ncid
108
109\param xtype The typeid
110
111\param name The \ref object_name will be copied here. \ref
112ignored_if_null.
113
114\param size the (in-memory) size of the type in bytes will be copied
115here. VLEN type size is the size of nc_vlen_t. String size is returned
116as the size of a character pointer. The size may be used to malloc
117space for the data, no matter what the type. \ref ignored_if_null.
118
119\param base_nc_typep The base type will be copied here for enum and
120VLEN types. \ref ignored_if_null.
121
122\param nfieldsp The number of fields will be copied here for enum and
123compound types. \ref ignored_if_null.
124
125\param classp Return the class of the user defined type, ::NC_VLEN,
126::NC_OPAQUE, ::NC_ENUM, or ::NC_COMPOUND. \ref ignored_if_null.
127
128\returns ::NC_NOERR No error.
129\returns ::NC_EBADID Bad \ref ncid.
130\returns ::NC_EBADTYPE Bad type id.
131\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
132\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
133 */
134int
135nc_inq_user_type(int ncidnc_type xtype, char *name, size_t *size,
136  nc_type *base_nc_typep, size_t *nfieldsp, int *classp)
137{
138    NC *ncp;
139    int stat = NC_check_id(ncid,&ncp);
140    if(stat != NC_NOERR) return stat;
141    return ncp->dispatch->inq_user_type(ncidxtypenamesize,
142 base_nc_typepnfieldspclassp);
143}
144/*! \} */  /* End of named group ...*/
145
146/** \} */


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