Last modified: 20 March 2012
Name: H5Tcommit2
Signature:
  herr_t `H5Tcommit2`( hid_t `loc_id`, const char *`name`, hid_t `dtype_id`, hid_t `lcpl_id`, hid_t `tcpl_id`, hid_t `tapl_id` )

Purpose:
  Commits a transient datatype, linking it into the file and creating a new committed datatype.

Motivation:
  Committed datatypes can be used to save space in a file where many datasets or attributes use the same datatype or to avoid defining a complex compound datatype more than once. Committed datatypes can also be used to ensure that multiple instances of the same datatype are truly identical.

Description:
  `H5Tcommit2` saves a transient datatype as an immutable committed datatype in a file. The datatype specified by `dtype_id` is committed to the file with the name `name` at the location specified by `loc_id` and with the datatype creation and access property lists `tcpl_id` and `tapl_id`, respectively.

  `loc_id` may be a file identifier, or a group identifier within that file. `name` may be either an absolute path in the file or a relative path from `loc_id` naming the newly-commited datatype.

  The link creation property list, `lcpl_id`, governs creation of the link(s) by which the new committed datatype is accessed and the creation of any intermediate groups that may be missing.

  Once commited, this datatype may be used to define the datatype of any other dataset or attribute in the file.

  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.

  Committed datatypes are sometimes referred to as named datatypes.

Parameters:

  hid_t `loc_id` | IN: Location identifier
  const char *`name` | IN: Name given to committed datatype
  hid_t `dtype_id` | IN: Identifier of datatype to be committed and, upon function’s return, identifier for the committed datatype
  hid_t `lcpl_id` | IN: Link creation property list
  hid_t `tcpl_id` | IN: Datatype creation property list
  hid_t `tapl_id` | IN: Datatype access property list

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

Fortran90 Interface:
  See listing under `H5Tcommit`.

History:

  Release | C
  1.8.0 | Function introduced in this release.
  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.