- Created by Mike McGreevy, last modified by Barbara Jones on Jul 29, 2020
H5D_CREATE1
Creates a dataset at the specified location
This function is deprecated in favor of the function H5D_CREATE2 or the macro H5D_CREATE.
Procedure:
H5D_CREATE1(loc_id, name, type_id, space_id, dcpl_id)
Signature:
hid_t H5Dcreate1( hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id )
SUBROUTINE h5dcreate_f(loc_id, name, type_id, space_id, dset_id, &
hdferr, dcpl_id, lcpl_id, dapl_id)
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) :: dcpl_id
! Dataset creation property list
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id
! Link creation property list
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: dapl_id
! Dataset access property list
END SUBROUTINE h5dcreate_f
Parameters:
hid_t loc_id | IN: Location identifier; may be a file, group, dataset, named datatype, or attribute |
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 |
Description:
H5D_CREATE1 creates a data set with a name, name, in the location specified by the identifier loc_id. loc_id may be a file, group, dataset, named datatype or attribute. If an attribute, dataset, or named datatype is specified for loc_id then the dataset will be created at the location where the attribute, dataset, or named datatype is attached.
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: H5D_CREATE1 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 H5P_CREATE1 and initialized with various property list functions described in Property List Interface.
H5D_CREATE and H5D_CREATE_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.
H5D_CREATE and H5D_CREATE_ANON return a dataset identifier for success or a negative value for failure. The dataset identifier should eventually be closed by calling H5D_CLOSE to release resources it uses.
See H5D_CREATE_ANON for discussion of the differences between H5D_CREATE and H5D_CREATE_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:
This information is also included in the “HDF5 Datasets” chapter of the new HDF5 User's Guide, which is being prepared for release.
Returns:
Returns a dataset identifier if successful; otherwise returns a negative value.
Example:
History:
| Release | Change |
|---|---|
| 1.8.0 | Function H5Dcreate renamed to H5Dcreate1 and deprecated in this release. |
| 1.4.0 | Fortran call introduced in this release. |
| 1.0.0 | C function introduced in this release. |
--- Last Modified: July 29, 2020 | 01:38 PM