<html>
<head><title>
HDF5/H5R API Specification
</title>

<!-- #BeginLibraryItem "/ed_libs/styles_RM.lbi" -->

<!--
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  * Copyright by the Board of Trustees of the University of Illinois.         *
  * All rights reserved.                                                      *
  *                                                                           *
  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
  * terms governing use, modification, and redistribution, is contained in    *
  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
  * of the source code distribution tree; Copyright.html can be found at the  *
  * root level of an installed copy of the electronic HDF5 document set and   *
  * is linked from the top-level documents page.  It can also be found at     *
  * http://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html.  If you do not have     *
  * access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 -->

<link href="ed_styles/RMelect.css" rel="stylesheet" type="text/css">
<!-- #EndLibraryItem --></head>

<body bgcolor="#FFFFFF">
<!-- HEADER RIGHT " " -->


<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="index.html">HDF5 documents and links</a>&nbsp;<br>
<a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a>&nbsp;<br>
<!--
<a href="Glossary.html">Glossary</a><br>
-->
</td>
<td valign=top align=right>
And in this document, the 
<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;&nbsp;
<br>
<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
<a href="RM_H5E.html">H5E</a>&nbsp;&nbsp;
<a href="RM_H5F.html">H5F</a>&nbsp;&nbsp;
<a href="RM_H5G.html">H5G</a>&nbsp;&nbsp;
<a href="RM_H5I.html">H5I</a>&nbsp;&nbsp;
<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
<br>
<a href="RM_H5R.html">H5R</a>&nbsp;&nbsp;
<a href="RM_H5S.html">H5S</a>&nbsp;&nbsp;
<a href="RM_H5T.html">H5T</a>&nbsp;&nbsp;
<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
<a href="Tools.html">Tools</a>&nbsp;&nbsp;
<a href="PredefDTypes.html">Datatypes</a>&nbsp;&nbsp;
</td></tr>
</table>
</center>
<hr><!-- #EndLibraryItem --><center>
<h1>H5R: Reference Interface</h1>
</center>

<h2>Reference API Functions</h2>

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

<p>
<strong>The C Interfaces:</strong>

<table border=0 width=80%>
<tr><td valign=top width=40%>
<ul>
    <li><a href="#Reference-Create">H5Rcreate</a>
    <li><a href="#Reference-Dereference">H5Rdereference</a>
</ul>
</td><td valign=top width=40%>
<ul>
    <li><a href="#Reference-GetRegion">H5Rget_region</a>
    <li><a href="#Reference-GetObjType">H5Rget_obj_type</a>
</ul>
</td><td valign=top width=20%>
<ul>
    &nbsp;
</ul>
</td></tr>
</table>

<p>

<i>Alphabetical Listing</i>

<table border="0">
  <tr>
    <td valign="top">
	<ul>
      <li><a href="#Reference-Create">H5Rcreate</a>
      <li><a href="#Reference-Dereference">H5Rdereference</a>
	</ul>      
    </td>
    
    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
    
    <td valign="top">
	<ul>
      <li><a href="#Reference-GetObjType">H5Rget_obj_type</a>
	</ul>
    </td>
    
    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
    
    <td valign="top">
	<ul>
      <li><a href="#Reference-GetRegion">H5Rget_region</a>
	</ul>
    </td>
  </tr>
</table>

<br>
<strong>The FORTRAN90 Interfaces:</strong>
<br>
In general, each FORTRAN90 subroutine performs exactly the same task 
as the corresponding C function.  
<br>

<table border=0 width=80%>
<tr><td valign=top width=40%>
<ul>
    <li><a href="#Reference-Create">h5rcreate_f</a>
    <li><a href="#Reference-Dereference">h5rdereference_f</a>
</ul>
</td><td valign=top width=40%>
<ul>
    <li><a href="#Reference-GetRegion">h5rget_region_f</a>
    <li><a href="#Reference-GetObjType">h5rget_object_type_f</a>
</ul>
</td><td valign=top width=20%>
<ul>

</ul>
</td></tr>
</table>


<p>

<!-- NEW PAGE -->
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Rcreate" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Reference-Create">H5Rcreate</a>
<dt><strong>Signature:</strong>
    <dd><em>herr_t</em> <code>H5Rcreate</code>(<em>void *</em><code>ref</code>,
        <em>hid_t</em> <code>loc_id</code>,
        <em>const char *</em><code>name</code>,
        <em>H5R_type_t</em> <code>ref_type</code>,
        <em>hid_t</em> <code>space_id</code>
    )
<dt><strong>Purpose:</strong>
    <dd>Creates a reference.
<dt><strong>Description:</strong>
    <dd><code>H5Rcreate</code> creates the reference, <code>ref</code>,
        of the type specified in <code>ref_type</code>, pointing to 
        the object <code>name</code> located at <code>loc_id</code>.
        <p>
        The HDF5 library maps the <em>void</em> type specified above 
        for <code>ref</code> to the type specified in <code>ref_type</code>,
        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.
        <dir>
        <table border=0>
        <tr><td><em>hdset_reg_ref_t</em>&nbsp;&nbsp;</td>
            <td><code>H5R_DATASET_REGION</code>&nbsp;&nbsp;</td>
            <td>Dataset region reference</td></tr>
        <tr><td><em>hobj_ref_t</em></td>
            <td><code>H5R_OBJECT</code></td>
            <td>Object reference</td></tr>
        </table>
        </dir>
        <p>
        The parameters <code>loc_id</code> and <code>name</code> are 
        used to locate the object.
        <p>
        The parameter <code>space_id</code> identifies the region 
        to be pointed to for a dataset region reference.
        This parameter is unused with object references.  
<dt><strong>Parameters:</strong>
    <ul><table>
        <tr>
		    <td valign="top"><em>void *</em><code>ref</code></td>
            <td valign="top">OUT: Reference created by the function call.</td></tr>
        <tr>
		    <td valign="top"><em>hid_t</em> <code>loc_id</code></td>
            <td valign="top">IN: Location identifier used to locate the object being 
                    pointed to.</td></tr>
        <tr>
		    <td valign="top"><em>const char *</em><code>name</code></td>
            <td valign="top">IN: Name of object at location <code>loc_id</code>.</td></tr>
        <tr>
		    <td valign="top"><em>H5R_type_t</em>&nbsp;<code>ref_type&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
            <td valign="top">IN: Type of reference.</td></tr>
        <tr>
		    <td valign="top"><em>hid_t</em> <code>space_id</code></td>
            <td valign="top">IN: Dataspace identifier with selection. 
                    Used for dataset region references.</td></tr>
    </table></ul>
<dt><strong>Returns:</strong>
    <dd>Returns a non-negative value if successful;
        otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5rcreate_f

    <dd><p><strong>To create an object reference</strong> 
    
	<pre>
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
	</pre></dt>

<!-- NEW PAGE -->	
<dt><dd><strong>To create a region reference</strong>	
	
	<pre>
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
	</pre>		
		
		<!--<dt><strong>Non-C API(s):</strong>
    	<dd>
        
        <img src="Graphics/Java.gif"> 
        <img src="Graphics/C++.gif">
        -->
</dl>

<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Rdereference" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Reference-Dereference">H5Rdereference</a>
<dt><strong>Signature:</strong>
    <dd><em>hid_t</em> <code>H5Rdereference</code>(<em>hid_t</em> <code>dataset</code>,
        <em>H5R_type_t</em> <code>ref_type</code>,
        <em>void *</em><code>ref</code>
    )
<dt><strong>Purpose:</strong>
    <dd>Opens the HDF5 object referenced.
<dt><strong>Description:</strong>
    <dd>Given a reference to some object, <code>H5Rdereference</code>
        opens that object and returns an identifier.
        <p>
        The parameter <code>ref_type</code> specifies the reference type
        of <code>ref</code>. 
        <code>ref_type</code> may contain either of the following values:
        <ul>
        <li><code>H5R_OBJECT</code>  (<code>0</code>)
        <li><code>H5R_DATASET_REGION</code>  (<code>1</code>)
        </ul>
<dt><strong>Parameters:</strong>
    <ul><table>
        <tr>
		    <td valign="top"><em>hid_t</em> <code>dataset</code></td>
            <td valign="top">IN: Dataset containing reference object.</td></tr>
        <tr>
		    <td valign="top"><em>H5R_type_t</em>&nbsp;<code>ref_type&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
            <td valign="top">IN: The reference type of <code>ref</code>.</td></tr>
        <tr>
		    <td valign="top"><em>void *</em><code>ref</code></td>
            <td valign="top">IN: Reference to open.</td></tr>
    </table></ul>
<dt><strong>Returns:</strong>
    <dd>Returns valid identifier if successful;
        otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5rdereference_f

    <p><strong>To dereference an object</strong> 
    <dd>
	<pre>
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
	</pre>
</dt>
	
<dt><strong>To dereference a region</strong>	
	<dd>
	<pre>
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
	</pre>		
		
		<!--<dt><strong>Non-C API(s):</strong>
    	<dd>
        
        <img src="Graphics/Java.gif"> 
        <img src="Graphics/C++.gif">
        -->
</dl>

<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Rget_obj_type" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Reference-GetObjType">H5Rget_obj_type</a>
<dt><strong>Signature:</strong>
    <dd><em>H5G_obj_t</em> <code>H5Rget_obj_type</code>(<em>hid_t</em> <code>id</code>,
    <em>H5R_type_t</em> <code>ref_type</code>,
    <em>void *</em><code>ref</code>
    )
<dt><strong>Purpose:</strong>
    <dd>Retrieves the type of object that an object reference points to.
<dt><strong>Description:</strong>
    <dd>Given type of object reference, <code>ref_type</code>, 
        and a reference to an object, <code>ref</code>, 
        <code>H5Rget_obj_type</code> 
        returns the type of the referenced object.
	<p>
	Valid object reference types, to pass in as <code>ref_type</code>, 
	include the following:
	<table border="0">
	<tr align=left valign=top><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
	<code>H5R_OBJECT</code></td><td>
	Reference is an object reference.
	</td></tr>
	<tr align=left valign=top><td>&nbsp;</td><td>
	<code>H5R_DATASET_REGION&nbsp;&nbsp;</code></td><td>
	Reference is a dataset region reference.
	</td></tr>
	</table>
	<p>
	Valid object type return values include the following:
	<table border="0">
	<tr align=left valign=top><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
	<code>H5G_LINK</code></td><td>
	Object is a symbolic link.
	</td></tr>
	<tr align=left valign=top><td>&nbsp;</td><td>
	<code>H5G_GROUP</code></td><td>
	Object is a group.
	</td></tr>
	<tr align=left valign=top><td>&nbsp;</td><td>
	<code>H5G_DATASET&nbsp;&nbsp;</code></td><td>
	Object is a dataset.
	</td></tr>
	<tr align=left valign=top><td>&nbsp;</td><td>
	<code>H5G_TYPE</code></td><td>
	Object is a named datatype.
	</td></tr>
	</table>
<dt><strong>Parameters:</strong>
    <ul><table>
        <tr>
		    <td valign="top"><em>hid_t</em> <code>id</code>,</td>
            <td valign="top">IN: The dataset containing the reference object or 
                the location identifier of the object that the 
                dataset is located within.</td></tr>
        <tr>
		    <td valign="top"><em>H5R_type_t</em>&nbsp;<code>ref_type&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
            <td valign="top">IN: Type of reference to query.</td></tr>
        <tr>
		    <td valign="top"><em>void *</em><code>ref</code></td>
            <td valign="top">IN: Reference to query.</td></tr>
    </table></ul>
<dt><strong>Returns:</strong>
    <dd>Returns an object type as defined in <code>H5Gpublic.h</code> if successful;
        otherwise returns <code>H5G_UNKNOWN</code>.
<dt><strong>Fortran90 Interface:</strong> h5rget_object_type_f
    <dd>
	<pre>
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
	</pre>		
		
		<!--<dt><strong>Non-C API(s):</strong>
    	<dd>
        
        <img src="Graphics/Java.gif"> 
        <img src="Graphics/C++.gif">
        -->
</dl>


<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Rget_region" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Reference-GetRegion">H5Rget_region</a>
<dt><strong>Signature:</strong>
    <dd><em>hid_t</em> <code>H5Rget_region</code>(<em>hid_t</em> <code>dataset</code>,
    <em>H5R_type_t</em> <code>ref_type</code>,
    <em>void *</em><code>ref</code>
    )
<dt><strong>Purpose:</strong>
    <dd>Retrieves a dataspace with the specified region selected.
<dt><strong>Description:</strong>
    <dd>Given a reference to an object <code>ref</code>, 
        <code>H5Rget_region</code> creates a copy of the dataspace 
        of the dataset pointed to and defines a selection in the copy 
        which is the region pointed to.
        <p>
        The parameter <code>ref_type</code> specifies the reference type
        of <code>ref</code>. 
        <code>ref_type</code> may contain the following value:
        <ul>
        <li><code>H5R_DATASET_REGION</code>  (<code>1</code>)
        </ul>
<dt><strong>Parameters:</strong>
    <ul><table>
        <tr>
		    <td valign="top"><em>hid_t</em> <code>dataset</code></td>
            <td valign="top">IN: Dataset containing reference object.</td></tr>
        <tr>
		    <td valign="top"><em>H5R_type_t</em>&nbsp;<code>ref_type&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
            <td valign="top">IN: The reference type of <code>ref</code>.</td></tr>
        <tr>
		    <td valign="top"><em>void *</em><code>ref</code></td>
            <td valign="top">IN: Reference to open.</td></tr>
    </table></ul>
<dt><strong>Returns:</strong>
    <dd>Returns a valid identifier if successful;
        otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5rget_region_f
    <dd>
	<pre>
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
	</pre>		
		
		<!--<dt><strong>Non-C API(s):</strong>
    	<dd>
        
        <img src="Graphics/Java.gif"> 
        <img src="Graphics/C++.gif">
        -->
</dl>

<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="index.html">HDF5 documents and links</a>&nbsp;<br>
<a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a>&nbsp;<br>
<!--
<a href="Glossary.html">Glossary</a><br>
-->
</td>
<td valign=top align=right>
And in this document, the 
<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;&nbsp;
<br>
<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
<a href="RM_H5E.html">H5E</a>&nbsp;&nbsp;
<a href="RM_H5F.html">H5F</a>&nbsp;&nbsp;
<a href="RM_H5G.html">H5G</a>&nbsp;&nbsp;
<a href="RM_H5I.html">H5I</a>&nbsp;&nbsp;
<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
<br>
<a href="RM_H5R.html">H5R</a>&nbsp;&nbsp;
<a href="RM_H5S.html">H5S</a>&nbsp;&nbsp;
<a href="RM_H5T.html">H5T</a>&nbsp;&nbsp;
<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
<a href="Tools.html">Tools</a>&nbsp;&nbsp;
<a href="PredefDTypes.html">Datatypes</a>&nbsp;&nbsp;
</td></tr>
</table>
</center>
<hr><!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> 
<br>
Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0
</address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT">
<!--
document.writeln("Last modified: 24 February 2004");
-->
</SCRIPT> 

</body>
</html>