- Created by Mike McGreevy, last modified by Barbara Jones on Aug 20, 2019
H5G_CREATE
Creates a new empty group and links it to a location in the file
Signature:
hid_t H5Gcreate( hid_t loc_id, const char *name, size_t size_hint )hid_t H5Gcreate( hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id )
SUBROUTINE h5gcreate_f(loc_id, name, grp_id, hdferr, &
size_hint, lcpl_id, gcpl_id, gapl_id)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group
INTEGER(HID_T), INTENT(OUT) :: grp_id ! Group identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
INTEGER(SIZE_T), OPTIONAL, INTENT(IN) :: size_hint
! Parameter indicating the number of
! bytes to reserve for the names that
! will appear in the group.
! Note, set to OBJECT_NAMELEN_DEFAULT_F
! if using any of the optional
! parameters lcpl_id, gcpl_id,
! and/or gapl_id when not
! using keywords in specifying the
! optional parameters.
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id
! Property list for link creation
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gcpl_id
! Property list for group creation
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id
! Property list for group access
END SUBROUTINE h5gcreate_f
Description:
H5G_CREATE is a macro that is mapped to either H5G_CREATE1 or H5G_CREATE2, depending on the HDF5 library configuration and application compile-time compatibility macro mapping options.
This macro is provided to facilitate application compatibility. For example:
- The H5G_CREATE macro will be mapped to H5G_CREATE1 and will use the H5G_CREATE1 syntax (first signature above) if the application is coded for HDF5 Release 1.6.x.
- The H5G_CREATE macro will be mapped to H5G_CREATE2 and will use the H5G_CREATE2 syntax (second signature above) if the application is coded for HDF5 Release 1.8.x.
Macro use and compatibility macro mapping options are fully described in API Compatibility Macros in HDF5.
When both the HDF5 library and the application are built without specific compatibility macro mapping options, the default behavior occurs and H5G_CREATE is mapped to the most recent version of the function, currently H5G_CREATE2. If the library and/or application is compiled for Release 1.6 emulation, H5G_CREATE will be mapped to H5G_CREATE1.
Function mapping flags can be used to override these settings on a function-by-function basis when the application is compiled. The H5G_CREATE function mapping flags are shown:
h5cc flag | macro maps to |
|---|---|
-DH5Gcreate_vers=1 | H5Gcreate1 |
-DH5Gcreate_vers=2 | H5Gcreate2 |
A group created with this macro should be closed with H5G_CLOSE when the group is no longer needed so that resource leaks will not develop.
Interface history: Signature [1] above is the original H5G_CREATE interface and the only interface available prior to HDF5 Release 1.8.0. This signature and the corresponding function are now deprecated but will remain directly callable as H5G_CREATE1.
Signature [2] above was introduced with HDF5 Release 1.8.0 and is the recommended and default interface. It is directly callable as H5G_CREATE2.
Deprecated functions may not be available in all installations of the HDF5 library. See API Compatibility Macros in HDF5 for details.
See Also:
Example:
See H5G_CREATE2.
History:
| Release | Change |
|---|---|
| 1.8.0 | The function H5Gcreate renamed to H5Gcreate1 and deprecated in this release. The macro H5Gcreate and the function H5Gcreate2 introduced in this release. |
--- Last Modified: August 20, 2019 | 12:05 PM