H5A_ITERATE2 iterates over the attributes attached to a dataset, named datatype, or group, as specified by
obj_id. 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.
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,
The type of index specified by
idx_type can be one of the following:
|An alpha-numeric index by attribute name|
|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:
|Iteration is from beginning to end, i.e., a top-down iteration incrementing the index position at each step.|
|Iteration starts at the end of the index, i.e., a bottom-up iteration decrementing the index position at each step.|
|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
n are set to
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.
n is passed in on an H5A_ITERATE2 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 typedef herr_t (*
H5A_operator2_t prototype for the
op parameter is as follows:
location_id/*in*/, const char *
attr_name/*in*/, const H5A_info_t *
ainfo/*in*/, void *
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
Valid return values from an operator and the resulting H5A_ITERATE2 and
op behavior are as follows:
- Zero causes the iterator to continue, returning zero when all attributes have been processed.
- A positive value causes the iterator to immediately return that positive value, indicating short-circuit success. The iterator can be restarted at the next attribute, as indicated by the return value of
- A negative value causes the iterator to immediately return that value, indicating failure. The iterator can be restarted at the next attribute, as indicated by the return value of