- Created by Mike McGreevy, last modified by Barbara Jones on Dec 18, 2018
H5D_GATHER
Gathers data from a selection within a memory buffer
Procedure:
H5D_GATHER(src_space_id, src_buf, type-id, dst_buf_size, dst_buf, op, op_data)
Signature:
herr_t 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, )
Parameters:
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 |
Description:
H5D_GATHER 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, H5D_GATHER simply gathers the data into dst_buf and returns. If a callback function is provided, H5D_GATHER 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):
herr_t (*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 H5D_GATHER. |
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 H5D_GATHER 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 H5Tconvertand 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.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Example:
Coming Soon!
History:
| Release | Change |
|---|---|
| 1.8.11 | C function introduced. |
--- Last Modified: December 18, 2018 | 01:22 PM