diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 1998-10-29 22:35:48 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 1998-10-29 22:35:48 (GMT) |
| commit | ed5859ad80ac770b7066c6305458d03e901683b2 (patch) | |
| tree | e1dab642635b1b64f1b46c7d3878a9a9c5df657b /doc | |
| parent | cd3b1059977b1a80e320334c68630f88867341c8 (diff) | |
| download | hdf5-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.html | 208 | ||||
| -rw-r--r-- | doc/html/RM_H5I.html | 136 | ||||
| -rw-r--r-- | doc/html/RM_H5R.html | 213 | ||||
| -rw-r--r-- | doc/html/References.html | 558 |
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 + <tname> a token with the name tname + <a> | <b> one of <a> or <b> + <a><FONT SIZE=1.7>opt</FONT> zero or one occurrence of <a> + <a>* zero or more occurrence of <a> + <a>+ one or more occurrence of <a> + TBD To Be Decided +</pre> + +<h2>3. The DDL</h2> + +<dir> +<pre> +<file> ::= HDF5 "<file_name>" { <file_boot_block><FONT SIZE=1.7>opt</FONT> <root_group> } + +<file_name> ::= <identifier> + +<file_boot_block> ::= BOOT_BLOCK { <boot_block_content> } + +<boot_block_content> ::= TBD + +<root_group> ::= GROUP "/" { <unamed_datatype>* <group_attribute>* <group_member>* } + +<unamed_datatype> ::= DATATYPE "<unamed_type_name>" { <compound_type_def>+ } + +<unamed_type_name> ::= the assigned name for unamed type is in the form of + #oid1:oid2, where oid1 and oid2 are the object ids of the type + +<compound_type_def> ::= <named_scalar_type> | <named_array_type> + +<named_scalar_type> ::= <scalar_type> <field_name> ; + +<scalar_type> ::= H5T_STD_I8BE | H5T_STD_I8LE | ... + +<field_name> ::= <identifier> + +<named_array_type> ::= <scalar_type> <field_name> <dim_sizes> ; + +<dim_sizes> ::= dimension sizes in the form of [dimsize1][dimzise2]..., + where dimsize1, dimsize2 are integers + +<group_attribute> ::= <attribute> + +<attribute> ::= ATTRIBUTE "<attr_name>" { <datatype> + <dataspace> + <data><FONT SIZE=1.7>opt</FONT> } +// <datatype> and <dataspace> must appear before <data>. + +<attr_name> ::= <identifier> + +<datatype> ::= DATATYPE { <named_type> } | + DATATYPE { "<scalar_type>" } | + DATATYPE { <compound_type_def>+ } + +<named_type> ::= <hardlink> + +<hardlink> ::= HARDLINK { "<abs_name>" } + +<abs_name> ::= object absolute name + +<dataspace> ::= DATASPACE { "<dataspace_name>" } | + DATASPACE { ARRAY <current_dims> <max_dims> } | + DATASPACE { OTHER <ds_definition>+ } + +<dataspace_name> ::= <identifier> + +<current_dims> ::= 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,... + +<max_dims> ::= (<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 + +<ds_definition> ::= TBD + +<data> ::= data {TBD} + +<group_member> ::= <named_datatype> | <named_dataspace> | <group> | <dataset> | + <softlink> + +<named_datatype> ::= DATATYPE "<type_name>" { <compound_type_def>+ } + +<type_name> ::= "<identifier>" + +<named_dataspace> ::= DATASPACE "<dataspace_name>" { ARRAY <current_dims> <max_dims> } | + DATASPACE "<dataspace_name>" { OTHER <ds_definition>+ } + +<group> ::= GROUP "<group_name>" { <hardlink> } | + GROUP "<group_name>" { <group_attribute>* <group_member>* } + +<group_name> ::= <identifier> + +<dataset> ::= DATASET "<dataset_name>" { <hardlink> } | + DATASET "<dataset_name>" { <datatype> + <dataspace> + <storagelayout><FONT SIZE=1.7>opt</FONT> + <compression><FONT SIZE=1.7>opt</FONT> + <dataset_attribute>* + <data><FONT SIZE=1.7>opt</FONT> } +// Tokens within {} can be in any order as long as <data> and <dataset_attribute> +// are after <datatype> and <dataspace>. + +<dataset_name> ::= <identifier> + +<storagelayout> :: = STORAGELAYOUT <contiguous_layout> | + STORAGELAYOUT <chunked_layout> | + STORAGELAYOUT <compact_layout> | + STORAGELAYOUT <external_layout> + +<contiguous_layout> ::= {CONTIGUOUS} // default + +<chunked_layout> ::= {CHUNKED <dims> } + +<dims> ::= (<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,... + +<compact_layout> ::= TBD + +<external_layout> ::= {EXTERNAL <external_file>+ } + +<external_file> ::= (<file_name> <offset> <size>) + +<offset> ::= an integer + +<size> ::= an integer + +<compression> :: = COMPRESSION { TBD } + +<dataset_attribute> ::= <attribute> + +<softlink> ::= SOFTLINK "<softlink_name>" { LINKTARGET "<target>" } + +<softlink_name> ::= <identifier> + +<target> ::= <identifier> + +<identifier> ::= 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> +<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> +H5I +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5R.html">H5R</a> +<a href="RM_H5RA.html">H5RA</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="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> </td><td valign=top> +<ul> + +</ul> +</td><td> </td><td valign=top> +<ul> + +</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> H5I_FILE</code> + </td><td>File</td></tr> + <tr><td><code> H5I_GROUP</code> + </td><td>Group</td></tr> + <tr><td><code> H5I_DATATYPE</code> + </td><td>Datatype</td></tr> + <tr><td><code> H5I_DATASPACE</code> + </td><td>Dataspace</td></tr> + <tr><td><code> H5I_DATASET</code> + </td><td>Dataset</td></tr> + <tr><td><code> 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> 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> +<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> +H5R +<a href="RM_H5RA.html">H5RA</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="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> +<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> +H5R +<a href="RM_H5RA.html">H5RA</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="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> </td><td valign=top> +<ul> + <li><a href="#Reference-Dereference">H5Rdereference</a> +</ul> +</td><td> </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> + <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> +<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> +H5R +<a href="RM_H5RA.html">H5RA</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="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 </th><th align=left>Description</th></tr> +<tr><td><code>H5R_BADTYPE</code></td> + <td align=right><code>-1 </code></td> + <td>Invalid reference type</td></tr> +<tr><td><code>H5R_OBJECT</code></td> + <td align=right><code>0 </code></td> + <td>Object reference</td></tr> +<tr><td><code>H5R_DATASET_REGION</code></td> + <td align=right><code>1 </code></td> + <td>Dataset region reference</td></tr> +<tr><td><code>H5R_INTERNAL</code></td> + <td align=right><code>2 </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 </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> |