1 /*! \file
2 Functions for User-Defined Types
3
4 Copyright 2018 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 /**
43 \ingroup user_types
44 Learn if two types are equal.
45
46 \note User-defined types in netCDF-4/HDF5 files must be committed to
47 the file before nc_inq_type_equal() will work on the type. For
48 uncommitted user-defined types, nc_inq_type_equal() will return
49 ::NC_EHDFERR. Commit types to the file with a call to nc_enddef().
50
51 \param ncid1 \ref ncid of first typeid.
52 \param typeid1 First typeid.
53 \param ncid2 \ref ncid of second typeid.
54 \param typeid2 Second typeid.
55 \param equal Pointer to int. A non-zero value will be copied here if
56 the two types are equal, a zero if they are not equal.
57
58 \returns ::NC_NOERR No error.
59 \returns ::NC_EBADID Bad \ref ncid.
60 \returns ::NC_EBADTYPE Bad type id.
61 \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
62 \returns ::NC_EHDFERR An error was reported by the HDF5 layer. This
63 will occur if either of the types have not been committed to the file
64 (with an nc_enddef()).
65
66 \author Dennis Heimbigner, Ward Fisher, Ed Hartnett
67 */
68 int
nc_inq_type_equal(int ncid1,nc_type typeid1,int ncid2,nc_type typeid2,int * equal)69 nc_inq_type_equal(int ncid1, nc_type typeid1, int ncid2,
70 nc_type typeid2, int *equal)
71 {
72 NC* ncp1;
73 int stat = NC_check_id(ncid1,&ncp1);
74 if(stat != NC_NOERR) return stat;
75 return ncp1->dispatch->inq_type_equal(ncid1,typeid1,ncid2,typeid2,equal);
76 }
77
78 /** \name Learning about User-Defined Types
79
80 Functions to learn about any kind of user-defined type. */
81 /*! \{ */ /* All these functions are part of this named group... */
82
83 /** \ingroup user_types
84
85 Find a type by name. Given a group ID and a type name, find the ID of
86 the type. If the type is not found in the group, then the parents are
87 searched. If still not found, the entire file is searched.
88
89 \param ncid \ref ncid
90 \param name \ref object_name of type to search for.
91 \param typeidp Typeid of named type will be copied here, if it is
92 found.
93
94 \returns ::NC_NOERR No error.
95 \returns ::NC_EBADID Bad \ref ncid.
96 \returns ::NC_EBADTYPE Bad type id.
97 \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
98 \returns ::NC_EHDFERR An error was reported by the HDF5 layer.
99 \author Ed Hartnett, Dennis Heimbigner
100 */
101 int
nc_inq_typeid(int ncid,const char * name,nc_type * typeidp)102 nc_inq_typeid(int ncid, const char *name, nc_type *typeidp)
103 {
104 NC* ncp;
105 int stat = NC_check_id(ncid,&ncp);
106 if(stat != NC_NOERR) return stat;
107 return ncp->dispatch->inq_typeid(ncid,name,typeidp);
108 }
109
110 /** \ingroup user_types
111 Learn about a user defined type.
112
113 Given an ncid and a typeid, get the information about a user defined
114 type. This function will work on any user defined type, whether
115 compound, opaque, enumeration, or variable length array.
116
117 \param ncid \ref ncid
118
119 \param xtype The typeid
120
121 \param name The \ref object_name will be copied here. \ref
122 ignored_if_null.
123
124 \param size the (in-memory) size of the type in bytes will be copied
125 here. VLEN type size is the size of nc_vlen_t. String size is returned
126 as the size of a character pointer. The size may be used to malloc
127 space for the data, no matter what the type. \ref ignored_if_null.
128
129 \param base_nc_typep The base type will be copied here for enum and
130 VLEN types. \ref ignored_if_null.
131
132 \param nfieldsp The number of fields will be copied here for enum and
133 compound types. \ref ignored_if_null.
134
135 \param classp Return the class of the user defined type, ::NC_VLEN,
136 ::NC_OPAQUE, ::NC_ENUM, or ::NC_COMPOUND. \ref ignored_if_null.
137
138 \returns ::NC_NOERR No error.
139 \returns ::NC_EBADID Bad \ref ncid.
140 \returns ::NC_EBADTYPE Bad type id.
141 \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
142 \returns ::NC_EHDFERR An error was reported by the HDF5 layer.
143 \author Ed Hartnett, Dennis Heimbigner
144 */
145 int
nc_inq_user_type(int ncid,nc_type xtype,char * name,size_t * size,nc_type * base_nc_typep,size_t * nfieldsp,int * classp)146 nc_inq_user_type(int ncid, nc_type xtype, char *name, size_t *size,
147 nc_type *base_nc_typep, size_t *nfieldsp, int *classp)
148 {
149 NC *ncp;
150 int stat = NC_check_id(ncid,&ncp);
151 if(stat != NC_NOERR) return stat;
152 return ncp->dispatch->inq_user_type(ncid, xtype, name, size,
153 base_nc_typep, nfieldsp, classp);
154 }
155 /*! \} */ /* End of named group ...*/
156
157 /** \} */
158