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

Alphabetical Listing
  • H5Rcreate
  • H5Rdereference
  •       
  • H5Rget_obj_type
  •       
  • H5Rget_region
  • The FORTRAN90 Interfaces:
    In general, each FORTRAN90 subroutine performs exactly the same task as the corresponding C function. The links below go to the C function descriptions, which serve as general descriptions for both. A button, under Non-C API(s) at the end of the C function description, opens an external browser window displaying the FORTRAN90-specific information. You will probably want to adjust the size and location of this external window so that both browser windows are visible and to facilitate moving easily between them.


    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.
    Non-C API(s):

    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:

    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.
    Non-C API(s):

    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:

    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.
    Non-C API(s):

    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.
    Non-C API(s):

    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  

    HDF Help Desk
    Describes HDF5 Release 1.6.0, July 2003
    Last modified: 25 June 2003