hdf5/doc/html/RM_H5R.html
Frank Baker 9fb77d56b8 [svn-r8221]
Purpose:
    Clean up RM formatting.
    Modify RM HTML code to facilitate automated generation of PDF version.
    Minor edits.

Description:
    Reworked format of "Parameters" sections.
    Added HTML tags (and pseudo-HTML tags) used by HTMLdoc to
        generate PDF files.
    Fixed the "Copyright" link on RM_H5Front.html.
    Other minor copy edits.

Platforms tested:
    IE 5
2004-02-24 17:10:12 -05:00

533 lines
18 KiB
HTML

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