You are viewing an old version of this page. View the current version.
Version 1 Next »
Gathers data from a selection within a memory buffer.
H5D_GATHER(src_space_id, src_buf, type-id, dst_buf_size, dst_buf, op, op_data)
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, )
|hid_t ||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 *||IN: Source buffer which the data will be gathered from.|
|hid_t ||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 ||IN: Size in bytes of |
|void *||OUT: Destination buffer where the gathered data will be placed.|
|H5D_gather_func_t ||IN: Callback function which handles the gathered data. Optional if |
|void * ||IN: User-defined pointer to data required by |
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
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
op to process the serialized data. The prototype of the callback function
op is as follows (as defined in the source code file
(*H5D_gather_func_t)( const void *
dst_buf_bytes_used, void *
The parameters of this callback function have the following values or meanings:
|Pointer to the destination buffer which has been filled with the next set of elements gathered. This will always be identical to the |
|Pointer to the number of valid bytes in |
|User-defined pointer to data required by the callback function; a pass-through of the |
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_type_conv_cb and functions such as
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 a non-negative value if successful; otherwise returns a negative value.
|1.8.11||C function introduced.|