Last modified: 29 July 2009
Name: H5Dcreate1
Signature:
  hid_t `H5Dcreate1`( hid_t `loc_id`, const char *`name`, hid_t `type_id`, hid_t `space_id`, hid_t `dcpl_id` )
Purpose:
  Creates a dataset at the specified location.
Notice:
  This function is deprecated in favor of the function `H5Dcreate2` or the macro `H5Dcreate`.
Description:
  `H5Dcreate1` creates a data set with a name, `name`, in the file or in the group specified by the identifier `loc_id`.

  `name` can be a relative path based at `loc_id` or an absolute path from the root of the file. Use of this function requires that any intermediate groups specified in the path already exist.

  The dataset’s datatype and dataspace are specified by `type_id` and `space_id`, respectively. These are the datatype and dataspace of the dataset as it will exist in the file, which may differ from the datatype and dataspace in application memory.

  Names within a group are unique: `H5Dcreate1` will return an error if a link with the name specified in `name` already exists at the location specified in `loc_id`.

  As is the case for any object in a group, the length of a dataset name is not limited.

  `dcpl_id` is an `H5P_DATASET_CREATE` property list created with `H5Pcreate1` and initialized with various property list functions described in “H5P: Property List Interface.”

  `H5Dcreate` and `H5Dcreate_anon` return an error if the dataset’s datatype includes a variable-length (VL) datatype and the fill value is undefined, i.e., set to `NULL` in the dataset creation property list. Such a VL datatype may be directly included, indirectly included as part of a compound or array datatype, or indirectly included as part of a nested compound or array datatype.

  `H5Dcreate` and `H5Dcreate_anon` return a dataset identifier for success or a negative value for failure. The dataset identifier should eventually be closed by calling `H5Dclose` to release resources it uses.

  See `H5Dcreate_anon` for discussion of the differences between `H5Dcreate` and `H5Dcreate_anon`.

  Fill values and space allocation:
  The HDF5 library provides flexible means of specifying a fill value, of specifying when space will be allocated for a dataset, and of specifying when fill values will be written to a dataset. For further information on these topics, see the document Fill Value and Dataset Storage Allocation Issues in HDF5 and the descriptions of the following HDF5 functions in this HDF5 Reference Manual:

  | `H5Dfill` `H5Pset_fill_value` `H5Pget_fill_value` `H5Pfill_value_defined` | `H5Pset_fill_time` `H5Pget_fill_time` `H5Pset_alloc_time` `H5Pget_alloc_time`

  This information is also included in the “HDF5 Datasets” chapter of the new HDF5 User's Guide, which is being prepared for release.
Note:
  `H5Dcreate` and `H5Dcreate_anon` can fail if there has been an error in setting up an element of the dataset creation property list. In such cases, each item in the property list must be examined to ensure that the setup satisfies all required conditions. This problem is most likely to occur with the use of filters.

  For example, either function will fail without a meaningful explanation if the following conditions exist simultaneously:

  - SZIP compression is being used on the dataset.
  - The SZIP parameter `pixels_per_block` is set to an inappropriate value.

  In such a case, one would refer to the description of `H5Pset_szip`, looking for any conditions or requirements that might affect the local computing environment.

Parameters:

hid_t `loc_id` | IN: Identifier of the file or group within which to create the dataset.
const char * `name` | IN: The name of the dataset to create.
hid_t `type_id` | IN: Identifier of the datatype to use when creating the dataset.
hid_t `space_id` | IN: Identifier of the dataspace to use when creating the dataset.
hid_t `dcpl_id` | IN: Dataset creation property list identifier.

Returns:
  Returns a dataset identifier if successful; otherwise returns a negative value.
Fortran90 Interface: See listing under `H5Dcreate`.

History:

  Release | C
  1.8.0 | Function `H5Dcreate` renamed to `H5Dcreate1` and deprecated in this release.