Last modified: 18 August 2010
Name: H5Tget_native_type
Signature:
  hid_t `H5Tget_native_type`( hid_t `dtype_id`, H5T_direction_t `direction` )

Purpose:
  Returns the native datatype of a specified datatype.

Description:
  `H5Tget_native_type` returns the equivalent native datatype for the datatype specified in `dtype_id`.

  `H5Tget_native_type` is a high-level function designed primarily to facilitate use of the `H5Dread` function, for which users otherwise must undertake a multi-step process to determine the native datatype of a dataset prior to reading it into memory. This function can be used for the following purposes:

  - To determine the native datatype of an atomic datatype
  - To determine the base datatype of an array, enumerated, or variable-length datatype
  - To determine the native atomic datatypes of the individual components of a compound datatype
  For example, if `dtype_id` is a compound datatype, the returned datatype identifier will be for a similar compound datatype with each element converted to the corresponding native datatype; nested compound datatypes will be unwound. If `dtype_id` is an array, the returned datatype identifier will be for the native datatype of a single array element.

  `H5Tget_native_type` selects the first matching native datatype from the following list:

              H5T_NATIVE_CHAR
              H5T_NATIVE_SHORT
              H5T_NATIVE_INT
              H5T_NATIVE_LONG
              H5T_NATIVE_LLONG

              H5T_NATIVE_UCHAR
              H5T_NATIVE_USHORT
              H5T_NATIVE_UINT
              H5T_NATIVE_ULONG
              H5T_NATIVE_ULLONG

              H5T_NATIVE_FLOAT
              H5T_NATIVE_DOUBLE
              H5T_NATIVE_LDOUBLE

              H5T_NATIVE_B8
              H5T_NATIVE_B16
              H5T_NATIVE_B32
              H5T_NATIVE_B64

  The `direction` parameter indicates the order in which the library searches for a native datatype match. Valid values for `direction` are as follows:

  | `H5T_DIR_ASCEND` | Searches the above list in ascending size of the datatype, i.e., from top to bottom. (Default)
  | `H5T_DIR_DESCEND` | Searches the above list in descending size of the datatype, i.e., from bottom to top.

  `H5Tget_native_type` is designed primarily for use with integer, floating point, and bitfield datatypes. String, time, opaque, and reference datatypes are returned as a copy of `dtype_id`. See above for compound, array, enumerated, and variable-length datatypes.

  The identifier returned by `H5Tget_native_type` should eventually be closed by calling `H5Tclose` to release resources.

Parameters:

  hid_t `dtype_id` | IN: Datatype identifier for the dataset datatype.
  H5T_direction_t `direction` | IN: Direction of search.

Returns:
  Returns the native datatype identifier for the specified dataset datatype if successful; otherwise returns a negative value.

Fortran90 Interface: h5tget_native_type_f

      SUBROUTINE h5tget_native_type_f(dtype_id, direction, native_dtype_id, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: dtype_id
                                          ! Datatype identifier
        INTEGER, INTENT(IN) :: direction  ! Direction of search:
                                          ! H5T_DIR_ASCEND_F = 1 in inscendent order
                                          ! H5T_DIR_DESCEND_F= 2 in descendent order
        INTEGER(HID_T), INTENT(OUT) :: native_dtype_id
                                          ! The native datatype identifier
        INTEGER, INTENT(OUT) :: hdferr    ! Error code:
                                          ! 0 on success and -1 on failure
      END SUBROUTINE h5tget_native_type_f

History:

  Release | C
  1.6.0 | Function introduced in this release.