HDF5 documents and links Introduction to HDF5 HDF5 User Guide	And in this document, the HDF5 Reference Manual H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes Collective Calls in Parallel
(PDF of complete manual formatted as print volume)

H5R: Reference Interface

Reference API Functions

The Reference interface allows the user to create references to specific objects and data regions in an HDF5 file.

The C Interfaces:

H5Rcreate
H5Rdereference

H5Rget_region
H5Rget_obj_type

Alphabetical Listing

H5Rcreate
H5Rdereference

H5Rget_obj_type
H5Rget_object_type *

H5Rget_region

* Functions labelled with an asterisk (*) are provided only for backwards compatibility with HDF5 Releases 1.4.x. See further notes in the description of each function.

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 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.

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 only for dataset region references; pass as -1 if reference is an object reference, i.e., of type H5R_OBJECT.

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 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 )

Purpose:

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

Description:

Given an object reference, ref, H5Rget_obj_type 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:

Call H5Dget_type on the dataset containing the reference to get 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 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  
                                          ! 0 on success and -1 on failure

END SUBROUTINE h5rget_object_type_f

History:

Release	C
1.6.0	Function introduced in this release.

Name: H5Rget_object_type
Signature:: int H5Rget_object_type(hid_t id, void *ref )
Purpose:: Retrieves the type of object that an object reference points to.
Description:: [NOTE: This function is provided only to enable backward compatibility with HDF5 Releases 1.4.x. This function is enabled only if the HDF5 library is configured with the flag H5_WANT_H5_V1_4_COMPAT and is not enabled in the binaries distributed by NCSA. This function has been replaced in Release 1.6 by the function H5Rget_obj_type and will eventually be deleted from the HDF5 distribution.]

Given a reference to an object ref, H5Rget_object_type returns the type of the object pointed to.
Parameters:

hid_t id,
IN: The dataset containing the reference object or the location identifier of the object that the dataset is located within.
void *ref
IN: Reference to query.
Returns:: Returns an object type as defined in H5Gpublic.h; otherwise returns H5G_UNKNOWN.
History:

Release C

1.6.0 Function introduced in this release.

Last modified: 30 April 2009

Name: H5Rget_region

Signature:

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

Purpose:

Sets up a dataspace and selection as specified by a region reference.

Description:

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)

Parameters:

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

Returns:

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

Fortran90 Interface: h5rget_region_f

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
 
END SUBROUTINE h5rget_region_f

HDF5 documents and links Introduction to HDF5 HDF5 User Guide	And in this document, the HDF5 Reference Manual H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes Collective Calls in Parallel
(PDF of complete manual formatted as print volume)

The HDF Group Help Desk:

Describes HDF5 Release 1.6.10, November 2009

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`.

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.

	`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.