HDF5 Reference Manual H5 H5A H5D H5E H5F H5G H5I H5P H5R H5RA H5S H5T H5Z Tools

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

- H5Rcreate

- H5Rdereference

- H5Rget_region (NYI)

NYI = Not yet implemented.

Note: The only type of reference implemented in this release is an object reference pointing to a dataset.

Name: H5Rcreate
Signature:
  herr_t `H5Rcreate`(href_t *`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 parameters `loc_id` and `name` are used to locate the object.

  The parameter `space_id` identifies the region to be pointed to (for dataset region references).

  Note: Only object references of type `H5T_STD_REF_OBJ` pointing to entire datasets are implemented at this time.

Parameters:

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

Name: H5Rdereference
Signature:
  hid_t `H5Rdereference`(hid_t `dataset`, H5R_type_t `ref_type`, href_t *`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`. See Reference Types in References (H5R) for a list of valid reference types.

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.

Name: H5Rget_region (Not yet implemented.)
Signature:
  hid_t `H5Rget_region`(hid_t `dataset`, H5R_type_t `ref_type`, href_t *`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`. See Reference Types in References (H5R) for a list of valid reference types.

Parameters:

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

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

HDF5 Reference Manual H5 H5A H5D H5E H5F H5G H5I H5P H5R H5RA H5S H5T H5Z Tools

HDF Help Desk
Last modified: 27 October 1998