Last modified: 9 October 2014
Name: H5Dcreate2
Signature:
  hid_t `H5Dcreate2`( hid_t `loc_id`, const char *`name`, hid_t `dtype_id`, hid_t `space_id`, hid_t `lcpl_id`, hid_t `dcpl_id`, hid_t `dapl_id` )

Purpose:
  Creates a new dataset and links it into the file.

Description:
  `H5Dcreate2` creates a new dataset named `name` at the location specified by `loc_id`, and associates constant and initial persistent properties with that dataset, including `dtype_id`, the datatype of each data element as stored in the file; `space_id`, the dataspace of the dataset; and other initial properties as defined in the dataset creation property and access property lists, `dcpl_id` and `dapl_id`, respectively. Once created, the dataset is opened for access.

  `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 dataset.

  If `dtype_id` is either a fixed-length or variable-length string, it is important to set the string length when defining the datatype. String datatypes are derived from `H5T_C_S1` (or `H5T_FORTRAN_S1` for Fortran codes), which defaults to 1 character in size. See `H5Tset_size` and “Creating variable-length string datatypes.”

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

  The datatype and dataspace properties and the dataset creation and access property lists are attached to the dataset, so the caller may derive new datatypes, dataspaces, and creation and access properties from the old ones and reuse them in calls to create additional datasets.

  Once created, the dataset is ready to receive raw data. Immediately attempting to read raw data from the dataset will probably return the fill value.

  To conserve and release resources, the dataset should be closed when access is no longer required.

Parameters:

  hid_t `loc_id` | IN: Location identifier
  const char *`name` | IN: Dataset name
  hid_t `dtype_id` | IN: Datatype identifier
  hid_t `space_id` | IN: Dataspace identifier
  hid_t `lcpl_id` | IN: Link creation property list
  hid_t `dcpl_id` | IN: Dataset creation property list
  hid_t `dapl_id` | IN: Dataset access property list

Returns:
  Returns a dataset identifier if successful; otherwise returns a negative value.

Fortran90 Interface: See listing under `H5Dcreate`.

See Also:
  `H5Tset_size`
  “Creating variable-length string datatypes”
  “Using Identifiers”

History:

  Release | Change
  1.8.0 | C function introduced in this release.