1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2 * Copyright by The HDF Group. *
3 * Copyright by the Board of Trustees of the University of Illinois. *
4 * All rights reserved. *
5 * *
6 * This file is part of HDF5. The full HDF5 copyright notice, including *
7 * terms governing use, modification, and redistribution, is contained in *
8 * the files COPYING and Copyright.html. COPYING can be found at the root *
9 * of the source code distribution tree; Copyright.html can be found at the *
10 * root level of an installed copy of the electronic HDF5 document set and *
11 * is linked from the top-level documents page. It can also be found at *
12 * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have *
13 * access to either file, you may request a copy from help@hdfgroup.org. *
14 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
15
16 /*-------------------------------------------------------------------------
17 *
18 * Created: H5Adeprec.c
19 * November 27 2006
20 * Quincey Koziol <koziol@hdfgroup.org>
21 *
22 * Purpose: Deprecated functions from the H5A interface. These
23 * functions are here for compatibility purposes and may be
24 * removed in the future. Applications should switch to the
25 * newer APIs.
26 *
27 *-------------------------------------------------------------------------
28 */
29
30 /****************/
31 /* Module Setup */
32 /****************/
33
34 #define H5A_PACKAGE /*suppress error about including H5Apkg */
35 #define H5O_PACKAGE /*suppress error about including H5Opkg */
36
37 /* Interface initialization */
38 #define H5_INTERFACE_INIT_FUNC H5A__init_deprec_interface
39
40
41 /***********/
42 /* Headers */
43 /***********/
44 #include "H5private.h" /* Generic Functions */
45 #include "H5Apkg.h" /* Attributes */
46 #include "H5Dprivate.h" /* Datasets */
47 #include "H5Eprivate.h" /* Error handling */
48 #include "H5Iprivate.h" /* IDs */
49 #include "H5Opkg.h" /* Object headers */
50
51
52 /****************/
53 /* Local Macros */
54 /****************/
55
56
57 /******************/
58 /* Local Typedefs */
59 /******************/
60
61
62 /********************/
63 /* Package Typedefs */
64 /********************/
65
66
67 /********************/
68 /* Local Prototypes */
69 /********************/
70
71
72 /*********************/
73 /* Package Variables */
74 /*********************/
75
76
77 /*****************************/
78 /* Library Private Variables */
79 /*****************************/
80
81
82 /*******************/
83 /* Local Variables */
84 /*******************/
85
86
87
88 /*--------------------------------------------------------------------------
89 NAME
90 H5A__init_deprec_interface -- Initialize interface-specific information
91 USAGE
92 herr_t H5A__init_deprec_interface()
93 RETURNS
94 Non-negative on success/Negative on failure
95 DESCRIPTION
96 Initializes any interface-specific data or routines. (Just calls
97 H5A_init() currently).
98
99 --------------------------------------------------------------------------*/
100 static herr_t
H5A__init_deprec_interface(void)101 H5A__init_deprec_interface(void)
102 {
103 FUNC_ENTER_STATIC_NOERR
104
105 FUNC_LEAVE_NOAPI(H5A_init())
106 } /* H5A__init_deprec_interface() */
107
108
109 /*--------------------------------------------------------------------------
110 NAME
111 H5A__term_deprec_interface -- Terminate interface
112 USAGE
113 herr_t H5A__term_deprec_interface()
114 RETURNS
115 Non-negative on success/Negative on failure
116 DESCRIPTION
117 Terminates interface. (Just resets H5_interface_initialize_g
118 currently).
119
120 --------------------------------------------------------------------------*/
121 herr_t
H5A__term_deprec_interface(void)122 H5A__term_deprec_interface(void)
123 {
124 FUNC_ENTER_PACKAGE_NOERR
125
126 /* Mark closed */
127 H5_interface_initialize_g = 0;
128
129 FUNC_LEAVE_NOAPI(0)
130 } /* H5A__term_deprec_interface() */
131
132 #ifndef H5_NO_DEPRECATED_SYMBOLS
133
134 /*--------------------------------------------------------------------------
135 NAME
136 H5Acreate1
137 PURPOSE
138 Creates an attribute on an object
139 USAGE
140 hid_t H5Acreate1(loc_id, name, type_id, space_id, plist_id)
141 hid_t loc_id; IN: Object (dataset or group) to be attached to
142 const char *name; IN: Name of attribute to create
143 hid_t type_id; IN: ID of datatype for attribute
144 hid_t space_id; IN: ID of dataspace for attribute
145 hid_t plist_id; IN: ID of creation property list (currently not used)
146 RETURNS
147 Non-negative on success/Negative on failure
148
149 DESCRIPTION
150 This function creates an attribute which is attached to the object
151 specified with 'location_id'. The name specified with 'name' for each
152 attribute for an object must be unique for that object. The 'type_id'
153 and 'space_id' are created with the H5T and H5S interfaces respectively.
154 The attribute ID returned from this function must be released with H5Aclose
155 or resource leaks will develop.
156
157 NOTE
158 Deprecated in favor of H5Acreate2
159
160 --------------------------------------------------------------------------*/
161 hid_t
H5Acreate1(hid_t loc_id,const char * name,hid_t type_id,hid_t space_id,hid_t plist_id)162 H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id,
163 hid_t plist_id)
164 {
165 H5G_loc_t loc; /* Object location */
166 H5T_t *type; /* Datatype to use for attribute */
167 H5S_t *space; /* Dataspace to use for attribute */
168 hid_t ret_value; /* Return value */
169
170 FUNC_ENTER_API(FAIL)
171 H5TRACE5("i", "i*siii", loc_id, name, type_id, space_id, plist_id);
172
173 /* check arguments */
174 if(H5I_ATTR == H5I_get_type(loc_id))
175 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "location is not valid for an attribute")
176 if(H5G_loc(loc_id, &loc) < 0)
177 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
178 if(0 == (H5F_INTENT(loc.oloc->file) & H5F_ACC_RDWR))
179 HGOTO_ERROR(H5E_ARGS, H5E_WRITEERROR, FAIL, "no write intent on file")
180 if(!name || !*name)
181 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
182 if(NULL == (type = (H5T_t *)H5I_object_verify(type_id, H5I_DATATYPE)))
183 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a type")
184 if(NULL == (space = (H5S_t *)H5I_object_verify(space_id, H5I_DATASPACE)))
185 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a data space")
186
187 /* Go do the real work for attaching the attribute to the dataset */
188 if((ret_value = H5A_create(&loc, name, type, space, plist_id, H5AC_dxpl_id)) < 0)
189 HGOTO_ERROR(H5E_ATTR, H5E_CANTINIT, FAIL, "unable to create attribute")
190
191 done:
192 FUNC_LEAVE_API(ret_value)
193 } /* H5Acreate1() */
194
195
196 /*--------------------------------------------------------------------------
197 NAME
198 H5Aopen_name
199 PURPOSE
200 Opens an attribute for an object by looking up the attribute name
201 USAGE
202 hid_t H5Aopen_name (loc_id, name)
203 hid_t loc_id; IN: Object (dataset or group) to be attached to
204 const char *name; IN: Name of attribute to locate and open
205 RETURNS
206 ID of attribute on success, negative on failure
207
208 DESCRIPTION
209 This function opens an existing attribute for access. The attribute
210 name specified is used to look up the corresponding attribute for the
211 object. The attribute ID returned from this function must be released with
212 H5Aclose or resource leaks will develop.
213 The location object may be either a group or a dataset, both of
214 which may have any sort of attribute.
215 NOTE
216 Deprecated in favor of H5Aopen
217 --------------------------------------------------------------------------*/
218 hid_t
H5Aopen_name(hid_t loc_id,const char * name)219 H5Aopen_name(hid_t loc_id, const char *name)
220 {
221 H5G_loc_t loc; /* Object location */
222 H5A_t *attr = NULL; /* Attribute opened */
223 hid_t ret_value;
224
225 FUNC_ENTER_API(FAIL)
226 H5TRACE2("i", "i*s", loc_id, name);
227
228 /* check arguments */
229 if(H5I_ATTR == H5I_get_type(loc_id))
230 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "location is not valid for an attribute")
231 if(H5G_loc(loc_id, &loc) < 0)
232 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
233 if(!name || !*name)
234 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
235
236 /* Open the attribute on the object header */
237 if(NULL == (attr = H5A_open_by_name(&loc, ".", name, H5P_LINK_ACCESS_DEFAULT, H5AC_ind_dxpl_id)))
238 HGOTO_ERROR(H5E_ATTR, H5E_CANTOPENOBJ, FAIL, "can't open attribute: '%s'", name)
239
240 /* Register the attribute and get an ID for it */
241 if((ret_value = H5I_register(H5I_ATTR, attr, TRUE)) < 0)
242 HGOTO_ERROR(H5E_ATOM, H5E_CANTREGISTER, FAIL, "unable to register attribute for ID")
243
244 done:
245 /* Cleanup on failure */
246 if(ret_value < 0)
247 if(attr && H5A_close(attr) < 0)
248 HDONE_ERROR(H5E_ATTR, H5E_CANTFREE, FAIL, "can't close attribute")
249
250 FUNC_LEAVE_API(ret_value)
251 } /* H5Aopen_name() */
252
253
254 /*--------------------------------------------------------------------------
255 NAME
256 H5Aopen_idx
257 PURPOSE
258 Opens the n'th attribute for an object
259 USAGE
260 hid_t H5Aopen_idx (loc_id, idx)
261 hid_t loc_id; IN: Object that attribute is attached to
262 unsigned idx; IN: Index (0-based) attribute to open
263 RETURNS
264 ID of attribute on success, negative on failure
265
266 DESCRIPTION
267 This function opens an existing attribute for access. The attribute
268 index specified is used to look up the corresponding attribute for the
269 object. The attribute ID returned from this function must be released with
270 H5Aclose or resource leaks will develop.
271 The location object may be either a group or a dataset, both of
272 which may have any sort of attribute.
273 NOTE
274 Deprecated in favor of H5Aopen_by_idx
275 --------------------------------------------------------------------------*/
276 hid_t
H5Aopen_idx(hid_t loc_id,unsigned idx)277 H5Aopen_idx(hid_t loc_id, unsigned idx)
278 {
279 H5G_loc_t loc; /* Object location */
280 H5A_t *attr = NULL; /* Attribute opened */
281 hid_t ret_value;
282
283 FUNC_ENTER_API(FAIL)
284 H5TRACE2("i", "iIu", loc_id, idx);
285
286 /* check arguments */
287 if(H5I_ATTR == H5I_get_type(loc_id))
288 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "location is not valid for an attribute")
289 if(H5G_loc(loc_id, &loc) < 0)
290 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
291
292 /* Open the attribute in the object header */
293 if(NULL == (attr = H5A_open_by_idx(&loc, ".", H5_INDEX_CRT_ORDER, H5_ITER_INC, (hsize_t)idx, H5P_LINK_ACCESS_DEFAULT, H5AC_ind_dxpl_id)))
294 HGOTO_ERROR(H5E_ATTR, H5E_CANTOPENOBJ, FAIL, "unable to open attribute")
295
296 /* Register the attribute and get an ID for it */
297 if((ret_value = H5I_register(H5I_ATTR, attr, TRUE)) < 0)
298 HGOTO_ERROR(H5E_ATOM, H5E_CANTREGISTER, FAIL, "unable to register attribute for ID")
299
300 done:
301 /* Cleanup on failure */
302 if(ret_value < 0)
303 if(attr && H5A_close(attr) < 0)
304 HDONE_ERROR(H5E_ATTR, H5E_CANTFREE, FAIL, "can't close attribute")
305
306 FUNC_LEAVE_API(ret_value)
307 } /* H5Aopen_idx() */
308
309
310 /*--------------------------------------------------------------------------
311 NAME
312 H5Aget_num_attrs
313 PURPOSE
314 Determines the number of attributes attached to an object
315 NOTE
316 Deprecated in favor of H5Oget_info[_by_idx]
317 USAGE
318 int H5Aget_num_attrs (loc_id)
319 hid_t loc_id; IN: Object (dataset or group) to be queried
320 RETURNS
321 Number of attributes on success, negative on failure
322 DESCRIPTION
323 This function returns the number of attributes attached to a dataset or
324 group, 'location_id'.
325 NOTE
326 Deprecated in favor of H5Oget_info
327 --------------------------------------------------------------------------*/
328 int
H5Aget_num_attrs(hid_t loc_id)329 H5Aget_num_attrs(hid_t loc_id)
330 {
331 H5O_loc_t *loc; /* Object location for attribute */
332 void *obj;
333 int ret_value;
334
335 FUNC_ENTER_API(FAIL)
336 H5TRACE1("Is", "i", loc_id);
337
338 /* check arguments */
339 if(H5I_BADID == H5I_get_type(loc_id))
340 HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "bad location ID")
341 if(H5I_FILE == H5I_get_type(loc_id) || H5I_ATTR == H5I_get_type(loc_id))
342 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "location is not valid for an attribute")
343 if(NULL == (obj = H5I_object(loc_id)))
344 HGOTO_ERROR(H5E_ARGS, H5E_BADATOM, FAIL, "illegal object atom")
345 switch(H5I_get_type (loc_id)) {
346 case H5I_DATASET:
347 if(NULL == (loc = H5D_oloc((H5D_t*)obj)))
348 HGOTO_ERROR(H5E_ATTR, H5E_CANTGET, FAIL, "can't get location for object")
349 break;
350
351 case H5I_DATATYPE:
352 if(NULL == (loc = H5T_oloc((H5T_t*)obj)))
353 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "target datatype is not committed")
354 break;
355
356 case H5I_GROUP:
357 if(NULL == (loc = H5G_oloc((H5G_t*)obj)))
358 HGOTO_ERROR(H5E_ATTR, H5E_CANTGET, FAIL, "can't get location for object")
359 break;
360
361 case H5I_UNINIT:
362 case H5I_BADID:
363 case H5I_FILE:
364 case H5I_DATASPACE:
365 case H5I_ATTR:
366 case H5I_REFERENCE:
367 case H5I_VFL:
368 case H5I_GENPROP_CLS:
369 case H5I_GENPROP_LST:
370 case H5I_ERROR_CLASS:
371 case H5I_ERROR_MSG:
372 case H5I_ERROR_STACK:
373 case H5I_NTYPES:
374 default:
375 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "inappropriate attribute target")
376 } /*lint !e788 All appropriate cases are covered */
377
378 /* Look up the # of attributes for the object */
379 if((ret_value = H5O_attr_count(loc, H5AC_ind_dxpl_id)) < 0)
380 HGOTO_ERROR(H5E_ATTR, H5E_CANTCOUNT, FAIL, "can't get attribute count for object")
381
382 done:
383 FUNC_LEAVE_API(ret_value)
384 } /* H5Aget_num_attrs() */
385
386
387 /*--------------------------------------------------------------------------
388 NAME
389 H5Aiterate1
390 PURPOSE
391 Calls a user's function for each attribute on an object
392 USAGE
393 herr_t H5Aiterate1(loc_id, attr_num, op, data)
394 hid_t loc_id; IN: Object (dataset or group) to be iterated over
395 unsigned *attr_num; IN/OUT: Starting (IN) & Ending (OUT) attribute number
396 H5A_operator1_t op; IN: User's function to pass each attribute to
397 void *op_data; IN/OUT: User's data to pass through to iterator operator function
398 RETURNS
399 Returns a negative value if something is wrong, the return value of the
400 last operator if it was non-zero, or zero if all attributes were processed.
401
402 DESCRIPTION
403 This function interates over the attributes of dataset or group
404 specified with 'loc_id'. For each attribute of the object, the
405 'op_data' and some additional information (specified below) are passed
406 to the 'op' function. The iteration begins with the '*attr_number'
407 object in the group and the next attribute to be processed by the operator
408 is returned in '*attr_number'.
409 The operation receives the ID for the group or dataset being iterated
410 over ('loc_id'), the name of the current attribute about the object
411 ('attr_name') and the pointer to the operator data passed in to H5Aiterate
412 ('op_data'). The return values from an operator are:
413 A. Zero causes the iterator to continue, returning zero when all
414 attributes have been processed.
415 B. Positive causes the iterator to immediately return that positive
416 value, indicating short-circuit success. The iterator can be
417 restarted at the next attribute.
418 C. Negative causes the iterator to immediately return that value,
419 indicating failure. The iterator can be restarted at the next
420 attribute.
421 NOTE
422 Deprecated in favor of H5Aiterate2
423 --------------------------------------------------------------------------*/
424 herr_t
H5Aiterate1(hid_t loc_id,unsigned * attr_num,H5A_operator1_t op,void * op_data)425 H5Aiterate1(hid_t loc_id, unsigned *attr_num, H5A_operator1_t op, void *op_data)
426 {
427 H5A_attr_iter_op_t attr_op; /* Attribute operator */
428 hsize_t start_idx; /* Index of attribute to start iterating at */
429 hsize_t last_attr; /* Index of last attribute examined */
430 herr_t ret_value; /* Return value */
431
432 FUNC_ENTER_API(FAIL)
433 H5TRACE4("e", "i*Iux*x", loc_id, attr_num, op, op_data);
434
435 /* check arguments */
436 if(H5I_ATTR == H5I_get_type(loc_id))
437 HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "location is not valid for an attribute")
438
439 /* Build attribute operator info */
440 attr_op.op_type = H5A_ATTR_OP_APP;
441 attr_op.u.app_op = op;
442
443 /* Call attribute iteration routine */
444 last_attr = start_idx = (hsize_t)(attr_num ? *attr_num : 0);
445 if((ret_value = H5O_attr_iterate(loc_id, H5AC_ind_dxpl_id, H5_INDEX_CRT_ORDER, H5_ITER_INC, start_idx, &last_attr, &attr_op, op_data)) < 0)
446 HERROR(H5E_ATTR, H5E_BADITER, "error iterating over attributes");
447
448 /* Set the last attribute information */
449 if(attr_num)
450 *attr_num = (unsigned)last_attr;
451
452 done:
453 FUNC_LEAVE_API(ret_value)
454 } /* H5Aiterate1() */
455 #endif /* H5_NO_DEPRECATED_SYMBOLS */
456
457