H5R: Reference Interface

Reference API Functions

The C Interfaces:

H5Rcreate H5Rdereference	H5Rget_obj_type H5Rget_obj_type1  * H5Rget_obj_type2	H5Rget_region H5Rget_name
* Use of this function is deprecated in Release 1.8.0.

Alphabetical Listing

H5Rcreate H5Rdereference H5Rget_name

H5Rget_obj_type H5Rget_obj_type1  * H5Rget_obj_type2

H5Rget_region

The FORTRAN90 Interfaces:
In general, each FORTRAN90 subroutine performs exactly the same task as the corresponding C function.

h5rcreate_f h5rdereference_f

h5rget_region_f h5rget_object_type_f

Name: H5Rcreate

Signature:

herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id )

Purpose:

Creates a reference.

Description:

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 region to be pointed to for a dataset region reference. This parameter is unused with object references.

Parameters:

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 for dataset region references.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5rcreate_f

To create an object reference

SUBROUTINE h5rcreate_f(loc_id, name, ref, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: loc_id     ! Location identifier 
  CHARACTER(LEN=*), INTENT(IN) :: name     ! Name of the object at location 
                                           ! specified by loc_id identifier 
  TYPE(hobj_ref_t_f), INTENT(OUT) :: ref   ! Object reference 
  INTEGER, INTENT(OUT) :: hdferr           ! Error code 

END SUBROUTINE h5rcreate_f
	

To create a region reference

SUBROUTINE h5rcreate_f(loc_id, name, space_id, ref, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: loc_id        ! Location identifier 
  CHARACTER(LEN=*), INTENT(IN) :: name        ! Name of the dataset at location 
                                              ! specified by loc_id identifier 
  INTEGER(HID_T), INTENT(IN) :: space_id      ! Dataset's dataspace identifier 
  TYPE(hdset_reg_ref_t_f), INTENT(OUT) :: ref ! Dataset region reference 
  INTEGER, INTENT(OUT) :: hdferr              ! Error code 

END SUBROUTINE h5rcreate_f
	

Name: H5Rdereference

Signature:

hid_t H5Rdereference(hid_t obj_id, H5R_type_t ref_type, void *ref )

Purpose:

Opens the HDF5 object referenced.

Description:

Given a reference, 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)

Parameters:

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.

Returns:

Returns identifier of referenced object if successful; otherwise returns a negative value.

Fortran90 Interface: h5rdereference_f

To dereference an object

SUBROUTINE h5rdereference_f(obj_id, ref, ref_obj_id, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: obj_id      ! Valid identifier 
                                            ! in file
  TYPE(hobj_ref_t_f), INTENT(IN) :: ref     ! Object reference 
  INTEGER(HID_T), INTENT(OUT) :: ref_obj_id ! Identifier of 
                                            ! referenced object 
  INTEGER, INTENT(OUT) :: hdferr            ! Error code 

END SUBROUTINE h5rdereference_f
	

To dereference a region

SUBROUTINE h5rdereference_f(obj_id, ref, ref_obj_id, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: obj_id       ! Valid identifier 
                                             ! in file 
  TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref ! Object reference 
  INTEGER(HID_T), INTENT(OUT) :: ref_obj_id  ! Identifier of 
                                             ! referenced object 
  INTEGER, INTENT(OUT) :: hdferr             ! Error code 
          
END SUBROUTINE h5rdereference_f
	

Name: H5Rget_obj_type

Signature:

H5G_obj_t H5Rget_obj_type( hid_t loc_id, H5R_type_t ref_type, void *ref )

herr_t H5Rget_obj_type( hid_t loc_id, H5R_type_t ref_type, void *ref, H5O_type_t *obj_type )

Purpose:

Retrieves the type of object that an object reference points to.

Description:

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

Fortran90 Interface: h5gcreate_f

Holding...

History:

Release	C
1.8.0	The function H5Rget_obj_type renamed to H5Rget_obj_type1 and deprecated in this release. The macro H5Rget_obj_type and the function H5Rget_obj_type2 introduced in this release.

Name: H5Rget_obj_type1

Signature:

H5G_obj_t H5Rget_obj_type1( hid_t loc_id, H5R_type_t ref_type, void *ref )

Purpose:

Retrieves the type of object that an object reference points to.

Notice:

This function has been renamed from H5Rget_obj_type and is deprecated in favor of the macro H5Rget_obj_type or the function H5Rget_obj_type2.

Description:

Given an object reference, ref, H5Rget_obj_type1 returns the type of the referenced object.

An object reference is a reference that points to an object. The referenced object is the object 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 returns a datatype identifier for the dataset’s datatype.
• Using that datatype identifier, H5Tget_class returns a datatype class.
• If the datatype class is H5T_REFERENCE, H5Tequal can then be used to determine whether the reference’s datatype is H5T_STD_REF_OBJ or H5T_STD_REF_DSETREG:
  • If the datatype is H5T_STD_REF_OBJ, the reference object type is H5R_OBJECT.
  • If the datatype is 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.

Parameters:

hid_t loc_id	IN: The dataset containing the reference object or the group containing that the dataset.
H5R_type_t ref_type	IN: Type of reference to query.
void *ref	IN: Reference to query.

Returns:

Returns a valid object type if successful; otherwise returns H5G_UNKNOWN.

Fortran90 Interface: h5rget_object_type_f

SUBROUTINE h5rget_object_type_f(dset_id, ref, obj_type, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: dset_id   ! Dataset identifier 
  TYPE(hobj_ref_t_f), INTENT(IN) :: ref   ! Object reference 
  INTEGER, INTENT(OUT) :: obj_type        ! Object type  
                                          !     H5G_UNKNOWN_F (-1)
                                          !     H5G_LINK_F      0
                                          !     H5G_GROUP_F     1
                                          !     H5G_DATASET_F   2
                                          !     H5G_TYPE_F      3
  INTEGER, INTENT(OUT) :: hdferr          ! Error code 

END SUBROUTINE h5rget_object_type_f
	

History:

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.

Name: H5Rget_obj_type2

Signature:

herr_t H5Rget_obj_type2( hid_t loc_id, H5R_type_t ref_type, void *ref, H5O_type_t *obj_type )

Purpose:

Retrieves the type of object that an object reference points to.

Description:

Given an object reference, ref, H5Rget_obj_type2 retrieves the type of the referenced object in obj_type.

An object reference is a reference that points to an object. The referenced object is the object 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 returns a datatype identifier for the dataset’s datatype.
• Using that datatype identifier, H5Tget_class returns a datatype class.
• If the datatype class is H5T_REFERENCE, H5Tequal can then be used to determine whether the reference’s datatype is H5T_STD_REF_OBJ or H5T_STD_REF_DSETREG:
  • If the datatype is H5T_STD_REF_OBJ, the reference object type is H5R_OBJECT.
  • If the datatype is 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.

Parameters:

hid_t loc_id	IN: The dataset containing the reference object or the group containing that the 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.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface:

(None)

History:

Release	C
1.8.0	Function introduced in this release.

Name: H5Rget_name

Signature:

ssize_t H5Rget_name( hid_t loc_id, H5R_type_t ref_type, void *ref, char *name, size_t size )

Purpose:

Retrieves a name of a referenced object.

Description:

H5Rget_name retrieves a name for the object identified by ref.

loc_id is the identifier for the dataset containing the reference or for the group containing that dataset.

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 the name of the referenced object. If ref is a dataset region reference, name will contain the name of 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 0 (zero).

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.

Parameters:

hid_t loc_id	IN: Identifier for the dataset containing the reference or for the group that dataset is in.
H5R_type_t ref_type	IN: Type of reference.
void *ref	IN: An object or dataset region reference.
char *name	OUT: A name associated with the referenced object or dataset region.
size_t size	IN: The size of the name buffer.

Returns:

Returns the length of the name if successful, returning 0 (zero) if no name is associated with the identifier. Otherwise returns a negative value.

Fortran90 Interface:

None.

History:

Release	C
1.8.0	Function introduced in this release.

Name: H5Rget_region

Signature:

hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, void *ref )

Purpose:

Retrieves a dataspace with the specified region selected.

Description:

Given a reference to an object ref, H5Rget_region creates a copy of the dataspace of the dataset pointed to and defines a selection in the copy which is the region pointed to.

The parameter ref_type specifies the reference type of ref. ref_type may contain the following value:

• H5R_DATASET_REGION (1)

Parameters:

hid_t dataset	IN: Dataset containing reference object.
H5R_type_t ref_type	IN: The reference type of ref.
void *ref	IN: Reference to open.

Returns:

Returns a valid identifier if successful; otherwise returns a negative value.

Fortran90 Interface: h5rget_region_f

SUBROUTINE h5rget_region_f(dset_id, ref, space_id, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: dset_id       ! Dataset 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
 
END SUBROUTINE h5rget_region_f
	

THG Help Desk:
Describes HDF5 Release 1.8.0, January 2008.