H5Dcreate
(hid_t loc_id
,
const char *name
,
hid_t type_id
,
hid_t space_id
,
hid_t create_plist_id
)
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
|
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
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.
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 create_plist_id |
IN: Identifier of the set creation property list. |
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