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

# 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_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

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