Last modified: 26 August 2013
Name: H5Tcommit_anon
Signature:
  herr_t `H5Tcommit_anon`( hid_t `loc_id`, hid_t `dtype_id`, hid_t `tcpl_id`, hid_t `tapl_id` )

Purpose:
  Commits a transient datatype to a file, creating a new named datatype, but does not link it into the file structure.

Description:
  `H5Tcommit_anon` commits a transient datatype (not immutable) to a file, turning it into a named datatype with the specified creation and property lists. With default property lists, `H5P_DEFAULT`, `H5Tcommit_anon` provides similar functionality to that of `H5Tcommit`, with the differences described below.

  The datatype access property list identifier, `tapl_id`, is provided for future functionality and is not used at this time. This parameter should always be passed as the value `H5P_DEFAULT`.

  Note that `H5Tcommit_anon` does not link this newly-committed datatype into the file. After the `H5Tcommit_anon` call, the datatype identifier `dtype_id` must be linked into the HDF5 file structure with `H5Olink` or it will be deleted from the file when the file is closed.

  The differences between this function and `H5Tcommit` are as follows:

  - `H5Tcommit_anon` explicitly includes property lists, which provides for greater control of the creation process and of the properties of the new named datatype. `H5Tcommit` always uses default properties.
  - `H5Tcommit_anon` neither provides the new named datatype’s name nor links it into the HDF5 file structure; those actions must be performed separately through a call to `H5Olink`, which offers greater control over linking.

  This function will not accept a datatype that cannot actually hold data. This currently includes compound datatypes with no fields and enumerated datatypes with no members.

Parameters:

  hid_t `loc_id` | IN: A file or group identifier specifying the file in which the new named datatype is to be created.
  hid_t `dtype_id` | IN: A datatype identifier.
  hid_t `tcpl_id` | IN: A datatype creation property list identifier. (`H5P_DEFAULT` for the default property list.)
  hid_t `tapl_id` | IN: A datatype access property list identifier. Currently unused; should always be passed as the value `H5P_DEFAULT`.

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

Fortran90 Interface: h5tcommit_anon_f

      SUBROUTINE h5tcommit_anon_f(loc_id, dtype_id, hdferr, tcpl_id, tapl_id)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: loc_id ! A file or group identifier specifying
                                             ! the file in which the new named
                                             ! datatype is to be created.
        INTEGER(HID_T), INTENT(IN) :: dtype_id
                                             ! Datatype identifier
        INTEGER, INTENT(OUT) :: hdferr       ! Error code
                                             ! 0 on success and -1 on failure

        INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tcpl_id
                                             ! A datatype creation property
                                             ! list identifier.
                                             !  H5P_DEFAULT_F = default property list
        INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tapl_id
                                             ! A datatype access property list id
      END SUBROUTINE h5tcommit_anon_f

See Also:
  `H5Olink`
  `H5Tcommit`
History:

  Release | C
  1.8.7 | Function modified in this release to reject datatypes that will not accomodate actual data, such as a compound datatype with no fields or an enumerated datatype with no members.
  1.8.0 | Function introduced in this release.