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.

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.