Last modified: 24 September 2012
Name: H5Pget_mpio_no_collective_cause
Signature:
  herr_t `H5Pget_mpio_no_collective_cause`( hid_t `dxpl_id`, uint32_t * `local_no_collective_cause`, uint32_t * `global_no_collective_cause`)

Purpose:
  Retrieves local and global causes that broke collective I/O on the last parallel I/O call.

Motivation:
  A user can request collective I/O via a data transfer property list (DXPL) that has been suitably modified with `H5Pset_dxpl_mpio`. However, there are conditions that can cause HDF5 to forgo collective I/O and perform independent I/O. Such causes can be different across the processes of a parallel application. This function allows the user to determine what caused the HDF5 Library to skip collective I/O locally, that is in the local process, and globally, across all processes.

Description:
  `H5Pget_mpio_no_collective_cause` serves two purposes. It can be used to determine whether collective I/O was used for the last preceding parallel I/O call. If collective I/O was not used, the function retrieves the local and global causes that broke collective I/O on that parallel I/O call. The properties retrieved by this function are set before I/O takes place and are retained even when I/O fails.

  Valid values returned in `local_no_collective_cause` and `global_no_collective_cause` are as follows or, if there are multiple causes, a bitwise OR of the relevant causes; the numbers in the center column are the bitmask values:

  | `H5D_MPIO_COLLECTIVE` | `00000000` |  | Collective I/O was performed successfully. (Default)
  | `H5D_MPIO_SET_INDEPENDENT` | `00000001` |  | Collective I/O was not performed because independent I/O was requested.
  | `H5D_MPIO_DATATYPE_CONVERSION` | `00000010` |  | Collective I/O was not performed because datatype conversions were required.
  | `H5D_MPIO_DATA_TRANSFORMS` | `00000100` |  | Collective I/O was not performed because data transforms needed to be applied.
  | `H5D_MPIO_SET_MPIPOSIX` | `00001000` |  | Collective I/O was not performed because the selected file driver was MPI-POSIX.
  | `H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES`
  |  | `00010000` |  | Collective I/O was not performed because one of the dataspaces was neither simple nor scalar.
  | `H5D_MPIO_POINT_SELECTIONS` | `00100000` |  | Collective I/O was not performed because there were point selections in one of the dataspaces.
  | `H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET`
  |  | `01000000` |  | Collective I/O was not performed because the dataset was neither contiguous nor chunked.
  | `H5D_MPIO_FILTERS` | `10000000` |  | Collective I/O was not performed because filters needed to be applied.

  The above name/value pairs are members of HDF5’s `H5D_mpio_no_collective_cause_t` enumeration.

Note:
  Each process determines whether it can perform collective I/O and broadcasts the result. Those results are combined to make a collective decision; collective I/O will be performed only if all processes can perform collective I/O.

  If collective I/O was not used, the causes that prevented it are reported by individual process by means of an enumerated set. The causes may differ among processes, so `H5Pget_mpio_no_collective_cause` returns two property values. The first value is the one produced by the local process to report local causes. This local information is encoded in an enumeration, the `H5D_mpio_no_collective_cause_t` described above, with all individual causes combined into a single enumeration value by means of a bitwise OR operation. The second value reports global causes; this global value is the result of a bitwise-OR operation across the values returned by all the processes.

Parameters:

  hid_t `dxpl_id` |  | IN: Dataset transfer property list identifier
  uint32_t *`local_no_collective_cause` |  | OUT: An enumerated set value indicating the causes that prevented collective I/O in the local process.
  uint32_t *`global_no_collective_cause` |  | OUT: An enumerated set value indicating the causes across all processes that prevented collective I/O.

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

See Also:

  `H5Pget_mpio_actual_chunk_opt_mode``` | Reports type of optimization HDF5 actually attempted.
  `H5Pget_mpio_actual_io_mode` | Reports type of I/O HDF5 actually performed.

History:

  Release | Change
  1.8.10 | C function introduced in this release.