Describes HDF5 Release 1.8.20, November 2017.
and the Board of Trustees of the University of Illinois
The C Interfaces:
| * Use of this function is deprecated in Release 1.8.0. | ||||
Alphabetical Listing
H5Rcreate(
void *ref,
hid_t loc_id,
const char *name,
H5R_type_t ref_type,
hid_t space_id
)
H5Rcreate creates the reference, ref,
of the type specified in ref_type, pointing to
the object name located at loc_id.
The HDF5 library maps the void type specified above
for ref to the type specified in ref_type,
which will be one of those appearing in the first column of
the following table.
The second column of the table lists the HDF5 constant associated
with each reference type.
| hdset_reg_ref_t | H5R_DATASET_REGION |
Dataset region reference |
| hobj_ref_t | H5R_OBJECT |
Object reference |
The parameters loc_id and name are
used to locate the object.
The parameter space_id identifies the dataset region
that a dataset region reference points to.
This parameter is used only with dataset region references
and should be set to -1 if the reference is an
object reference, H5R_OBJECT.
More specifically, references can refer to objects only within the current logical HDF5 file while external links typically point to an object in a different logical HDF5 file. Therefore, neither an HDF5 object reference nor an HDF5 dataset region reference may refer to an object or to a region in any dataset, respectively, that is accessed by means of an external link.
void *ref |
OUT: Reference created by the function call. |
hid_t loc_id |
IN: Location identifier used to locate the object being pointed to. |
const char *name |
IN: Name of object at location
loc_id. |
H5R_type_t ref_type |
IN: Type of reference. |
hid_t space_id |
IN: Dataspace identifier with selection.
Used only for dataset region references;
pass as -1 if reference is an object reference,
i.e., of type H5R_OBJECT. |
To create an object reference:
Signature:
SUBROUTINE h5rcreate_f(loc_id, name, ref, hdferr)
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*) , INTENT(IN) :: name
TYPE(hobj_ref_t_f), INTENT(INOUT) :: ref
INTEGER , INTENT(OUT) :: hdferr
Inputs:
loc_id - Location identifier name - Name of the object at location specified by loc_id identifier
Outputs:
ref - Object reference
hdferr - Error code:
0 on success and -1 on failure
To create a region reference:
Signature:
SUBROUTINE h5rcreate_f(loc_id, name, space_id, ref, hdferr)
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*) , INTENT(IN) :: name
INTEGER(HID_T) , INTENT(IN) :: space_id
TYPE(hdset_reg_ref_t_f), INTENT(OUT) :: ref
INTEGER , INTENT(OUT) :: hdferr
Inputs:
loc_id - Location identifier name - Name of the dataset at location specified by loc_id identifier space_id - Dataset's dataspace identifier
Outputs:
ref - Dataset region reference
hdferr - Error code
0 on success and -1 on failure
SUBROUTINE h5rcreate_f(loc_id, name, ref_type, ref, hdferr, space_id)
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*), INTENT(IN) :: name
INTEGER , INTENT(IN) :: ref_type
TYPE(C_PTR) , INTENT(INOUT) :: ref
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: space_id
Inputs:
loc_id - Location identifier used to locate the object being pointed to.
name - Name of object at location loc_id.
ref_type - Type of reference:
H5R_OBJECT
H5T_STD_REF_DSETREG
Outputs:
ref - Reference created by the function call.
hdferr - Error code
0 on success and -1 on failure
Optional Parameter:
space_id - Dataspace identifier that describes selected region.
| Release | Change |
| 1.8.8 | Fortran updated to Fortran2003. |
| 1.8.0 | C function introduced in this release. |
H5Rdereference(
hid_t obj_id,
H5R_type_t ref_type,
void *ref
)
ref, to an object or a region
in an object, H5Rdereference opens that object and
returns an identifier.
The parameter obj_id must be a valid identifier for
an object in the HDF5 file containing the referenced object,
including the file identifier.
The parameter ref_type specifies the reference type
of the reference ref.
ref_type may contain either of the following values:
H5R_OBJECT (0)
H5R_DATASET_REGION (1)
The object opened with this function should be closed when
it is no longer needed so that resource leaks will not develop.
Use the appropriate close function such as H5Oclose
or H5Dclose for datasets.
hid_t obj_id |
IN: Valid identifier for the file containing the referenced object or any object in that file. |
H5R_type_t ref_type |
IN: The reference type of ref. |
void *ref |
IN: Reference to open. |
To dereference an object:
Signature:
SUBROUTINE h5rdereference_f(obj_id, ref, ref_obj_id, hdferr)
INTEGER(HID_T) , INTENT(IN) :: obj_id
TYPE(hobj_ref_t_f), INTENT(IN) :: ref
INTEGER(HID_T) , INTENT(OUT) :: ref_obj_id
INTEGER , INTENT(OUT) :: hdferr
Inputs:
obj_id - Valid identifier in file ref - Object reference
Outputs:
ref_obj_id - Identifier of referenced object
hdferr - Error code
0 on success and -1 on failure
To dereference a region:
Signature:
SUBROUTINE h5rdereference_f(obj_id, ref, ref_obj_id, hdferr)
INTEGER(HID_T) , INTENT(IN) :: obj_id
TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref
INTEGER(HID_T) , INTENT(OUT) :: ref_obj_id
INTEGER , INTENT(OUT) :: hdferr
Inputs:
dset_id - Valid identifier in file ref - Object reference
Outputs:
ref_obj_id - Identifier of referenced object
hdferr - Error code
0 on success and -1 on failure
SUBROUTINE h5rdereference_f(obj_id, ref_type, ref, ref_obj_id, hdferr)
INTEGER(HID_T), INTENT(IN) :: obj_id
INTEGER , INTENT(IN) :: ref_type
TYPE(C_PTR) , INTENT(IN) :: ref
INTEGER(HID_T), INTENT(OUT) :: ref_obj_id
INTEGER , INTENT(OUT) :: hdferr
Inputs:
obj_id - Valid identifier for the file containing the
referenced object or any object in that file.
ref_type - The reference type of ref.
ref - Object reference
Outputs:
ref_obj_id - Identifier of referenced object
hdferr - Error code
0 on success and -1 on failure
| Release | Change |
| 1.8.8 | Fortran updated to Fortran2003. |
| 1.8.0 | C function introduced in this release. |
H5Rget_obj_type(
hid_t loc_id,
H5R_type_t ref_type,
void *ref
)
H5Rget_obj_type(
hid_t loc_id,
H5R_type_t ref_type,
void *ref,
H5O_type_t *obj_type
)
H5Rget_obj_type is a macro that is mapped to either
H5Rget_obj_type1 or
H5Rget_obj_type2,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in “API Compatibility Macros in HDF5”; we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Rget_obj_type is mapped to the most recent version of
the function, currently
H5Rget_obj_type2.
If the library and/or application is compiled for Release 1.6
emulation, H5Rget_obj_type will be mapped to
H5Rget_obj_type1.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
| Compatibility setting | H5Rget_obj_type mapping |
|---|---|
Global settings |
|
| No compatibility flag | H5Rget_obj_type2 |
| Enable deprecated symbols | H5Rget_obj_type2 |
| Disable deprecated symbols | H5Rget_obj_type2 |
Emulate Release 1.6 interface |
H5Rget_obj_type1 |
Function-level macros |
|
H5Rget_obj_type_vers = 2 |
H5Rget_obj_type2 |
H5Rget_obj_type_vers = 1 |
H5Rget_obj_type1 |
SUBROUTINE h5rget_object_type_f(loc_id, ref, obj_type, hdferr)
INTEGER(HID_T) , INTENT(IN) :: loc_id
TYPE(hobj_ref_t_f), INTENT(IN) :: ref
INTEGER , INTENT(OUT) :: obj_type
INTEGER , INTENT(OUT) :: hdferr
Inputs:
loc_id - Identifier for the dataset containing the reference or
for the group that dataset is in.
ref_type - Type of reference to query.
ref - Reference to query.
Outputs:
obj_type - Type of referenced object.
H5G_UNKNOWN_F
H5G_LINK_F
H5G_GROUP_F
H5G_DATASET_F
H5G_TYPE_F
hdferr - Returns 0 if successful and -1 if fails
SUBROUTINE h5rget_object_type_f(loc_id, ref_type, ref, obj_type, hdferr)
INTEGER(HID_T), INTENT(IN) :: loc_id
INTEGER , INTENT(IN) :: ref_type
TYPE(C_PTR) , INTENT(IN) :: ref
INTEGER , INTENT(OUT) :: obj_type
INTEGER , INTENT(OUT) :: hdferr
Inputs:
loc_id - Identifier for the dataset containing the reference or
for the group that dataset is in.
ref_type - Type of reference to query.
ref - Reference to query.
Outputs:
obj_type - Type of referenced object.
H5G_UNKNOWN_F
H5G_LINK_F
H5G_GROUP_F
H5G_DATASET_F
H5G_TYPE_F
hdferr - Returns 0 if successful and -1 if fails
| Release | Change |
| 1.8.8 | Fortran updated to Fortran2003. |
| 1.8.0 | The C function
H5Rget_obj_type renamed to H5Rget_obj_type1
and deprecated in this release.
The C macro H5Rget_obj_type
and the C function H5Rget_obj_type2
introduced in this release. |
H5Rget_obj_type1(
hid_t loc_id,
H5R_type_t ref_type,
void *ref
)
H5Rget_obj_type
and is deprecated in favor of the macro
H5Rget_obj_type
or the function
H5Rget_obj_type2.
ref,
H5Rget_obj_type1
returns the type of the referenced object.
A reference type is the type of reference, either an object reference or a dataset region reference. An object reference points to an HDF5 object while a dataset region reference points to a defined region within a dataset.
The referenced object is the object the reference points to. The referenced object type, or the type of the referenced object, is the type of the object that the reference points to.
The location identifier, loc_id, is the identifier
for either the dataset containing the object reference or
the group containing that dataset.
Valid reference types, to pass in as ref_type,
include the following:
H5R_OBJECT | Object reference | |
H5R_DATASET_REGION | Dataset region reference |
If the application does not already know the object reference type, that can be determined with three preliminary calls:
H5Dget_type on the dataset
containing the reference to get a datatype identifier
for the dataset’s datatype.
H5Tget_class returns a datatype class.
H5T_REFERENCE,
H5Tequal can then be used to determine whether
the reference’s datatype is
H5T_STD_REF_OBJ or
H5T_STD_REF_DSETREG:
H5T_STD_REF_OBJ,
the reference object type is H5R_OBJECT.
H5T_STD_REF_DSETREG,
the reference object type is
H5R_DATASET_REGION.
When the function completes successfully, it returns one of
the following valid object type values
(defined in H5Gpublic.h):
H5G_LINK | Object is a symbolic link. | |
H5G_GROUP | Object is a group. | |
H5G_DATASET | Object is a dataset. | |
H5G_TYPE | Object is a named datatype. |
hid_t loc_id |
IN: The dataset containing the reference object or the group containing that dataset. |
H5R_type_t ref_type |
IN: Type of reference to query. |
void *ref |
IN: Reference to query. |
H5G_UNKNOWN.
H5Rget_obj_type macro description.
| Release | C |
| 1.6.0 | Function introduced in this release. |
| 1.8.0 | Function H5Rget_obj_type renamed to
H5Rget_obj_type1 and deprecated in this release.
|
H5Rget_obj_type2(
hid_t loc_id,
H5R_type_t ref_type,
void *ref,
H5O_type_t *obj_type
)
ref,
H5Rget_obj_type2
retrieves the type of the referenced object in obj_type.
A reference type is the type of reference, either an object reference or a dataset region reference. An object reference points to an HDF5 object while a dataset region reference points to a defined region within a dataset.
The referenced object is the object the reference points to. The referenced object type, or the type of the referenced object, is the type of the object that the reference points to.
The location identifier, loc_id, is the identifier
for either the dataset containing the object reference or
the group containing that dataset.
Valid reference types, to pass in as ref_type,
include the following:
H5R_OBJECT | Object reference | |
H5R_DATASET_REGION | Dataset region reference |
If the application does not already know the object reference type, that can be determined with three preliminary calls:
H5Dget_type on the dataset
containing the reference to get a datatype identifier
for the dataset’s datatype.
H5Tget_class returns a datatype class.
H5T_REFERENCE,
H5Tequal can then be used to determine whether
the reference’s datatype is
H5T_STD_REF_OBJ or
H5T_STD_REF_DSETREG:
H5T_STD_REF_OBJ,
the reference object type is H5R_OBJECT.
H5T_STD_REF_DSETREG,
the reference object type is
H5R_DATASET_REGION.
When the function completes successfully, it returns one of
the following valid object type values
(defined in H5Opublic.h):
H5O_TYPE_GROUP | Object is a group. | |
H5O_TYPE_DATASET | Object is a dataset. | |
H5O_TYPE_NAMED_DATATYPE | Object is a named datatype. |
hid_t loc_id |
IN: The dataset containing the reference object or the group containing that dataset. |
H5R_type_t ref_type |
IN: Type of reference to query. |
void *ref |
IN: Reference to query. |
H5O_type_t *obj_type |
OUT: Type of referenced object. |
H5Rget_obj_type macro description.
| Release | C |
| 1.8.0 | Function introduced in this release. |
ssize_t H5Rget_name(hid_t loc_id,
H5R_type_t ref_type,
void *ref,
char *name,
size_t size)
H5Rget_name retrieves a name for the object identified
by ref.
loc_id is used to identify the file containing the
reference. It can be the file identifier for the file containing
the reference or an identifier for any object in that file.
H5R_type_t is the reference type of ref.
Valid values include the following:
H5R_OBJECT | Object reference | |
H5R_DATASET_REGION | Dataset region reference |
ref is the reference for which the target object’s
name is sought.
If ref is an object reference, name
will be returned with a name for the referenced object.
If ref is a dataset region reference,
name will contain a name for the object containing
the referenced region.
Up to size characters of the name are returned in
name; additional characters, if any, are not returned
to the user application.
If the length of the name, which determines the required
value of size, is unknown, a preliminary
H5Rget_name call can be made.
The return value of this call will be the size of the
object name.
That value can then be assigned to size
for a second H5Rget_name call,
which will retrieve the actual name.
If there is no name associated with the object identifier
or if the name is NULL, H5Rget_name
returns the size of the name buffer (the size does not include
the NULL terminator).
Note that an object in an HDF5 file may have multiple paths if there are multiple links pointing to it. This function may return any one of these paths.
hid_t loc_id |
IN: Identifier for the file containing the reference or for any object in that file. |
H5R_type_t ref_type |
IN: Type of reference. |
void *ref |
IN: An object or dataset region reference. |
char *name |
OUT: A buffer to place the name of the referenced object or dataset region. If NULL, then this call will return the size in bytes of the name. |
size_t size |
IN: The size of the name buffer. When the
size is passed in, the NULL terminator needs to be included. |
0
(zero) if no name is associated with the identifier.
Otherwise returns a negative value.
To get name of an object reference: h5rget_name_object_f
Signature:
SUBROUTINE h5rget_name_object_f(loc_id, ref, name, hdferr, size)
INTEGER(HID_T) , INTENT(IN) :: loc_id
TYPE(hobj_ref_t_f), INTENT(IN) :: ref
CHARACTER(LEN=*) , INTENT(OUT) :: name
INTEGER , INTENT(OUT) :: hdferr
INTEGER(SIZE_T) , INTENT(OUT), OPTIONAL :: size
Inputs:
loc_id - Identifier for the file containing the reference or
for any object in that file.
ref - Object reference
Outputs:
name - A name associated with the referenced object or dataset region.
hdferr - Error code
0 on success and -1 on failure
Optional parameters:
size - The size of the name buffer,
returning 0 (zero) if no name is associated with the identifier
To get name of a region reference: h5rget_name_region_f
Signature:
SUBROUTINE h5rget_name_region_f(loc_id, ref, name, hdferr, size)
INTEGER(HID_T) , INTENT(IN) :: loc_id
TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref
CHARACTER(LEN=*) , INTENT(OUT) :: name
INTEGER(SIZE_T) , INTENT(OUT), OPTIONAL :: size
INTEGER , INTENT(OUT) :: hdferr
Inputs:
loc_id - Identifier for the file containing the reference or
for any object in that file.
ref - Object reference
Outputs:
name - A name associated with the referenced object or dataset region.
hdferr - Error code
0 on success and -1 on failure
Optional parameters:
size - The size of the name buffer,
returning 0 (zero) if no name is associated with the identifier
SUBROUTINE h5rget_name_f(loc_id, ref_type, ref, name, hdferr, size) INTEGER(HID_T) , INTENT(IN) :: loc_id INTEGER , INTENT(IN) :: ref_type TYPE(C_PTR) , INTENT(IN) :: ref CHARACTER(LEN=*), INTENT(OUT) :: name INTEGER , INTENT(OUT) :: hdferr INTEGER(SIZE_T) , INTENT(OUT), OPTIONAL :: size
Inputs:
loc_id - Identifier for the file containing the reference or
for any object in that file.
ref_type - Type of reference.
ref - An object or dataset region reference.
Outputs:
name - A name associated with the referenced object or dataset ptr.
hdferr - Error code
0 on success and -1 on failure
Optional parameters:
size - The size of the name buffer.
| Release | Change |
| 1.8.8 | Fortran updated to Fortran2003. |
| 1.8.0 | C function introduced in this release. |
H5Rget_region(
hid_t loc_id,
H5R_type_t ref_type,
void *ref
)
H5Rget_region creates a copy of the dataspace
of the dataset pointed to by a region reference, ref,
and defines a selection matching the selection pointed to by
ref within the dataspace copy.
loc_id is used to identify the file containing the
referenced region; it can be a file identifier or
an identifier for any object in the file.
The parameter ref_type specifies the reference type of
ref and must contain the following value:
H5R_DATASET_REGION (1)
Use H5Sclose to release the dataspace identifier
returned by this function when the identifier is no longer
needed.
hid_t loc_id |
IN: File identifier or identifier for any object in the file containing the referenced region |
H5R_type_t ref_type |
IN: Reference type of ref,
which must be H5R_DATASET_REGION |
void *ref |
IN: Region reference to open |
SUBROUTINE h5rget_region_f(obj_id, ref, space_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier
TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref ! Dataset region reference
INTEGER(HID_T), INTENT(OUT) :: space_id ! Space identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5rget_region_f
|
The HDF Group Help Desk:
Describes HDF5 Release 1.8.20, November 2017. |
Copyright by
The HDF Group
and the Board of Trustees of the University of Illinois |