mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
4e23c80758
Version update
Description:
Removed 1.4 compatibility code in the library.
Platforms tested:
FreeBSD 4.8 (sleipnir)
h5committest
428 lines
15 KiB
HTML
428 lines
15 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">
|
|
|
|
|
|
<!-- #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> <br>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <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>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<br>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<a href="PredefDTypes.html">Datatypes</a>
|
|
</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>
|
|
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
|
|
* Functions labelled with an asterisk (*) are provided only for
|
|
backwards compatibility with HDF5 Releases 1.4.<i>x</i>.
|
|
See further notes in the description of each function.
|
|
<p>
|
|
|
|
<i>Alphabetical Listing</i>
|
|
|
|
<table border="0">
|
|
<tr>
|
|
<td valign="top">
|
|
<li><a href="#Reference-Create">H5Rcreate</a>
|
|
<li><a href="#Reference-Dereference">H5Rdereference</a>
|
|
</td>
|
|
|
|
<td> </td>
|
|
|
|
<td valign="top">
|
|
<li><a href="#Reference-GetObjType">H5Rget_obj_type</a>
|
|
</td>
|
|
|
|
<td> </td>
|
|
|
|
<td valign="top">
|
|
<li><a href="#Reference-GetRegion">H5Rget_region</a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
<strong>The FORTRAN90 Interfaces:</strong>
|
|
|
|
<br>
|
|
<font size=-1>
|
|
<i>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 <strong>Non-C API(s)</strong> 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.</i>
|
|
</font>
|
|
|
|
<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>
|
|
</ul>
|
|
</td><td valign=top width=20%>
|
|
<ul>
|
|
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
|
|
|
|
<p>
|
|
|
|
<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> </td>
|
|
<td><code>H5R_DATASET_REGION</code> </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>
|
|
<dl>
|
|
<dt><em>void *</em><code>ref</code>
|
|
<dd>OUT: Reference created by the function call.
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>IN: Location identifier used to locate the object being
|
|
pointed to.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>IN: Name of object at location <code>loc_id</code>.
|
|
<dt><em>H5R_type_t</em> <code>ref_type</code>
|
|
<dd>IN: Type of reference.
|
|
<dt><em>hid_t</em> <code>space_id</code>
|
|
<dd>IN: Dataspace identifier with selection.
|
|
Used for dataset region references.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5r_FORTRAN.html#h5rcreate_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
|
|
<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>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset</code>
|
|
<dd>IN: Dataset containing reference object.
|
|
<dt><em>H5R_type_t</em> <code>ref_type</code>
|
|
<dd>IN: The reference type of <code>ref</code>.
|
|
<dt><em>void *</em><code>ref</code>
|
|
<dd>IN: Reference to open.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns valid identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5r_FORTRAN.html#h5rdereference_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
|
|
<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>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset</code>,
|
|
<dd>IN: Dataset containing reference object.
|
|
<dt><em>H5R_type_t</em> <code>ref_type</code>,
|
|
<dd>IN: The reference type of <code>ref</code>.
|
|
<dt><em>void *</em><code>ref</code>
|
|
<dd>IN: Reference to open.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a valid identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5r_FORTRAN.html#h5rget_region_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
|
|
<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> </td><td>
|
|
<code>H5R_OBJECT</code></td><td>
|
|
Reference is an object reference.
|
|
</td></tr>
|
|
<tr align=left valign=top><td> </td><td>
|
|
<code>H5R_DATASET_REGION </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> </td><td>
|
|
<code>H5G_LINK</code></td><td>
|
|
Object is a symbolic link.
|
|
</td></tr>
|
|
<tr align=left valign=top><td> </td><td>
|
|
<code>H5G_GROUP</code></td><td>
|
|
Object is a group.
|
|
</td></tr>
|
|
<tr align=left valign=top><td> </td><td>
|
|
<code>H5G_DATASET </code></td><td>
|
|
Object is a dataset.
|
|
</td></tr>
|
|
<tr align=left valign=top><td> </td><td>
|
|
<code>H5G_TYPE</code></td><td>
|
|
Object is a named datatype.
|
|
</td></tr>
|
|
</table>
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>id</code>,
|
|
<dd>IN: The dataset containing the reference object or
|
|
the location identifier of the object that the
|
|
dataset is located within.
|
|
<dt><em>H5R_type_t</em> <code>ref_type</code>
|
|
<dd>IN: Type of reference to query.
|
|
<dt><em>void *</em><code>ref</code>
|
|
<dd>IN: Reference to query.
|
|
</dl>
|
|
<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>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5r_FORTRAN.html#h5rget_obj_type_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<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> <br>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <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>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<br>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<a href="PredefDTypes.html">Datatypes</a>
|
|
</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.6.0, July 2003
|
|
</address><!-- #EndLibraryItem -->
|
|
|
|
Last modified: 25 June 2003
|
|
|
|
</body>
|
|
</html>
|