H5Dgather(
hid_t src_space_id,
const void * src_buf,
hid_t type_id,
size_t dst_buf_size,
void *dst_buf
H5D_gather_func_t op,
void * op_data,
)
H5Dgather retrieves data from a selection within the
supplied buffer src_buf and passes it to the supplied
callback function op in a contiguous form.
src_space_id is a dataspace which defines the extent
of src_buf and the selection within it to gather the
data from.
type_id is the datatype of the data to be gathered in
both the source and destination buffers.
src_buf must be at least as large as the number of
elements in the extent of src_space_id times the size
in bytes of type_id.
The data is gathered into dst_buf, which needs to be
large enough to hold all the data if the callback function
op is not provided.
If no callback function is provided, H5Dgather
simply gathers the data into dst_buf and returns.
If a callback function is provided, H5Dgather repeatedly
gathers up to dst_buf_size bytes op to
process the serialized data.
The prototype of the callback function op is as follows
(as defined in the source code file H5Dpublic.h):
(*H5D_gather_func_t)(
const void * dst_buf,
size_t dst_buf_bytes_used,
void *op_data)
The parameters of this callback function have the following values or meanings:
|
dst_buf
|
Pointer to the destination buffer which has been filled with the
next set of elements gathered.
This will always be identical to the dst_buf passed
to H5Dgather.
|
|
dst_buf_bytes_used
|
Pointer to the number of valid bytes in dst_buf.
This number must be a multiple of the datatype size.
|
|
op_data
|
User-defined pointer to data required by the callback function;
a pass-through of the op_data pointer provided
with the H5Dgather function call.
|
The callback function should process, store, or otherwise make use of
the data returned in dst_buf before it returns, because the
buffer will be overwritten unless it is the last call to the callback.
This function will be repeatedly called until all gathered elements have
been passed to the callback in dst_buf.
The callback function should return zero (0) to indicate
success, and a negative value to indicate failure.
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb and H5Pset_type_conv_cb
and functions such as H5Tconvert and
H5Ewalk2.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the The HDF5 C Library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
hid_t src_space_id
|
IN: Identifier for the dataspace describing both the dimensions of the source buffer and the selection within the source buffer to gather data from. |
const void *src_buf
|
IN: Source buffer which the data will be gathered from. |
hid_t type_id
|
IN: Identifier for the datatype describing the data in both the source and definition buffers. This is only used to calculate the element size. |
size_t dst_buf_size
|
IN: Size in bytes of dst_buf.
|
void *dst_buf
|
OUT: Destination buffer where the gathered data will be placed. |
H5D_gather_func_t op
|
IN: Callback function which handles the gathered
data.
Optional if dst_buf is large enough to hold all of
the gathered data; required otherwise.
|
void * op_data
|
IN: User-defined pointer to data required by
op.
|
H5Dscatter
| Release | Change |
| 1.8.11 | C function introduced. |