Name: H5Diterate

Signature:

herr_t H5Diterate( void *buf, hid_t type_id, hid_t space_id, H5D_operator_t operator, void *operator_data )

Purpose:

Iterates over all selected elements in a dataspace.

Description:

H5Diterate iterates over all the data elements in the memory buffer buf, executing the callback function operator once for each such data element.

The protoype of the callback function operator is as follows (as defined in the source code file H5Lpublic.h):


          herr_t (*H5D_operator_t)(void elem, 
              hid_t type_id, 
              unsigned ndim, 
              
         
                           
                      
              const hsize_t *point, 
              void *operator_data)

The parameters of this callback function have the following values or meanings:

void *elem IN/OUT: Pointer to the memory buffer containing the current data element

hid_t type_id IN: Datatype identifier for the elements stored in elem

unsigned ndim IN: Number of dimensions for the point array

const hsize_t *point IN: Array containing the location of the element within the original dataspace

void *operator_data IN/OUT: Pointer to any user-defined data associated with the operation

The possible return values from the callback function, and the effect of each, are as follows:

Zero causes the iterator to continue, returning zero when all data elements have been processed.
A positive value causes the iterator to immediately return that positive value, indicating short-circuit success.
A negative value causes the iterator to immediately return that value, indicating failure.

The H5Diterate operator_data parameter is a user-defined pointer to the data required to process dataset elements in the course of the iteration. If operator needs to pass data back to the application, such data can be returned in this same buffer. This pointer is passed back to each step of the iteration in the operator callback function’s operator_data parameter.

Unlike other HDF5 iterators, this iteration operation cannot be restarted at the point of exit; a second H5Diterate call will always restart at the beginning.

Parameters:

void *buf IN/OUT: Pointer to the buffer in memory containing the elements to iterate over

hid_t type_id IN: Datatype identifier for the elements stored in buf

hid_t space_id IN: Dataspace identifier for buf

H5D_operator_t operator IN: Function pointer to the routine to be called for each element in buf iterated over

void *operator_data IN/OUT: Pointer to any user-defined data associated with the operation

Returns:

Returns the return value of the last operator if it was non-zero, or zero if all elements have been processed. Otherwise returns a negative value.

Fortran90 Interface:

None.

History:

Release     C

1.6.4 The following changes occured in the H5D_operator_t function in this release:
   ndim parameter type was changed to unsigned
   point parameter type was changed to const hsize_t

	`void *elem`		IN/OUT: Pointer to the memory buffer containing the current data element
	`hid_t type_id`		IN: Datatype identifier for the elements stored in `elem`
	`unsigned ndim`		IN: Number of dimensions for the `point` array
	`const hsize_t *point`		IN: Array containing the location of the element within the original dataspace
	`void *operator_data`		IN/OUT: Pointer to any user-defined data associated with the operation

void *`buf`	IN/OUT: Pointer to the buffer in memory containing the elements to iterate over
hid_t `type_id`	IN: Datatype identifier for the elements stored in `buf`
hid_t `space_id`	IN: Dataspace identifier for `buf`
H5D_operator_t `operator`	IN: Function pointer to the routine to be called for each element in `buf` iterated over
void *`operator_data`	IN/OUT: Pointer to any user-defined data associated with the operation

Release	C
1.6.4	The following changes occured in the `H5D_operator_t` function in this release: `ndim` parameter type was changed to unsigned `point` parameter type was changed to const hsize_t