diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 1998-10-29 22:13:17 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 1998-10-29 22:13:17 (GMT) |
| commit | cd3b1059977b1a80e320334c68630f88867341c8 (patch) | |
| tree | 4f38388af7f9667610ac50ca63df3311f8794d07 /doc | |
| parent | f9fd7a35c22952248e114704fbb189d43419f442 (diff) | |
| download | hdf5-cd3b1059977b1a80e320334c68630f88867341c8.zip hdf5-cd3b1059977b1a80e320334c68630f88867341c8.tar.gz hdf5-cd3b1059977b1a80e320334c68630f88867341c8.tar.bz2 | |
[svn-r830] ======
Intro
======
H5.intro.html
Major rewrite to Groups section. New Example 7 (groups).
Added TOC and requisite links.
Numbered sections.
Labelled figures and centered those that were not.
Fixed table formatting.
===========
User Guide
===========
H5.user.html
Linked in Chunking.html.
Linked in References.html.
Linked in DDL.html.
Chunking.html
Minor edits.
DDL.html
References.html
New documents.
Datatypes.html
Added "R Reference" to base name description and
"H5T_STD_ROBJ -- Reference to an entire object
in a file" to list of datatype names.
Files.html
H5Fflush
Added scope parameter.
Groups.html
Removed references to "current working group."
Removed H5Gpush, H5Gpop, and H5Gset functions.
Removed note that H5Glink and H5Gunlink were not implemented.
=================
Reference Manual
=================
RM_*.html and Tools.html
Updated Reference Manual internal cross-linking (the link
banner at the top and bottom of each page).
Changed
Returns SUCCEED (0) if successful;
otherwise FAIL (-1).
to read
Returns a non-negative value if successful;
otherwise returns a negative value.
and several derived changes where circumstances differred
only slightly.
Minor copy edits throughout.
RM_H5.html
Corrected H5open "Purpose" statement.
RM_H5A.html
Changed H5Aget_name return type to hssize_t.
RM_H5F.html
H5Fflush
Added scope parameter.
Added H5Freopen.
RM_H5Front.html
Reordered listing of interfaces to alphabetical order (H5,
H5A, H5D, ...)
Added H5I, H5R, and H5RA.
RM_H5G.html
H5Gopen
Edited "Description."
H5Gget_objinfo
Added named datatype to list of valid values for loc_id.
RM_H5I.html Identifier Interface
New section.
RM_H5P.html
Added H5Pset_fill_value and H5Pget_fill_value.
Several minor copy edits.
RM_H5R.html Reference Interface
New section.
H5RA.html
Essentially a new section. It was in the tree previously,
but it did not actually have content.
RM_H5S.html
Changed H5Sget_select_npoints return type to hssize_t.
Tools.html
Updated h5dump documentation.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/html/Chunking.html | 17 | ||||
| -rw-r--r-- | doc/html/Dataspaces.html | 6 | ||||
| -rw-r--r-- | doc/html/Datatypes.html | 12 | ||||
| -rw-r--r-- | doc/html/Files.html | 6 | ||||
| -rw-r--r-- | doc/html/Groups.html | 64 | ||||
| -rw-r--r-- | doc/html/H5.intro.html | 572 | ||||
| -rw-r--r-- | doc/html/H5.user.html | 8 | ||||
| -rw-r--r-- | doc/html/RM_H5.html | 28 | ||||
| -rw-r--r-- | doc/html/RM_H5A.html | 42 | ||||
| -rw-r--r-- | doc/html/RM_H5D.html | 34 | ||||
| -rw-r--r-- | doc/html/RM_H5E.html | 32 | ||||
| -rw-r--r-- | doc/html/RM_H5F.html | 72 | ||||
| -rw-r--r-- | doc/html/RM_H5Front.html | 26 | ||||
| -rw-r--r-- | doc/html/RM_H5G.html | 74 | ||||
| -rw-r--r-- | doc/html/RM_H5P.html | 302 | ||||
| -rw-r--r-- | doc/html/RM_H5RA.html | 225 | ||||
| -rw-r--r-- | doc/html/RM_H5S.html | 60 | ||||
| -rw-r--r-- | doc/html/RM_H5T.html | 124 | ||||
| -rw-r--r-- | doc/html/RM_H5Z.html | 12 | ||||
| -rw-r--r-- | doc/html/Ragged.html | 2 | ||||
| -rw-r--r-- | doc/html/Tools.html | 103 |
21 files changed, 1184 insertions, 637 deletions
diff --git a/doc/html/Chunking.html b/doc/html/Chunking.html index ccf4f9e..3267783 100644 --- a/doc/html/Chunking.html +++ b/doc/html/Chunking.html @@ -1,11 +1,11 @@ <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <html> <head> - <title>Dataset Chunking Pitfalls</title> + <title>Dataset Chunking Issues</title> </head> <body> - <h1>Dataset Chunking Pitfalls</h1> + <h1>Dataset Chunking Issues</h1> <h2>Table of Contents</h2> @@ -183,11 +183,24 @@ +<!-- <hr> <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +--> <!-- Created: Tue Oct 20 12:38:40 EDT 1998 --> <!-- hhmts start --> +<!-- Last modified: Fri Oct 23 10:30:52 EDT 1998 +--> <!-- hhmts end --> + +<hr> +<address> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> + +<br> +Last modified: 26 October 1998 + + </body> </html> diff --git a/doc/html/Dataspaces.html b/doc/html/Dataspaces.html index 3136dd2..1004d3b 100644 --- a/doc/html/Dataspaces.html +++ b/doc/html/Dataspaces.html @@ -565,9 +565,9 @@ is returned. <BR> --> -<!-- Created: Thu Dec 4 14:57:32 EST 1997 --><!-- hhmts start -->Last +<!-- Created: Thu Dec 4 14:57:32 EST 1997 --><!-- hhmts start --> <!-- -modified: Thu May 28 15:12:04 EST 1998 +Last modified: Thu May 28 15:12:04 EST 1998 --> <!-- hhmts end --> @@ -576,7 +576,7 @@ modified: Thu May 28 15:12:04 EST 1998 <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 3 September 1998 +Last modified: 26 October 1998 </BODY> </HTML> diff --git a/doc/html/Datatypes.html b/doc/html/Datatypes.html index 248966c..473d4cb 100644 --- a/doc/html/Datatypes.html +++ b/doc/html/Datatypes.html @@ -531,7 +531,9 @@ <code>H5Tinsert()</code>) and cannot be subsequently modified. This makes it imposible to define recursive data structures. + <a name="DTypes-PredefinedAtomic"> <h2>5. Predefined Atomic Data Types</h2> + </a> <p>The library predefines a modest number of data types having names like <code>H5T_<em>arch</em>_<em>base</em></code> where @@ -641,6 +643,10 @@ <td>Signed integer</td> </tr> <tr> + <td align=center>R</td> + <td>References</td> + </tr> + <tr> <td align=center>S</td> <td>Character string</td> </tr> @@ -711,6 +717,10 @@ <td><code>H5T_CRAY_F64</code></td> <td>Eight-byte Cray floating point</td> </tr> + <tr valign=top> + <td><code>H5T_STD_ROBJ</code></td> + <td>Reference to an entire object in a file</td> + </tr> </table> </center> @@ -1425,7 +1435,7 @@ Last modified: Tue Sep 8 14:43:32 EDT 1998 <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> </address> -Last modified: 9 September 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/Files.html b/doc/html/Files.html index 07ecead..ecec10b 100644 --- a/doc/html/Files.html +++ b/doc/html/Files.html @@ -76,11 +76,13 @@ function returns zero for success or a negative value for failure. <br><br> - <dt><code>herr_t H5Fflush (hid_t <em>object_id</em>)</code> + <dt><code>herr_t H5Fflush (hid_t <em>object_id</em>, + H5F_scope_t <em>scope</em>)</code> <dd>This function will cause all buffers associated with a file to be immediately flushed to the file. The <em>object_id</em> can be any object which is associated with a file, including - the file itself. + the file itself. <em>scope</em> specifies whether the flushing + action is to be global or local. </dl> <h2>4. File Property Lists</h2> diff --git a/doc/html/Groups.html b/doc/html/Groups.html index a313f6c..d6999d9 100644 --- a/doc/html/Groups.html +++ b/doc/html/Groups.html @@ -51,7 +51,7 @@ name which begins with a slash is an <em>absolute</em> name which is looked up beginning at the root group of the file while all other <em>relative</em> names are looked up beginning at the - current working group (described below) or a specified group. + specified group. Multiple consecutive slashes in a full name are treated as single slashes and trailing slashes are not significant. A special case is the name "/" (or equivalent) which refers to the @@ -104,9 +104,7 @@ <td>File ID</td> <td><code>foo/bar</code></td> <td>The object <code>bar</code> in group <code>foo</code> - in the current working group of the specified file. The - initial current working group is the root group of the - file as described below.</td> + in the specified group.</td> </tr> <tr> @@ -119,7 +117,7 @@ <tr> <td>File ID</td> <td><code>.</code></td> - <td>The current working group of the specified file.</td> + <td>The specified file.</td> </tr> <tr> @@ -181,51 +179,7 @@ returns zero for success or a negative value for failure. </dl> - <h2>4. Current Working Group</h2> - - <p>Each file handle (<code>hid_t <em>file_id</em></code>) has a - current working group, initially the root group of the file. - Names which do not begin with a slash are relative to the - specified group or to the current working group as described - above. For instance, the name "/Foo/Bar/Baz" is resolved by - first looking up "Foo" in the root group. But the name - "Foo/Bar/Baz" is resolved by first looking up "Foo" in the - current working group. - - <dl> - <dt><code>herr_t H5Gset (hid_t <em>location_id</em>, const char - *<em>name</em>)</code> - <dd>The group with the specified name is made the current - working group for the file which contains it. The - <em>location_id</em> can be a file handle or a group handle - and the name is resolved as described above. Each file handle - has it's own current working group and if the - <em>location_id</em> is a group handle then the file handle is - derived from the group handle. This function returns zero for - success or negative for failure. - - <br><br> - <dt><code>herr_t H5Gpush (hid_t <em>location_id</em>, const char - *<em>name</em>)</code> - <dd>Each file handle has a stack of groups and the top group on - that stack is the current working group. The stack initially - contains only the root group. This function pushes a new - group onto the stack and returns zero for success or negative - for failure. - - <br><br> - <dt><code>herr_t H5Gpop (hid_t <em>location_id</em>)</code> - <dd>This function pops one group off the group stack for the - specified file (if the <em>location_id</em> is a group then - the file is derived from that group), changing the current - working group to the new top-of-stack group. The function - returns zero for success or negative for failure (failure - includes attempting to pop from an empty stack). If the last - item is popped from the stack then the current working group - is set to the root group. - </dl> - - <h2>5. Objects with Multiple Names</h2> + <h2>4. Objects with Multiple Names</h2> <p>An object (including a group) can have more than one name. Creating the object gives it the first name, and then @@ -263,8 +217,7 @@ <code>H5T_LINK_SOFT</code> a soft link is created which is an alias for the <em>current_name</em>. When creating a soft link the object need not exist. This function returns zero - for success or negative for failure. <b>This function is not - part of the prototype API.</b> + for success or negative for failure. <br><br> <dt><code>herr_t H5Gunlink (hid_t <em>file_id</em>, const char @@ -274,11 +227,10 @@ to the object and when the hard link count reaches zero the object can be removed from the file (but objects which are open are not removed until all handles to the object are - closed). <b>This function is not part of the prototype - API.</b> + closed). </dl> - <h2>6. Comments</h2> + <h2>5. Comments</h2> <p>Objects can have a comment associated with them. The comment is set and queried with these two functions: @@ -320,7 +272,7 @@ Last modified: Wed Jul 22 14:24:34 EDT 1998 <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> </address> -Last modified: 9 September 1998 +Last modified: 29 October 1998 </body> </html> diff --git a/doc/html/H5.intro.html b/doc/html/H5.intro.html index d00552f..f13ad13 100644 --- a/doc/html/H5.intro.html +++ b/doc/html/H5.intro.html @@ -16,7 +16,8 @@ --> -<h1 ALIGN="CENTER">Introduction to HDF5 1.0 Beta</h1> +<a name="Intro-Intro"> +<h1 ALIGN="CENTER">Introduction to HDF5 Release 1.0</h1></a> </FONT><FONT FACE="Times"><P>This is an introduction to the HDF5 data model and programming model. Being a <I>Getting Started</I> or <I>QuickStart</I> document, this </FONT><I>Introduction to HDF5</I> <FONT FACE="Times">is intended to provide enough information for you to develop a basic understanding of how HDF5 works and is meant to be used. Knowledge of the current version of HDF will make it easier to follow the text, but it is not required. More complete information of the sort you will need to actually use HDF5 is available in the HDF5 documentation at </FONT><A HREF="http://hdf.ncsa.uiuc.edu/HDF5/"><FONT FACE="Times">http://hdf.ncsa.uiuc.edu/HDF5/</FONT></A><FONT FACE="Times">. Available documents include the following: @@ -30,10 +31,104 @@ </FONT><LI>The directory<FONT FACE="Courier" SIZE=2> hdf5/examples</FONT> contains the examples used in this document. <LI>The directory<FONT FACE="Courier" SIZE=2> hdf5/test</FONT> contains the development tests used by the HDF5 developers. Since these codes are intended to fully exercise the system, they provide more diverse and sophisticated examples of what HDF5 can do.</UL> -<H2><A NAME="_Toc429885299">What is HDF5?</A></H2> +<a name="Intro-TOC"> +<hr> +<center> +<table border=0 width=90%> +<tr><th colspan=3>Table of Contents</th></tr></a> +<tr><td valign=top align=left width=42%> + <a href="#Intro-Intro">Introduction to HDF5 Release 1.0</a><p> + <a href="#Intro-WhatIs">1. What Is HDF5?</a><br> + <font size=-1> +    <a href="#Intro-Why">Why HDF5?</a><br> +    <a href="#Intro-Limits">Limitations of the + Current Release</a><br> +    <a href="#Intro-Changes">Changes in the + Current Release</a><br> + </font> + <a href="#Intro-FileOrg">2. HDF5 File Organization and Data Model</a><br> + <font size=-1> +    <a href="#Intro-OGroups">HDF5 Groups</a><br> +    <a href="#Intro-ODatasets">HDF5 Datasets</a><br> +    <a href="#Intro-OAttributes">HDF5 Attributes</a><br> + </font> + <a href="#Intro-APIs">3. The HDF5 API</a><br> + <font size=-1> +    <a href="#Intro-NameConv">Naming + Conventions</a><br> +    <a href="#Intro-Include">Include Files</a><br> +    <a href="#Intro-ProgModels">Programming + Models</a><br> +     + <A href="#Intro-PMCreateFile">Creating an HDF5 file</A><br> +     + <A href="#Intro-PMDiscard">Discarding objects</A><br> +     + <A href="#Intro-PMWriteNew">Writing a dataset to a + new file</A><br> +     + <A href="#Intro-PMGetInfo">Getting information about + a dataset</A><br> + +</td><td width=6%> </td><td valign=top align=left width=42%> + + <a href="#Intro-APIs">3. The HDF5 API</a> <i>(continued)</i><br> + <font size=-1> +    <a href="#Intro-ProgModels">Programming + Models</a> <i>(continued)</i><br> +     + <A href="#Intro-PMRdWrPortion">Reading/writing a portion of + a dataset</A><br> +     + <A href="#Intro-PMSelectHyper">Selecting hyperslabs</A><br> +     + <A href="#Intro-PMSelectPoints">Selecting of independent + points</A><br> +     + <A href="#Intro-PMCreateCompound">Creating compound + datatypes</A><br> +     + <A href="#Intro-PMCreateExtendible">Creating/writing + extendible datasets</A><br> +     + <A href="#Intro-PMWorkGroups">Working with groups</A><br> +     + <A href="#Intro-PMWorkAttributes">Working with attributes</A><br> + </font> + <a href="#Intro-Examples">4. Example Codes</a><br> + <font size=-1> +     + <A href="#CreateExample">1: Creating and writing a + dataset</A><br> +     + <A href="#CheckAndReadExample">2. Reading a hyperslab</A><br> +     + <A href="#WriteSelected">3. Writing selected data</A><br> +     + <A href="#Compound">4. Working with compound datatypes</A><br> +     + <A href="#CreateExtendWrite">5. Creating and writing an + extendible dataset</A><br> +     + <A href="#ReadExtended">6. Reading data</A><br> +     + <A href="#CreateGroups">7. Creating groups</A><br> +     + <A href="#ReadWriteAttributes">8. Writing and reading + attributes</A><br> + </font> +</td></tr> +</table> +</center> +<p> + +<hr> +<H2><A NAME="Intro-WhatIs">1. What Is HDF5?</A></H2> <FONT FACE="Times"><P>HDF5 is a new, experimental version of HDF that is designed to address some of the limitations of the current version of HDF (HDF4.x) and to address current and anticipated requirements of modern systems and applications. <P>We urge you to look at this new version of HDF and give us feedback on what you like or do not like about it, and what features you would like to see added to it. -<B><P>Why HDF5?</B> The development of HDF5 is motivated by a number of limitations in the current HDF format, as well as limitations in the library. Some of these limitations are: +<a name="Intro-Why"> +<P><B>Why HDF5?</B></a> +The development of HDF5 is motivated by a number of limitations in the current HDF format, as well as limitations in the library. Some of these limitations are: <UL> </FONT><LI>A single file cannot store more than 20,000 complex objects, and a single file cannot be larger than 2 gigabytes. @@ -47,7 +142,7 @@ <LI>A simpler, more comprehensive data model that includes only two basic structures: a multidimensional array of record structures, and a grouping structure. <LI>A simpler, better-engineered library and API, with improved support for parallel i/o, threads, and other requirements imposed by modern systems and applications.</UL> -<H2><A NAME="_Toc429885300">Limitations of the current release</A></H2> +<H3><A NAME="Intro-Limits">Limitations of the Current Release</A></H3> <FONT FACE="Times"><P>The beta release includes most of the basic functionality that is planned for the HDF5 library. However, the library does not implement all of the features detailed in the format and API specifications. Here is a listing of some of the limitations of the current release: <UL> @@ -57,7 +152,7 @@ </FONT><LI>Deletion (unlinking) and renaming objects is not yet implemented. <LI>The library is not currently thread aware although we have planned for that possibility and intend eventually to implement it.</UL> -<H2><A NAME="_Toc429885301">Changes in the current release</A></H2> +<H3><A NAME="Intro-Changes">Changes in the Current Release</A></H3> <P>A detailed listing of changes in HDF5 since the last release (HDF5 1.0 alpha 2.0) can be found in the file <CODE>hdf5/RELEASE </CODE>in the beta code installation. Important changes include: <UL> @@ -68,7 +163,9 @@ <LI>All number type conversions have been implemented except conversions between integer and floating point. <LI>New performance-enhancing features have been implemented.</UL> -<H2><A NAME="_Toc429885302">HDF5 file organization and data model</A></H2> +<p align=right><font size=-1><a href="#Intro-TOC">(Return to TOC)</a></font> +<hr> +<H2><A NAME="Intro-FileOrg">2. HDF5 File Organization and Data Model</A></H2> <FONT FACE="Times"><P>HDF5 files are organized in a hierarchical structure, with two primary structures: <I>groups</I> and <I>datasets</I>. <UL> @@ -82,14 +179,14 @@ <CODE><DD>/foo/zoo</CODE> signifies a member of the group <CODE>foo</CODE>, which in turn is a member of the root group.</DD> </DL> <FONT FACE="Times"><P>Any HDF5 group or dataset may have an associated <I>attribute list.</I> An HDF5 <I>attribute</I> is a user-defined HDF5 structure that provides extra information about an HDF5 object. Attributes are described in more detail below. -</FONT><H3><A NAME="_Toc429885303">HDF5 Groups</A></H3> +</FONT><H3><A NAME="Intro-OGroups">HDF5 Groups</A></H3> <FONT FACE="Times"><P>An<I> HDF5 group</I> is a structure containing zero or more HDF5 objects. A group has two parts: <UL> </FONT><LI>A <I>group header</I>, which contains a group name and a list of group attributes. <LI>A group symbol table, which is a list of the HDF5 objects that belong to the group.</UL> -<H3><A NAME="_Toc429885304">HDF5 Datasets</A></H3> +<H3><A NAME="Intro-ODatasets">HDF5 Datasets</A></H3> <FONT FACE="Times"><P>A dataset is stored in a file in two parts: a header and a data array. <P>The header contains information that is needed to interpret the array portion of the dataset, as well as metadata (or pointers to metadata) that describes or annotates the dataset. Header information includes the name of the object, its dimensionality, its number-type, information about how the data itself is stored on disk, and other information used by the library to speed up access to the dataset or maintain the file's integrity. <P>There are four essential classes of information in any header: <I>name</I>, <I>datatype</I>, <I>dataspace</I>, and <I>storage layout</I>: @@ -108,97 +205,101 @@ <p> <em><code>NATIVE</code> datatypes.</em> Although it is possible to describe nearly any kind of atomic data type, most applications will use predefined datatypes that are supported by their compiler. In HDF5 these are called <i>native</i> datatypes. <CODE>NATIVE</CODE> datatypes are C-like datatypes that are generally supported by the hardware of the machine on which the library was compiled. In order to be portable, applications should almost always use the <CODE>NATIVE </CODE>designation to describe data values in memory. -<P>The <CODE>NATIVE</CODE> architecture has base names which do not follow the same rules as the others. Instead, native type names are similar to the C type names. Here are some examples: -<P ALIGN="CENTER"><CENTER><TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=462> +<P>The <CODE>NATIVE</CODE> architecture has base names which do not follow the same rules as the others. Instead, native type names are similar to the C type names. The following figure shows several examples. +<p> + +<center> +<b>Examples of Native Data Types and Corresponding C Types</b><br> +<TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=462> <TR><TD WIDTH="49%" VALIGN="TOP"> <B><P ALIGN="CENTER">Example</B></TD> <TD WIDTH="51%" VALIGN="TOP"> <B><P ALIGN="CENTER">Corresponding C Type</B></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_CHAR</FONT></TD> +<code>H5T_NATIVE_CHAR</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>signed char</PRE></TD> +<code>signed char</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_UCHAR</FONT></TD> +<code>H5T_NATIVE_UCHAR</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>unsigned char</PRE></TD> +<code>unsigned char</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_SHORT</FONT></TD> +<code>H5T_NATIVE_SHORT</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>short</PRE></TD> +<code>short</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_USHORT</FONT></TD> +<code>H5T_NATIVE_USHORT</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>unsigned short</PRE></TD> +<code>unsigned short</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_INT</FONT></TD> +<code>H5T_NATIVE_INT</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>int</PRE></TD> +<code>int</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_UINT</FONT></TD> +<code>H5T_NATIVE_UINT</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>unsigned</PRE></TD> +<code>unsigned</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_LONG</FONT></TD> +<code>H5T_NATIVE_LONG</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>long</PRE></TD> +<code>long</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_ULONG</FONT></TD> +<code>H5T_NATIVE_ULONG</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>unsigned long</PRE></TD> +<code>unsigned long</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_LLONG</FONT></TD> +<code>H5T_NATIVE_LLONG</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>long long</PRE></TD> +<code>long long</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_ULLONG</FONT></TD> +<code>H5T_NATIVE_ULLONG</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>unsigned long long</PRE></TD> +<code>unsigned long long</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_FLOAT</FONT></TD> +<code>H5T_NATIVE_FLOAT</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>float</PRE></TD> +<code>float</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_DOUBLE</FONT></TD> +<code>H5T_NATIVE_DOUBLE</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>double</PRE></TD> +<code>double</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<FONT FACE="Courier" SIZE=2><P>H5T_NATIVE_LDOUBLE</FONT></TD> +<code>H5T_NATIVE_LDOUBLE</code></TD> <TD WIDTH="51%" VALIGN="TOP"> -<PRE>long double</PRE></TD> +<code>long double</code></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<CODE><P>H5T_NATIVE_HSIZE</CODE></TD> +<CODE>H5T_NATIVE_HSIZE</CODE></TD> <TD WIDTH="51%" VALIGN="TOP"> -<CODE><P>hsize_t</CODE></TD> +<CODE>hsize_t</CODE></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<CODE><P>H5T_NATIVE_HSSIZE</CODE></TD> +<CODE>H5T_NATIVE_HSSIZE</CODE></TD> <TD WIDTH="51%" VALIGN="TOP"> -<CODE><P>hssize_t</CODE></TD> +<CODE>hssize_t</CODE></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<CODE><P>H5T_NATIVE_HERR</CODE></TD> +<CODE>H5T_NATIVE_HERR</CODE></TD> <TD WIDTH="51%" VALIGN="TOP"> -<CODE><P>herr_t</CODE></TD> +<CODE>herr_t</CODE></TD> </TR> <TR><TD WIDTH="49%" VALIGN="TOP"> -<CODE><P>H5T_NATIVE_HBOOL</CODE></TD> +<CODE>H5T_NATIVE_HBOOL</CODE></TD> <TD WIDTH="51%" VALIGN="TOP"> -<CODE><P>hbool_t</CODE></TD> +<CODE>hbool_t</CODE></TD> </TR> </TABLE> </CENTER> @@ -231,14 +332,17 @@ See <I>Datatypes</I> at </FONT><A HREF="http://hdf.ncsa.uiuc.edu/HDF5/Datatypes. <LI>It makes it possible efficiently to extend the dimensions of a dataset in any direction.</OL> <P>See <I>Datasets</I> at </FONT><A HREF="http://hdf.ncsa.uiuc.edu/HDF5/Datasets.html">http://hdf.ncsa.uiuc.edu/HDF5/Datasets.html</A><FONT FACE="Times"> in the<I> HDF User’s Guide</I> for further information. -</FONT><H3><A NAME="_Toc429885305">HDF5 Attributes</A></H3> +</FONT><H3><A NAME="Intro-OAttributes">HDF5 Attributes</A></H3> <I>Attributes </I>are small named datasets that are attached to primary datasets, groups, or named datatypes. Attributes can be used to describe the nature and/or the intended usage of a dataset or group. An attribute has two parts: (1) a <I>name</I> and (2) a <I>value</I>. The value part contains one or more data entries of the same data type. <FONT FACE="Times"><P>The Attribute API (H5A) is used to read or write attribute information. When accessing attributes, they can be identified by name or by an <I>index value</I>. The use of an index value makes it possible to iterate through all of the attributes associated with a given object. <P>The HDF5 format and I/O library are designed with the assumption that attributes are small datasets. They are always stored in the object header of the object they are attached to. Because of this, large datasets should not be stored as attributes. How large is "large" is not defined by the library and is up to the user's interpretation. (Large datasets with metadata can be stored as supplemental datasets in a group with the primary dataset.) <P>See <I>Attributes</I> at </FONT><A HREF="http://hdf.ncsa.uiuc.edu/HDF5/Attributes.html">http://hdf.ncsa.uiuc.edu/HDF5/Attributes.html</A><FONT FACE="Times"> in the<I> HDF User’s Guide</I> for further information. -</FONT><H2><A NAME="_Toc429885306">The HDF5 Applications Programming Interface (API)</A></H2> + +<p align=right><font size=-1><a href="#Intro-TOC">(Return to TOC)</a></font> +<hr> +</FONT><H2><A NAME="Intro-APIs">3. The HDF5 Applications Programming Interface (API)</A></H2> <FONT FACE="Times"><P>The current HDF5 API is implemented only in C. The API provides routines for creating HDF5 files, creating and writing groups, datasets, and their attributes to HDF5 files, and reading groups, datasets and their attributes from HDF5 files. -</FONT><H3><A NAME="_Toc429885307">Naming conventions</A></H3> +</FONT><H3><A NAME="Intro-NameConv">Naming conventions</A></H3> <FONT FACE="Times"><P>All C routines in the HDF 5 library begin with a prefix of the form <B>H5*</B>, where <B>*</B> is a single letter indicating the object on which the operation is to be performed: <UL> @@ -261,11 +365,11 @@ Example: <CODE>H5Zregister</CODE>, which registers new compression and uncompres <B><LI>H5E</B>: <B>E</B>rror handling routines. <BR> Example: <CODE>H5Eprint</CODE>, which prints the current error stack.</UL> -<H3><A NAME="_Toc429885308">Include files</A> </H3> +<H3><A NAME="Intro-Include">Include Files</A> </H3> <FONT FACE="Times"><P>There are a number definitions and declarations that should be included with any HDF5 program. These definitions and declarations are contained in several <I>include</I> files. The main include </FONT>file is <CODE>hdf5.h</CODE>. This file<FONT FACE="Times"> includes all of the other files that your program is likely to need. <I>Be sure to include </i><code>hdf5.h</code><i> in any program that uses the HDF5 library.</I></FONT> -<H3><A NAME="_Toc429885310">Programming models</A></H3> +<H3><A NAME="Intro-ProgModels">Programming Models</A></H3> <FONT FACE="Times"><P>In this section we describe how to program some basic operations on files, including how to <UL> @@ -281,7 +385,7 @@ Example: <CODE>H5Eprint</CODE>, which prints the current error stack.</UL> <LI>Work with attributes. </UL> -<H4><A NAME="_Toc429885311">How to create an HDF5 file</A></H4> +<H4><A NAME="Intro-PMCreateFile">How to create an HDF5 file</A></H4> <P>This programming model shows how to create a file and also how to close the file. <OL> @@ -303,7 +407,7 @@ status = H5Fclose(file); </PRE> </CODE><DL> <DT> </DT> </DL> -<H4><A NAME="_Toc429885312">How to create and initialize the essential components of a dataset for writing to a file</A></H4> +<H4><A NAME="Intro-PMComponents">How to create and initialize the essential components of a dataset for writing to a file</A></H4> <P>Recall that datatypes and dimensionality (dataspace) are independent objects, which are created separately from any dataset that they might be attached to. Because of this the creation of a dataset requires, at a minimum, separate definitions of datatype, dimensionality, and dataset. Hence, to create a dataset the following steps need to be taken: <ol> <FONT FACE="Times"><LI VALUE=1>Create and initialize a dataspace for the dataset to be written. @@ -335,12 +439,12 @@ status = H5Tset_order(datatype, H5T_ORDER_LE); * to little endian is not needed. */ dataset = H5Dcreate(file, DATASETNAME, datatype, dataspace, H5P_DEFAULT);</PRE> -</CODE><H4><A NAME="_Toc429885313">How to discard objects when they are no longer needed</A></H4> +</CODE><H4><A NAME="Intro-PMDiscard">How to discard objects when they are no longer needed</A></H4> <FONT FACE="Times"><P>The datatype, dataspace and dataset objects should be released once they are no longer needed by a program. Since each is an independent object, the must be released (or <I>closed</I>) separately. The following lines of code close the datatype, dataspace, and datasets that were created in the preceding section. </FONT><CODE><P>H5Tclose(datatype); <P>H5Dclose(dataset); <P>H5Sclose(dataspace); -</CODE><H4><A NAME="_Toc429885314">How to write a dataset to a new file</A></H4> +</CODE><H4><A NAME="Intro-PMWriteNew">How to write a dataset to a new file</A></H4> <FONT FACE="Times"><P>Having defined the datatype, dataset, and dataspace parameters, you write out the data with a call to </FONT><CODE>H5Dwrite</CODE><FONT FACE="Courier">. </FONT><CODE><PRE>/* * Write the data to the dataset using default transfer @@ -351,7 +455,7 @@ status = H5Dwrite(dataset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, </CODE><FONT FACE="Times"><P>The third and fourth parameters of </FONT><CODE>H5Dwrite</CODE><FONT FACE="Times"> in the example describe the dataspaces in memory and in the file, respectively. They are set to the value </FONT><CODE>H5S_ALL</CODE><FONT FACE="Times"> to indicate that an entire dataset is to be written. In a later section we look at how we would access a portion of a dataset. </FONT><P><A HREF="#CreateExample"><FONT FACE="Times">Example 1</FONT></A><FONT FACE="Times"> contains a program that creates a file and a dataset, and writes the dataset to the file. <P>Reading is analogous to writing. If, in the previous example, we wish to read an entire dataset, we would use the same basic calls with the same parameters. Of course, the routine </FONT><CODE>H5Dread</CODE><FONT FACE="Times"> would replace </FONT><CODE>H5Dwrite</CODE><FONT FACE="Courier">.</FONT><FONT FACE="Times"> -</FONT><H4><A NAME="_Toc429885315">Getting information about a dataset</A></H4> +</FONT><H4><A NAME="Intro-PMGetInfo">Getting information about a dataset</A></H4> <FONT FACE="Times"><P>Although reading is analogous to writing, it is often necessary to query a file to obtain information about a dataset. For instance, we often need to know about the datatype associated with a dataset, as well dataspace information (e.g. rank and dimensions). There are several "get" routines for obtaining this information The following code segment illustrates how we would get this kind of information: </FONT><CODE><PRE>/* * Get datatype and dataspace identifiers and then query @@ -371,7 +475,7 @@ dataspace = H5Dget_space(dataset); /* dataspace identifier */ rank = H5Sget_simple_extent_ndims(dataspace); status_n = H5Sget_simple_extent_dims(dataspace, dims_out); printf("rank %d, dimensions %d x %d \n", rank, dims_out[0], dims_out[1]);</PRE> -</CODE><H4><A NAME="_Toc429885316">Reading and writing a portion of a dataset</A></H4> +</CODE><H4><A NAME="Intro-PMRdWrPortion">Reading and writing a portion of a dataset</A></H4> <P>In the previous discussion, we describe how to access an entire dataset with one write (or read) operation. HDF5 also supports access to portions (or selections) of a dataset in one read/write operation. Currently selections are limited to hyperslabs and the lists of independent points. Both types of selection will be discussed in the following sections. Several sample cases of selection reading/writing are shown on the following figure. <center> <table bgcolor="#FFFFFF" border=1> @@ -392,8 +496,12 @@ printf("rank %d, dimensions %d x %d \n", rank, dims_out[0], dims_out[1]);</PRE> </center> </B><P>In example (a) a single hyperslab is read from the midst of a two-dimensional array in a file and stored in the corner of a smaller two-dimensional array in memory. In (b) a regular series of blocks is read from a two-dimensional array in the file and stored as a contiguous sequence of values at a certain offset in a one-dimensional array in memory. In (c) a sequence of points with no regular pattern is read from a two-dimensional array in a file and stored as a sequence of points with no regular pattern in a three-dimensional array in memory. <P>As these examples illustrate, whenever we perform partial read/write operations on the data, the following information must be provided: file dataspace, file dataspace selection, memory dataspace and memory dataspace selection. After the required information is specified, actual read/write operation on the portion of data is done in a single call to the HDF5 read/write functions H5Dread(write). -<H5><A NAME="_Toc429885317">Selecting hyperslabs</A></H5> +<H5><A NAME="Intro-PMSelectHyper">Selecting hyperslabs</A></H5> <FONT FACE="Times"><P>Hyperslabs are portions of datasets. A hyperslab selection can be a logically contiguous collection of points in a dataspace, or it can be regular pattern of points or blocks in a dataspace. The following picture illustrates a selection of regularly spaced 3x2 blocks in an 8x12 dataspace.</FONT> +<p> + +<center> +<b>Hyperslab selection</b><br> <TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=345> <TR><TD WIDTH="8%" VALIGN="TOP" HEIGHT=1> </TD> <TD WIDTH="8%" VALIGN="TOP" HEIGHT=1> @@ -548,6 +656,7 @@ printf("rank %d, dimensions %d x %d \n", rank, dims_out[0], dims_out[1]);</PRE> <TD WIDTH="8%" VALIGN="TOP" HEIGHT=1> </TD> </TR> </TABLE> +</center> <FONT FACE="Times"><P>Four parameters are required to describe a completely general hyperslab. Each parameter is an array whose rank is the same as that of the dataspace: @@ -599,6 +708,10 @@ status = H5Sselect_hyperslab(memspace, H5S_SELECT_SET, offset_out, NULL, count_o /*</PRE> </CODE><P><A HREF="#CheckAndReadExample"><FONT FACE="Times">Example 2</FONT></A><FONT FACE="Times"> contains a complete program that performs these operations. <B><P>Example with strides and blocks</B>. Consider the 8x12 dataspace described above, in which we selected eight 3x2 blocks. Suppose we wish to fill these eight blocks. </FONT> +<p> + +<center> +<b>Hyperslab selection</b><br> <TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=345> <TR><TD WIDTH="8%" VALIGN="TOP" HEIGHT=1> </TD> <TD WIDTH="8%" VALIGN="TOP" HEIGHT=1> @@ -753,9 +866,14 @@ status = H5Sselect_hyperslab(memspace, H5S_SELECT_SET, offset_out, NULL, count_o <TD WIDTH="8%" VALIGN="TOP" HEIGHT=1> </TD> </TR> </TABLE> +</center> <P>This hyperslab has the following parameters:<FONT FACE="Times"> </FONT><CODE>start=(0,1), stride=(4,3), count=(2,4), block=(3,2). </CODE><FONT FACE="Times"><P>Suppose that the source dataspace in memory is this 50-element one dimensional array called </FONT><CODE>vector</CODE><FONT FACE="Times">:</FONT> +<p> + +<center> +<b>A 50-element one dimensional array</b><br> <TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=457> <TR><TD WIDTH="8%" VALIGN="TOP" HEIGHT=1> <CODE><P>-1</CODE></TD> @@ -783,6 +901,7 @@ status = H5Sselect_hyperslab(memspace, H5S_SELECT_SET, offset_out, NULL, count_o <CODE><P>-1</CODE></TD> </TR> </TABLE> +</center> <FONT FACE="Times"><P>The following code will write 48 elements from </FONT><CODE>vector</code> to our file dataset, starting with the second element in <code>vector</code>. <pre> @@ -817,6 +936,10 @@ ret = H5Sselect_hyperslab(mid1, H5S_SELECT_SET, start, stride, count, block); ret = H5Dwrite(dataset, H5T_NATIVE_INT, midd1, fid, H5P_DEFAULT, vector) </pre><CODE><P> </CODE><P>After these operations, the file dataspace will have the following values. +<p> + +<center> +<b>Hyperslab selection with assigned values</b><br> <TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=460> <TR><TD WIDTH="8%" VALIGN="TOP" HEIGHT=1> </TD> <TD WIDTH="8%" VALIGN="TOP" HEIGHT=1> @@ -971,10 +1094,11 @@ ret = H5Dwrite(dataset, H5T_NATIVE_INT, midd1, fid, H5P_DEFAULT, vector) <TD WIDTH="8%" VALIGN="TOP" HEIGHT=1> </TD> </TR> </TABLE> +</center> <P>Notice that the values are inserted in the file dataset in row-major order. <P><a href="#WriteSelected">Example 3</a> includes this code and other example code illustrating the use of hyperslab selection. -<H5><A NAME="_Toc429885318">Selecting a list of independent points</A></H5> +<H5><A NAME="Intro-PMSelectPoints">Selecting a list of independent points</A></H5> A hyperslab specifies a regular pattern of elements in a dataset. It is also possible to specify a list of independent elements to read or write using the function <CODE>H5Sselect_elements</CODE>. Suppose, for example, that we wish to write the values 53, 59, 61, 67 to the following elements of the 8x12 array used in the previous example: (0,0), (3,3), (3,5), and (5,6). The following code selects the points and writes them to the dataset: <pre> #define FSPACE_RANK 2 /* Dataset rank as it is stored in the file */ @@ -1014,7 +1138,10 @@ ret = H5Dwrite(dataset, H5T_NATIVE_INT, mid2, fid, H5P_DEFAULT, values); <P> </FONT><P>After these operations, the file dataspace will have the following values: +<p> + <center> +<b>Hyperslab selection with an overlay of independent points</b><br> <TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=460> <TR><TD WIDTH="8%" VALIGN="TOP" HEIGHT=1> <B><CODE><P>53</B></CODE></TD> @@ -1583,7 +1710,7 @@ the previous selection example. -</FONT><H4><A NAME="_Toc429885319">Creating compound datatypes</A></H4> +</FONT><H4><A NAME="Intro-PMCreateCompound">Creating compound datatypes</A></H4> <B><P>Properties of compound datatypes. </B>A compound datatype is similar to a struct in C or a common block in Fortran. It is a collection of one or more atomic types or small arrays of such types. To create and use of a compound datatype you need to refer to various <i>properties</i> of the data compound datatype: <UL> @@ -1615,7 +1742,7 @@ H5Tinsert (complex_id, "real", HOFFSET(tmp,re), H5Tinsert (complex_id, "imaginary", HOFFSET(tmp,im), H5T_NATIVE_DOUBLE);</PRE> </CODE><P><A HREF="#Compound">Example 4</A><FONT FACE="Times"> shows how to create a compound data type, write an array that has the compound data type to the file, and read back subsets of the members. -</FONT><H4><A NAME="_Toc429885320">Creating and writing extendible datasets</A></H4> +</FONT><H4><A NAME="Intro-PMCreateExtendible">Creating and writing extendible datasets</A></H4> <FONT FACE="Times"><P>An <I>extendible</I> dataset is one whose dimensions can grow. In HDF5, it is possible to define a dataset to have certain initial dimensions, then later to increase the size of any of the initial dimensions. <P>For example, you can create and store the following 3x3 HDF5 dataset: </FONT><PRE> 1 1 1 @@ -1691,43 +1818,131 @@ status = H5Dextend (dataset, size);</PRE> <FONT FACE="Courier" SIZE=2><P> </FONT><P><A HREF="#CreateExtendWrite">Example 5</A> shows how to create a 3x3 extendible dataset, write the dataset, extend the dataset to 10x3, write the dataset again, extend it again to 10x5, write the dataset again. <P><A HREF="#ReadExtended">Example 6</A> shows how to read the data written by Example 5. -<H4><A NAME="_Toc429885321">Working with groups in a file</A></H4> +<H4><A NAME="Intro-PMWorkGroups">Working with groups in a file</A></H4> <P>Groups provide a mechanism for organizing meaningful and extendible sets of datasets within an HDF5 file. The H5G API contains routines for working with groups. -<B><P>Creating a group. </B>To create a group, use <CODE>H5Gcreate</CODE>. For example, the following code creates two groups that are members of the root group. They are called <CODE>/IntData</CODE> and <CODE>/FloatData</CODE>. The return value <CODE>dir</CODE> is the group identifier. -<CODE><PRE>/* -* Create two groups in a file. -*/ -dir = H5Gcreate(file, "/IntData", 0); -status = H5Gclose(dir); -dir = H5Gcreate(file,"/FloatData", 0); -status = H5Gclose(dir);</PRE> -</CODE><P>The third parameter in <CODE>H5Gcreate</CODE> optionally specifies how much file space to reserve to store the names that will appear in this group. If a non-positive value is supplied then a default size is chosen. -<CODE><P>H5Gclose</CODE> closes the group and releases the group identifier. -<P> -<B><P>Creating an object in a particular group. </B>Except for single-object HDF5 files, every object in an HDF5 file must belong to a group, and hence has a path name. Hence, we put an object in a particular group by giving its path name when we create it. For example, the following code creates a dataset <CODE>IntArray</CODE> in the group <CODE>/IntData</CODE>: -<CODE><PRE>/* - * Create dataset in the /IntData group by specifying full path. - */ -dims[0] = 2; -dims[1] = 3; -dataspace = H5Pcreate_simple(2, dims, NULL); -dataset = H5Dcreate(file, "/IntData/IntArray", H5T_NATIVE_INT, dataspace, H5C_DEFAULT); </PRE> -</CODE><B><P>Changing the current group. </B>The HDF5 Group API supports the idea of a <i>current group</i>. This is analogous to the <i>current working directory</i> idea in UNIX. You can set the current group in HDF5 with the routine <CODE>H5Gset</CODE>. The following code shows how to set a current group, then create a certain dataset, <CODE>FloatData</CODE>, in that group. -<CODE><PRE>/* - * Set current group to /FloatData. - */ -status = H5Gset (file, "/FloatData"); +<B><P>Creating a group. </B>To create a group, use +<CODE>H5Gcreate</CODE>. For example, the following code +creates a group called <code>Data</code> in the root group. +<pre> + /* + * Create a group in the file. + */ + grp = H5Gcreate(file, "/Data", 0); +</pre> +A group may be created in another group by providing the +absolute name of the group to the <code>H5Gcreate</code> +function or by specifying its location. For example, +to create the group <code>Data_new</code> in the +<code>Data</code> group, one can use the following sequence +of calls: +<pre> + /* + * Create group "Data_new" in the group "Data" by specifying + * absolute name of the group. + */ + grp_new = H5Gcreate(file, "/Data/Data_new", 0); +</pre> +or +<pre> + /* + * Create group "Data_new" in the "Data" group. + */ + grp_new = H5Gcreate(grp, "Data_new", 0); +</pre> +Note that the group identifier <code>grp</code> is used +as the first parameter in the <code>H5Gcreate</code> function +when the relative name is provided. +<p> +The third parameter in <code>H5Gcreate</code> optionally +specifies how much file space to reserve to store the names +that will appear in this group. If a non-positive +value is supplied, then a default size is chosen. +<p> +<code>H5Gclose</code> closes the group and releases the +group identifier. +<p> -/* - * Create two datasets - */ +<b>Creating a dataset in a particular group.</b> +As with groups, a dataset can be created in a particular +group by specifying its absolute name as illustrated in +the following example: + +<pre> + /* + * Create the dataset "Compressed_Data" in the group using the + * absolute name. The dataset creation property list is modified + * to use GZIP compression with the compression effort set to 6. + * Note that compression can be used only when the dataset is + * chunked. + */ + dims[0] = 1000; + dims[1] = 20; + cdims[0] = 20; + cdims[1] = 20; + dataspace = H5Screate_simple(RANK, dims, NULL); + plist = H5Pcreate(H5P_DATASET_CREATE); + H5Pset_chunk(plist, 2, cdims); + H5Pset_deflate( plist, 6); + dataset = H5Dcreate(file, "/Data/Compressed_Data", H5T_NATIVE_INT, + dataspace, plist); +</pre> +A relative dataset name may also be used when a dataset is +created. First obtain the identifier of the group in which +the dataset is to be created. Then create the dataset +with <code>H5Dcreate</code> as illustrated in the following +example: +<pre> + /* + * Open the group. + */ + grp = H5Gopen(file, "Data"); + + /* + * Create the dataset "Compressed_Data" in the "Data" group + * by providing a group identifier and a relative dataset + * name as parameters to the H5Dcreate function. + */ + dataset = H5Dcreate(grp, "Compressed_Data", H5T_NATIVE_INT, + dataspace, plist); +</pre> +<p> + +<b>Accessing an object in a group.</b> +Any object in a group can be accessed by its absolute or +relative name. The following lines of code show how to use +the absolute name to access the dataset +<code>Compressed_Data</code> in the group <code>Data</code> +created in the examples above: +<pre> + /* + * Open the dataset "Compressed_Data" in the "Data" group. + */ + dataset = H5Dopen(file, "/Data/Compressed_Data"); +</pre> +The same dataset can be accessed in another manner. First +access the group to which the dataset belongs, then open +the dataset. +<pre> + /* + * Open the group "data" in the file. + */ + grp = H5Gopen(file, "Data"); + + /* + * Access the "Compressed_Data" dataset in the group. + */ + dataset = H5Dopen(grp, "Compressed_Data"); +</pre> -dims[0] = 5; -dims[1] = 10; -dataspace = H5Screate_simple(2, dims, NULL); -dataset = H5Dcreate(file, "FloatArray", H5T_NATIVE_FLOAT, dataspace, H5P_DEFAULT); </PRE> -</CODE><P><A HREF="#CreateGroups">Example 7</A> shows how to create an HDF5 file with two group, and to place some datasets within those groups. -<H4><A NAME="_Toc429885322">Working with attributes</A></H4> +<p> +<A HREF="#CreateGroups">Example 7</A> shows +how to create a group in a file and a +dataset in a group. It uses the iterator function +<code>H5Giterate</code> to find the names of the objects +in the root group. + + +<H4><A NAME="Intro-PMWorkAttributes">Working with attributes</A></H4> <P>Think of an attribute as a small datasets that is attached to a normal dataset or group. The H5A API contains routines for working with attributes. Since attributes share many of the characteristics of datasets, the programming model for working with attributes is analogous in many ways to the model for working with datasets. The primary differences are that an attribute must be attached to a dataset or a group, and subsetting operations cannot be performed on attributes. <B><P>To create an attribute </B>belonging to a particular dataset or group<B>, </B>first create a dataspace for the attribute with the call to <CODE>H5Screate</CODE>, then create the attribute using <CODE>H5Acreate</CODE>. For example, the following code creates an attribute called <CODE> Integer_attribute </CODE>that is a member of a dataset whose identifier is <CODE>dataset</CODE>. The attribute identifier is <CODE>attr2</CODE>.<CODE> H5Awrite</CODE> then sets the value of the attribute of that of the integer variable <CODE>point</code>. <code>H5Aclose</code> <FONT FACE="Times">then releases the attribute identifier. </CODE> @@ -1787,13 +2002,14 @@ printf("The value of the attribute with the index 2 is %s \n", string_out); <a href="#ReadWriteAttributes">Example 8</a> <A NAME="_Toc429885323">illustrates the use of the <code>H5Aiterate</code> function, as well as the other attribute examples described above.</A> +<p align=right><font size=-1><a href="#Intro-TOC">(Return to TOC)</a></font> <hr> -<H3><A NAME="_Toc429885324">Example code</A></H3> +<H2><A NAME="Intro-Examples">4. Example Codes</A></H2> -<H4><A NAME="CreateExample"><A NAME="_Toc429885325">Example 1: How to create a homogeneous multi-dimensional dataset</A> and write it to a file.</A></H4> +<H4><A NAME="CreateExample">Example 1: How to create a homogeneous multi-dimensional dataset</A> and write it to a file.</A></H4> <P>This example creates a 2-dimensional HDF 5 dataset of little endian 32-bit integers. <PRE> <!-- Insert Example 1, h5_write.c, here. --> @@ -2785,30 +3001,40 @@ main (void) <H4><A NAME="CreateGroups"><A NAME="_Toc429885330"></A>Example 7. Creating groups.</A></H4> <P>This example shows how to create an HDF5 file with two groups, and to place some datasets within those groups. + <PRE> <!-- Insert Example 7, h5_group.c, here. --> /* - * This example shows how to create groups within the file and - * datasets within the file and groups. + * This example creates a group in the file and dataset in the group. + * Hard link to the group object is created and the dataset is accessed + * under different names. + * Iterator function is used to find the object names in the root group. */ #include "hdf5.h" -#define FILE "DIR.h5" +#define FILE "group.h5" #define RANK 2 + +herr_t file_info(hid_t loc_id, const char *name, void *opdata); + /* Operator function */ int main(void) { - hid_t file, dir; + hid_t file; + hid_t grp; hid_t dataset, dataspace; + hid_t plist; herr_t status; hsize_t dims[2]; - hsize_t size[1]; + hsize_t cdims[2]; + + int idx; /* * Create a file. @@ -2816,95 +3042,118 @@ main(void) file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); /* - * Create two groups in a file. + * Create a group in the file. */ - dir = H5Gcreate(file, "/IntData", 0); - status = H5Gclose(dir); - - dir = H5Gcreate(file,"/FloatData", 0); - status = H5Gclose(dir); + grp = H5Gcreate(file, "/Data", 0); + /* + * Create dataset "Compressed Data" in the group using absolute + * name. Dataset creation property list is modified to use + * GZIP compression with the compression effort set to 6. + * Note that compression can be used only when dataset is chunked. + */ + dims[0] = 1000; + dims[1] = 20; + cdims[0] = 20; + cdims[1] = 20; + dataspace = H5Screate_simple(RANK, dims, NULL); + plist = H5Pcreate(H5P_DATASET_CREATE); + H5Pset_chunk(plist, 2, cdims); + H5Pset_deflate( plist, 6); + dataset = H5Dcreate(file, "/Data/Compressed_Data", H5T_NATIVE_INT, + dataspace, plist); + /* - * Create dataspace for the character string + * Close the dataset and the file. */ - size[0] = 80; - dataspace = H5Screate_simple(1, size, NULL); + H5Sclose(dataspace); + H5Dclose(dataset); + H5Fclose(file); /* - * Create dataset "String" in the root group. + * Now reopen the file and group in the file. */ - dataset = H5Dcreate(file, "String", H5T_NATIVE_CHAR, dataspace, - H5P_DEFAULT); - H5Dclose(dataset); + file = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT); + grp = H5Gopen(file, "Data"); - /* - * Create dataset "String" in the /IntData group. + /* + * Access "Compressed_Data" dataset in the group. */ - dataset = H5Dcreate(file, "/IntData/String", H5T_NATIVE_CHAR, dataspace, - H5P_DEFAULT); - H5Dclose(dataset); + dataset = H5Dopen(grp, "Compressed_Data"); + if( dataset < 0) printf(" Dataset is not found. \n"); + printf("\"/Data/Compressed_Data\" dataset is open \n"); /* - * Create dataset "String" in the /FloatData group. + * Close the dataset. */ - dataset = H5Dcreate(file, "/FloatData/String", H5T_NATIVE_CHAR, dataspace, - H5P_DEFAULT); - H5Sclose(dataspace); - H5Dclose(dataset); + status = H5Dclose(dataset); /* - * Create IntArray dataset in the /IntData group by specifying full path. + * Create hard link to the Data group. */ - dims[0] = 2; - dims[1] = 3; - dataspace = H5Screate_simple(RANK, dims, NULL); - dataset = H5Dcreate(file, "/IntData/IntArray", H5T_NATIVE_INT, dataspace, - H5P_DEFAULT); - H5Sclose(dataspace); - H5Dclose(dataset); + status = H5Glink(file, H5G_LINK_HARD, "Data", "Data_new"); - /* - * Set current group to /IntData and attach to the dataset String. + /* + * We can access "Compressed_Data" dataset using created + * hard link "Data_new". */ - status = H5Gset (file, "/IntData"); - dataset = H5Dopen(file, "String"); - if (dataset > 0) printf("String dataset in /IntData group is found\n"); - H5Dclose(dataset); + dataset = H5Dopen(file, "/Data_new/Compressed_Data"); + if( dataset < 0) printf(" Dataset is not found. \n"); + printf("\"/Data_new/Compressed_Data\" dataset is open \n"); /* - * Set current group to /FloatData. + * Close the dataset. */ - status = H5Gset (file, "/FloatData"); + status = H5Dclose(dataset); /* - * Create two datasets FlatArray and DoubleArray. + * Use iterator to see the names of the objects in the file + * root directory. */ - dims[0] = 5; - dims[1] = 10; - dataspace = H5Screate_simple(RANK, dims, NULL); - dataset = H5Dcreate(file, "FloatArray", H5T_NATIVE_FLOAT, dataspace, - H5P_DEFAULT); - H5Sclose(dataspace); - H5Dclose(dataset); + idx = H5Giterate(file, "/", NULL, file_info, NULL); - dims[0] = 4; - dims[1] = 6; - dataspace = H5Screate_simple(RANK, dims, NULL); - dataset = H5Dcreate(file, "DoubleArray", H5T_NATIVE_DOUBLE, dataspace, - H5P_DEFAULT); - H5Sclose(dataspace); - H5Dclose(dataset); + /* + * Unlink name "Data" and use iterator to see the names + * of the objects in the file root direvtory. + */ + if (H5Gunlink(file, "Data") < 0) + printf(" H5Gunlink failed \n"); + else + printf("\"Data\" is unlinked \n"); - /* - * Attach to /FloatData/String dataset. + idx = H5Giterate(file, "/", NULL, file_info, NULL); + + + /* + * Close the file. */ - dataset = H5Dopen(file, "/FloatData/String"); - if (dataset > 0) printf("/FloatData/String dataset is found\n"); - H5Dclose(dataset); - H5Fclose(file); + + status = H5Fclose(file); return 0; } +/* + * Operator function. + */ +herr_t +file_info(hid_t loc_id, const char *name, void *opdata) +{ + hid_t grp; + /* + * Open the group using its name. + */ + grp = H5Gopen(loc_id, name); + + /* + * Display group name. + */ + printf("\n"); + printf("Name : "); + puts(name); + + H5Gclose(grp); + return 0; + } </pre> @@ -3184,13 +3433,14 @@ attr_info(hid_t loc_id, const char *name, void *opdata) <P> +<p align=right><font size=-1><a href="#Intro-TOC">(Return to TOC)</a></font> <hr> <address> <table width=100% border=0> <tr><td align=left valign=top> <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 20 October 1998 +Last modified: 28 October 1998 </td><td align=right valign=top> <a href="Copyright.html">Copyright</a> diff --git a/doc/html/H5.user.html b/doc/html/H5.user.html index 6863ccb..b3fb1b3 100644 --- a/doc/html/H5.user.html +++ b/doc/html/H5.user.html @@ -22,6 +22,8 @@ A guide to the H5S interface. <li><a href="Groups.html">Groups</a> - A guide to the H5G interface. + <li><a href="References.html">References and Identifiers</a> - + A guide to the H5R and H5I interfaces. <li><a href="Attributes.html">Attributes</a> - A guide to the H5A interface. <li><a href="Properties.html">Property Lists</a> - @@ -32,11 +34,15 @@ A guide to the H5Z interface. <li><a href="Caching.html">Caching</a> - A guide for meta and raw data caching. + <li><a href="Chunking.html">Dataset Chunking</a> - + A guide to the issues and pitfalls of dataset chunking. <li><a href="Debugging.html">Debugging</a> - A guide to debugging HDF5 API calls. <li><a href="Environment.html">Environment Variables and Configuration Parameters</a> - A list of HDF5 environment variables and configuration parameters. + <li><a href="DDL.html">DDL for HDF5</a> - + A DDL in BNF for HDF5. <li><a href="Ragged.html">Ragged Arrays</a> - A guide to the H5RA interface. <em><font color=red>(Experimental)</font></em> @@ -85,7 +91,7 @@ Last modified: Wed Aug 19 15:29:11 PDT 1998 <tr><td align=left valign=top> <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 9 September 1998 +Last modified: 27 October 1998 </td><td align=right valign=top> <a href="Copyright.html">Copyright</a> diff --git a/doc/html/RM_H5.html b/doc/html/RM_H5.html index ad2cb8d..8e4c174 100644 --- a/doc/html/RM_H5.html +++ b/doc/html/RM_H5.html @@ -14,7 +14,10 @@ H5 <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> +<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> @@ -57,7 +60,7 @@ and it users. <dt><strong>Signature:</strong> <dd><em>herr_t</em> <code>H5open</code>(<em>void</em>) <dt><strong>Purpose:</strong> - <dd>Flushes all data to disk, closes file identifiers, and cleans up memory. + <dd>Initializes the HDF5 library. <dt><strong>Description:</strong> <dd><code>H5open</code> initialize the library. This function is normally called automatically, but if you find that an @@ -68,8 +71,8 @@ and it users. <dt>None. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -92,8 +95,8 @@ and it users. <dt>None. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -123,8 +126,8 @@ and it users. <dt>None. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -152,8 +155,8 @@ and it users. <dd>The release number of the library. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -188,7 +191,7 @@ and it users. <dd>The patch number of the library. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful. + <dd>Returns a non-negative value if successful. Upon failure, this function causes the application to abort. </dl> @@ -202,7 +205,10 @@ H5 <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> +<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> @@ -217,7 +223,7 @@ H5 <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 2 September 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/RM_H5A.html b/doc/html/RM_H5A.html index bda4333..e53a6d4 100644 --- a/doc/html/RM_H5A.html +++ b/doc/html/RM_H5A.html @@ -14,7 +14,10 @@ H5A <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> +<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> @@ -122,7 +125,7 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the </dl> <dt><strong>Returns:</strong> <dd>Returns an attribute identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -154,7 +157,7 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the </dl> <dt><strong>Returns:</strong> <dd>Returns attribute identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -187,7 +190,7 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the </dl> <dt><strong>Returns:</strong> <dd>Returns attribute identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -224,8 +227,8 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the <dd>IN: Data to be written. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -262,8 +265,8 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the <dd>IN: Buffer for data to be read. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -286,7 +289,7 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the </dl> <dt><strong>Returns:</strong> <dd>Returns attribute dataspace identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -315,7 +318,7 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the </dl> <dt><strong>Returns:</strong> <dd>Returns a datatype identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -323,7 +326,7 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the <dl> <dt><strong>Name:</strong> <a name="Annot-GetName">H5Aget_name</a> <dt><strong>Signature:</strong> - <dd><em>size_t</em> <code>H5Aget_name</code>(<em>hid_t</em> <code>attr_id</code>, + <dd><em>hssize_t</em> <code>H5Aget_name</code>(<em>hid_t</em> <code>attr_id</code>, <em>char *</em><code>buf</code>, <em>size_t</em> <code>buf_size</code> ) @@ -349,7 +352,7 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the <dt><strong>Returns:</strong> <dd>Returns the length of the attribute's name, which may be longer than <code>buf_size</code>, if successful. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -372,7 +375,7 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the </dl> <dt><strong>Returns:</strong> <dd>Returns the number of attributes if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -436,7 +439,7 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the <dt><strong>Returns:</strong> <dd>If successful, returns the return value of the last operator if it was non-zero, or zero if all attributes were processed. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -465,8 +468,8 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the <dd>IN: Name of the attribute to delete. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -488,8 +491,8 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the <dd>IN: Attribute to release access to. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -502,7 +505,10 @@ H5A <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> +<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> @@ -517,7 +523,7 @@ H5A <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 1 September 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/RM_H5D.html b/doc/html/RM_H5D.html index bb2c4dc..22b096c 100644 --- a/doc/html/RM_H5D.html +++ b/doc/html/RM_H5D.html @@ -14,7 +14,10 @@ H5D <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> +<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> @@ -103,7 +106,7 @@ and set and retrieve their constant or persistent properties. </dl> <dt><strong>Returns:</strong> <dd>Returns a dataset identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -130,7 +133,7 @@ and set and retrieve their constant or persistent properties. </dl> <dt><strong>Returns:</strong> <dd>Returns a dataset identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -154,7 +157,7 @@ and set and retrieve their constant or persistent properties. </dl> <dt><strong>Returns:</strong> <dd>Returns a dataspace identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -182,7 +185,7 @@ and set and retrieve their constant or persistent properties. </dl> <dt><strong>Returns:</strong> <dd>Returns a datatype identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -207,7 +210,7 @@ and set and retrieve their constant or persistent properties. </dl> <dt><strong>Returns:</strong> <dd>Returns a dataset creation property list identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -274,8 +277,8 @@ and set and retrieve their constant or persistent properties. <dd>Buffer to store data read from the file. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -344,8 +347,8 @@ and set and retrieve their constant or persistent properties. <dd>Buffer with data to be written to the file. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -372,8 +375,8 @@ and set and retrieve their constant or persistent properties. <dd>Array containing the new magnitude of each dimension. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -396,8 +399,8 @@ and set and retrieve their constant or persistent properties. <dd>Identifier of the dataset to finish access to. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -410,7 +413,10 @@ H5D <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> +<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> @@ -425,7 +431,7 @@ H5D <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 12 August 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/RM_H5E.html b/doc/html/RM_H5E.html index d29380e..8efe624 100644 --- a/doc/html/RM_H5E.html +++ b/doc/html/RM_H5E.html @@ -14,7 +14,10 @@ HDF5/H5E Draft API Specification H5E <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> +<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> @@ -112,8 +115,8 @@ errors within the H5E package. <dd>Data passed to the error function. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -141,8 +144,8 @@ errors within the H5E package. <dd>Current setting for the data passed to the error function. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -166,8 +169,8 @@ errors within the H5E package. <dt>None </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -194,8 +197,8 @@ errors within the H5E package. <dd>File pointer, or stderr if NULL. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -240,8 +243,8 @@ errors within the H5E package. <dd>Data to be passed with <code>func</code>. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -288,8 +291,8 @@ errors within the H5E package. <dd>A file pointer, or stderr if null. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -346,7 +349,10 @@ errors within the H5E package. H5E <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> +<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> @@ -361,7 +367,7 @@ H5E <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 14 July 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/RM_H5F.html b/doc/html/RM_H5F.html index a242e2a..220a307 100644 --- a/doc/html/RM_H5F.html +++ b/doc/html/RM_H5F.html @@ -14,7 +14,10 @@ HDF5/H5F Draft API Specification <a href="RM_H5E.html">H5E</a> H5F <a href="RM_H5G.html">H5G</a> +<a href="RM_H5I.html">H5I</a> <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> @@ -46,6 +49,7 @@ documented below. <ul> <li><a href="#File-Flush">H5Fflush</a> <li><a href="#File-Close">H5Fclose</a> + <li><a href="#File-Reopen">H5Freopen</a> </ul> </td><td> </td><td valign=top> <ul> @@ -102,7 +106,7 @@ documented below. </dl> <dt><strong>Returns:</strong> <dd>Returns a file identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -166,7 +170,7 @@ documented below. </dl> <dt><strong>Returns:</strong> <dd>Returns a file identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -174,7 +178,8 @@ documented below. <dl> <dt><strong>Name:</strong> <a name="File-Flush">H5Fflush</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Fflush</code>(<em>hid_t </em><code>object_id</code> + <dd><em>herr_t </em><code>H5Fflush</code>(<em>hid_t </em><code>object_id</code>, + <em>H5F_scope_t</em> <code>scope</code> ) <dt><strong>Purpose:</strong> <dd>Flushes all buffers associated with a file to disk. @@ -186,14 +191,29 @@ documented below. <code>object_id</code> can be any object associated with the file, including the file itself, a dataset, a group, an attribute, or a named data type. + <p> + <code>scope</code> specifies whether the scope of the flushing + action is global or local. Valid values are + <center> + <table border=0> + <tr><td align=left valign=bottom><code>H5F_SCOPE_GLOBAL</code></td> + <td> </td> + <td align=left valign=bottom>Flushes the entire virtual file.</td></tr> + <tr><td align=left valign=bottom><code>H5F_SCOPE_LOCAL</code></td> + <td></td> + <td align=left valign=bottom>Flushes only the specified file.</td></tr> + </table> + </center> <dt><strong>Parameters:</strong> <dl> <dt><em>const char *</em><code>object_id</code> <dd>Identifier of object used to identify the file. + <dt><em>H5F_scope_t</em> <code>scope</code> + <dd>Specifies the scope of the flushing action. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise returns FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -215,7 +235,7 @@ documented below. </dl> <dt><strong>Returns:</strong> <dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -247,7 +267,7 @@ documented below. </dl> <dt><strong>Returns:</strong> <dd>Returns a file creation property list identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -276,7 +296,7 @@ documented below. </dl> <dt><strong>Returns:</strong> <dd>Returns a file access property list identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -299,8 +319,35 @@ documented below. <dd>Identifier of a file to terminate access to. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="File-Reopen">H5Freopen</a> +<dt><strong>Signature:</strong> + <dd><em>hid__t </em><code>H5Freopen</code>(<em>hid_t</em> <code>file_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Reopens an HDF5 file. +<dt><strong>Description:</strong> + <dd><code>H5Freopen</code> reopens an HDF5 file. The new + file identifier which is returned points to the same file + as the specified file idetifier, <code>file_id</code>. + Both identifiers share caches and other information. + The only difference between the identifiers is that the + new identifier is not mounted anywhere and no files are + mounted on it. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>file_id</code> + <dd>Identifier of a file to terminate access to. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a new file identifier if successful; + otherwise returns a negative value. </dl> @@ -313,7 +360,10 @@ documented below. <a href="RM_H5E.html">H5E</a> H5F <a href="RM_H5G.html">H5G</a> +<a href="RM_H5I.html">H5I</a> <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> @@ -328,7 +378,7 @@ H5F <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 14 August 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/RM_H5Front.html b/doc/html/RM_H5Front.html index e0e6397..8f23c56 100644 --- a/doc/html/RM_H5Front.html +++ b/doc/html/RM_H5Front.html @@ -13,10 +13,10 @@ HDF5 Reference Manual <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> -<!-- +<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> @@ -37,23 +37,23 @@ tools required to meet specific aspects of the HDF5 data-handling requirements. <ul> <li><a href="RM_H5.html">Library Functions</a> -- The general-purpose <strong>H5</strong> functions. +<li><a href="RM_H5A.html">Annotation Interface</a> -- The <strong>H5A</strong> API for annotations. +<li><a href="RM_H5D.html">Dataset Interface</a> -- The <strong>H5D</strong> API for manipulating scientific datasets. +<li><a href="RM_H5E.html">Error Interface</a> -- The <strong>H5E</strong> API for error handling. <li><a href="RM_H5F.html">File Interface</a> -- The <strong>H5F</strong> API for accessing HDF files. +<li><a href="RM_H5G.html">Group Interface</a> -- The <strong>H5G</strong> API for creating physical groups of objects on disk. +<li><a href="RM_H5I.html">Identifier Interface</a> -- The <strong>H5I</strong> API for working with object identifiers. <li><a href="RM_H5P.html">Property List Interface</a> -- The <strong>H5P</strong> API for manipulating object property lists. -<li><a href="RM_H5D.html">Dataset Interface</a> -- The <strong>H5D</strong> API for manipulating scientific datasets. -<li><a href="RM_H5T.html">Datatype Interface</a> -- The <strong>H5T</strong> API for defining dataset element information. +<li><a href="RM_H5R.html">Reference Interface</a> -- The <strong>H5R</strong> API for references. <li><a href="RM_H5S.html">Dataspace Interface</a> -- The <strong>H5S</strong> API for defining dataset dataspace. -<li><a href="RM_H5G.html">Group Interface</a> -- The <strong>H5G</strong> API for creating physical groups of objects on disk. -<li><a href="RM_H5E.html">Error Interface</a> -- The <strong>H5E</strong> API for error handling. +<li><a href="RM_H5T.html">Datatype Interface</a> -- The <strong>H5T</strong> API for defining dataset element information. <li><a href="RM_H5Z.html">Compression Interface</a> -- The <strong>H5Z</strong> API for compression. -<li><a href="RM_H5A.html">Annotation Interface</a> -- The <strong>H5A</strong> API for annotations. <li><a href="Tools.html">Tools</a> -- Interactive tools for the examination of existing HDF5 files. <!-- <li><a href="Glossary.html">Glossary</a> -- A glossary of data-types used in the APIs. --> -<!-- -<hr> +<hr width=300 align=left> <li>Experimental interface:<a href="RM_H5RA.html">Ragged Arrays</a> -- The <strong>H5RA</strong> API for ragged arrays. ---> </ul> @@ -67,10 +67,10 @@ HDF5 Reference Manual <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> -<!-- +<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> @@ -86,7 +86,7 @@ HDF5 Reference Manual <tr><td align=left valign=top> <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 8 September 1998 +Last modified: 27 October 1998 </td><td align=right valign=top> <a href="Copyright.html">Copyright</a> diff --git a/doc/html/RM_H5G.html b/doc/html/RM_H5G.html index 1e79039..fce1706 100644 --- a/doc/html/RM_H5G.html +++ b/doc/html/RM_H5G.html @@ -14,7 +14,10 @@ HDF5/H5G Draft API Specification <a href="RM_H5E.html">H5E</a> <a href="RM_H5F.html">H5F</a> H5G +<a href="RM_H5I.html">H5I</a> <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> @@ -31,8 +34,8 @@ H5G <h2>Group Object API Functions</h2> -The Group interface functions create and manipulate physical groups -of objects on disk. +The Group interface functions create and manipulate groups +of objects in an HDF5 file. <table border=0> <tr><td valign=top> @@ -77,7 +80,7 @@ object is located by looking for the first component in the root object, then looking for the second component in the first object, etc., until the entire name is traversed. A relative name does not begin with a slash and the traversal begins at the location specified by the -calling function. +create or access function. <p> @@ -105,7 +108,7 @@ calling function. is usually adequate since the library is able to dynamically resize the name heap, but a correct hint may result in better performance. - If a non-positive value is supplied for size_hint, + If a non-positive value is supplied for <code>size_hint</code>, then a default size is chosen. <p> The return value is a group identifier for the open group. @@ -128,7 +131,7 @@ calling function. </dl> <dt><strong>Returns:</strong> <dd>Returns a valid group identifier for the open group if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -143,12 +146,14 @@ calling function. <dd>Opens an existing group for modification and returns a group identifier for that group. <dt><strong>Description:</strong> - <dd><code>H5Gopen</code> opens an existing group with the specified name at - the specified location, <code>loc_id</code>. - The location is identified by a file or - group identifier, and returns a group identifier for the group. - The obtained group identifier should be released by calling - <code>H5Gclose()</code> when it is no longer needed. + <dd><code>H5Gopen</code> opens an existing group with the specified + name at the specified location, <code>loc_id</code>. + <p> + The location is identified by a file or group identifier + <p> + <code>H5Gopen</code> returns a group identifier for the group + that was opened. This group identifier should be released by + calling <code>H5Gclose()</code> when it is no longer needed. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>loc_id</code> @@ -158,7 +163,7 @@ calling function. </dl> <dt><strong>Returns:</strong> <dd>Returns a valid group identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -181,8 +186,8 @@ calling function. <dd>Group identifier to release. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -203,7 +208,8 @@ calling function. name, possibly one of many names it currently has. <p> If <code>link_type</code> is <code>H5G_LINK_HARD</code>, then - <code>current_name</code> must name an existing object and both + <code>current_name</code> must specify the name of an + existing object and both names are interpreted relative to <code>loc_id</code>, which is either a file identifier or a group identifier. <p> @@ -229,8 +235,8 @@ calling function. <dd>New name for the object. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -263,8 +269,8 @@ calling function. <dd>Name of the object to unlink. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -334,7 +340,7 @@ calling function. <dt><strong>Returns:</strong> <dd>Returns the return value of the last operator if it was non-zero, or zero if all group members were processed. - Otherwise, returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -365,8 +371,8 @@ calling function. <dd>Object's new name. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -384,7 +390,8 @@ calling function. <dt><strong>Description:</strong> <dd><code>H5Gget_objinfo</code> returns information about the specified object through the <code>statbuf</code> argument. - <code>loc_id</code> (a file, group, or dataset identifier) and + <code>loc_id</code> (a file, group, dataset, or + named datatype identifier) and <code>name</code> together determine the object. If the object is a symbolic link and <code>follow_link</code> is zero (<code>0</code>), then the information returned is that for the link itself; @@ -441,9 +448,9 @@ calling function. <dd>OUT: Buffer in which to return information about the object. </dl> <dt><strong>Returns:</strong> - <dd> Returns SUCCEED (0) with the fields of <code>statbuf</code> - (if non-null) initialized. - Otherwise returns FAIL (-1). + <dd> Returns a non-negative value if successful, with the fields of + <code>statbuf</code> (if non-null) initialized. + Otherwise returns a negative value. </dl> @@ -484,9 +491,9 @@ calling function. <dd>OUT: Link value. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0), with the link value in <code>value</code>, + <dd>Returns a non-negative value, with the link value in <code>value</code>, if successful. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -528,8 +535,8 @@ calling function. <dd>IN: The new comment. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise returns FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -571,7 +578,7 @@ calling function. <dd>Returns the number of characters in the comment, counting the null terminator, if successful; the value returned may be larger than <code>bufsize</code>. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -589,7 +596,10 @@ calling function. <a href="RM_H5E.html">H5E</a> <a href="RM_H5F.html">H5F</a> H5G +<a href="RM_H5I.html">H5I</a> <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> @@ -604,7 +614,7 @@ H5G <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 2 September 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/RM_H5P.html b/doc/html/RM_H5P.html index d9f1191..8dda42f 100644 --- a/doc/html/RM_H5P.html +++ b/doc/html/RM_H5P.html @@ -14,7 +14,10 @@ HDF5/H5P Draft API Specification <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> H5P +<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> @@ -57,6 +60,11 @@ many different parameters to be easily manipulated. <li><a href="#Property-SetIstoreK">H5Pset_istore_k</a> <li><a href="#Property-GetIstoreK">H5Pget_istore_k</a> </ul> +<br> +<br> +|| <i>Available only in the +<br> +parallel HDF5 library.</i> </td><td> </td><td valign=top> @@ -95,6 +103,8 @@ many different parameters to be easily manipulated. <li><a href="#Property-SetCompression">H5Pset_compression</a> <li><a href="#Property-GetCompression">H5Pget_compression</a> --> + <li><a href="#Property-SetFillValue">H5Pset_fill_value</a> + <li><a href="#Property-GetFillValue">H5Pget_fill_value</a> <li><a href="#Property-SetFilter">H5Pset_filter</a> <li><a href="#Property-GetNFilters">H5Pget_nfilters</a> <li><a href="#Property-GetFilter">H5Pget_filter</a> @@ -115,10 +125,12 @@ many different parameters to be easily manipulated. </td></tr> +<!-- <tr><td colspan=5 align=right> <br> || <i>Available only in the parallel HDF5 library.</i> </td></tr> +--> </table> </dir @@ -187,8 +199,8 @@ many different parameters to be easily manipulated. <dd>IN: Identifier of the property list to terminate access to. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -202,7 +214,7 @@ many different parameters to be easily manipulated. <dd>Returns the property list class for a property list. <dt><strong>Description:</strong> <dd><code>H5Pget_class</code> returns the property list class for the - property list identied by the <code>plist</code> parameter. + property list identified by the <code>plist</code> parameter. Valid property list classes are defined in the description of <code>H5Pcreate()</code>. <dt><strong>Parameters:</strong> @@ -236,7 +248,7 @@ many different parameters to be easily manipulated. </dl> <dt><strong>Returns:</strong> <dd>Returns a property list identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -271,8 +283,8 @@ many different parameters to be easily manipulated. <dd>OUT: Pointer to location to return shared object header version number. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -298,8 +310,8 @@ many different parameters to be easily manipulated. <dd>IN: Size of the user-block in bytes. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -323,8 +335,8 @@ many different parameters to be easily manipulated. <dd>OUT: Pointer to location to return user-block size. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -344,7 +356,7 @@ many different parameters to be easily manipulated. address objects in an HDF5 file. This function is only valid for file creation property lists. Passing in a value of 0 for one of the sizeof parameters retains the current value. The default value - for both values is 4 bytes. Valid values currenly are 2, 4, 8 and + for both values is 4 bytes. Valid values currently are 2, 4, 8 and 16. <dt><strong>Parameters:</strong> <dl> @@ -356,8 +368,8 @@ many different parameters to be easily manipulated. <dd>IN: Size of an object length in bytes. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -385,8 +397,8 @@ many different parameters to be easily manipulated. <dd>OUT: Pointer to location to return length size in bytes. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -426,8 +438,8 @@ many different parameters to be easily manipulated. again to setup the property list. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -457,8 +469,8 @@ many different parameters to be easily manipulated. <dd>OUT: Pointer to location to return the info object. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if the file access property list is set to the MPI. - Otherwise returns FAIL (-1). + <dd>Returns a non-negative value if the file access property list is set to the MPI. + Otherwise returns a negative value. </dl> @@ -495,8 +507,8 @@ many different parameters to be easily manipulated. <dd>IN: Data transfer mode. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -522,8 +534,8 @@ many different parameters to be easily manipulated. <dd>OUT: Pointer to location to return the data transfer mode. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -565,8 +577,8 @@ many different parameters to be easily manipulated. <dd>IN: Symbol table node size. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -599,8 +611,8 @@ many different parameters to be easily manipulated. <dd>OUT: Pointer to location to return the symbol table's leaf node 1/2 size. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -633,8 +645,8 @@ many different parameters to be easily manipulated. <dd>IN: 1/2 rank of chunked storage B-tree. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -662,8 +674,8 @@ many different parameters to be easily manipulated. <dd>OUT: Pointer to location to return the chunked storage B-tree 1/2 rank. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -687,12 +699,12 @@ many different parameters to be easily manipulated. This should only be used for very small amounts of raw data (suggested less than 1KB). <dt>H5D_CONTIGUOUS - <dd>Store raw data seperately from object header in one + <dd>Store raw data separately from object header in one large chunk in the file. <dt>H5D_CHUNKED - <dd>Store raw data seperately from object header in one + <dd>Store raw data separately from object header in one large chunk in the file and store chunks of the raw - data in seperate locations in the file. + data in separate locations in the file. </dl></ul> <dt><strong>Parameters:</strong> <dl> @@ -702,8 +714,8 @@ many different parameters to be easily manipulated. <dd>IN: Type of storage layout for raw data. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -722,11 +734,11 @@ many different parameters to be easily manipulated. <dt>H5D_COMPACT <dd>Raw data and object header stored contiguously in file. <dt>H5D_CONTIGUOUS - <dd>Raw data stored seperately from object header in one + <dd>Raw data stored separately from object header in one large chunk in the file. <dt>H5D_CHUNKED - <dd>Raw data stored seperately from object header in - chunks in seperate locations in the file. + <dd>Raw data stored separately from object header in + chunks in separate locations in the file. </dl> </ul> <dt><strong>Parameters:</strong> <dl> @@ -769,8 +781,8 @@ many different parameters to be easily manipulated. <dd>IN: An array containing the size of each chunk. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -802,7 +814,7 @@ many different parameters to be easily manipulated. </dl> <dt><strong>Returns:</strong> <dd>Returns chunk dimensionality successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -836,13 +848,13 @@ many different parameters to be easily manipulated. <dt><em>hid_t</em> <code>plist</code> <dd>IN: Identifier for a file access property list. <dt><em>hsize_t</em> <code>threshold</code> - <dd>IN: Threshhold value. + <dd>IN: Threshold value. <dt><em>hsize_t</em> <code>alignment</code> <dd>IN: Alignment value. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -867,13 +879,13 @@ many different parameters to be easily manipulated. <dt><em>hid_t</em> <code>plist</code> <dd>IN: Identifier of a file access property list. <dt><em>hsize_t</em> <code>*threshold</code> - <dd>OUT: Pointer to location of return threshhold value. + <dd>OUT: Pointer to location of return threshold value. <dt><em>hsize_t</em> <code>*alignment</code> <dd>OUT: Pointer to location of return alignment value. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -911,8 +923,8 @@ many different parameters to be easily manipulated. <dd>IN: Number of bytes reserved in the file for the data. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -934,7 +946,7 @@ many different parameters to be easily manipulated. </dl> <dt><strong>Returns:</strong> <dd>Returns the number of external files if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -982,11 +994,92 @@ many different parameters to be easily manipulated. external file data. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. +</dl> + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetFillValue">H5Pset_fill_value</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_fill_value</code>(<em>hid_t</em> <code>plist_id</code>, + <em>hid_t</em> <code>type_id</code>, + <em>const void *</em><code>value</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets a dataset fill value. + <dt><strong>Description:</strong> + <dd><code>H5Pset_fill_value</code> sets the fill value for a + dataset creation property list. + <p> + The <code>value</code> is interpreted as being of type + <code>type_id</code>. This need not be the same type + as the dataset, but the library must be able to convert + <code>value</code> to the dataset type when the dataset + is created. + <dt><strong>Notes:</strong> + <dd>If a fill value is set for a dataset (even if the + fill value is all zeros), the fill value will be written + to the file. If no fill value is set, then HDF5 relies on + the underlying file driver (usually a Unix file system) + to initialize unwritten parts of the file to zeros. + <p> + Creating a contiguous dataset with a fill value can be a + very expensive operation since the optimization has not + yet been implemented that would delay the writing of the + fill values until after some data has been written. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist_id</code> + <dd>IN: Property list identifier. + <dt><em>hid_t</em> <code>type_id</code>, + <dd>IN: The datatype identifier of <code>value</code>. + <dt><em>const void *</em><code>value</code> + <dd>IN: The fill value. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetFillValue">H5Pget_fill_value</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_fill_value</code>(<em>hid_t</em> <code>plist_id</code>, + <em>hid_t</em> <code>type_id</code>, + <em>void *</em><code>value</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves a dataset fill value. + <dt><strong>Description:</strong> + <dd><code>H5Pget_fill_value</code> queries the + fill value property of a dataset creation property list. + <p> + The fill value is returned through the <code>value</code> + pointer. + <p> + Memory is allocated by the caller. + <p> + The fill value will be converted from its current + data type to the type specified by <code>type_id</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist_id</code> + <dd>IN: Property list identifier. + <dt><em>hid_t</em> <code>type_id</code>, + <dd>IN: The datatype identifier of <code>value</code>. + <dt><em>const void *</em><code>value</code> + <dd>IN: The fill value. + </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="Property-SetFilter">H5Pset_filter</a> @@ -1055,8 +1148,8 @@ many different parameters to be easily manipulated. <dd>IN: Auxiliary data for the filter. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1092,7 +1185,7 @@ many different parameters to be easily manipulated. </dl> <dt><strong>Returns:</strong> <dd>Returns the number of filters in the pipeline if successful; - otherwise returns FAIL (-1). + otherwise returns a negative value. </dl> @@ -1129,8 +1222,8 @@ many different parameters to be easily manipulated. <code>filter_number</code> is a value between zero and <em>N</em>-1, as described in <a href="#Property-GetNFilters"><code>H5Pget_nfilters()</code></a>. - The function will return FAIL (-1) if the filter number is out - of range. + The function will return a negative value if the filter number + is out of range. <p> If <code>name</code> is a pointer to an array of at least <code>namelen</code> bytes, the filter name will be copied @@ -1218,8 +1311,8 @@ many different parameters to be easily manipulated. <dd>IN: Identifier of a file access property list. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1242,9 +1335,9 @@ many different parameters to be easily manipulated. <dd>IN: Identifier of a file access property list. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if the file access propety list is set + <dd>Returns a non-negative value if the file access property list is set to the stdio driver. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -1267,8 +1360,8 @@ many different parameters to be easily manipulated. <dd>IN: Identifier of a file access property list. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1278,7 +1371,7 @@ many different parameters to be easily manipulated. <dt><strong>Signature:</strong> <dd><em>returntype</em> <code>H5Pget_sec2</code>(<em>hid_t</em> <code>plist</code>) <dt><strong>Purpose:</strong> - <dd>Checks whether the file access propety list is set + <dd>Checks whether the file access property list is set to the sec2 driver. <dt><strong>Description:</strong> <dd><code>H5Pget_sec2</code> checks to determine whether the @@ -1291,9 +1384,9 @@ many different parameters to be easily manipulated. <dd>IN: Identifier of a file access property list. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if the file access propety list is set + <dd>Returns a non-negative value if the file access property list is set to the sec2 driver. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -1323,8 +1416,8 @@ many different parameters to be easily manipulated. <dd>IN: File block size in bytes. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1353,9 +1446,9 @@ many different parameters to be easily manipulated. <dd>OUT: Pointer to a location to return the file block size (in bytes). </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if the file access propety list is set + <dd>Returns a non-negative value if the file access property list is set to the core driver. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -1399,8 +1492,8 @@ many different parameters to be easily manipulated. <dd>IN: Identifier of the raw file access property list. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1458,9 +1551,9 @@ many different parameters to be easily manipulated. <dd>OUT: Pointer to a copy of the raw file access property list. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if the file access propety list is set + <dd>Returns a non-negative value if the file access property list is set to the split driver. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -1491,7 +1584,7 @@ many different parameters to be easily manipulated. opened. Note: if the size of the <code>off_t</code> type is four bytes then the maximum family member size is usually 2^31-1 because the byte at offset 2,147,483,647 is generally - inaccessable. Additional parameters may be added to this + inaccessible. Additional parameters may be added to this function in the future. <dt><strong>Parameters:</strong> <dl> @@ -1504,8 +1597,8 @@ many different parameters to be easily manipulated. for each member of the family. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1526,7 +1619,7 @@ many different parameters to be easily manipulated. to use the <code>family</code> driver; any previously defined driver properties are erased from the property list. See <a href="Files.html#File_Families">File Families</a> - in the <cite>HDF5 User's Guide</dite> for a discussion + in the <cite>HDF5 User's Guide</cite> for a discussion of file families. <p> Each member of the file family will use <code>memb_plist</code> @@ -1543,7 +1636,7 @@ many different parameters to be easily manipulated. Note: If the size of the <code>off_t</code> type is four bytes, then the maximum family member size is usually 2^31-1 because the byte at offset 2,147,483,647 is generally - inaccessable. + inaccessible. <p> Additional parameters may be added to this function in the future. @@ -1558,8 +1651,8 @@ many different parameters to be easily manipulated. for each member of the family. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1596,9 +1689,9 @@ many different parameters to be easily manipulated. for each member of the family. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if the file access propety list is set + <dd>Returns a non-negative value if the file access property list is set to the family driver. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -1645,8 +1738,8 @@ many different parameters to be easily manipulated. <dd>IN: Preemption policy. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1660,7 +1753,7 @@ many different parameters to be easily manipulated. <em>double</em> <code>*rdcc_w0</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves maximun sizes of meta data cache and RDCC_WO. + <dd>Retrieves maximum sizes of meta data cache and RDCC_WO. <dt><strong>Description:</strong> <dd>Retrieves the maximum possible number of elements in the meta data cache and the maximum possible number of bytes and the @@ -1679,8 +1772,8 @@ many different parameters to be easily manipulated. <dd>IN/OUT: Preemption policy. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1701,7 +1794,7 @@ many different parameters to be easily manipulated. for the type conversion buffer and background buffer and optionally supply pointers to application-allocated buffers. If the buffer size is smaller than the entire amount of data - being transfered between application and file, and a type + being transferred between application and file, and a type conversion buffer or background buffer is required then strip mining will be used. However, certain restrictions apply for the size of buffer which can be used for strip @@ -1725,8 +1818,8 @@ many different parameters to be easily manipulated. <dd>IN: Pointer to application-allocated background buffer. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1787,8 +1880,8 @@ many different parameters to be easily manipulated. (TRUE/FALSE). </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1809,7 +1902,7 @@ many different parameters to be easily manipulated. </dl> <dt><strong>Returns:</strong> <dd>Returns TRUE or FALSE if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -1830,7 +1923,7 @@ many different parameters to be easily manipulated. <dt><strong>Description:</strong> <dd><code>H5Pset_compression</code> sets the compression method in a dataset creation property list. This is a catch-all - function for defining compresion methods + function for defining compression methods and is intended to be called from a wrapper such as <code>H5Pset_deflate()</code>. The dataset creation property list <em>plist</em> is adjusted to use the specified @@ -1861,8 +1954,8 @@ many different parameters to be easily manipulated. <dd>IN: Client data byte array passed to the compression method. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> --> @@ -1902,7 +1995,7 @@ many different parameters to be easily manipulated. </dl> <dt><strong>Returns:</strong> <dd>Returns compression method if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> --> @@ -1932,8 +2025,8 @@ many different parameters to be easily manipulated. <dd>IN: Compression level. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1958,7 +2051,7 @@ many different parameters to be easily manipulated. </dl> <dt><strong>Returns:</strong> <dd>Returns compression level, a value between 0 and 9, if successful. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> --> @@ -1973,7 +2066,10 @@ many different parameters to be easily manipulated. <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> H5P +<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> @@ -1989,7 +2085,7 @@ H5P <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 25 August 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/RM_H5RA.html b/doc/html/RM_H5RA.html index 2b2d80e..bb7bca4 100644 --- a/doc/html/RM_H5RA.html +++ b/doc/html/RM_H5RA.html @@ -14,7 +14,9 @@ HDF5/H5RA Draft API Specification <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> +<a href="RM_H5R.html">H5R</a> H5RA <a href="RM_H5S.html">H5S</a> <a href="RM_H5T.html">H5T</a> @@ -46,11 +48,13 @@ Do not create any archives using this interface!</center> <p> These functions enable the user to store and retrieve data in ragged arrays. - <table border=0> <tr><td valign=top> <ul> <li><a href="#Ragged-Create">H5RAcreate</a> +</ul> +</td><td> </td><td valign=top> +<ul> <li><a href="#Ragged-Open">H5RAopen</a> <li><a href="#Ragged-Close">H5RAclose</a> </ul> @@ -63,6 +67,21 @@ These functions enable the user to store and retrieve data in ragged arrays. </table> <p> +This version of the Ragged Array interface implements a +two-dimensional array where each row of the array is a different length. +It is intended for applications where the distribution of row lengths +is such that most rows are near an average length with only a few rows +that are significantly shorter or longer. The raw data is split among +two datasets, <code>raw</code> and <code>over</code>: the <code>raw</code> +dataset is a two-dimensional chunked dataset whose width is large enough +to hold most of the rows while the <code>over</code> dataset is a heap +that stores the ends of rows that overflow the first dataset. +A third dataset, called <code>meta</code>, contains one record for each +row and describes what elements, if any, overflow the <code>raw</code> +dataset and where they are stored in the <code>over</code> dataset. +All three datasets are contained in a single group whose name is the +name of the ragged array. +<p> @@ -70,26 +89,49 @@ These functions enable the user to store and retrieve data in ragged arrays. <dl> <dt><strong>Name:</strong> <a name="Ragged-Create">H5RAcreate</a> <dt><strong>Signature:</strong> - <dd><em> </em> <code>H5RAcreate</code>(<em> </em> <code> </code>, - <em> </em> <code> </code>, - <em> </em> <code> </code> + <dd><em>hid_t</em> <code>H5RAcreate</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code>, + <em>hid_t</em> <code>type_id</code>, + <em>hid_t</em> <code>plist_id</code> ) <dt><strong>Purpose:</strong> - <dd> + <dd>Creates a ragged array. <dt><strong>Description:</strong> - <dd><code>H5RAcreate</code> + <dd><code>H5RAcreate</code> creates a new ragged array with the + name specified in <code>name</code>. A ragged array is + implemented as a group containing three datasets. + The dataset <code>raw</code> is a fixed width dataset + which will hold the majority of the data. + The dataset <code>over</code> is a one dimensional heap + which will hold the end of rows which are too long to fit + in <code>raw</code> + Finally, the <code>meta</code> dataset contains information + about the <code>over</code> array. All elements of the + ragged array are stored with the same data type. + <p> + The property list <code>plist_id</code> should contain + information about chunking. The chunk width will determine + the width of the <code>raw</code> dataset while the chunk + length should be such that the total chunk size is + reasonably large since I/O will be performed in units + of chunks). If the <code>plist_id</code> does not have + a chunk size defined (e.g., <code>H5P_DEFAULT</code>) + then this function will fail. <dt><strong>Parameters:</strong> <dl> - <dt><em> </em> <code> </code> - <dd> - <dt><em> </em> <code> </code> - <dd> - <dt><em> </em> <code> </code> - <dd> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>Location identifier of the dataset. + <dt><em>const char *</em><code>name</code> + <dd>The assigned name of the data set to be stored in the + ragged array. + <dt><em>hid_t</em> <code>type_id</code> + <dd>Data type identifier for the ragged array data. + <dt><em>hid_t</em> <code>plist_id</code> + <dd>Property list of the dataset. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a ragged array identifier if successful; + otherwise returns a negative value. </dl> @@ -97,26 +139,27 @@ These functions enable the user to store and retrieve data in ragged arrays. <dl> <dt><strong>Name:</strong> <a name="Ragged-Open">H5RAopen</a> <dt><strong>Signature:</strong> - <dd><em> </em> <code>H5RAopen</code>(<em> </em> <code> </code>, - <em> </em> <code> </code>, - <em> </em> <code> </code> + <dd><em>hid_t</em> <code>H5RAopen</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> ) <dt><strong>Purpose:</strong> - <dd> + <dd>Opens a ragged array. <dt><strong>Description:</strong> - <dd><code>H5RAopen</code> + <dd><code>H5RAopen</code> opens an existing ragged array. + <p> + The name of the array, <code>name</code>, should be the same + that was used when the array was created, i.e., the name of + the group which implements the array. <dt><strong>Parameters:</strong> <dl> - <dt><em> </em> <code> </code> - <dd> - <dt><em> </em> <code> </code> - <dd> - <dt><em> </em> <code> </code> - <dd> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>The location identifier of the dataset. + <dt><em>const char *</em><code>name</code> + <dd>The name of the ragged array. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a ragged array identifier if successful; + otherwise returns a negative value. </dl> @@ -124,26 +167,20 @@ These functions enable the user to store and retrieve data in ragged arrays. <dl> <dt><strong>Name:</strong> <a name="Ragged-Close">H5RAclose</a> <dt><strong>Signature:</strong> - <dd><em> </em> <code>H5RAclose</code>(<em> </em> <code> </code>, - <em> </em> <code> </code>, - <em> </em> <code> </code> - ) + <dd><em>herr_t</em> <code>H5RAclose</code>(<em>hid_t</em> <code>array_id</code>) <dt><strong>Purpose:</strong> - <dd> + <dd>Closes a ragged array. <dt><strong>Description:</strong> - <dd><code>H5RAclose</code> + <dd><code>H5RAclose</code> closes the ragged array specified + with the array identifier <code>array_id</code>. <dt><strong>Parameters:</strong> <dl> - <dt><em> </em> <code> </code> - <dd> - <dt><em> </em> <code> </code> - <dd> - <dt><em> </em> <code> </code> - <dd> + <dt><em>hid_t</em> <code>array_id</code> + <dd>The array identifier for the ragged array to be closed. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -151,14 +188,23 @@ These functions enable the user to store and retrieve data in ragged arrays. <dl> <dt><strong>Name:</strong> <a name="Ragged-Write">H5RAwrite</a> <dt><strong>Signature:</strong> - <dd><em> </em> <code>H5RAwrite</code>(<em> </em> <code> </code>, - <em> </em> <code> </code>, - <em> </em> <code> </code> + <dd><em>herr_t</em> <code>H5RAwrite</code>(<em>hid_t</em> <code>array_id</code>, + <em>hssize_t</em> <code>start_row</code>, + <em>hsize_t</em> <code>nrows</code>, + <em>hid_t</em> <code>type_id</code>, + <em>hsize_t</em> <code>size[/*nrows*/]</code>, + <em>void *</em><code>buf[/*nrows*/]</code> ) <dt><strong>Purpose:</strong> - <dd> + <dd>Writes to a ragged array. <dt><strong>Description:</strong> - <dd><code>H5RAwrite</code> + <dd><code>H5RAwrite</code> writes a contiguous set of rows to a + ragged array beginning at row number <code>start_row</code> + and continuing for <code>nrows</code> rows. + <p> + Each row of the ragged array contains <code>size[]</code> + elements of type <code>type_id</code> and each row is stored + in a buffer pointed to by <code>buf[]</code>. <p> Datatype conversion takes place at the time of a read or write and is automatic. See the @@ -169,16 +215,22 @@ These functions enable the user to store and retrieve data in ragged arrays. supported by the HDF5 libraries. <dt><strong>Parameters:</strong> <dl> - <dt><em> </em> <code> </code> - <dd> - <dt><em> </em> <code> </code> - <dd> - <dt><em> </em> <code> </code> - <dd> + <dt><em>hid_t</em> <code>array_id</code> + <dd>Array identifier for the ragged array to be written to. + <dt><em>hssize_t</em> <code>start_row</code> + <dd>Row at which the write will start. + <dt><em>hsize_t</em> <code>nrows</code> + <dd>Number of rows to be written + <dt><em>hid_t</em> <code>type_id</code> + <dd>Data type identifier for the data to be written. + <dt><em>hsize_t</em> <code>size[/*nrows*/]</code> + <dd>Lengths of the rows to be written. + <dt><em>void *</em><code>buf[/*nrows*/]</code> + <dd>Pointers to buffers containing the data to be written. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -186,14 +238,36 @@ These functions enable the user to store and retrieve data in ragged arrays. <dl> <dt><strong>Name:</strong> <a name="Ragged-Read">H5RAread</a> <dt><strong>Signature:</strong> - <dd><em> </em> <code>H5RAread</code>(<em> </em> <code> </code>, - <em> </em> <code> </code>, - <em> </em> <code> </code> + <dd><em>herr_t</em> <code>H5RAread</code>(<em>hid_t</em> <code>array_id</code>, + <em>hssize_t</em> <code>start_row</code>, + <em>hsize_t</em> <code>nrows</code>, + <em>hid_t</em> <code>type_id</code>, + <em>hsize_t</em> <code>size[/*nrows*/]</code>, + <em>void *</em><code>buf[/*nrows*/]</code> ) <dt><strong>Purpose:</strong> <dd> <dt><strong>Description:</strong> - <dd><code>H5RAread</code> + <dd><code>H5RAread</code> reads the contents of one or more rows + of the ragged array pointed to by <code>array_id</code>. + <p> + The rows to be read begin at row <code>start_row</code> and + continue for <code>nrows</code> rows. + <p> + All raw data is converted to type <code>type_id</code>. + <p> + The caller must allocate the <code>size[]</code> and + <code>buf[]</code> arrays. + <p> + Memory for the data can be allocated by either the caller or + the library. In the former case, the caller should initialize + the <code>buf[]</code> array with pointers to valid memory and + the <code>size[]</code> array with the lengths of the buffers. + In the latter case, the caller should initialize + <code>buf[]</code> with null pointers (the input value of + <code>size[]</code> is irrelevant in this case) and the + library will allocate memory for each row by calling + <code>malloc()</code>. <p> Datatype conversion takes place at the time of a read or write and is automatic. See the @@ -204,16 +278,31 @@ These functions enable the user to store and retrieve data in ragged arrays. supported by the HDF5 libraries. <dt><strong>Parameters:</strong> <dl> - <dt><em> </em> <code> </code> - <dd> - <dt><em> </em> <code> </code> - <dd> - <dt><em> </em> <code> </code> - <dd> + <dt><em>hid_t</em> <code>array_id</code> + <dd>Array identifier for the ragged array to be read from. + <dt><em>hssize_t</em> <code>start_row</code> + <dd>Row at which the read will start. + <dt><em>hsize_t</em> <code>nrows</code> + <dd>Number of rows to be read + <dt><em>hid_t</em> <code>type_id</code> + <dd>Data type identifier for the data to be read. + <dt><em>hsize_t</em> <code>size[/*nrows*/]</code> + <dd>Lengths of the rows to be read. + <dt><em>void *</em><code>buf[/*nrows*/]</code> + <dd>Pointers to buffers into which the data is to be read. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful. + The values of the <code>size[]</code> array will be the + true length of each row. If a row is longer than the + caller-allocated length, then <code>size[]</code> will + contain the true length of the row although not all elements + of that row will be stored in the buffer. + <p> + Returns a negative value on failure. The <code>buf[]</code> + array will contain it's original pointers (null or otherwise), + although the caller-supplied buffers may have been modified. + The <code>size[]</code> array may also have been modified. </dl> @@ -226,7 +315,9 @@ These functions enable the user to store and retrieve data in ragged arrays. <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> +<a href="RM_H5R.html">H5R</a> H5RA <a href="RM_H5S.html">H5S</a> <a href="RM_H5T.html">H5T</a> @@ -242,7 +333,7 @@ H5RA <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 1 September 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/RM_H5S.html b/doc/html/RM_H5S.html index d0ed17a..5d34684 100644 --- a/doc/html/RM_H5S.html +++ b/doc/html/RM_H5S.html @@ -14,7 +14,10 @@ HDF5/H5S Draft API Specification <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> +<a href="RM_H5R.html">H5R</a> +<a href="RM_H5RA.html">H5RA</a> H5S <a href="RM_H5T.html">H5T</a> <a href="RM_H5Z.html">H5Z</a> @@ -117,7 +120,7 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <dt><strong>Returns:</strong> <dd>Returns a dataspace identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -156,7 +159,7 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <dt><strong>Returns:</strong> <dd>Returns a dataspace identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -180,7 +183,7 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <dt><strong>Returns:</strong> <dd>Returns a dataspace identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -229,8 +232,8 @@ of the <cite>HDF5 User's Guide.</cite>. elements being selected. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -256,8 +259,8 @@ of the <cite>HDF5 User's Guide.</cite>. selection is being made. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -278,8 +281,8 @@ of the <cite>HDF5 User's Guide.</cite>. selection is being reset. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -303,7 +306,7 @@ of the <cite>HDF5 User's Guide.</cite>. <dt><strong>Returns:</strong> <dd>Returns <tt>TRUE</tt> if the selection is contained within the extent and <tt>FALSE</tt> if it is not. - Returns <tt>FAIL</tt> (<tt>-1</tt>) on error conditions + Returns returns a negative value on error conditions such as the selection or extent not being defined. </dl> @@ -334,7 +337,7 @@ of the <cite>HDF5 User's Guide.</cite>. <dl> <dt><strong>Name:</strong> <a name="Dataspace-SelectNpoints">H5Sget_select_npoints</a> <dt><strong>Signature:</strong> - <dd><em>hsize_t</em> <code>H5Sget_select_npoints</code>(<em>hid_t</em> <code>space_id</code>) + <dd><em>hssize_t</em> <code>H5Sget_select_npoints</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> <dd>Determines the number of elements in a dataspace. <dt><strong>Description:</strong> @@ -347,7 +350,7 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <dt><strong>Returns:</strong> <dd>Returns the number of elements in the selection if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -368,7 +371,7 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <dt><strong>Returns:</strong> <dd>Returns the number of dimensions in the dataspace if successful; - otherwise FAIL (-1) + otherwise returns a negative value. </dl> @@ -397,7 +400,7 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <dt><strong>Returns:</strong> <dd>Returns the number of dimensions in the dataspace if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -467,7 +470,7 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <dt><strong>Returns:</strong> <dd>Returns a dataspace identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -489,7 +492,7 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <dt><strong>Returns:</strong> <dd>Returns TRUE or FALSE if Successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -521,8 +524,8 @@ of the <cite>HDF5 User's Guide.</cite>. <dd>IN: The offset at which to position the selection. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -574,8 +577,8 @@ of the <cite>HDF5 User's Guide.</cite>. the extent is copied. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -596,8 +599,8 @@ of the <cite>HDF5 User's Guide.</cite>. the extent is to be removed. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -690,8 +693,8 @@ I/O is performed. <dd>IN: Size of block in hyperslab. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -714,8 +717,8 @@ I/O is performed. <dd>Identifier of dataspace to release. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -728,7 +731,10 @@ I/O is performed. <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> +<a href="RM_H5R.html">H5R</a> +<a href="RM_H5RA.html">H5RA</a> H5S <a href="RM_H5T.html">H5T</a> <a href="RM_H5Z.html">H5Z</a> @@ -743,7 +749,7 @@ H5S <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 1 September 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/RM_H5T.html b/doc/html/RM_H5T.html index 086b9cc..672ec32 100644 --- a/doc/html/RM_H5T.html +++ b/doc/html/RM_H5T.html @@ -14,7 +14,10 @@ HDF5/H5T Draft API Specification <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> +<a href="RM_H5R.html">H5R</a> +<a href="RM_H5RA.html">H5RA</a> <a href="RM_H5S.html">H5S</a> H5T <a href="RM_H5Z.html">H5Z</a> @@ -151,7 +154,7 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl </dl> <dt><strong>Returns:</strong> <dd>Returns a named datatype identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -181,8 +184,8 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl <dd>A datatype identifier. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -208,7 +211,7 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl </dl> <dt><strong>Returns:</strong> <dd>The successful return values are TRUE if committed, else FALSE. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -256,8 +259,8 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl <dd>Identifier of the datatype of the new member. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -334,8 +337,8 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl <dd>Optional background buffer. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -367,8 +370,8 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl <dd>Overflow function. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -424,7 +427,7 @@ H5Tget_overflow () </dl> <dt><strong>Returns:</strong> <dd>Returns datatype identifier if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -511,7 +514,7 @@ H5Tget_overflow () </dl> <dt><strong>Returns:</strong> <dd>Returns a datatype identifier if successful; - otherwise FAIL (-1) + otherwise returns a negative value </dl> @@ -537,7 +540,7 @@ H5Tget_overflow () <dt><strong>Returns:</strong> <dd>When successful, returns TRUE if the datatype identifiers refer to the same datatype, else FALSE. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -562,8 +565,8 @@ H5Tget_overflow () <dd>Identifier of datatype to lock. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -647,8 +650,8 @@ H5Tget_overflow () <dd>Size in bytes to modify datatype. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -712,8 +715,8 @@ H5Tget_overflow () <dd>Byte ordering constant. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -769,8 +772,8 @@ H5Tget_overflow () <dd>Number of bits of precision for datatype. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -913,8 +916,8 @@ zero. <dd>Offset of first significant bit. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -951,8 +954,8 @@ zero. bit padding type. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -986,8 +989,8 @@ zero. <dd>Padding type for most-significant bits. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1044,8 +1047,8 @@ zero. <dd>Sign type. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1081,8 +1084,8 @@ zero. <dd>OUT: Pointer to location to return size of mantissa in bits. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1120,8 +1123,8 @@ zero. <dd>Size of mantissa in bits. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1165,8 +1168,8 @@ zero. <dd>Exponent bias value. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1228,8 +1231,8 @@ zero. <dd>Mantissa normalization type. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1295,8 +1298,8 @@ zero. <dd>Padding type. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1353,8 +1356,8 @@ zero. <dd>Character set type. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1415,8 +1418,8 @@ zero. <dd>String padding type. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1437,7 +1440,7 @@ zero. </dl> <dt><strong>Returns:</strong> <dd>Returns number of members datatype has if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -1503,7 +1506,7 @@ zero. <dt><strong>Returns:</strong> <dd>Returns the number of dimensions, a number from 0 to 4, if successful. - Otherwise returns FAIL (-1). + Otherwise returns a negative value. </dl> @@ -1529,7 +1532,7 @@ zero. <dt><strong>Returns:</strong> <dd>Returns the identifier of a copy of the datatype of the field if successful; - otherwise FAIL (-1). + otherwise returns a negative value. </dl> @@ -1567,8 +1570,8 @@ zero. <dd>Datatype identifier of the field to insert. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1589,8 +1592,8 @@ zero. <dd>Identifier of datatype to modify. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1638,8 +1641,8 @@ zero. <dd>Function to convert between source and destination datatypes. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1681,8 +1684,8 @@ zero. <dd>Function to convert between source and destination datatypes. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1711,8 +1714,8 @@ zero. <dd>Function to remove from conversion paths. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1734,8 +1737,8 @@ zero. <dd>Identifier of datatype to release. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -1748,7 +1751,10 @@ zero. <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> +<a href="RM_H5R.html">H5R</a> +<a href="RM_H5RA.html">H5RA</a> <a href="RM_H5S.html">H5S</a> H5T <a href="RM_H5Z.html">H5Z</a> @@ -1763,7 +1769,7 @@ H5T <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 2 September 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/RM_H5Z.html b/doc/html/RM_H5Z.html index 5cdc5c8..337552e 100644 --- a/doc/html/RM_H5Z.html +++ b/doc/html/RM_H5Z.html @@ -14,7 +14,10 @@ HDF5/H5Z Draft API Specification <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> +<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> H5Z @@ -94,8 +97,8 @@ See <a href="Compression.html"><cite>Compression</cite></a> in the <dd>Uncompression method. </dl> <dt><strong>Returns:</strong> - <dd>Returns SUCCEED (0) if successful; - otherwise FAIL (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. </dl> @@ -108,7 +111,10 @@ See <a href="Compression.html"><cite>Compression</cite></a> in the <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> +<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> H5Z @@ -123,7 +129,7 @@ H5Z <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 14 July 1998 +Last modified: 27 October 1998 </body> </html> diff --git a/doc/html/Ragged.html b/doc/html/Ragged.html index 42e6e0d..fa3b61e 100644 --- a/doc/html/Ragged.html +++ b/doc/html/Ragged.html @@ -157,7 +157,7 @@ Last modified: Fri Aug 28 14:27:19 EDT 1998 <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> </address> -Last modified: 8 September 1998 +Last modified: 21 October 1998 </body> </html> diff --git a/doc/html/Tools.html b/doc/html/Tools.html index bf44249..06aa2b7 100644 --- a/doc/html/Tools.html +++ b/doc/html/Tools.html @@ -14,10 +14,10 @@ HDF5/Tools Draft API Specification <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> -<!-- +<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> @@ -64,40 +64,56 @@ These tools enable the user to examine HDF5 files interactively. [-a </code><em>names</em><code>] [-d </code><em>names</em><code>] [-g </code><em>names</em><code>] - [-l </code><em>names</em><code>] </code> + [-l </code><em>names</em><code>] + [-t </code><em>names</em><code>] </code> <em>file</em> <dt><strong>Purpose:</strong> <dd>Displays HDF5 file contents. <dt><strong>Description:</strong> <dd><code>h5dump</code> enables the user to interactively examine the contents of an HDF5 file and dump those contents, - in human readable form, to an ASCII file or to other tools. + in human readable form, to an ASCII file. <p> <code>h5dump</code> displays HDF5 file content on standard output. It may display the content of the whole HDF5 file or selected objects, which can be groups, - datasets, links, or attributes. + datasets, links, attributes, or data types. <p> The <code>-header</code> option displays object - header information only and must appear before the - <code>-a</code>, <code>-d</code>, <code>-g</code>, or - <code>-l</code> options. + header information only. + <p> + Names are the absolute names of the objects. + <code>h5dump</code> displays objects in the order same as the + command order. If a name does not start with a slash, + <code>h5dump</code> begins searching for the specified object + starting at the root group. <p> - Native data types created in one machine are displayed with native - names when <code>h5dump</code> runs in the same machine type. But when - <code>h5dump</code> runs in a different machine type, it displays the - native data types with standard type names. This will be changed in the - next release to always display with standard type names. + If an object is hard linked with multiple names, + <code>h5dump</code> displays the content of the object in the + first occurrence. Only the link information is displayed in + later occurrences. <p> - The <code>h5dump</code> output is described in detail in - <a href="../html/ddl.html">DDL</a>, the <cite>Data Description - Language</cite> document. + <code>h5dump</code> assigns a name for any unnamed data type in + the form of <code>#</code><em>oid1</em><code>:</code><em>oid2</em>, + where <em>oid1</em> and <em>oid2</em> are the object identifiers + assigned by the library. The unnamed types are displayed within + the root group. + <p> + Data types are displayed with standard type names. For example, + if a data set is created with <code>H5T_NATIVE_INT</code> type + and the standard type name for integer on that machine is + <code>H5T_STD_I32BE</code>, <code>h5dump</code> displays + <code>H5T_STD_I32BE</code> as the type of the data set. + <p> + The <code>h5dump</code> output is described in detail in the + <a href="DDL.html"><cite>DDL for HDF5</cite></a>, the + <cite>Data Description Language</cite> document. <dt><strong>Options and Parameters:</strong> <dl> <dt><code>-h</code> - <dd>Print information on this command. + <dd>Prints information on this command. <dt><code>-bb</code> - <dd>Displays the content of boot block. The default is + <dd>Displays the contents of the boot block. The default is not to display. <dt><code>-header</code> <dd>Displays header information only; no data is displayed. @@ -106,35 +122,44 @@ These tools enable the user to examine HDF5 files interactively. <dt><code>-d</code> <em>names</em> <dd>Displays the specified dataset(s). <dt><code>-g</code> <em>names</em> - <dd>Displays all the objects within the specified group(s). + <dd>Displays the specified group(s) and all the members. <dt><code>-l</code> <em>names</em> - <dd>Displays the specified link value(s). + <dd>Displays the values of the specified soft link(s). + <dt><code>-t</code> <em>names</em> + <dd>Displays the specified named data type(s). <dt><em>file</em> <dd>The file to be examined. </dl> <dt><strong>Current Status:</strong> - <dd>The current version of <code>h5dump</code> can display the - following types of information: + <dd>The current version of <code>h5dump</code> displays the + following information: + <ul> + <li>Group <ul> - <li>Group name - <li>Attribute name, data type, data space, and data - <li>Dataset name, data type, data space, and data - <li>Soft link name, link value + <li>group attributes + <li>group member </ul> - - <dd>Limitions in the current implementaion include the - following: + <li>Dataset + <ul> + <li>dataset attributes + <li>data type + <li>data space + <li>data + </ul> + <li>Data type <ul> - <li>Only one file is displayed at a time (file families are - not supported). - <li>The whole file content is displayed (none of above - options are supported). - <li>Compound data types are not yet supported. - <li>Complex data spaces are not yet supported. + <li>scalar type + <li>transient type + <li>named type + <li>unnamed type + </ul> + <li>Simple data space + <li>Soft link + <li>Hard link </ul> <dt><strong>See Also:</strong> <dd>HDF5 Data Description Language syntax - (<a href="../html/ddl.html">DDL</a>) + (<a href="DDL.html"><cite>DDL for HDF5</cite></a>) </dl> @@ -241,10 +266,10 @@ These tools enable the user to examine HDF5 files interactively. <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> -<!-- +<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> @@ -259,7 +284,7 @@ Tools <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 9 September 1998 +Last modified: 27 October 1998 </body> </html> |