mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
420 lines
16 KiB
C
420 lines
16 KiB
C
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
||
* Copyright by The HDF Group. *
|
||
* Copyright by the Board of Trustees of the University of Illinois. *
|
||
* All rights reserved. *
|
||
* *
|
||
* This file is part of HDF5. The full HDF5 copyright notice, including *
|
||
* terms governing use, modification, and redistribution, is contained in *
|
||
* the files COPYING and Copyright.html. COPYING can be found at the root *
|
||
* of the source code distribution tree; Copyright.html can be found at the *
|
||
* root level of an installed copy of the electronic HDF5 document set and *
|
||
* is linked from the top-level documents page. It can also be found at *
|
||
* http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have *
|
||
* access to either file, you may request a copy from help@hdfgroup.org. *
|
||
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
||
|
||
/*-------------------------------------------------------------------------
|
||
*
|
||
* Created: H5Adeprec.c
|
||
* November 27 2006
|
||
* Quincey Koziol <koziol@hdfgroup.org>
|
||
*
|
||
* Purpose: Deprecated functions from the H5A interface. These
|
||
* functions are here for compatibility purposes and may be
|
||
* removed in the future. Applications should switch to the
|
||
* newer APIs.
|
||
*
|
||
*-------------------------------------------------------------------------
|
||
*/
|
||
|
||
/****************/
|
||
/* Module Setup */
|
||
/****************/
|
||
|
||
#define H5A_PACKAGE /*suppress error about including H5Apkg */
|
||
#define H5O_PACKAGE /*suppress error about including H5Opkg */
|
||
|
||
/* Interface initialization */
|
||
#define H5_INTERFACE_INIT_FUNC H5A_init_deprec_interface
|
||
|
||
|
||
/***********/
|
||
/* Headers */
|
||
/***********/
|
||
#include "H5private.h" /* Generic Functions */
|
||
#include "H5Apkg.h" /* Attributes */
|
||
#include "H5Dprivate.h" /* Datasets */
|
||
#include "H5Eprivate.h" /* Error handling */
|
||
#include "H5Iprivate.h" /* IDs */
|
||
#include "H5Opkg.h" /* Object headers */
|
||
|
||
|
||
/****************/
|
||
/* Local Macros */
|
||
/****************/
|
||
|
||
|
||
/******************/
|
||
/* Local Typedefs */
|
||
/******************/
|
||
|
||
|
||
/********************/
|
||
/* Package Typedefs */
|
||
/********************/
|
||
|
||
|
||
/********************/
|
||
/* Local Prototypes */
|
||
/********************/
|
||
|
||
|
||
/*********************/
|
||
/* Package Variables */
|
||
/*********************/
|
||
|
||
|
||
/*****************************/
|
||
/* Library Private Variables */
|
||
/*****************************/
|
||
|
||
|
||
/*******************/
|
||
/* Local Variables */
|
||
/*******************/
|
||
|
||
|
||
|
||
/*--------------------------------------------------------------------------
|
||
NAME
|
||
H5A_init_deprec_interface -- Initialize interface-specific information
|
||
USAGE
|
||
herr_t H5A_init_deprec_interface()
|
||
RETURNS
|
||
Non-negative on success/Negative on failure
|
||
DESCRIPTION
|
||
Initializes any interface-specific data or routines. (Just calls
|
||
H5A_init() currently).
|
||
|
||
--------------------------------------------------------------------------*/
|
||
static herr_t
|
||
H5A_init_deprec_interface(void)
|
||
{
|
||
FUNC_ENTER_NOAPI_NOINIT_NOFUNC(H5A_init_deprec_interface)
|
||
|
||
FUNC_LEAVE_NOAPI(H5A_init())
|
||
} /* H5A_init_deprec_interface() */
|
||
|
||
#ifndef H5_NO_DEPRECATED_SYMBOLS
|
||
|
||
/*--------------------------------------------------------------------------
|
||
NAME
|
||
H5Acreate1
|
||
PURPOSE
|
||
Creates an attribute on an object
|
||
USAGE
|
||
hid_t H5Acreate1(loc_id, name, type_id, space_id, plist_id)
|
||
hid_t loc_id; IN: Object (dataset or group) to be attached to
|
||
const char *name; IN: Name of attribute to create
|
||
hid_t type_id; IN: ID of datatype for attribute
|
||
hid_t space_id; IN: ID of dataspace for attribute
|
||
hid_t plist_id; IN: ID of creation property list (currently not used)
|
||
RETURNS
|
||
Non-negative on success/Negative on failure
|
||
|
||
DESCRIPTION
|
||
This function creates an attribute which is attached to the object
|
||
specified with 'location_id'. The name specified with 'name' for each
|
||
attribute for an object must be unique for that object. The 'type_id'
|
||
and 'space_id' are created with the H5T and H5S interfaces respectively.
|
||
The attribute ID returned from this function must be released with H5Aclose
|
||
or resource leaks will develop.
|
||
|
||
NOTE
|
||
Deprecated in favor of H5Acreate2
|
||
|
||
--------------------------------------------------------------------------*/
|
||
hid_t
|
||
H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id,
|
||
hid_t plist_id)
|
||
{
|
||
H5G_loc_t loc; /* Object location */
|
||
H5T_t *type; /* Datatype to use for attribute */
|
||
H5S_t *space; /* Dataspace to use for attribute */
|
||
hid_t ret_value; /* Return value */
|
||
|
||
FUNC_ENTER_API(H5Acreate1, FAIL)
|
||
H5TRACE5("i", "i*siii", loc_id, name, type_id, space_id, plist_id);
|
||
|
||
/* check arguments */
|
||
if(H5I_ATTR == H5I_get_type(loc_id))
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "location is not valid for an attribute")
|
||
if(H5G_loc(loc_id, &loc) < 0)
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
|
||
if(0 == (H5F_INTENT(loc.oloc->file) & H5F_ACC_RDWR))
|
||
HGOTO_ERROR(H5E_ARGS, H5E_WRITEERROR, FAIL, "no write intent on file")
|
||
if(!name || !*name)
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
|
||
if(NULL == (type = (H5T_t *)H5I_object_verify(type_id, H5I_DATATYPE)))
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a type")
|
||
if(NULL == (space = (H5S_t *)H5I_object_verify(space_id, H5I_DATASPACE)))
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a data space")
|
||
|
||
/* Go do the real work for attaching the attribute to the dataset */
|
||
if((ret_value = H5A_create(&loc, name, type, space, plist_id, H5AC_dxpl_id)) < 0)
|
||
HGOTO_ERROR(H5E_ATTR, H5E_CANTINIT, FAIL, "unable to create attribute")
|
||
|
||
done:
|
||
FUNC_LEAVE_API(ret_value)
|
||
} /* H5Acreate1() */
|
||
|
||
|
||
/*--------------------------------------------------------------------------
|
||
NAME
|
||
H5Aopen_name
|
||
PURPOSE
|
||
Opens an attribute for an object by looking up the attribute name
|
||
USAGE
|
||
hid_t H5Aopen_name (loc_id, name)
|
||
hid_t loc_id; IN: Object (dataset or group) to be attached to
|
||
const char *name; IN: Name of attribute to locate and open
|
||
RETURNS
|
||
ID of attribute on success, negative on failure
|
||
|
||
DESCRIPTION
|
||
This function opens an existing attribute for access. The attribute
|
||
name specified is used to look up the corresponding attribute for the
|
||
object. The attribute ID returned from this function must be released with
|
||
H5Aclose or resource leaks will develop.
|
||
The location object may be either a group or a dataset, both of
|
||
which may have any sort of attribute.
|
||
NOTE
|
||
Deprecated in favor of H5Aopen
|
||
--------------------------------------------------------------------------*/
|
||
hid_t
|
||
H5Aopen_name(hid_t loc_id, const char *name)
|
||
{
|
||
H5G_loc_t loc; /* Object location */
|
||
H5A_t *attr = NULL; /* Attribute opened */
|
||
hid_t ret_value;
|
||
|
||
FUNC_ENTER_API(H5Aopen_name, FAIL)
|
||
H5TRACE2("i", "i*s", loc_id, name);
|
||
|
||
/* check arguments */
|
||
if(H5I_ATTR == H5I_get_type(loc_id))
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "location is not valid for an attribute")
|
||
if(H5G_loc(loc_id, &loc) < 0)
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
|
||
if(!name || !*name)
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
|
||
|
||
/* Open the attribute on the object header */
|
||
if(NULL == (attr = H5A_open_by_name(&loc, ".", name, H5P_LINK_ACCESS_DEFAULT, H5AC_ind_dxpl_id)))
|
||
HGOTO_ERROR(H5E_ATTR, H5E_CANTOPENOBJ, FAIL, "can't open attribute")
|
||
|
||
/* Register the attribute and get an ID for it */
|
||
if((ret_value = H5I_register(H5I_ATTR, attr)) < 0)
|
||
HGOTO_ERROR(H5E_ATOM, H5E_CANTREGISTER, FAIL, "unable to register attribute for ID")
|
||
|
||
done:
|
||
/* Cleanup on failure */
|
||
if(ret_value < 0)
|
||
if(attr && H5A_close(attr) < 0)
|
||
HDONE_ERROR(H5E_ATTR, H5E_CANTFREE, FAIL, "can't close attribute")
|
||
|
||
FUNC_LEAVE_API(ret_value)
|
||
} /* H5Aopen_name() */
|
||
|
||
|
||
/*--------------------------------------------------------------------------
|
||
NAME
|
||
H5Aopen_idx
|
||
PURPOSE
|
||
Opens the n'th attribute for an object
|
||
USAGE
|
||
hid_t H5Aopen_idx (loc_id, idx)
|
||
hid_t loc_id; IN: Object that attribute is attached to
|
||
unsigned idx; IN: Index (0-based) attribute to open
|
||
RETURNS
|
||
ID of attribute on success, negative on failure
|
||
|
||
DESCRIPTION
|
||
This function opens an existing attribute for access. The attribute
|
||
index specified is used to look up the corresponding attribute for the
|
||
object. The attribute ID returned from this function must be released with
|
||
H5Aclose or resource leaks will develop.
|
||
The location object may be either a group or a dataset, both of
|
||
which may have any sort of attribute.
|
||
NOTE
|
||
Deprecated in favor of H5Aopen_by_idx
|
||
--------------------------------------------------------------------------*/
|
||
hid_t
|
||
H5Aopen_idx(hid_t loc_id, unsigned idx)
|
||
{
|
||
H5G_loc_t loc; /* Object location */
|
||
H5A_t *attr = NULL; /* Attribute opened */
|
||
hid_t ret_value;
|
||
|
||
FUNC_ENTER_API(H5Aopen_idx, FAIL)
|
||
H5TRACE2("i", "iIu", loc_id, idx);
|
||
|
||
/* check arguments */
|
||
if(H5I_ATTR == H5I_get_type(loc_id))
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "location is not valid for an attribute")
|
||
if(H5G_loc(loc_id, &loc) < 0)
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
|
||
|
||
/* Open the attribute in the object header */
|
||
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)))
|
||
HGOTO_ERROR(H5E_ATTR, H5E_CANTOPENOBJ, FAIL, "unable to open attribute")
|
||
|
||
/* Register the attribute and get an ID for it */
|
||
if((ret_value = H5I_register(H5I_ATTR, attr)) < 0)
|
||
HGOTO_ERROR(H5E_ATOM, H5E_CANTREGISTER, FAIL, "unable to register attribute for ID")
|
||
|
||
done:
|
||
/* Cleanup on failure */
|
||
if(ret_value < 0)
|
||
if(attr && H5A_close(attr) < 0)
|
||
HDONE_ERROR(H5E_ATTR, H5E_CANTFREE, FAIL, "can't close attribute")
|
||
|
||
FUNC_LEAVE_API(ret_value)
|
||
} /* H5Aopen_idx() */
|
||
|
||
|
||
/*--------------------------------------------------------------------------
|
||
NAME
|
||
H5Aget_num_attrs
|
||
PURPOSE
|
||
Determines the number of attributes attached to an object
|
||
NOTE
|
||
Deprecated in favor of H5Oget_info[_by_idx]
|
||
USAGE
|
||
int H5Aget_num_attrs (loc_id)
|
||
hid_t loc_id; IN: Object (dataset or group) to be queried
|
||
RETURNS
|
||
Number of attributes on success, negative on failure
|
||
DESCRIPTION
|
||
This function returns the number of attributes attached to a dataset or
|
||
group, 'location_id'.
|
||
NOTE
|
||
Deprecated in favor of H5Oget_info
|
||
--------------------------------------------------------------------------*/
|
||
int
|
||
H5Aget_num_attrs(hid_t loc_id)
|
||
{
|
||
H5O_loc_t *loc; /* Object location for attribute */
|
||
void *obj;
|
||
int ret_value;
|
||
|
||
FUNC_ENTER_API(H5Aget_num_attrs, FAIL)
|
||
H5TRACE1("Is", "i", loc_id);
|
||
|
||
/* check arguments */
|
||
if(H5I_BADID == H5I_get_type(loc_id))
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "bad location ID")
|
||
if(H5I_FILE == H5I_get_type(loc_id) || H5I_ATTR == H5I_get_type(loc_id))
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "location is not valid for an attribute")
|
||
if(NULL == (obj = H5I_object(loc_id)))
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADATOM, FAIL, "illegal object atom")
|
||
switch(H5I_get_type (loc_id)) {
|
||
case H5I_DATASET:
|
||
if(NULL == (loc = H5D_oloc((H5D_t*)obj)))
|
||
HGOTO_ERROR(H5E_ATTR, H5E_CANTGET, FAIL, "can't get location for object")
|
||
break;
|
||
|
||
case H5I_DATATYPE:
|
||
if(NULL == (loc = H5T_oloc((H5T_t*)obj)))
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "target datatype is not committed")
|
||
break;
|
||
|
||
case H5I_GROUP:
|
||
if(NULL == (loc = H5G_oloc((H5G_t*)obj)))
|
||
HGOTO_ERROR(H5E_ATTR, H5E_CANTGET, FAIL, "can't get location for object")
|
||
break;
|
||
|
||
default:
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "inappropriate attribute target")
|
||
} /*lint !e788 All appropriate cases are covered */
|
||
|
||
/* Look up the # of attributes for the object */
|
||
if((ret_value = H5O_attr_count(loc, H5AC_ind_dxpl_id)) < 0)
|
||
HGOTO_ERROR(H5E_ATTR, H5E_CANTCOUNT, FAIL, "can't get attribute count for object")
|
||
|
||
done:
|
||
FUNC_LEAVE_API(ret_value)
|
||
} /* H5Aget_num_attrs() */
|
||
|
||
|
||
/*--------------------------------------------------------------------------
|
||
NAME
|
||
H5Aiterate1
|
||
PURPOSE
|
||
Calls a user's function for each attribute on an object
|
||
USAGE
|
||
herr_t H5Aiterate1(loc_id, attr_num, op, data)
|
||
hid_t loc_id; IN: Object (dataset or group) to be iterated over
|
||
unsigned *attr_num; IN/OUT: Starting (IN) & Ending (OUT) attribute number
|
||
H5A_operator1_t op; IN: User's function to pass each attribute to
|
||
void *op_data; IN/OUT: User's data to pass through to iterator operator function
|
||
RETURNS
|
||
Returns a negative value if something is wrong, the return value of the
|
||
last operator if it was non-zero, or zero if all attributes were processed.
|
||
|
||
DESCRIPTION
|
||
This function interates over the attributes of dataset or group
|
||
specified with 'loc_id'. For each attribute of the object, the
|
||
'op_data' and some additional information (specified below) are passed
|
||
to the 'op' function. The iteration begins with the '*attr_number'
|
||
object in the group and the next attribute to be processed by the operator
|
||
is returned in '*attr_number'.
|
||
The operation receives the ID for the group or dataset being iterated
|
||
over ('loc_id'), the name of the current attribute about the object
|
||
('attr_name') and the pointer to the operator data passed in to H5Aiterate
|
||
('op_data'). The return values from an operator are:
|
||
A. Zero causes the iterator to continue, returning zero when all
|
||
attributes have been processed.
|
||
B. Positive causes the iterator to immediately return that positive
|
||
value, indicating short-circuit success. The iterator can be
|
||
restarted at the next attribute.
|
||
C. Negative causes the iterator to immediately return that value,
|
||
indicating failure. The iterator can be restarted at the next
|
||
attribute.
|
||
NOTE
|
||
Deprecated in favor of H5Aiterate2
|
||
--------------------------------------------------------------------------*/
|
||
herr_t
|
||
H5Aiterate1(hid_t loc_id, unsigned *attr_num, H5A_operator1_t op, void *op_data)
|
||
{
|
||
H5A_attr_iter_op_t attr_op; /* Attribute operator */
|
||
hsize_t start_idx; /* Index of attribute to start iterating at */
|
||
hsize_t last_attr; /* Index of last attribute examined */
|
||
herr_t ret_value; /* Return value */
|
||
|
||
FUNC_ENTER_API(H5Aiterate1, FAIL)
|
||
H5TRACE4("e", "i*Iux*x", loc_id, attr_num, op, op_data);
|
||
|
||
/* check arguments */
|
||
if(H5I_ATTR == H5I_get_type(loc_id))
|
||
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "location is not valid for an attribute")
|
||
|
||
/* Build attribute operator info */
|
||
attr_op.op_type = H5A_ATTR_OP_APP;
|
||
attr_op.u.app_op = op;
|
||
|
||
/* Call attribute iteration routine */
|
||
last_attr = start_idx = (hsize_t)(attr_num ? *attr_num : 0);
|
||
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)
|
||
HERROR(H5E_ATTR, H5E_BADITER, "error iterating over attributes");
|
||
|
||
/* Set the last attribute information */
|
||
if(attr_num)
|
||
*attr_num = (unsigned)last_attr;
|
||
|
||
done:
|
||
FUNC_LEAVE_API(ret_value)
|
||
} /* H5Aiterate1() */
|
||
#endif /* H5_NO_DEPRECATED_SYMBOLS */
|
||
|