1 /*! \file
2 Functions for VLEN 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 /** \name Variable Length Array Types
10
11 Functions to create and learn about VLEN types. */
12 /*! \{ */ /* All these functions are part of this named group... */
13
14 /**
15 \ingroup user_types
16 Free memory in a VLEN object.
17
18 When you read VLEN type the library will actually allocate the storage
19 space for the data. This storage space must be freed, so pass the
20 pointer back to this function, when you're done with the data, and it
21 will free the vlen memory.
22
23 The function nc_free_vlens() is more useful than this function,
24 because it can free an array of VLEN objects.
25
26 WARNING: this code is incorrect because it will only
27 work if the basetype of the vlen is
28 - atomic
29 - + enum
30 - + opaque
31 - excluding string basetype,
32
33 The reason is that to operate properly, it needs to recurse when
34 the basetype is a complex object such as another vlen or compound.
35
36 \param vl pointer to the vlen object.
37
38 \returns ::NC_NOERR No error.
39 */
40 int
nc_free_vlen(nc_vlen_t * vl)41 nc_free_vlen(nc_vlen_t *vl)
42 {
43 free(vl->p);
44 return NC_NOERR;
45 }
46
47 /**
48 \ingroup user_types
49 Free an array of vlens given the number of elements and an array.
50
51 When you read VLEN type the library will actually allocate the storage
52 space for the data. This storage space must be freed, so pass the
53 pointer back to this function, when you're done with the data, and it
54 will free the vlen memory.
55
56 WARNING: this code is incorrect because it will only
57 work if the basetype of the vlen is
58 - atomic
59 - + enum
60 - + opaque
61 - excluding string basetype,
62
63 The reason is that to operate properly, it needs to recurse when
64 the basetype is a complex object such as another vlen or compound.
65
66 \param len number of elements in the array.
67 \param vlens pointer to the vlen object.
68
69 \returns ::NC_NOERR No error.
70 */
71 int
nc_free_vlens(size_t len,nc_vlen_t vlens[])72 nc_free_vlens(size_t len, nc_vlen_t vlens[])
73 {
74 int ret;
75 size_t i;
76
77 for(i = 0; i < len; i++)
78 if ((ret = nc_free_vlen(&vlens[i])))
79 return ret;
80
81 return NC_NOERR;
82 }
83
84 /**
85 \ingroup user_types
86 Use this function to define a variable length array type.
87
88 \param ncid \ref ncid
89 \param name \ref object_name of new type.
90
91 \param base_typeid The typeid of the base type of the VLEN. For
92 example, for a VLEN of shorts, the base type is ::NC_SHORT. This can be
93 a user defined type.
94
95 \param xtypep A pointer to an nc_type variable. The typeid of the new
96 VLEN type will be set here.
97
98 \returns ::NC_NOERR No error.
99 \returns ::NC_EBADID Bad \ref ncid.
100 \returns ::NC_EBADTYPE Bad type id.
101 \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
102 \returns ::NC_EHDFERR An error was reported by the HDF5 layer.
103 \returns ::NC_ENAMEINUSE That name is in use.
104 \returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
105 \returns ::NC_EBADNAME Name contains illegal characters.
106 \returns ::NC_EPERM Attempt to write to a read-only file.
107 \returns ::NC_ENOTINDEFINE Not in define mode.
108 */
109 int
nc_def_vlen(int ncid,const char * name,nc_type base_typeid,nc_type * xtypep)110 nc_def_vlen(int ncid, const char *name, nc_type base_typeid, nc_type *xtypep)
111 {
112 NC* ncp;
113 int stat = NC_check_id(ncid,&ncp);
114 if(stat != NC_NOERR) return stat;
115 return ncp->dispatch->def_vlen(ncid,name,base_typeid,xtypep);
116 }
117
118 /** \ingroup user_types
119 Learn about a VLEN type.
120
121 \param ncid \ref ncid
122 \param xtype The type of the VLEN to inquire about.
123 \param name \ref object_name of the type. \ref ignored_if_null.
124
125 \param datum_sizep A pointer to a size_t, this will get the size of
126 one element of this vlen. \ref ignored_if_null.
127
128 \param base_nc_typep Pointer to get the base type of the VLEN. \ref
129 ignored_if_null.
130
131 \returns ::NC_NOERR No error.
132 \returns ::NC_EBADID Bad \ref ncid.
133 \returns ::NC_EBADTYPE Bad type id.
134 \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
135 \returns ::NC_EHDFERR An error was reported by the HDF5 layer.
136 */
137 int
nc_inq_vlen(int ncid,nc_type xtype,char * name,size_t * datum_sizep,nc_type * base_nc_typep)138 nc_inq_vlen(int ncid, nc_type xtype, char *name, size_t *datum_sizep, nc_type *base_nc_typep)
139 {
140 int class = 0;
141 int stat = nc_inq_user_type(ncid,xtype,name,datum_sizep,base_nc_typep,NULL,&class);
142 if(stat != NC_NOERR) return stat;
143 if(class != NC_VLEN) stat = NC_EBADTYPE;
144 return stat;
145 }
146 /*! \} */ /* End of named group ...*/
147
148 /** \internal
149 \ingroup user_types
150
151 Put a VLEN element. This function writes an element of a VLEN for the
152 Fortran APIs.
153
154 \param ncid \ref ncid
155 \param typeid1 Typeid of the VLEN.
156 \param vlen_element Pointer to the element of the VLEN.
157 \param len Length of the VLEN element.
158 \param data VLEN data.
159
160 \returns ::NC_NOERR No error.
161 \returns ::NC_EBADID Bad \ref ncid.
162 \returns ::NC_EBADTYPE Bad type id.
163 \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
164 \returns ::NC_EHDFERR An error was reported by the HDF5 layer.
165 \returns ::NC_EPERM Attempt to write to a read-only file.
166 */
167 int
nc_put_vlen_element(int ncid,int typeid1,void * vlen_element,size_t len,const void * data)168 nc_put_vlen_element(int ncid, int typeid1, void *vlen_element, size_t len, const void *data)
169 {
170 NC* ncp;
171 int stat = NC_check_id(ncid,&ncp);
172 if(stat != NC_NOERR) return stat;
173 return ncp->dispatch->put_vlen_element(ncid,typeid1,vlen_element,len,data);
174 }
175
176 /**
177 \internal
178 \ingroup user_types
179
180 Get a VLEN element. This function reads an element of a VLEN for the
181 Fortran APIs.
182
183 \param ncid \ref ncid
184 \param typeid1 Typeid of the VLEN.
185 \param vlen_element Pointer to the element of the VLEN.
186 \param len Length of the VLEN element.
187 \param data VLEN data.
188
189 \returns ::NC_NOERR No error.
190 \returns ::NC_EBADID Bad \ref ncid.
191 \returns ::NC_EBADTYPE Bad type id.
192 \returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
193 \returns ::NC_EHDFERR An error was reported by the HDF5 layer.
194 */
195 int
nc_get_vlen_element(int ncid,int typeid1,const void * vlen_element,size_t * len,void * data)196 nc_get_vlen_element(int ncid, int typeid1, const void *vlen_element,
197 size_t *len, void *data)
198 {
199 NC *ncp;
200 int stat = NC_check_id(ncid,&ncp);
201 if(stat != NC_NOERR) return stat;
202 return ncp->dispatch->get_vlen_element(ncid, typeid1, vlen_element,
203 len, data);
204 }
205