Name: H5Dcreate
Signature:
hid_t H5Dcreate(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t create_plist_id )
Purpose:
Creates a dataset at the specified location.
Description:
H5Dcreate creates a data set with a name, name, in the file or in the group specified by the identifier loc_id. The dataset has the datatype and dataspace identified by type_id and space_id, respectively. The specified datatype and dataspace are the datatype and dataspace of the dataset as it will exist in the file, which may be different than in application memory. Dataset creation properties are specified by the argument create_plist_id.

Dataset names within a group are unique: H5Dcreate will return an error if a dataset 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.

create_plist_id is a H5P_DATASET_CREATE property list created with H5Pcreate and initialized with the various functions described above.

H5Dcreate returns 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 returns 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.

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 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 to all required conditions. This problem is most likely to occur with the use of filters.

For example, H5Dcreate will fail without a meaningful explanation if

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:
Returns:
Returns a dataset identifier if successful; otherwise returns a negative value.
Fortran90 Interface: h5dcreate_f
SUBROUTINE h5dcreate_f(loc_id, name, type_id, space_id, dset_id, & 
                       hdferr, creation_prp) 
  IMPLICIT NONE 
  INTEGER(HID_T), INTENT(IN) :: loc_id   ! File or group identifier
  CHARACTER(LEN=*), INTENT(IN) :: name   ! Name of the dataset 
  INTEGER(HID_T), INTENT(IN) :: type_id  ! Datatype identifier 
  INTEGER(HID_T), INTENT(IN) :: space_id ! Dataspace identifier
  INTEGER(HID_T), INTENT(OUT) :: dset_id ! Dataset identifier
  INTEGER, INTENT(OUT) :: hdferr         ! Error code 
                                         ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: creation_prp
                                         ! Dataset creation propertly 
                                         ! list identifier , default
                                         ! value is H5P_DEFAULT_F (6) 
END SUBROUTINE h5dcreate_f