summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorFrank Baker <fbaker@hdfgroup.org>1998-10-29 22:35:48 (GMT)
committerFrank Baker <fbaker@hdfgroup.org>1998-10-29 22:35:48 (GMT)
commited5859ad80ac770b7066c6305458d03e901683b2 (patch)
treee1dab642635b1b64f1b46c7d3878a9a9c5df657b /doc
parentcd3b1059977b1a80e320334c68630f88867341c8 (diff)
downloadhdf5-ed5859ad80ac770b7066c6305458d03e901683b2.zip
hdf5-ed5859ad80ac770b7066c6305458d03e901683b2.tar.gz
hdf5-ed5859ad80ac770b7066c6305458d03e901683b2.tar.bz2
[svn-r831] DDL.html
References.html New User Guide documents. RM_H5I.html Identifier Interface RM_H5R.html Reference Interface Created these two sections of Reference Manual.
Diffstat (limited to 'doc')
-rw-r--r--doc/html/DDL.html208
-rw-r--r--doc/html/RM_H5I.html136
-rw-r--r--doc/html/RM_H5R.html213
-rw-r--r--doc/html/References.html558
4 files changed, 1115 insertions, 0 deletions
diff --git a/doc/html/DDL.html b/doc/html/DDL.html
new file mode 100644
index 0000000..fcce13e
--- /dev/null
+++ b/doc/html/DDL.html
@@ -0,0 +1,208 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+<head>
+ <title>DDL for HDF5</title>
+</head>
+
+<body>
+<h1>DDL in BNF for HDF5</h1>
+
+
+<h2>1. Introduction</h2>
+
+This document contains the data description language (DDL) for an HDF5 file.
+The description is in Backus-Naur Form.
+
+<h2>2. Explanation of Symbols</h2>
+
+This section contains a brief explanation of the symbols used in the DDL.
+
+<PRE>
+ ::= defined as
+ &lt;tname&gt; a token with the name tname
+ &lt;a&gt; | &lt;b&gt; one of &lt;a&gt; or &lt;b&gt;
+ &lt;a&gt;<FONT SIZE=1.7>opt</FONT> zero or one occurrence of &lt;a&gt;
+ &lt;a&gt;* zero or more occurrence of &lt;a&gt;
+ &lt;a&gt;+ one or more occurrence of &lt;a&gt;
+ TBD To Be Decided
+</pre>
+
+<h2>3. The DDL</h2>
+
+<dir>
+<pre>
+&lt;file&gt; ::= HDF5 "&lt;file_name&gt;" { &lt;file_boot_block&gt;<FONT SIZE=1.7>opt</FONT> &lt;root_group&gt; }
+
+&lt;file_name&gt; ::= &lt;identifier&gt;
+
+&lt;file_boot_block&gt; ::= BOOT_BLOCK { &lt;boot_block_content&gt; }
+
+&lt;boot_block_content&gt; ::= TBD
+
+&lt;root_group&gt; ::= GROUP "/" { &lt;unamed_datatype&gt;* &lt;group_attribute&gt;* &lt;group_member&gt;* }
+
+&lt;unamed_datatype&gt ::= DATATYPE "&lt;unamed_type_name&gt;" { &lt;compound_type_def&gt;+ }
+
+&lt;unamed_type_name&gt; ::= the assigned name for unamed type is in the form of
+ #oid1:oid2, where oid1 and oid2 are the object ids of the type
+
+&lt;compound_type_def&gt; ::= &lt;named_scalar_type&gt; | &lt;named_array_type&gt;
+
+&lt;named_scalar_type&gt; ::= &lt;scalar_type&gt; &lt;field_name&gt; ;
+
+&lt;scalar_type&gt; ::= H5T_STD_I8BE | H5T_STD_I8LE | ...
+
+&lt;field_name&gt; ::= &lt;identifier&gt;
+
+&lt;named_array_type&gt; ::= &lt;scalar_type&gt; &lt;field_name&gt; &lt;dim_sizes&gt; ;
+
+&lt;dim_sizes&gt; ::= dimension sizes in the form of [dimsize1][dimzise2]...,
+ where dimsize1, dimsize2 are integers
+
+&lt;group_attribute&gt; ::= &lt;attribute&gt;
+
+&lt;attribute&gt; ::= ATTRIBUTE "&lt;attr_name&gt" { &lt;datatype&gt;
+ &lt;dataspace&gt;
+ &lt;data&gt;<FONT SIZE=1.7>opt</FONT> }
+// &lt;datatype&gt; and &lt;dataspace&gt; must appear before &lt;data&gt;.
+
+&lt;attr_name&gt; ::= &lt;identifier&gt;
+
+&lt;datatype&gt; ::= DATATYPE { &lt;named_type&gt; } |
+ DATATYPE { "&lt;scalar_type&gt;" } |
+ DATATYPE { &lt;compound_type_def&gt;+ }
+
+&lt;named_type&gt; ::= &lt;hardlink&gt;
+
+&lt;hardlink&gt; ::= HARDLINK { "&lt;abs_name&gt;" }
+
+&lt;abs_name&gt; ::= object absolute name
+
+&lt;dataspace&gt; ::= DATASPACE { "&lt;dataspace_name&gt;" } |
+ DATASPACE { ARRAY &lt;current_dims&gt; &lt;max_dims&gt; } |
+ DATASPACE { OTHER &lt;ds_definition&gt;+ }
+
+&lt;dataspace_name&gt; ::= &lt;identifier&gt;
+
+&lt;current_dims&gt; ::= a list of integers in the form of (<i>i<FONT SIZE=1.0>1</i></FONT>, <i>i<FONT SIZE=1.0>2</i></FONT>, ... ),
+ where <i>i<FONT SIZE=1.0>k</i></FONT> is an integer, <i>k</i> = 1,2,...
+
+&lt;max_dims&gt; ::= (<i>i<FONT SIZE=1.0>1</i></FONT>, <i>i<FONT SIZE=1.0>2</i></FONT>, ... ) where <i>i<FONT SIZE=1.0>k</i></FONT> is an integer or H5S_UNLIMITED
+
+&lt;ds_definition&gt; ::= TBD
+
+&lt;data&gt; ::= data {TBD}
+
+&lt;group_member&gt; ::= &lt;named_datatype&gt; | &lt;named_dataspace&gt; | &lt;group&gt; | &lt;dataset&gt; |
+ &lt;softlink&gt;
+
+&lt;named_datatype&gt; ::= DATATYPE "&lt;type_name&gt;" { &lt;compound_type_def&gt;+ }
+
+&lt;type_name&gt; ::= "&lt;identifier&gt;"
+
+&lt;named_dataspace&gt; ::= DATASPACE "&lt;dataspace_name&gt;" { ARRAY &lt;current_dims&gt; &lt;max_dims&gt; } |
+ DATASPACE "&lt;dataspace_name&gt;" { OTHER &lt;ds_definition&gt;+ }
+
+&lt;group&gt; ::= GROUP "&lt;group_name&gt;" { &lt;hardlink&gt; } |
+ GROUP "&lt;group_name&gt;" { &lt;group_attribute&gt;* &lt;group_member&gt;* }
+
+&lt;group_name&gt; ::= &lt;identifier&gt;
+
+&lt;dataset&gt; ::= DATASET "&lt;dataset_name&gt;" { &lt;hardlink&gt; } |
+ DATASET "&lt;dataset_name&gt;" { &lt;datatype&gt;
+ &lt;dataspace&gt;
+ &lt;storagelayout&gt;<FONT SIZE=1.7>opt</FONT>
+ &lt;compression&gt;<FONT SIZE=1.7>opt</FONT>
+ &lt;dataset_attribute&gt;*
+ &lt;data&gt;<FONT SIZE=1.7>opt</FONT> }
+// Tokens within {} can be in any order as long as &lt;data&gt; and &lt;dataset_attribute&gt;
+// are after &lt;datatype&gt; and &lt;dataspace&gt;.
+
+&lt;dataset_name&gt; ::= &lt;identifier&gt;
+
+&lt;storagelayout&gt; :: = STORAGELAYOUT &lt;contiguous_layout&gt; |
+ STORAGELAYOUT &lt;chunked_layout&gt; |
+ STORAGELAYOUT &lt;compact_layout&gt; |
+ STORAGELAYOUT &lt;external_layout&gt;
+
+&lt;contiguous_layout&gt; ::= {CONTIGUOUS} // default
+
+&lt;chunked_layout&gt; ::= {CHUNKED &lt;dims&gt; }
+
+&lt;dims&gt; ::= (<i>i<FONT SIZE=1.0>1</i></FONT>, <i>i<FONT SIZE=1.0>2</i></FONT>, ... ), <i>i<FONT SIZE=1.0>k</i></FONT> is an integer, <i>k</i> = 1,2,...
+
+&lt;compact_layout&gt; ::= TBD
+
+&lt;external_layout&gt; ::= {EXTERNAL &lt;external_file&gt;+ }
+
+&lt;external_file&gt; ::= (&lt;file_name&gt; &lt;offset&gt; &lt;size&gt;)
+
+&lt;offset&gt; ::= an integer
+
+&lt;size&gt; ::= an integer
+
+&lt;compression&gt; :: = COMPRESSION { TBD }
+
+&lt;dataset_attribute&gt; ::= &lt;attribute&gt;
+
+&lt;softlink&gt; ::= SOFTLINK "&lt;softlink_name&gt;" { LINKTARGET "&lt;target&gt;" }
+
+&lt;softlink_name&gt; ::= &lt;identifier&gt;
+
+&lt;target&gt; ::= &lt;identifier&gt;
+
+&lt;identifier&gt; ::= string
+// character '/' should be used with care.
+
+</PRE>
+</dir>
+
+
+<h2>4. An Example of an HDF5 File in DDL</h2>
+
+<dir>
+<PRE>
+HDF5 "example.h5" {
+GROUP "/" {
+ DATASET "dset1" {
+ DATATYPE {
+ H5T_STD_I32BE int_name;
+ H5T_IEEE_F32BE float_name;
+ H5T_IEEE_F64BE double_name;
+ }
+ DATASPACE { ARRAY ( 5 ) ( 5 ) }
+ DATA {{0,0,1}, {1,1,0.5}, {2,4,0.333333}, {3,9,0.25}, {4,16,0.2}}
+ }
+ GROUP "group1" {
+ DATASET "dset2" {
+ DATATYPE {
+ HARDLINK { "/type1" }
+ }
+ DATASPACE { ARRAY ( 5 ) ( 5 ) }
+ DATA {{0,0}, {1,1.1}, {2,2.2}, {3,3.3}, {4,4.4}}
+ }
+ }
+ GROUP "group2" {
+ HARDLINK { "/group1" }
+ }
+ SOFTLINK "slink1" {
+ LINKTARGET "somevalue"
+ }
+ DATATYPE "type1" {
+ H5T_STD_I32BE int_name;
+ H5T_IEEE_F32BE float_name;
+ }
+}
+}
+</pre>
+</dir>
+
+<hr>
+<address>
+<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
+</address>
+
+Last modified: 28 October 1998
+
+</body>
+</html>
diff --git a/doc/html/RM_H5I.html b/doc/html/RM_H5I.html
new file mode 100644
index 0000000..298eaea
--- /dev/null
+++ b/doc/html/RM_H5I.html
@@ -0,0 +1,136 @@
+<html>
+<head><title>
+HDF5/H5I Draft API Specification
+</title></head>
+
+<body>
+
+<hr>
+<center>
+<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;
+<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;
+H5I&nbsp;&nbsp;
+<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
+<a href="RM_H5R.html">H5R</a>&nbsp;&nbsp;
+<a href="RM_H5RA.html">H5RA</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="Glossary.html">Glossary</a>
+-->
+</center>
+<hr>
+
+<center>
+<h1>H5I: Identifier Interface</h1>
+</center>
+
+<h2>Identifier API Functions</h2>
+
+This function provides a tool for working with object identifiers.
+<p>
+
+<table border=0>
+<tr><td valign=top>
+<ul>
+ <li><a href="#Identify-GetType">H5Iget_type</a>
+</ul>
+</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
+<ul>
+ &nbsp;
+</ul>
+</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
+<ul>
+ &nbsp;
+</ul>
+</td></tr>
+</table>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Identify-GetType">H5Iget_type</a>
+<dt><strong>Signature:</strong>
+ <dd><em>H5I_type_t</em> <code>H5Iget_type</code>(<em>hid_t</em> <code>obj_id</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Retrieves the type of an object.
+<dt><strong>Description:</strong>
+ <dd><code>H5Iget_type</code> retrieves the type of the object
+ identified by <code>obj_id</code>.
+ <p>
+ Valid types returned by the function are
+ <table>
+ <tr><td width=200><code>&nbsp;&nbsp;&nbsp;&nbsp;H5I_FILE</code>
+ </td><td>File</td></tr>
+ <tr><td><code>&nbsp;&nbsp;&nbsp;&nbsp;H5I_GROUP</code>
+ </td><td>Group</td></tr>
+ <tr><td><code>&nbsp;&nbsp;&nbsp;&nbsp;H5I_DATATYPE</code>
+ </td><td>Datatype</td></tr>
+ <tr><td><code>&nbsp;&nbsp;&nbsp;&nbsp;H5I_DATASPACE</code>
+ </td><td>Dataspace</td></tr>
+ <tr><td><code>&nbsp;&nbsp;&nbsp;&nbsp;H5I_DATASET</code>
+ </td><td>Dataset</td></tr>
+ <tr><td><code>&nbsp;&nbsp;&nbsp;&nbsp;H5I_ATTR</code>
+ </td><td>Attribute</td></tr>
+ </table>
+ If no valid type can be determined or the identifier
+ submitted is invalid, the function returns
+ <table>
+ <tr><td width=200><code>&nbsp;&nbsp;&nbsp;&nbsp;H5I_BADID</code>
+ </td><td>Invalid identifier</td></tr>
+ </table>
+ <p>
+ This function is of particular value in determining the
+ type of object closing function (<code>H5Dclose</code>,
+ <code>H5Gclose</code>, etc.) to call after a call to
+ <code>H5Rdereference</code>.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>obj_id</code>
+ <dd>IN: Object identifier whose type is to be determined.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns the object type if successful;
+ otherwise <code>H5I_BADID</code>.
+</dl>
+
+
+<hr>
+
+<center>
+<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;
+<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;
+H5R&nbsp;&nbsp;
+<a href="RM_H5RA.html">H5RA</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="Glossary.html">Glossary</a>
+-->
+</center>
+<hr>
+
+<address>
+<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
+
+<br>
+Last modified: 27 October 1998
+
+</body>
+</html>
diff --git a/doc/html/RM_H5R.html b/doc/html/RM_H5R.html
new file mode 100644
index 0000000..5af6fad
--- /dev/null
+++ b/doc/html/RM_H5R.html
@@ -0,0 +1,213 @@
+<html>
+<head><title>
+HDF5/H5R Draft API Specification
+</title></head>
+
+<body>
+
+<hr>
+<center>
+<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;
+<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;
+H5R&nbsp;&nbsp;
+<a href="RM_H5RA.html">H5RA</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="Glossary.html">Glossary</a>
+-->
+</center>
+<hr>
+
+<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>
+
+<table border=0>
+<tr><td valign=top>
+<ul>
+ <li><a href="#Reference-Create">H5Rcreate</a>
+</ul>
+</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
+<ul>
+ <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-GetRegion">H5Rget_region</a> (NYI)
+</ul>
+</td></tr>
+<tr><td colspan=5 align=right><font size=-1>
+NYI = Not yet implemented.</font>
+</td></tr>
+</table>
+
+<p>
+<i>Note: The only type of reference implemented in this release
+is an object reference pointing to a dataset.</i>
+<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>href_t *</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 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 dataset region references).
+ <p>
+ <i>Note: Only object references of type <code>H5T_STD_REF_OBJ</code>
+ pointing to entire datasets are implemented at this time.</i>
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>href_t *</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.
+</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>href_t *</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>. See
+ <a href="References.html#Reference-RefTypes">Reference Types</a> in
+ <a href="References.html"><i>References (H5R)</i></a>
+ for a list of valid reference types.
+<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.
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Reference-GetRegion">H5Rget_region</a>
+&nbsp;&nbsp;<i>(Not yet implemented.)</i>
+<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>href_t *</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>. See
+ <a href="References.html#Reference-RefTypes">Reference Types</a> in
+ <a href="References.html"><i>References (H5R)</i></a>
+ for a list of valid reference types.
+<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>href_t *</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.
+</dl>
+
+
+<hr>
+
+<center>
+<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;
+<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;
+H5R&nbsp;&nbsp;
+<a href="RM_H5RA.html">H5RA</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="Glossary.html">Glossary</a>
+-->
+</center>
+<hr>
+
+<address>
+<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
+
+<br>
+Last modified: 27 October 1998
+
+</body>
+</html>
diff --git a/doc/html/References.html b/doc/html/References.html
new file mode 100644
index 0000000..88534e5
--- /dev/null
+++ b/doc/html/References.html
@@ -0,0 +1,558 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+<head>
+<title>References</title>
+</head>
+
+<body>
+<h1>References</h1>
+
+<h2>1. Introduction</h2>
+
+This document discusses the kinds of references implemented
+(and planned) in HDF5 and the functions implemented (and planned)
+to support them.
+
+
+<h2>2. References</h2>
+
+This section contains an overview of the kinds of references
+implemented, or planned for implementation, in HDF5.
+
+<p>
+
+<dl>
+ <dt>Object reference
+ <dd>Reference to an entire object in the current HDF5 file.
+ <br>
+ <em>The only kind of reference currently implemented.</em>
+ <p>
+ An object reference points to an entire object in the
+ current HDF5 file by storing the relative file address
+ (OID) of the object header for the object pointed to.
+ The relative file address of an object header is
+ constant for the life of the object.
+ An object reference is of a fixed size in the file.
+ <p>
+ <dt>Dataset region reference
+ <dd>Reference to a specific dataset region.
+ <br>
+ <em>Not yet implemented.</em>
+ <p>
+ A dataset region reference points to a region of a
+ dataset in the current HDF5 file by storing the OID
+ of the dataset and the global heap offset of the
+ region referenced. The region referenced is located
+ by retrieving the coordinates of the areas in the
+ region from the global heap. A dataset region
+ reference is of a variable size in the file.
+ <p>
+ <dt>Internal dataset region reference
+ <dd>Reference to a region within the current dataset.
+ <br>
+ <em>Not yet implemented.</em>
+ <p>
+ An internal dataset region reference points to a
+ region of the current dataset by storing the
+ coordinates of the region. An internal dataset
+ region reference is of a fixed size in the file.
+</dl>
+
+
+<b>Note:</b> All references are treated as soft links for the
+purposes of reference counting. The library does not keep track of
+reference links and they may dangle if the object they refer to
+is deleted, moved, or not yet available.
+
+
+<h2>3. Reference Types</h2>
+
+This section lists valid HDF5 reference types for use in the
+H5R functions.
+
+<center>
+<table>
+<tr><th align=left>Reference Type</th><th align=left>Value&nbsp;&nbsp;</th><th align=left>Description</th></tr>
+<tr><td><code>H5R_BADTYPE</code></td>
+ <td align=right><code>-1&nbsp;&nbsp;</code></td>
+ <td>Invalid reference type</td></tr>
+<tr><td><code>H5R_OBJECT</code></td>
+ <td align=right><code>0&nbsp;&nbsp;</code></td>
+ <td>Object reference</td></tr>
+<tr><td><code>H5R_DATASET_REGION</code></td>
+ <td align=right><code>1&nbsp;&nbsp;</code></td>
+ <td>Dataset region reference</td></tr>
+<tr><td><code>H5R_INTERNAL</code></td>
+ <td align=right><code>2&nbsp;&nbsp;</code></td>
+ <td>Internal reference</td></tr>
+</table>
+</center>
+
+
+<h2>4. Functions</h2>
+
+Four functions, three in the H5R interface and one in the
+H5I interface, have been implemented to support references.
+The H5I function is also useful outside the context of references.
+<p>
+<dl>
+ <dt><em>herr_t</em> <code>H5Rcreate(</code><em>href_t *</em><code>reference,</code>
+ <em>hid_t</em> <code>loc_id,</code>
+ <em>const char *</em><code>name,</code>
+ <em>H5R_type_t</em> <code>type,</code>
+ <em>hid_t</em> <code>space_id)</code>
+ <dd><code>H5Rcreate</code> creates an object which is a
+ particular type of reference (specified with the
+ <code>type</code> parameter) to some file object and/or
+ location specified with the <code>space_id</code> parameter.
+ For dataset region references, the selection specified
+ in the dataspace is the portion of the dataset which
+ will be referred to.
+ <p>
+ <em>Currently only object references which point to
+ entire datasets can be created.</em>
+ <p>
+
+ <dt><em>hid_t</em> <code>H5Rdereference(</code><em>hid_t</em> <code>dset,</code>
+ <em>H5R_type_t</em> <code>rtype,</code>
+ <em>href_t *</em><code>ref)</code>
+ <dd><code>H5Rdereference</code> opens the object referenced
+ and returns an identifier for that object.
+ The parameter <code>ref</code> specifies a reference of
+ type <code>rtype</code> that is stored in the dataset
+ <code>dset</code>.
+ <p>
+
+ <dt><em>hid_t</em> <code>H5Rget_region(</code><em>hid_t</em> <code>dataset,</code>
+ <em>H5R_type_t</em> <code>type,</code>
+ <em>href_t *</em><code>reference)</code>
+ <dd><code>H5Rget_region</code> creates a copy of dataspace of
+ the dataset that is pointed to and defines a selection in
+ the copy which is the location (or region) pointed to.
+ The parameter <code>ref</code> specifies a reference of
+ type <code>rtype</code> that is stored in the dataset
+ <code>dset</code>.
+ <p>
+ <em>This function is not yet implemented.</em>
+ <p>
+
+ <dt><em>H5I_type_t</em> <code>H5Iget_type(</code><em>hid_t</em> <code>id)</code>
+ <dd>Returns the type of object referred to by the
+ identifier <code>id</code>. Valid return values appear
+ in the following list:
+ <center>
+ <table>
+ <tr><td><code>H5I_BADID</code></td>
+ <td>Invalid ID</td></tr>
+ <tr><td><code>H5I_FILE</code></td>
+ <td>File objects</td></tr>
+ <tr><td><code>H5I_GROUP</code></td>
+ <td>Group objects</td></tr>
+ <tr><td><code>H5I_DATATYPE</code></td>
+ <td>Data type objects</td></tr>
+ <tr><td><code>H5I_DATASPACE</code></td>
+ <td>Dataspace objects</td></tr>
+ <tr><td><code>H5I_DATASET</code></td>
+ <td>Dataset objects</td></tr>
+ <tr><td><code>H5I_ATTR</code></td>
+ <td>Attribute objects</td></tr>
+ </table>
+ </center>
+ <p>
+ This function was inspired by the need of users to figure
+ out which type of object closing function
+ (<code>H5Dclose</code>, <code>H5Gclose</code>, etc.)
+ to call after a call to <code>H5Ddereference</code>,
+ but it is also of general use.
+ <p>
+</dl>
+
+
+
+<h2>5. Examples</h2>
+
+<b>Object Reference Writing Example</b>
+<br>
+Create a dataset which has links to other datasets as part
+of its raw data and write the dataset to the file.
+<p>
+
+<pre>
+{
+ hid_t file1;
+ hid_t dataset1;
+ hid_t datatype, dataspace;
+ char buf[128];
+ href_t link;
+ href_t data[10][10];
+ int rank;
+ size_t dimsf[2];
+ int i, j;
+
+ /* Open the file */
+ file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
+
+ /* Describe the size of the array and create the data space */
+ rank=2;
+ dimsf[0] = 10;
+ dimsf[1] = 10;
+ dataspace = H5Screate_simple(rank, dimsf, NULL);
+
+ /* Define datatype */
+ datatype = H5Tcopy(H5T_STD_REF_OBJ);
+
+ /* Create a dataset */
+ dataset1=H5Dcreate(file1,"Dataset One",datatype,dataspace,H5P_DEFAULT);
+
+ /* Construct array of OIDs for other datasets in the file */
+ /* somewhat hokey and artificial, but demonstrates the point */
+ for(i=0; i<10; i++)
+ for(j=0; j<10; i++)
+ {
+ sprintf(buf,"/Group/Linked Set %d-%d",i,j);
+ if(H5Rcreate(&link,file1,buf,H5R_REF_OBJ,-1)>0)
+ data[i][j]=link;
+ } /* end for */
+
+ /* Write the data to the dataset using default transfer properties. */
+ H5Dwrite(dataset, H5T_POINTER_OBJECT, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+
+ /* Close everything */
+ H5Sclose(dataspace);
+ H5Tclose(datatype);
+ H5Dclose(dataset1);
+ H5Fclose(file1);
+}
+</pre>
+
+
+<b>Object Reference Reading Example</b>
+<br>
+Open a dataset which has links to other datasets as part of
+its raw data and read in those links.
+<p>
+
+<pre>
+{
+ hid_t file1;
+ hid_t dataset1, tmp_dset;
+ href_t data[10][10];
+ int i, j;
+
+ /* Open the file */
+ file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
+
+ /* Open the dataset */
+ dataset1=H5Dopen(file1,"Dataset One",H5P_DEFAULT);
+
+ /*
+ * Read the data to the dataset using default transfer properties.
+ * (we are assuming the dataset is the same and not querying the
+ * dimensions, etc.)
+ */
+ H5Dread(dataset, H5T_STD_REF_OBJ, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+
+ /* Analyze array of OIDs of linked datasets in the file */
+ /* somewhat hokey and artificial, but demonstrates the point */
+ for(i=0; i<10; i++)
+ for(j=0; j<10; i++)
+ {
+ if((tmp_dset=H5Rdereference(dataset, H5T_STD_REF_OBJ, data[i][j]))>0)
+ {
+ <perform operations on linked dataset>
+ } /* end if */
+ H5Dclose(tmp_dset);
+ } /* end for */
+
+
+ /* Close everything */
+ H5Dclose(dataset1);
+ H5Fclose(file1);
+}
+</pre>
+
+
+<b>Dataset Region Reference Writing Example</b>
+<br>
+Create a dataset which has links to other dataset regions
+(single elements in this case) as part of its raw data and
+write the dataset to the file.
+<p>
+
+<pre>
+{
+ hid_t file1;
+ hid_t dataset1, dataset2;
+ hid_t datatype, dataspace1, dataspace2;
+ char buf[128];
+ href_t link;
+ href_t data[10][10]; /* HDF5 reference type */
+ int rank;
+ size_t dimsf[2];
+ hssize_t start[3],count[3];
+ int i, j;
+
+ /* Open the file */
+ file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
+
+ /* Describe the size of the array and create the data space */
+ rank=2;
+ dimsf[0] = 10;
+ dimsf[1] = 10;
+ dataspace1 = H5Screate_simple(rank, dimsf, NULL);
+
+ /* Define Dataset Region Reference datatype */
+ datatype = H5Tcopy(H5T_STD_REF_DATAREG);
+
+ /* Create a dataset */
+ dataset1=H5Dcreate(file1,"Dataset One",datatype,dataspace1,H5P_DEFAULT);
+
+ /* Construct array of OIDs for other datasets in the file */
+ /* (somewhat artificial, but demonstrates the point) */
+ for(i=0; i<10; i++)
+ for(j=0; j<10; i++)
+ {
+ sprintf(buf,"/Group/Linked Set %d-%d",i,j);
+
+ /* Get the dataspace for the object to point to */
+ dataset2=H5Dopen(file1,buf,H5P_DEFAULT);
+ dataspace2=H5Dget_space(dataspace2);
+
+ /* Select the region to point to */
+ /* (could be different region for each pointer) */
+ start[0]=5; start[1]=4; start[2]=3;
+ count[0]=2; count[1]=4; count[2]=1;
+ H5Sselect_hyperslab(dataspace2,H5S_SELECT_SET,start,NULL,count,NULL);
+
+ if(H5Rcreate(&link,file1,buf,H5R_REF_DATAREG,dataspace2)>0)
+ /* Store the reference */
+ data[i][j]=link;
+
+ H5Sclose(dataspace2);
+ H5Dclose(dataspace2);
+ } /* end for */
+
+ /* Write the data to the dataset using default transfer properties. */
+ H5Dwrite(dataset, H5T_STD_REF_DATAREG, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+
+ /* Close everything */
+ H5Sclose(dataspace);
+ H5Tclose(datatype);
+ H5Dclose(dataset1);
+ H5Fclose(file1);
+}
+</pre>
+
+
+<b>Dataset Region Reference Reading Example</b>
+<br>
+Open a dataset which has links to other datasets regions
+(single elements in this case) as part of its raw data and
+read in those links.
+<p>
+
+<pre>
+{
+ hid_t file1;
+ hid_t dataset1, tmp_dset;
+ hid_t dataspace;
+ href_t data[10][10]; /* HDF5 reference type */
+ int i, j;
+
+ /* Open the file */
+ file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
+
+ /* Open the dataset */
+ dataset1=H5Dopen(file1,"Dataset One",H5P_DEFAULT);
+
+ /*
+ * Read the data to the dataset using default transfer properties.
+ * (we are assuming the dataset is the same and not querying the
+ * dimensions, etc.)
+ */
+ H5Dread(dataset, H5T_STD_REF_DATAREG, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+
+ /* Analyze array of OIDs of linked datasets in the file */
+ /* (somewhat artificial, but demonstrates the point) */
+ for(i=0; i<10; i++)
+ for(j=0; j<10; i++)
+ {
+ if((tmp_dset=H5Rdereference(dataset, H5D_STD_REF_DATAREG,data[i][j]))>0)
+ {
+ /* Get the dataspace with the pointed to region selected */
+ dataspace=H5Rget_space(data[i][j]);
+
+ <perform operation on linked dataset region>
+
+ H5Sclose(dataspace);
+ } /* end if */
+ H5Dclose(tmp_dset);
+ } /* end for */
+
+
+ /* Close everything */
+ H5Dclose(dataset1);
+ H5Fclose(file1);
+}
+</pre>
+
+
+
+<hr>
+<address>
+<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
+</address>
+
+Last modified: 28 October 1998
+
+
+<h1>Material to Be Omitted!!!</h1>
+
+Additional material above will also need to be deleted or
+commented out.
+<p>
+
+<h2>"Kinds of Reference" Information</h2>
+
+<dl>
+ <dt>Dataset Offset Reference
+ <dd>Reference to a specific byte sequence in a dataset (3)
+ <dt>Disk Offset Reference
+ <dd>Reference to a specific byte sequence in a file (3)
+ <dt>External Object Reference
+ <dd>Reference to an entire object in another HDF5 file (3)
+ <dt>External Dataset Region Reference
+ <dd>Reference an a specific dataset region in another HDF5 file (3)
+ <dt>External Dataset Offset Reference
+ <dd>Reference to a specific byte sequence in a dataset in
+ another HDF5 file (3)
+ <dt>External Disk Offset Reference
+ <dd>Reference to a specific byte sequence in another HDF5 file (3)
+ <dt>Generic Reference
+ <dd>A reference which may be any of the types defined above. (3)
+</dl>
+
+Notes:
+<ul>
+ <li>1 - Planned for in final release.
+ <li>2 - Most useful reference types to tackle next
+ <li>3 - Optional reference types.
+</ul>
+
+<h2>Comments</h2>
+<pre>
+ Reference types are atomic types and may be included as fields in compound
+ data types.
+
+ There are (at least) three levels of reference strength:
+ Weak - We allow the user to store any type of reference in an array
+ of references. (u.e., the array of references in the example above
+ could be a mix of Object, Dataset Region and Internal references)
+ Medium - We force the user to stick with a particular type of
+ reference within a dataset, but the datasets pointed to (with
+ Object and Dataset Region references) may be of any data type
+ or dataspace.
+ Strong - We force the user to stick with a particular type of
+ reference and Object and Dataset Region references must point to
+ datasets with the same data type.
+ Extra Strong - We force the user to stick with a particular type of
+ reference and Object and Dataset Region references must point to
+ datasets with the same data type _and_ dataspace.
+
+ The library is currently implemented with "medium" strength references.
+</pre>
+
+
+<h2>Reference Type</h2>
+
+<center>
+<table>
+<tr><td><code>H5R_MAXTYPE</code></td>
+ <td align=right><code>3&nbsp;&nbsp;</code></td>
+ <td>Highest type in group (invalid as true type)</td></tr>
+</table>
+</center>
+
+
+<h2>Information Regarding Specific Kinds of References</h2>
+
+<dl>
+<dt>Dataset Offset Reference
+ <dd>Points to a sequence of bytes within a dataset in
+ the current HDF5 file by storing the OID of the dataset and the byte
+ length and offset of the sequence within the dataset. The offset is
+ the logical byte offset within the dataset, meaning that the data is
+ de-compressed before returning the sequence of bytes requested. No
+ interpretation of the data at that location is provided. However,
+ if the dataset is extendible and the size of the dimensions are changed,
+ the element(s) that the sequence is located within may vary. Fixed size
+ in file.
+
+<dt>Disk Offset Reference
+ <dd>Points to a sequence of bytes in the current
+ HDF5 file by storing the byte length and offset of the sequence within
+ the file, relative to the boot-block (as are all the other high-level
+ addresses used in the file). The offset is the absolute byte offset
+ within the file, no interpretation of the data at that location is
+ provided. Fixed size in file.
+
+<dt>External Object Reference
+ <dd>Points to an entire object in another HDF5 file by
+ storing a global heap offset which points to the URL of the external
+ file and the OID of the object pointed to. Variable size in file.
+
+<dt>External Dataset Region Reference
+ <dd>Points to a region of a dataset in
+ another HDF5 file by storing a global heap offset which points to the
+ URL of the external file, OID of the dataset and the coordinates of the
+ region. Variable size in file.
+
+<dt>External Dataset Offset Reference
+ <dd>Points to a sequence of bytes within a
+ dataset in another HDF5 file by storing a global heap offset which
+ points to the URL of the external file, the OID of the dataset and the
+ byte length and offset of the sequence within the dataset. The offset
+ is the logical byte offset within the dataset, meaning that the data is
+ de-compressed before returning the sequence of bytes requested.
+ However, if the dataset is not stored contiguously and the size of the
+ dimensions are changed, the element(s) that the sequence is located
+ within may vary. Variable size in file.
+
+<dt>External Disk Offset Reference
+ <dd>Points to a sequence of bytes in another
+ HDF5 file by storing a global heap reference which points to the URL
+ of the external file and the byte length and offset of the sequence
+ within the file. The offset is the absolute byte offset within the
+ file, no interpretation of the data at that location is provided.
+ Variable size in file.
+
+<dt>Generic Reference
+ <dd>A reference which may contain any of the other
+ references defined above. (Mostly useful for implementing "weak"
+ strength pointers within the medium strength model we are using)
+ Variable size in file.
+
+</dl>
+
+<h2>Implementation Details</h2>
+
+<dl>
+<dt>File Storage
+ <dd>In order to efficiently index an array, each element must be the
+ same size when stored in the dataset on disk. Fixed-sized references
+ will be stored directly in the dataset array on disk; variable-sized
+ references will have a fixed-size head offset stored in the array on
+ disk with a file heap used to store the actual variable-sized
+ information stored in the heap.
+
+<dt>Memory Storage
+ <dd>Each <code>href_t</code> object in memory is a struct containing
+ a pointer type and union of information required for each
+ pointer type.
+ Information in this structure is not designed for users to view.
+ Non-C APIs may have to mangle this structure in some way, in order
+ to provide users with access to references in a language-appropriate
+ way.
+</dl>
+ </body>
+</html>