H5R: Reference Interface

Reference API Functions

The C Interfaces:

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 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 dataset, H5R_type_t ref_type, void *ref )

Purpose:

Opens the HDF5 object referenced.

Description:

Given a reference to some object, H5Rdereference opens that object and returns an 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 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 valid identifier if successful; otherwise returns a negative value.

Fortran90 Interface: h5rdereference_f

To dereference an object

SUBROUTINE h5rdereference_f(dset_id, ref, obj_id, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: dset_id   ! Dataset identifier 
  TYPE(hobj_ref_t_f), INTENT(IN) :: ref   ! Object reference 
  INTEGER(HID_T), INTENT(OUT) :: obj_id   ! Object identifier 
  INTEGER, INTENT(OUT) :: hdferr          ! Error code 

END SUBROUTINE h5rdereference_f
	

To dereference a region

SUBROUTINE h5rdereference_f(dset_id, ref, obj_id, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: dset_id        ! Dataset identifier 
  TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref   ! Object reference 
  INTEGER(HID_T), INTENT(OUT) :: obj_id        ! Object identifier 
  INTEGER, INTENT(OUT) :: hdferr               ! Error code 
          
END SUBROUTINE h5rdereference_f
	

Name: H5Rget_obj_type

Signature:

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

Purpose:

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

Description:

Given type of object reference, ref_type, and a reference to an object, ref, H5Rget_obj_type returns the type of the referenced object.

Valid object reference types, to pass in as ref_type, include the following:

	H5R_OBJECT	Reference is an object reference.
	H5R_DATASET_REGION	Reference is a dataset region reference.

Valid object type return values include the following:

	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 id,

IN: The dataset containing the reference object or the location identifier of the object that the dataset is located within.

H5R_type_t ref_type

IN: Type of reference to query.

void *ref

IN: Reference to query.

Returns:

Returns an object type as defined in H5Gpublic.h 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
	

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.

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