Last modified: 10 June 2010
Name: H5Pget_filter1
Signature:
  H5Z_filter_t `H5Pget_filter1`( hid_t `plist_id`, unsigned int `idx`, unsigned int *`flags`, size_t *`cd_nelmts`, unsigned int *`cd_values`, size_t `namelen`, char `name[]` )

Purpose:
  Returns information about a filter in a pipeline.

Notice:
  This function is renamed from `H5Pget_filter` and deprecated in favor of the function `H5Pget_filter2` or the new macro `H5Pget_filter`.

Description:
  `H5Pget_filter1` returns information about a filter, specified by its filter number, in a filter pipeline, specified by the property list with which it is associated.

  `plist_id` must be a dataset or group creation property list.

  `idx` is a value between zero and N-1, as described in `H5Pget_nfilters`. The function will return a negative value if the filter number is out of range.

  The structure of the `flags` argument is discussed in `H5Pset_filter`.

  On input, `cd_nelmts` indicates the number of entries in the `cd_values` array, as allocated by the caller; on return,`cd_nelmts` contains the number of values defined by the filter.

  If `name` is a pointer to an array of at least `namelen` bytes, the filter name will be copied into that array. The name will be null terminated if `namelen` is large enough. The filter name returned will be the name appearing in the file, the name registered for the filter, or an empty string.

Parameters:

  hid_t `plist_id` | IN: Dataset or group creation property list identifier.
  int `idx` | IN: Sequence number within the filter pipeline of the filter for which information is sought.
  unsigned int *`flags` | OUT: Bit vector specifying certain general properties of the filter.
  size_t *`cd_nelmts` | IN/OUT: Number of elements in `cd_values`.
  unsigned int *`cd_values` | OUT: Auxiliary data for the filter.
  size_t `namelen` | IN: Anticipated number of characters in `name`.
  char `name[]` | OUT: Name of the filter.

Returns:
  Returns the filter identifier if successful:

  `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
  `H5Z_FILTER_NBIT` | Data compression filter, employing the N-bit algorithm
  `H5Z_FILTER_SCALEOFFSET` | Data compression filter, employing the scale-offset algorithm

  Otherwise returns a negative value.

Fortran90 Interface: h5pget_filter_f

      SUBROUTINE h5pget_filter_f(prp_id, filter_number, flags, cd_nelmts,
                                 cd_values, namelen, name, filter_id, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: prp_id    ! Property list identifier
        INTEGER, INTENT(IN) :: filter_number    ! Sequence number within the filter
                                                ! pipeline of the filter for which
                                                ! information is sought
        INTEGER, DIMENSION(*), INTENT(OUT) :: cd_values
                                                ! Auxiliary data for the filter
        INTEGER, INTENT(OUT) :: flags           ! Bit vector specifying certain
                                                ! general properties of the filter
        INTEGER(SIZE_T), INTENT(INOUT) :: cd_nelmts
                                                ! Number of elements in cd_values
        INTEGER(SIZE_T), INTENT(IN) :: namelen  ! Anticipated number of characters
                                                ! in name
        CHARACTER(LEN=*), INTENT(OUT) :: name   ! Name of the filter
        INTEGER, INTENT(OUT) :: filter_id       ! Filter identification number
        INTEGER, INTENT(OUT) :: hdferr          ! Error code
                                                ! 0 on success and -1 on failure
      END SUBROUTINE h5pget_filter_f

History:

Release | Change
1.6.4 | `filter` parameter type changed to unsigned.
1.8.0 | N-bit and scale-offset filters added.
1.8.0 | Function `H5Pget_filter` renamed to `H5Pget_filter1` and deprecated in this release.
1.8.5 | Function extended to work with group creation property lists.