Name: H5Pset_filter
Signature:
  herr_t `H5Pset_filter`(hid_t `plist`, H5Z_filter_t `filter`, unsigned int `flags`, size_t `cd_nelmts`, const unsigned int `cd_values[]` )

Purpose:
  Adds a filter to the filter pipeline.

Description:
  `H5Pset_filter` adds the specified `filter` and corresponding properties to the end of an output filter pipeline. If `plist` is a dataset creation property list, the filter is added to the permanent filter pipeline; if `plist` is a dataset transfer property list, the filter is added to the transient filter pipeline.

  The array `cd_values` contains `cd_nelmts` integers which are auxiliary data for the filter. The integer values will be stored in the dataset object header as part of the filter information.

  The `flags` argument is a bit vector with the following fields specifying certain general properties of the filter:

  `H5Z_FLAG_OPTIONAL` | If this bit is set then the filter is optional. If the filter fails (see below) during an `H5Dwrite` operation then the filter is just excluded from the pipeline for the chunk for which it failed; the filter will not participate in the pipeline during an `H5Dread` of the chunk. This is commonly used for compression filters: if the filter result would be larger than the input, then the compression filter returns failure and the uncompressed data is stored in the file. If this bit is clear and a filter fails, then `H5Dwrite` or `H5Dread` also fails. This flag should not be set for the Fletcher32 checksum filter as it will bypass the checksum filter without reporting checksum errors to an application.

  The `filter` parameter specifies the filter to be set. Valid filter identifiers are as follows:

  `H5Z_FILTER_DEFLATE` | Data compression filter, employing the gzip algorithm
  `H5Z_FILTER_SHUFFLE` | Data shuffling filter
  `H5Z_FILTER_FLETCHER32` | Error detection filter, employing the Fletcher32 checksum algorithm
  `H5Z_FILTER_SZIP` | Data compression filter, employing the SZIP algorithm

  Also see H5Pset_edc_check and H5Pset_filter_callback.

Notes:
  This function currently supports only the permanent filter pipeline; `plist` must be a dataset creation property list.

  If multiple filters are set for a property list, they will be applied to each chunk in the order in which they were set.

See Also:
  For a discussion of optional versus required filter behavior, see “Filter Behavior in HDF5.”

Parameters:

hid_t `plist` | IN: Property list identifier.
H5Z_filter_t `filter` | IN: Filter identifier for the filter to be added to the pipeline.
unsigned int `flags` | IN: Bit vector specifying certain general properties of the filter.
size_t `cd_nelmts` | IN: Number of elements in `cd_values`.
const unsigned int `cd_values[]` | IN: Auxiliary data for the filter.

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

Fortran90 Interface: h5pset_filter_f

      SUBROUTINE h5pset_filter_f(prp_id, filter, flags, cd_nelmts, cd_values,  hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: prp_id  ! Property list identifier
        INTEGER, INTENT(IN) :: filter         ! Filter to be added to the pipeline
        INTEGER, INTENT(IN) :: flags          ! Bit vector specifying certain
                                              ! general properties of the filter
        INTEGER(SIZE_T), INTENT(IN) :: cd_nelmts
                                              ! Number of elements in cd_values
        INTEGER, DIMENSION(*), INTENT(IN) :: cd_values
                                              ! Auxiliary data for the filter
        INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                              ! 0 on success and -1 on failure
      END SUBROUTINE h5pset_filter_f

History:

Release | C
1.6.0 | Function introduced in this release.