Last modified: 11 July 2013
Name: H5Dgather
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`, )

Purpose:
  Gathers data from a selection within a memory buffer.

Description:
  `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`): 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 `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.

Programming Note for C++ Developers Using C Functions:

  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.

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`.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.

See Also:
  `H5Dscatter`

History:

  Release | Change
  1.8.11 | C function introduced.