Name: H5Aiterate2
Signature:
  herr_t `H5Aiterate2`( hid_t `obj_id`, H5_index_t `idx_type`, H5_iter_order_t `order`, hsize_t *`n`, H5A_operator2_t `op`, void *`op_data`, )

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

Description:
  `H5Aiterate2` 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, `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 `H5Aiterate2` 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 `H5Aiterate2`, `op_data`.

  Valid return values from an operator and the resulting `H5Aiterate2` 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 `n`.
  - 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 `n`.

Parameters:

  hid_t `obj_id` | IN: Identifier for object to which attributes are attached; may be group, dataset, or named datatype.
  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

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.