Name: H5Aiterate_by_name
Signature:
herr_t H5Aiterate_by_name( hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t *n, H5A_operator2_t op, void *op_data, hid_t lapd_id )

Purpose:
Calls user-defined function for each attribute on an object.

Description:
H5Aiterate_by_name iterates over the attributes attached to the dataset or group specified with loc_id and obj_name. For each attribute, user-provided data, op_data, with additional information as defined below, is passed to a user-defined function, op, which operates on that attribute.

If loc_id fully specifies the object to which these attributes are attached, obj_name should be '.' (a dot).

The order of the iteration and the attributes iterated over are specified by three parameters: the index type, idx_type; the order in which the index is to be traversed, order; and the attribute’s position in the index, n.

The type of index specified by idx_type can be one of the following:
     H5_INDEX_NAME      An alpha-numeric index by attribute name
H5_INDEX_CRT_ORDER An index by creation order

The order in which the index is to be traversed, as specified by order, can be one of the following:
     H5_ITER_INC      Iteration is from beginning to end, i.e., a top-down iteration incrementing the index position at each step.
H5_ITER_DEC Iteration starts at the end of the index, i.e., a bottom-up iteration decrementing the index position at each step.
H5_ITER_NATIVE HDF5 iterates in the fastest-available order. No information is provided as to the order, but HDF5 ensures that each element in the index will be visited if the iteration completes successfully.

The next attribute to be operated on is specified by n, a position in the index.

For example, if idx_type, order, and n are set to H5_INDEX_NAME, H5_ITER_INC, and 5, respectively, the attribute in question is the fifth attribute from the beginning of the alpha-numeric index of attribute names. If order were set to H5_ITER_DEC, it would be the fifth attribute from the end of the index.

The parameter n is passed in on an H5Aiterate_by_name call with one value and may be returned with another value. The value passed in identifies the parameter to be operated on first; the value returned identifies the parameter to be operated on in the next step of the iteration.

The H5A_operator2_t prototype for the op parameter is as follows:

typedef herr_t (*H5A_operator2_t)( hid_t location_id/*in*/, const char *attr_name/*in*/, const H5A_info_t *ainfo/*in*/, void *op_data/*in,out*/)

The operation receives the location identifier for the group or dataset being iterated over, location_id; the name of the current object attribute, attr_name; the attribute’s info struct, ainfo; and a pointer to the operator data passed into H5Aiterate_by_name, op_data.

Valid return values from an operator and the resulting H5Aiterate_by_name and op behavior are as follows:

The link access property list, lapl_id, may provide information regarding the properties of links required to access the object, obj_name. See “Link Access Properties” in the H5P APIs.

Parameters:
hid_t loc_id IN: Location or object identifier; may be dataset or group
const char *obj_name IN: Name of object, relative to location
H5_index_t idx_type IN: Type of index
H5_iter_order_t order     IN: Order in which to iterate over index
hsize_t *n IN/OUT: Initial and returned offset within index
H5A_operator2_t op IN: User-defined function to pass each attribute to
void *op_data IN/OUT: User data to pass through to and to be returned by iterator operator function
hid_t lapd_id IN: Link access property list

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Further note that this function returns the return value of the last operator if it was non-zero, which can be a negative value, zero if all attributes were processed, or a positive value indicating short-circuit success (see above).

Fortran90 Interface:
None.

History:
Release     C
1.8.0 Function introduced in this release.