diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 1998-07-15 04:37:39 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 1998-07-15 04:37:39 (GMT) |
| commit | 3e213ecf064638989c816ba3a10b3b6c6307fdad (patch) | |
| tree | 46469ba129015faaf4d275b20f8f2b033c1461d6 /doc/src | |
| parent | 3a4ad842e1fde72698b45f5d143b46076a643756 (diff) | |
| download | hdf5-3e213ecf064638989c816ba3a10b3b6c6307fdad.zip hdf5-3e213ecf064638989c816ba3a10b3b6c6307fdad.tar.gz hdf5-3e213ecf064638989c816ba3a10b3b6c6307fdad.tar.bz2 | |
[svn-r502] HDF5 Reference Manual
Final updates for Alpha2.
All currently-implemented functions added.
Technical content verified.
Diffstat (limited to 'doc/src')
| -rwxr-xr-x | doc/src/Glossary.html | 50 | ||||
| -rwxr-xr-x | doc/src/RM_H5.html | 220 | ||||
| -rw-r--r-- | doc/src/RM_H5A.html | 40 | ||||
| -rw-r--r-- | doc/src/RM_H5D.html | 39 | ||||
| -rw-r--r-- | doc/src/RM_H5E.html | 38 | ||||
| -rw-r--r-- | doc/src/RM_H5F.html | 241 | ||||
| -rw-r--r-- | doc/src/RM_H5Front.html | 256 | ||||
| -rw-r--r-- | doc/src/RM_H5G.html | 309 | ||||
| -rw-r--r-- | doc/src/RM_H5P.html | 52 | ||||
| -rw-r--r-- | doc/src/RM_H5S.html | 470 | ||||
| -rw-r--r-- | doc/src/RM_H5T.html | 898 |
11 files changed, 1456 insertions, 1157 deletions
diff --git a/doc/src/Glossary.html b/doc/src/Glossary.html index 58e0b00..31b2db6 100755 --- a/doc/src/Glossary.html +++ b/doc/src/Glossary.html @@ -1,12 +1,33 @@ <html><head><title> HDF5 Draft Glossary -</title></head><body> +</title></head> + +<body> + +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +Glossary +</center> +<hr> <center> <h1>HDF5 Glossary</h1> </center> -A glossary of data-types used in the HDF5 APIs. +<i>(<b>Under construction!</b> + This is the bare beginning of a Glossary to accompany the HDF5 documentation; + it is by no means complete.)</i> <ol type=A> <li><a href="#Glossary-Basic">Basic Types</a> @@ -51,3 +72,28 @@ the types below may change radically en route to a final API... <li>hlen_t - (64-bit?) length on disk in bytes </ul> +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +Glossary +</center> +<hr> + +<address> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> + +<br> +Last modified: 14 July 1998 + +</body> +</html> diff --git a/doc/src/RM_H5.html b/doc/src/RM_H5.html new file mode 100755 index 0000000..8b2ab70 --- /dev/null +++ b/doc/src/RM_H5.html @@ -0,0 +1,220 @@ +<html> +<head><title> +HDF5/H5 Draft API Specification +</title></head> + +<body> + +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +H5 +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + +<center> +<h1>H5: General Library Functions</h1> +</center> + +These functions serve general-purpose needs of the HDF5 library +and it users. + +<table border=0> +<tr><td valign=top> +<ul> + <li><a href="#Library-Open">H5open</a> + <li><a href="#Library-Close">H5close</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Library-Version">H5version</a> + <li><a href="#Library-VersCheck">H5vers_check</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Library-DontAtExit">H5dont_atexit</a> +</ul> +</td></tr> +</table> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Library-Open">H5open</a> +<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. +<dt><strong>Description:</strong> + <dd><code>H5open</code> initialize the library. This function is + normally called automatically, but if you find that an + HDF5 library function is failing inexplicably, try calling + this function first. +<dt><strong>Parameters:</strong> + <dl> + <dt>None. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Library-Close">H5close</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5close</code>(<em>void</em>) +<dt><strong>Purpose:</strong> + <dd>Flushes all data to disk, closes file identifiers, and cleans up memory. +<dt><strong>Description:</strong> + <dd><code>H5close</code> flushes all data to disk, + closes all file identifiers, and cleans up all memory used by + the library. This function is generall called when the + application calls <code>exit</code>, but may be called earlier + in event of an emergency shutdown or out of desire to free all + resources used by the HDF5 library. +<dt><strong>Parameters:</strong> + <dl> + <dt>None. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Library-DontAtExit">H5dont_atexit</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5dont_atexit</code>(<em>void</em>) +<dt><strong>Purpose:</strong> + <dd>Instructs library not to install <code>atexit</code> cleanup routine. +<dt><strong>Description:</strong> + <dd><code>H5dont_atexit</code> indicates to the library that an + <code>atexit()</code> cleanup routine should not be installed. + The major purpose for this is in situations where the + library is dynamically linked into an application and is + un-linked from the application before <code>exit()</code> gets + called. In those situations, a routine installed with + <code>atexit()</code> would jump to a routine which was + no longer in memory, causing errors. + <p> + In order to be effective, this routine <em>must</em> be called + before any other HDF function calls, and must be called each + time the library is loaded/linked into the application + (the first time and after it's been un-loaded). +<dt><strong>Parameters:</strong> + <dl> + <dt>None. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Library-Version">H5version</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5version</code>(<em>unsigned *</em><code>majnum</code>, + <em>unsigned *</em><code>minnum</code>, + <em>unsigned *</em><code>relnum</code>, + <em>unsigned *</em><code>patnum</code> + ) +<dt><strong>Purpose:</strong> + <dd> +<dt><strong>Description:</strong> + <dd><code>H5version</code> retrieves the major, minor, release, and + patch versions of the library which is linked to the application. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>unsigned *</em><code>majnum</code> + <dd>The major version of the library. + <dt><em>unsigned *</em><code>minnum</code> + <dd>The minor version of the library. + <dt><em>unsigned *</em><code>relnum</code> + <dd>The release number of the library. + <dt><em>unsigned *</em><code>patnum</code> + <dd>The patch number of the library. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Library-VersCheck">H5vers_check</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5vers_check</code>(<em>unsigned *</em><code>majnum</code>, + <em>unsigned *</em><code>minnum</code>, + <em>unsigned *</em><code>relnum</code>, + <em>unsigned *</em><code>patnum</code> + ) +<dt><strong>Purpose:</strong> + <dd> +<dt><strong>Description:</strong> + <dd><code>H5vers_check</code> verifies that the arguments match the + version numbers compiled into the library. This function is intended + to be called from user to verify that the versions of header files + compiled into the application match the version of the HDF5 library. + <p> + Due to the risks of data corruption or segmentation faults, + <code>H5vers_check</code> causes the application to abort if the + version numbers do not match. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>unsigned *</em><code>majnum</code> + <dd>The major version of the library. + <dt><em>unsigned *</em><code>minnum</code> + <dd>The minor version of the library. + <dt><em>unsigned *</em><code>relnum</code> + <dd>The release number of the library. + <dt><em>unsigned *</em><code>patnum</code> + <dd>The patch number of the library. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful. + Upon failure, this function causes the application to abort. +</dl> + + +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +H5 +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + +<address> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> + +<br> +Last modified: 14 July 1998 + +</body> +</html> diff --git a/doc/src/RM_H5A.html b/doc/src/RM_H5A.html index a3b46c1..0c236da 100644 --- a/doc/src/RM_H5A.html +++ b/doc/src/RM_H5A.html @@ -5,6 +5,23 @@ HDF5/H5A Draft API Specification <body> +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +H5A +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + <center> <h1>H5A: Attribute Interface</h1> </center> @@ -55,7 +72,7 @@ is located in the group. How small is "small" is not defined by the library and is up to the user's interpretation. <p> See <a href="Attributes.html"><cite>Attributes</cite></a> in the -<cite>HDF5 User's Guide</cite> for further information. +<a href="H5.user.html"><cite>HDF5 User's Guide</cite></a> for further information. <hr> <dl> @@ -458,14 +475,27 @@ See <a href="Attributes.html"><cite>Attributes</cite></a> in the <hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +H5A +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> <address> -<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> -<br> -<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 6 July 1998 +Last modified: 14 July 1998 </body> </html> diff --git a/doc/src/RM_H5D.html b/doc/src/RM_H5D.html index a9f5189..7b5263d 100644 --- a/doc/src/RM_H5D.html +++ b/doc/src/RM_H5D.html @@ -5,6 +5,23 @@ HDF5/H5D Draft API Specification <body> +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +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_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + <center> <h1>H5D: Datasets Interface</h1> </center> @@ -362,13 +379,27 @@ and set and retrieve their constant or persistent properties. <hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +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_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + <address> -<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> -<br> -<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 8 July 1998 +Last modified: 14 July 1998 </body> </html> diff --git a/doc/src/RM_H5E.html b/doc/src/RM_H5E.html index 4c70b6a..e3c8177 100644 --- a/doc/src/RM_H5E.html +++ b/doc/src/RM_H5E.html @@ -5,6 +5,23 @@ HDF5/H5E Draft API Specification <body> +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +H5E +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + <center> <h1>H5E: Error Interface</h1> </center> @@ -318,14 +335,27 @@ errors within the H5E package. <hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +H5E +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> <address> -<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> -<br> -<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 6 July 1998 +Last modified: 14 July 1998 </body> </html> diff --git a/doc/src/RM_H5F.html b/doc/src/RM_H5F.html index f8e25f4..926d7ba 100644 --- a/doc/src/RM_H5F.html +++ b/doc/src/RM_H5F.html @@ -5,6 +5,23 @@ HDF5/H5F Draft API Specification <body> +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +H5F +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + <center> <h1>H5F: File Interface</h1> </center> @@ -34,160 +51,250 @@ documented below. </td></tr> </table> -<hr> +<hr> <dl> <dt><strong>Name:</strong> <a name="File-Open">H5Fopen</a> <dt><strong>Signature:</strong> <dd><em>hid_t </em><code>H5Fopen</code>(<em>const char *</em><code>name</code>, - <em>uintn</em> <code>flags</code>, - <em>hid_t</em> <code>access_template</code> + <em>unsigned</em> <code>flags</code>, + <em>hid_t</em> <code>access_id</code> ) +<dt><strong>Purpose:</strong> + <dd>Opens an existing file. <dt><strong>Description:</strong> - <dd>This is the primary function for opening existing HDF5 files. - The <code>flags</code> parameter determines the file access mode. - There is no read flag, all open files are implicitily opened for - read access. - All flags may be combined with the '|' (boolean OR operator) to - change the behavior of the file open call. - The <code>access_template</code> parameter is a template containing - additional information required for specific methods of access, - parallel I/O for example. The paramters for access templates are - described in the H5P API documentation. + <dd><code>H5Fopen</code> opens an existing file and is the primary + function for accessing existing HDF5 files. + <p> + The parameter <code>access_id</code> is a file access property + list identifier or <code>H5P_DEFAULT</code> for the default I/O access + parameters. + <p> + The <code>flags</code> argument determines whether writing + to an existing file will be allowed or not. + The file is opened with read and write permission if + <code>flags</code> is set to <code>H5F_ACC_RDWR</code>. + All flags may be combined with the bit-wise OR operator (`|') + to change the behavior of the file open call. + The more complex behaviors of a file's access are controlled + through the file-access property list. + <p> + Files which are opened more than once return a unique identifier + for each <code>H5Fopen()</code> call and can be accessed + through all file identifiers. + <p> + The return value is a file identifier for the open file and it + should be closed by calling <code>H5Fclose()</code> when it is + no longer needed. <dt><strong>Parameters:</strong> <dl> <dt><em>const char *</em><code>name</code> <dd>Name of the file to access. - <dt><em>uintn</em> <code>flags</code> - <dd>File access flags: - <ul><dl> - <dt>H5F_ACC_RDWR - <dd>Allow read and write access to file. - </dl></ul> - <dt><em>hid_t</em><code>access_template</code> - <dd>Template indicating the file access properties. - If parallel file access is desired, this is a collective - call according to the communicator stored in the - access_template. Use 0 for default access template. + <dt><em>unsigned</em> <code>flags</code> + <dd>File access flags. See the <code>H5Fcreate</code> + parameters list for a list of possible values. + <dt><em>hid_t</em> <code>access_id</code> + <dd>Identifier for the file access properties list. </dl> <dt><strong>Returns:</strong> - <dd>A file identifier if successful; + <dd>Returns a file identifier if successful; otherwise FAIL (-1). </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="File-Create">H5Fcreate</a> <dt><strong>Signature:</strong> <dd><em>hid_t </em><code>H5Fcreate</code>(<em>const char *</em><code>name</code>, - <em>uintn</em> <code>flags</code>, - <em>hid_t</em> <code>create_template</code>, - <em>hid_t</em> <code>access_template</code> + <em>unsigned</em> <code>flags</code>, + <em>hid_t</em> <code>create_id</code>, + <em>hid_t</em> <code>access_id</code> ) +<dt><strong>Purpose:</strong> + <dd>Creates HDF5 files. <dt><strong>Description:</strong> - <dd>This is the primary function for opening and creating HDF5 files. - The <code>flags</code> parameter determines whether an existing - file will be overwritten or not. All newly created files are opened - for both reading and writing. - All flags may be combined with the '|' (boolean OR operator) to - change the behavior of the file open call. - The <code>create_template</code> and <code>access_template</code> - parameters are templates containing additional information required - for specific methods of access or particular aspects of the file - to set when creating a file. - The parameters for creation and access templates are - described in the H5P API documentation. + <dd><code>H5Fcreate</code> is the primary function for creating + HDF5 files . + <p> + The <code>flags</code> parameter determines whether an + existing file will be overwritten. All newly created files + are opened for both reading and writing. All flags may be + combined with the bit-wise OR operator (`|') to change + the behavior of the <code>H5Fcreate</code> call. + <p> + The more complex behaviors of file creation and access + are controlled through the file-creation and file-access + property lists. The value of <code>H5P_DEFAULT</code> for + a template value indicates that the library should use + the default values for the appropriate template. Also see + <code>H5Fpublic.h</code> for the list of supported flags. <dt><strong>Parameters:</strong> <dl> <dt><em>const char *</em><code>name</code> <dd>Name of the file to access. <dt><em>uintn</em> <code>flags</code> - <dd>File access flags: + <dd>File access flags. Possible values include: <ul><dl> + <dt>H5F_ACC_RDWR + <dd>Allow read and write access to file. + <dt>H5F_ACC_RDONLY + <dd>Allow read-only access to file. <dt>H5F_ACC_TRUNC - <dd>Truncate file, if it already exists. The file will - be truncated, erasing all data previously stored in - the file. + <dd>Truncate file, if it already exists, + erasing all data previously stored in the file. + <dt>H5F_ACC_EXCL + <dd>Fail if file already exists. + <dt>H5F_ACC_DEBUG + <dd>Print debug information. + <dt>H5P_DEFAULT + <dd>Apply default file access and creation properties. </dl></ul> - <dt><em>hid_t</em><code>create_template</code> - <dd>File creation template ID, used when modifying default file meta-data - <dt><em>hid_t</em><code>access_template</code> - <dd>Template indicating the file access properties. + <dt><em>hid_t</em> <code>create_id</code> + <dd>File creation template identifier, used when modifying + default file meta-data. + <dt><em>hid_t</em> <code>access_id</code> + <dd>File access property list identifier. If parallel file access is desired, this is a collective call according to the communicator stored in the - access_template. Use 0 for default access template. + <code>access_template</code>. + Use <code>0</code> for default access template. </dl> <dt><strong>Returns:</strong> - <dd>An ID (of type <em>hid_t</em>) for the file upon success, - otherwise negative + <dd>Returns a file identifier if successful; + otherwise FAIL (-1). </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="File-IsHDF5">H5Fis_hdf5</a> <dt><strong>Signature:</strong> <dd><em>hbool_t </em><code>H5Fis_hdf5</code>(<em>const char *</em><code>name</code> ) +<dt><strong>Purpose:</strong> + <dd>Determines whether a file is in the HDF5 format. <dt><strong>Description:</strong> - <dd>This function determines whether a file is in the HDF5 format. + <dd><code>H5Fis_hdf5</code> determines whether a file is in + the HDF5 format. <dt><strong>Parameters:</strong> <dl> <dt><em>const char *</em><code>name</code> <dd>File name to check format. </dl> <dt><strong>Returns:</strong> - <dd>TRUE/FALSE/negative + <dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful. + Otherwise returns FAIL (-1). </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="File-GetCreateTemplate">H5Fget_create_template</a> <dt><strong>Signature:</strong> <dd><em>hid_t </em><code>H5Fget_create_template</code>(<em>hid_t</em> <code>file_id</code> ) +<dt><strong>Purpose:</strong> + <dd>Returns a file creation property list identifier. <dt><strong>Description:</strong> - <dd>This function returns an template ID with a copy of the parameters - used to create this file. Useful for duplicating the parameters - when creating another file. + <dd><code>H5Fget_create_template</code> returns a file creation + property list identifier identifying the creation properties + used to create this file. This function is useful for + duplicating properties when creating another file. + <p> + See "File Creation Properties" in + <a href="RM_H5P.html">H5P: Property List Interface</a> + in this reference manual and + "File Creation Properties" + in <a href="Files.html"><cite>Files</cite></a> in the + <cite>HDF5 User's Guide</cite> for + additional information and related functions. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>file_id</code> - <dd>File ID to get creation template of + <dd>Identifier of the file to get creation property list of </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns a file creation property list identifier if successful; + otherwise FAIL (-1). </dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="File-GetAccessTemplate">H5Fget_access_template</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Fget_access_template</code>(<em>hid_t</em> <code>file_id</code>) +<dt><strong>Purpose:</strong> + <dd>Returns a file access property list identifier. +<dt><strong>Description:</strong> + <dd><code>H5Fget_access_template</code> returns the + file access property list identifier of the specified file. + <p> + See "File Access Properties" in + <a href="RM_H5P.html">H5P: Property List Interface</a> + in this reference manual and + "File Access Property Lists" + in <a href="Files.html"><cite>Files</cite></a> in the + <cite>HDF5 User's Guide</cite> for + additional information and related functions. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>file_id</code> + <dd>Identifier of file to get access property list of + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a file access property list identifier if successful; + otherwise FAIL (-1). +</dl> + + <hr> <dl> <dt><strong>Name:</strong> <a name="File-Close">H5Fclose</a> <dt><strong>Signature:</strong> <dd><em>herr_t </em><code>H5Fclose</code>(<em>hid_t</em> <code>file_id</code> ) +<dt><strong>Purpose:</strong> + <dd>Terminates access to an HDF5 file. <dt><strong>Description:</strong> - <dd>This function terminates access to an HDF5 file. If this is the - last file ID open for a file and if access IDs are still in use, + <dd><code>H5Fclose</code> terminates access to an HDF5 file. + If this is the last file identifier open for a file + and if access identifiers are still in use, this function will fail. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>file_id</code> - <dd>File ID to terminate access to. + <dd>Identifier of a file to terminate access to. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> -<hr> <hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +H5F +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> <address> -<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> -<br> -<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 29 June 1998 +Last modified: 14 July 1998 </body> </html> diff --git a/doc/src/RM_H5Front.html b/doc/src/RM_H5Front.html index 374a1ad..9c4e1ce 100644 --- a/doc/src/RM_H5Front.html +++ b/doc/src/RM_H5Front.html @@ -4,6 +4,23 @@ HDF5 Draft API Specification </title></head> <body> +<hr> +<center> +HDF5 Reference Manual +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + <center> <h1>HDF5: API Specification<br>Reference Manual</h1> </center> @@ -13,246 +30,43 @@ tools required to meet specific aspects of the HDF5 data-handling requirements. <ul> -<!-- -<li><a href="#Library">Library</a> - H5<name> - API for global library HDF information/modification. -<ol type=A> - <li><a href="#Library-DontAtExit">H5dont_atexit</a> - <li><a href="#Library-Close">H5close</a> - <li><a href="#Library-Version">H5version</a> -</ol> ---> - +<li><a href="RM_H5.html">Library Functions</a> -- The general-purpose <strong>H5</strong> functions. <li><a href="RM_H5F.html">File Interface</a> -- The <strong>H5F</strong> API for accessing HDF files. -<!-- -<ul type=A> - <li><font size=-2> - ( <a href="RM_H5F.html#File-Open">H5Fopen</a> - <a href="RM_H5F.html#File-Create">H5Fcreate</a> - <a href="RM_H5F.html#File-IsHDF5">H5Fis_hdf5</a> - <a href="RM_H5F.html#File-GetCreateTemplate">H5Fget_create_template</a> - <a href="RM_H5F.html#File-Close">H5Fclose</a> ) - </font> -</ul> ---> - <li><a href="RM_H5P.html">Property List Interface</a> -- The <strong>H5P</strong> API for manipulating object templates. -<!-- -<ul type=A> - <li><font size=-2> - ( <a href="RM_H5P.html#Template-Create">H5Pcreate</a> - <a href="RM_H5P.html#Template-GetClass">H5Pget_class</a> - <a href="RM_H5P.html#Template-Copy">H5Pcopy</a> - <a href="RM_H5P.html#Template-Close">H5Pclose</a> - <a href="RM_H5P.html#Template-GetVersion">H5Pget_version</a> - <a href="RM_H5P.html#Template-SetUserblock">H5Pset_userblock</a> - <a href="RM_H5P.html#Template-GetUserblock">H5Pget_userblock</a> - <a href="RM_H5P.html#Template-SetSizes">H5Pset_sizes</a> - <a href="RM_H5P.html#Template-GetSizes">H5Pget_sizes</a> - <a href="RM_H5P.html#Template-SetMPI">H5Pset_mpi</a> - <a href="RM_H5P.html#Template-GetMPI">H5Pget_mpi</a> - <a href="RM_H5P.html#Template-SetXfer">H5Pset_xfer</a> - <a href="RM_H5P.html#Template-GetXfer">H5Pget_xfer</a> - <a href="RM_H5P.html#Template-SetSymK">H5Pset_sym_k</a> - <a href="RM_H5P.html#Template-GetSymK">H5Pget_sym_k</a> - <a href="RM_H5P.html#Template-SetIstoreK">H5Pset_istore_k</a> - <a href="RM_H5P.html#Template-GetIstoreK">H5Pget_istore_k</a> - <a href="RM_H5P.html#Template-SetLayout">H5Pset_layout</a> - <a href="RM_H5P.html#Template-GetLayout">H5Pget_layout</a> - <a href="RM_H5P.html#Template-SetChunk">H5Pset_chunk</a> - <a href="RM_H5P.html#Template-GetChunk">H5Pget_chunk</a> ) - </font> -</ul> ---> - -<!-- -<li><a href="#Error">Error</a> - H5E<name> - API for error reporting -<ol type=A> - <li><a href="#Error-SetPush">H5Eset_push</a> -</ol> ---> - -<!-- -<li><a href="#Relationships">Relationships</a> - H5R<name> - API for logically linking objects together (ie. attributes). -<ol type=A> - <li><a href="#Relationships-GetNumRelations">H5Rget_num_relations</a> - <li><a href="#Relationships-GetMemberOfOIDs">H5Rget_memberof_oids</a> - <li><a href="#Relationships-GetAttachedOIDs">H5Rget_attached_oids</a> - <li><a href="#Relationships-Attach">H5Rattach_oid</a> -</ol> ---> - <li><a href="RM_H5D.html">Dataset Interface</a> -- The <strong>H5D</strong> API for manipulating scientific datasets. -<!-- -<table border=0 width=100> - <tr><td> </td><td width=200> - <a href="RM_H5D.html#Dataset-Create"><font size=-2>H5Dcreate</font></a> - </td><td> </td><td width=200> - <a href="RM_H5D.html#Dataset-Open"><font size=-2>H5Dopen</font></a> - </td><td> </td><td width=200> - <a href="RM_H5D.html#Dataset-GetSpace"><font size=-2>H5Dget_space</font></a> - </td><td> </td><td width=200> - <a href="RM_H5D.html#Dataset-GetType"><font size=-2>H5Dget_type</font></a> - </td></tr><tr><td></td><td> - <a href="RM_H5D.html#Dataset-GetCreateParms"><font size=-2>H5Dget_create_parms</font></a> - </td><td> </td><td> - <a href="RM_H5D.html#Dataset-Read"><font size=-2>H5Dread</font></a> - </td><td> </td><td> - <a href="RM_H5D.html#Dataset-Write"><font size=-2>H5Dwrite</font></a> - </td><td> </td><td> - <a href="RM_H5D.html#Dataset-Extend"><font size=-2>H5Dextend</font></a> - </td></tr><tr><td></td><td> - <a href="RM_H5D.html#Dataset-Close"><font size=-2>H5Dclose</font></a> -</table> ---> - <li><a href="RM_H5T.html">Datatype Interface</a> -- The <strong>H5T</strong> API for defining dataset element information. -<!-- -<table border=0> -<tr><td valign=top> -<font size=-2> -<ul> - <li><a href="RM_H5T.html#Datatype-Create">H5Tcreate</a> - <li><a href="RM_H5T.html#Datatype-Copy">H5Tcopy</a> - <li><a href="RM_H5T.html#Datatype-Equal">H5Tequal</a> - <li><a href="RM_H5T.html#Datatype-Lock">H5Tlock</a> - <li><a href="RM_H5T.html#Datatype-GetClass">H5Tget_class</a> - <li><a href="RM_H5T.html#Datatype-GetSize">H5Tget_size</a> - <li><a href="RM_H5T.html#Datatype-SetSize">H5Tset_size</a> - <li><a href="RM_H5T.html#Datatype-GetOrder">H5Tget_order</a> - <li><a href="RM_H5T.html#Datatype-SetOrder">H5Tset_order</a> - <li><a href="RM_H5T.html#Datatype-GetPrecision">H5Tget_precision</a> -</ul> -</font> -</td><td> </td><td valign=top> -<font size=-2> -<ul> - <li><a href="RM_H5T.html#Datatype-SetPrecision">H5Tset_precision</a> - <li><a href="RM_H5T.html#Datatype-GetOffset">H5Tget_offset</a> - <li><a href="RM_H5T.html#Datatype-SetOffset">H5Tset_offset</a> - <li><a href="RM_H5T.html#Datatype-GetPad">H5Tget_pad</a> - <li><a href="RM_H5T.html#Datatype-SetPad">H5Tset_pad</a> - <li><a href="RM_H5T.html#Datatype-GetSign">H5Tget_sign</a> - <li><a href="RM_H5T.html#Datatype-SetSign">H5Tset_sign</a> - <li><a href="RM_H5T.html#Datatype-GetFields">H5Tget_fields</a> - <li><a href="RM_H5T.html#Datatype-SetFields">H5Tset_fields</a> - <li><a href="RM_H5T.html#Datatype-GetEbias">H5Tget_ebias</a> -</ul> -</font> -</td><td> </td><td valign=top> -<font size=-2> -<ul> - <li><a href="RM_H5T.html#Datatype-SetEbias">H5Tset_ebias</a> - <li><a href="RM_H5T.html#Datatype-GetNorm">H5Tget_norm</a> - <li><a href="RM_H5T.html#Datatype-SetNorm">H5Tset_norm</a> - <li><a href="RM_H5T.html#Datatype-GetInpad">H5Tget_inpad</a> - <li><a href="RM_H5T.html#Datatype-SetInpad">H5Tset_inpad</a> - <li><a href="RM_H5T.html#Datatype-GetCset">H5Tget_cset</a> - <li><a href="RM_H5T.html#Datatype-SetCset">H5Tset_cset</a> - <li><a href="RM_H5T.html#Datatype-GetStrpad">H5Tget_strpad</a> - <li><a href="RM_H5T.html#Datatype-SetStrpad">H5Tset_strpad</a> - <li><a href="RM_H5T.html#Datatype-GetNmembers">H5Tget_nmembers</a> -</ul> -</font> -</td><td> </td><td valign=top> -<font size=-2> -<ul> - <li><a href="RM_H5T.html#Datatype-GetMemberName">H5Tget_member_name</a> - <li><a href="RM_H5T.html#Datatype-GetMemberOffset">H5Tget_member_offset</a> - <li><a href="RM_H5T.html#Datatype-GetMemberDims">H5Tget_member_dims</a> - <li><a href="RM_H5T.html#Datatype-GetMemberType">H5Tget_member_type</a> - <li><a href="RM_H5T.html#Datatype-Insert">H5Tinsert</a> - <li><a href="RM_H5T.html#Datatype-Pack">H5Tpack</a> - <li><a href="RM_H5T.html#Datatype-RegisterHard">H5Tregister_hard</a> - <li><a href="RM_H5T.html#Datatype-RegisterSoft">H5Tregister_soft</a> - <li><a href="RM_H5T.html#Datatype-Unregister">H5Tunregister</a> - <li><a href="RM_H5T.html#Datatype-Close">H5Tclose</a> -</ul> -</td></tr> -</table> ---> - <li><a href="RM_H5S.html">Dataspace Interface</a> -- The <strong>H5S</strong> API for defining dataset dataspace. -<!-- -<table border=0> -<tr></td><td> </td><td valign=top> -<font size=-2> - <a href="RM_H5S.html#Dataspace-CreateSimple">H5Screate_simple</a> <br> - <a href="RM_H5S.html#Dataspace-Copy">H5Scopy</a> <br> - <a href="RM_H5S.html#Dataspace-GetNpoints">H5Sget_npoints</a> <br> -</ul> -</font> -</td><td> </td><td valign=top> -<font size=-2> - <a href="RM_H5S.html#Dataspace-GetNdims">H5Sget_ndims</a> <br> - <a href="RM_H5S.html#Dataspace-GetDims">H5Sget_dims</a> <br> - <a href="RM_H5S.html#Dataspace-IsSimple">H5Sis_simple</a> <br> -</ul> -</font> -</td><td> </td><td valign=top> -<font size=-2> - <a href="RM_H5S.html#Dataspace-SetSpace">H5Sset_space</a> <br> - <a href="RM_H5S.html#Dataspace-SetHyperslab">H5Sset_hyperslab</a> <br> - <a href="RM_H5S.html#Dataspace-GetHyperslab">H5Sget_hyperslab</a> <br> -</ul> -</font> -</td><td> </td><td valign=top> -<font size=-2> - <a href="RM_H5S.html#Dataspace-Close">H5Sclose</a> <br> -</ul> -</td></tr> -</table> ---> - <li><a href="RM_H5G.html">Group Interface</a> -- The <strong>H5G</strong> API for creating physical groups of objects on disk. -<!-- -<ol type=A> - <li><a href="RM_H5G.html#Group-Create">H5Gcreate</a> - <li><a href="RM_H5G.html#Group-Open">H5Gopen</a> - <li><a href="RM_H5G.html#Group-Set">H5Gset</a> - <li><a href="RM_H5G.html#Group-Push">H5Gpush</a> - <li><a href="RM_H5G.html#Group-Pop">H5Gpop</a> - <li><a href="RM_H5G.html#Group-Close">H5Gclose</a> -sub-commented-------- - <li><a href="RM_H5G.html#Group-GetNumContents">get_num_contents</a> - <li><a href="RM_H5G.html#Group-GetContentInfo">get_content_info</a> - <li><a href="RM_H5G.html#Group-GetContentInfoMult">get_content_info_mult</a> - <li><a href="RM_H5G.html#Group-GetOIDByName">get_oid_by_name</a> - <li><a href="RM_H5G.html#Group-GetOIDByIndex">get_oid_by_index</a> - <li><a href="RM_H5G.html#Group-GetNameByOID">get_name_by_oid</a> - <li><a href="RM_H5G.html#Group-GetNameByIndex">get_name_by_index</a> - <li><a href="RM_H5G.html#Group-InsertItem">insert_item</a> - <li><a href="RM_H5G.html#Group-InsertItemMult">insert_item_mult</a> - <li><a href="RM_H5G.html#Group-RemoveItem">remove_item</a> - <li><a href="RM_H5G.html#Group-RemoveItemMult">remove_item_mult</a> ---------sub-commented -</ol> ---> - <li><a href="RM_H5E.html">Error Interface</a> -- The <strong>H5E</strong> API for error handling. <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="Glossary.html">Glossary</a> -- A glossary of data-types used in the APIs. -<!-- -<ol type=A> - <li><a href="Glossary.html#Glossary-Basic">Basic Types</a> - <li><a href="Glossary.html#Glossary-Complex">Complex Types</a> - <li><a href="Glossary.html#Glossary-DiskIO">Disk I/O Types</a> -</ol> ---> </ul> <hr> +<center> +HDF5 Reference Manual +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> <address> -<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> -<br> -<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 29 June 1998 +Last modified: 14 July 1998 </body> </html> diff --git a/doc/src/RM_H5G.html b/doc/src/RM_H5G.html index b4baa99..55b7d5b 100644 --- a/doc/src/RM_H5G.html +++ b/doc/src/RM_H5G.html @@ -5,6 +5,23 @@ HDF5/H5G Draft API Specification <body> +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +H5G +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + <center> <h1>H5G: Group Interface</h1> </center> @@ -596,287 +613,27 @@ then be trivial. <hr> -<hr> -</b>UNUSED PORTIONS OF EMAIL NOTES.</b> -<br> -<code>....</code> in left margin indicates where material was pulled out for use. -<HR> -<HR> -<pre> - -Hi Elena, here's a hodgepodge of stuff from html documents and -previous e-mails to answer your questions. Let me know if you need -further clarification. - -.... -.... [H5Gmove and H5Gunlink "NYI" comments were here] -.... - -Elena> We need little bit more user-friendly description of the H5Gstat and -Elena> H5Giterate functions. - ->From a Mar 31 e-mail... - -Robb> -.... -.... [H5Giterate was here] -.... -Robb> -Robb> -Robb> Group Information Functions: -.... -.... [H5Gstat was here] -.... -Robb> -Robb> herr_t H5Gname(hid_t group_id, char *name, size_t max_name_len); -Robb> -Robb> This function retrieves the name of the group for a group ID. The -Robb> name is returned in 'name' up to the length specified in 'max_name_len'. -Robb> -.... -.... [H5Gget_linkval was here] -.... -Robb> -Robb> H5Giterate example #1: The operator just looks at the member name and if it has an -Robb> `X' in it then it returns 1, otherwise return zero. Returning 1 (or any -Robb> positive value) causes the iterator to immediately return that value. If -Robb> none of the operators return 1 then the iterator eventually returns zero. -Robb> -Robb> 1 herr_t -Robb> 2 any_X (hid_t group_id/*unused*/, -Robb> 4 const char *member_name, -Robb> 5 void *op_data/*unused*/) -Robb> 6 { -Robb> 7 return strchr(member_name,'X') ? 1 : 0; -Robb> 8 } -Robb> -Robb> The iterator is invoked as: -Robb> -Robb> 9 int elmt=0; -Robb> 10 herr_t found = H5Giterate(file_id, "/foo", &elmt, any_X, NULL); -Robb> 11 -Robb> 12 if (found<0) { -Robb> 13 printf ("Error iterating through group, at member %d\n", elmt); -Robb> 14 } else if (found) { -Robb> 15 printf ("Yes, member %d has an `X' in the name\n", elmt); -Robb> 16 } else { -Robb> 17 printf ("No member name contains an `X'\n"); -Robb> 18 } -Robb> -Robb> H5Giterate example #2: An iterator to find an object whose name contains an `X' -Robb> This is the same as Example 1 except the operator also returns the name -Robb> that contains the `X'. We do this by passing a pointer to a `char*' as the -Robb> operator data and the operator will initialize that `char*' by strdup'ing -Robb> the object name. -Robb> -Robb> 1 herr_t -Robb> 2 find_X (hid_t group_id/*unused*/, -Robb> 4 const char *member_name, -Robb> 5 void *op_data/*out*/) -Robb> 6 { -Robb> 7 if (strchr(member_name,'X')) { -Robb> 8 *((char**)op_data) = strdup(member_name); -Robb> 9 return 1; -Robb> 10 } -Robb> 11 return 0; -Robb> 12 } -Robb> -Robb> To print all the names with an `X' the iterator is invoked -Robb> repeatedly until it returns zero. -Robb> -Robb> 13 int elmt = 0; -Robb> 14 char *name; -Robb> 15 while (H5Giterate(file_id, "/foo", &elmt, find_X, &name)) { -Robb> 16 puts (name); -Robb> 17 free (name); -Robb> 18 } -Robb> -Robb> H5Giterate example #3: Print all names that contain the specified character. -Robb> This is the same as Example 2 except we have to pass data into the operator -Robb> as well as get data out. We create a struct that contains the input data -Robb> (character to look for) and a slot for the output data (the name) and pass -Robb> that as the operator data. -Robb> -Robb> 1 typedef struct { -Robb> 2 char look_for; -Robb> 3 char *name; -Robb> 4 } find_char_t; -Robb> 5 -Robb> 6 herr_t -Robb> 7 find_char (hid_t group_id/*unused*/, -Robb> 9 const char *member_name, -Robb> 10 find_char_t *op_data/*in,out*/) -Robb> 11 { -Robb> 13 if (strchr(member_name, op_data->look_for)) { -Robb> 14 op_data->name = strdup (member_name); -Robb> 15 return 1; -Robb> 16 } -Robb> 17 return 0; -Robb> 18 } -Robb> -Robb> To print all names that have a `Y' one would say -Robb> -Robb> 19 find_char_t op_data; -Robb> 20 int elmt = 0; -Robb> 21 op_data->look_for = 'Y'; -Robb> 22 while (H5Giterate(file_id, "/foo", &elmt, find_X, &op_data)) { -Robb> 23 puts (op_data->name); -Robb> 24 free (op_data->name); -Robb> 25 } -Robb> -Robb> H5Giterate example #4: Efficient version of Example 3. -Robb> Examples 2 and 3 weren't too efficient because we kept interrupting the -Robb> iterator and it had to start over, albeit from the middle of the search. If -Robb> we could allow the iterator to go further then we wouldn't end up scanning -Robb> through the leaf nodes of the symbol table so often (searching for a -Robb> particular index, n, in a B-tree is an O(n) operation). -Robb> The H5Glist() function defined earlier returns the names of all the group -Robb> members which belong to a certain class, H5G_ALL, H5G_DATASET, or H5G_GROUP. -Robb> This example shows how to implement that functionality. -Robb> First we need a struct to describe the operator data and it's return -Robb> value(s). These correspond to the arguments presented for H5Glist, whose -Robb> definition is at the end of this example. (Since most of the work is done by -Robb> the operator we have to pass all this stuff back and forth through the -Robb> iterator). -Robb> -Robb> 1 typedef struct { -Robb> 2 size_t name_heap_size; -Robb> 3 char *name_heap; -Robb> 4 unsigned max_entries; -Robb> 5 char *names[]; -Robb> 6 int type; -Robb> 7 unsigned cur_entries; /* How many names read so far */ -Robb> 8 size_t cur_heap_size; /* How large is the heap */ -Robb> 9 } H5G_list_t; -Robb> -Robb> The operator checks if an object is the right type, and if so adds it to -Robb> the return value arrays in the op_data struct. If the arrays become full -Robb> then the operator returns 1 to stop the iterator. The H5*isa() functions -Robb> return true iff the named object is of the * type (sans error handling). -Robb> -Robb> 10 herr_t -Robb> 11 H5G_list_op (hid_t grp_id, const char *memb_name, -Robb> 12 H5G_list_t *op_data) -Robb> 13 { -Robb> 14 char *out_name; -Robb> 15 -Robb> 16 if (H5G_ALL==op_data->type || -Robb> 17 (H5G_DATASET==op_data->type && H5Disa(grp_id,memb_name)) || -Robb> 18 (H5G_GROUP==op_data->type && H5Gisa(grp_id, memb_name))) { -Robb> 19 -Robb> 20 /* Is there enough room for the name in the heap? */ -Robb> 21 if (op_data->cur_heap_size + strlen(memb_name) + 1 > -Robb> 22 op_data->name_heap_size) { -Robb> 23 return 2; /*try again later, see lines 59-62*/ -Robb> 24 } -Robb> 25 -Robb> 26 /* Add name to op_data return value arrays */ -Robb> 27 out_name = op_data->name_heap + op_data->cur_heap_size; -Robb> 28 strcpy (out_name, memb_name); -Robb> 29 op_data->names[op_data->cur_entries] = out_name; -Robb> 30 op_data->cur_heap_size += strlen(memb_name) + 1; -Robb> 31 -Robb> 32 /* Is the output full? */ -Robb> 33 if (op_data->cur_entries >= op_data->max_entries) { -Robb> 34 return 1; -Robb> 35 } -Robb> 36 } -Robb> 37 return 0; -Robb> 38 } -Robb> -Robb> And finally, the definition of H5Glist(): -Robb> -Robb> 39 int -Robb> 40 H5Glist (hid_t group_id, size_t name_heap_size, char *name_heap, -Robb> 41 int *start_idx, unsigned max_entries, char *names[], -Robb> 42 int type) -Robb> 43 { -Robb> 44 H5G_list_t op_data; -Robb> 45 herr_t status; -Robb> 46 -Robb> 47 op_data->name_heap_size = name_heap_size; -Robb> 48 op_data->name_heap = name_heap; -Robb> 49 op_data->max_entries = max_entries; -Robb> 50 op_data->names = names; -Robb> 51 op_data->type = type; -Robb> 52 op_data->cur_entries = 0; -Robb> 53 op_data->cur_heap_size = 0; -Robb> 54 -Robb> 55 if (0==cur_entries) return 0; -Robb> 56 status = H5Giterate (group_id, ".", start_idx, H5G_list_op, -Robb> 57 &op_data); -Robb> 58 -Robb> 59 if (2==status && 0==op_data->cur_entries) { -Robb> 60 return -1; /*heap not large enough for even one name*/ -Robb> 61 } else if (2==status) { -Robb> 62 --*start_idx; /*heap overflow, try again later*/ -Robb> 63 } else if (status<0) { -Robb> 64 return status; /*iterator or operator error*/ -Robb> 65 } -Robb> 66 return op_data->cur_entries; -Robb> 67 } -Robb> -Robb> The only other really interesting thing in this example are lines 23, 61, -Robb> and 62. We don't know if the name heap will overflow until we find a name to -Robb> put there. And then if it does, we need to be able to restart the iterator at -Robb> the entry that failed instead of the following entry. -Robb> -Robb> H5Giterate example #5: Print all the names of objects in a group, without any -Robb> buffers. -Robb> --------------------- -Robb> -Robb> herr_t print_names (hid_t grp_id, const char *name, void *opdata) -Robb> { -Robb> puts (name); -Robb> return 0; -Robb> } -Robb> -Robb> { -Robb> H5Giterate (file_id, "/foo/bar", NULL, print_names, NULL); -Robb> } - -Elena> I believe there is a typo in the H5Pget_layout function in the source -Elena> code. Second argument ( H5D_layout_t *layout is missing....) - -It's returned by value, not reference. It returns only the class of -layout and then, based on the class, you must call some other H5Pget -function like H5Pget_chunk() like this: - - hid_t dcpl; /*dataset creation property list*/ - hsize_t dims[32]; /*chunk dimensions*/ - ... - switch (H5Pget_layout(dcpl)) { - case H5D_CHUNKED: - H5Pget_chunk(dcpl, NELMTS(dims), dims); - break; - ... - case H5D_LAYOUT_ERROR: - ... - ... - } - - -Quincy and html> -Quincy and html> -.... -.... [Datatype material move to H5T.html] -.... -Quincy and html> -Quincy and html> - - -</pre> -<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +H5G +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> <hr> -<hr> <address> -<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> -<br> -<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 8 July 1998 +Last modified: 14 July 1998 </body> </html> diff --git a/doc/src/RM_H5P.html b/doc/src/RM_H5P.html index 90d6920..5329ec1 100644 --- a/doc/src/RM_H5P.html +++ b/doc/src/RM_H5P.html @@ -5,6 +5,23 @@ HDF5/H5P Draft API Specification <body> +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +H5P +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + <center> <h1>H5P: Property List Interface</h1> </center> @@ -115,19 +132,23 @@ many different parameters to be easily manipulated. <dl> <dt><code>H5P_FILE_CREATE</code> <dd>Properties for file creation. - See <a href="../Files.html">H5F</a> + See <a href="Files.html">Files</a> + in the <cite>HDF User's Guide</cite> for details about the file creation properties. <dt><code>H5P_FILE_ACCESS</code> <dd>Properties for file access. - See <a href="../Files.html">H5F</a> + See <a href="Files.html">Files</a> + in the <cite>HDF User's Guide</cite> for details about the file creation properties. <dt><code>H5P_DATASET_CREATE</code> <dd>Properties for dataset creation. - See <a href="../Datasets.html">H5D</a> + See <a href="Datasets.html">Datasets</a> + in the <cite>HDF User's Guide</cite> for details about dataset creation properties. <dt><code>H5P_DATASET_XFER</code> <dd>Properties for raw data transfer. - See <a href="../Datasets.html">H5D</a> + See <a href="Datasets.html">Datasets</a> + in the <cite>HDF User's Guide</cite> for details about raw data transfer properties. </dl> <dt><strong>Parameters:</strong> @@ -1570,7 +1591,7 @@ many different parameters to be easily manipulated. property list and eventually to the file and passed to the compression functions. <p> - See <a href="UG/Compression.html"><cite>Compression</cite></a> + See <a href="Compression.html"><cite>Compression</cite></a> in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Parameters:</strong> <dl> @@ -1680,14 +1701,27 @@ many different parameters to be easily manipulated. <hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +H5P +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> <address> -<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> -<br> -<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 8 July 1998 +Last modified: 14 July 1998 </body> </html> diff --git a/doc/src/RM_H5S.html b/doc/src/RM_H5S.html index 903d720..6230e56 100644 --- a/doc/src/RM_H5S.html +++ b/doc/src/RM_H5S.html @@ -5,6 +5,23 @@ HDF5/H5S Draft API Specification <body> +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +H5S +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + <center> <h1>H5S: Dataspace Interface</h1> </center> @@ -17,28 +34,56 @@ elements of a dataset. <table border=0> <tr><td valign=top> <ul> + <li><a href="#Dataspace-Create">H5Screate</a> <li><a href="#Dataspace-CreateSimple">H5Screate_simple</a> <li><a href="#Dataspace-Copy">H5Scopy</a> - <li><a href="#Dataspace-GetNpoints">H5Sget_npoints</a> - <li><a href="#Dataspace-GetNdims">H5Sget_ndims</a> + <li><a href="#Dataspace-SelectNpoints">H5Sselect_npoints</a> + <li><a href="#Dataspace-SelectElements">H5Sselect_elements</a> </ul> </td><td> </td><td valign=top> <ul> - <li><a href="#Dataspace-GetDims">H5Sget_dims</a> - <li><a href="#Dataspace-IsSimple">H5Sis_simple</a> - <li><a href="#Dataspace-SetSpace">H5Sset_space</a> - <li><a href="#Dataspace-SetHyperslab">H5Sset_hyperslab</a> + <li><a href="#Dataspace-ExtentNpoints">H5Sextent_npoints</a> + <li><a href="#Dataspace-ExtentNdims">H5Sextent_ndims</a> + <li><a href="#Dataspace-ExtentDims">H5Sextent_dims</a> + <li><a href="#Dataspace-GetClass">H5Sget_class</a> </ul> </td><td> </td><td valign=top> <ul> - <li><a href="#Dataspace-GetHyperslab">H5Sget_hyperslab</a> + <li><a href="#Dataspace-SetExtentSimple">H5Sset_extent_simple</a> + <li><a href="#Dataspace-IsSimple">H5Sis_simple</a> + <li><a href="#Dataspace-SelectHyperslab">H5Sselect_hyperslab</a> <li><a href="#Dataspace-Close">H5Sclose</a> </ul> </td></tr> </table> + <hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-Create">H5Screate</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em> <code>H5Screate</code>(<em>H5S_class_t</em> <code>type</code>) +<dt><strong>Purpose:</strong> + <dd>Creates a new dataspace of a specified type. +<dt><strong>Description:</strong> + <dd><code>H5Screate</code> creates a new dataspace of a particular + <code>type</code>. + The types currently supported are <code>H5S_SCALAR</code>, + <code>H5S_SIMPLE</code>, and <code>H5S_NONE</code>; + others are planned to be added later. The <code>H5S_NONE</code> + dataspace can only hold a selection, not an extent. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5S_class_t</em> <code>type</code> + <dd>The type of dataspace to be created. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a dataspace identifier if successful; + otherwise FAIL (-1). +</dl> + +<hr> <dl> <dt><strong>Name:</strong> <a name="Dataspace-CreateSimple">H5Screate_simple</a> <dt><strong>Signature:</strong> @@ -46,18 +91,22 @@ elements of a dataset. <em>const hsize_t *</em> <code>dims</code>, <em>const hsize_t *</em> <code>maxdims</code> ) +<dt><strong>Purpose:</strong> + <dd>Creates a new simple data space and opens it for access. <dt><strong>Description:</strong> - <dd>This function creates a new simple data space object and opens it for - access. The <code>rank</code> is the number of dimensions used in the - dataspace. The <code>dims</code> argument is the size of the simple - dataset and the <code>maxdims</code> argument is the upper limit on the - size of the dataset. <code>maxdims</code> may be the null pointer in - which case the upper limit is the same as <code>dims</code>. If an - element of <code>maxdims</code> is zero then the corresponding dimension - is unlimited, otherwise no element of <code>maxdims</code> should be - smaller than the corresponding element of <code>dims</code>. The - dataspace ID returned from this function should be released with - H5Sclose or resource leaks will occur. + <dd><code>H5Screate_simple</code> creates a new simple data space + and opens it for access. The <code>rank</code> is the number of + dimensions used in the dataspace. + The <code>dims</code> argument is the size + of the simple dataset and the <code>maxdims</code> argument is + the upper limit on the size of the dataset. <code>maxdims</code> + may be the null pointer in which case the upper limit is the + same as <code>dims</code>. If an element of <code>maxdims</code> + is zero then the corresponding dimension is unlimited, otherwise + no element of <code>maxdims</code> should be smaller than the + corresponding element of <code>dims</code>. The dataspace + identifier returned from this function should be released with + <code>H5Sclose</code> or resource leaks will occur. <dt><strong>Parameters:</strong> <dl> <dt><em>int</em> <code>rank</code> @@ -68,224 +117,413 @@ elements of a dataset. <dd>An array of the maximum size of each dimension. </dl> <dt><strong>Returns:</strong> - <dd>A dataspace ID on success, negative on failure. + <dd>Returns a dataspace identifier if successful; + otherwise FAIL (-1). </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Dataspace-Copy">H5Scopy</a> <dt><strong>Signature:</strong> <dd><em>hid_t </em><code>H5Scopy</code>(<em>hid_t </em><code>space_id</code> ) +<dt><strong>Purpose:</strong> + <dd>Creates an exact copy of a dataspace. <dt><strong>Description:</strong> - <dd>This function copies a dataspace. The dataspace ID returned from this - function should be released with H5Sclose or resource leaks will occur. + <dd><code>H5Scopy</code> creates a new dataspace which is an exact + copy of the dataspace identified by <code>space_id</code>. + The dataspace identifier returned from this function should be + released with <code>H5Sclose</code> or resource leaks will occur. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of dataspace to copy. + <dd>Identifier of dataspace to copy. </dl> <dt><strong>Returns:</strong> - <dd>A dataspace ID on success, negative on failure. + <dd>Returns a dataspace identifier if successful; + otherwise FAIL (-1). </dl> + <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-GetNpoints">H5Sget_npoints</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectElements">H5Sselect_elements</a> <dt><strong>Signature:</strong> - <dd><em>hsize_t</em> <code>H5Sget_npoints</code>(<em>hid_t </em><code>space_id</code>) + <dd><em>herr_t</em> <code>H5Sselect_elements</code>(<em>hid_t </em><code>space_id</code>, + <em>dh5s_selopt_t</em> <code>op</code>, + <em>const size_t</em> <code>num_elements</code>, + <em>const hssize_t *</em><code>coord</code>[ ] + ) +<dt><strong>Purpose:</strong> + <dd>Selects array elements to be included in the selection for a dataspace. <dt><strong>Description:</strong> - <dd>This function determines the number of elements in a dataspace. For - example, a simple 3-dimensional dataspace with dimensions 2, 3 and 4 - would have 24 elements. + <dd><code>H5Sselect_elements</code> selects array elements to be + included in the selection for the <code>space_id</code> + dataspace. The number of elements selected must be set with + the <code>num_elements</code>. The <code>coord</code> array + is a two-dimensional array of size <em>dataspace rank</em> + by <code>num_elements</code> (ie. a list of coordinates in + the array). The order of the element coordinates in the + <code>coord</code> array also specifies the order in which + the array elements are iterated through when I/O is performed. + Duplicate coordinate locations are not checked for. + <P> + The selection operator <code>op</code> determines how the + new selection is to be combined with the previously existing + selection for the dataspace. Currently, only the + <code>H5S_SELECT_SET</code> operator is supported, which + replaces the existing selection with the parameters from + this call. When operators other than <code>H5S_SELECT_SET</code> + are used to combine a new selection with an existing selection, + the selection ordering is reset to 'C' array ordering. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to query + <dd>Identifier of the dataspace. + <dt><em>dh5s_selopt_t</em> <code>op</code> + <dd>operator specifying how the new selection is to be + combined with the existing selection for the dataspace. + <dt><em>const size_t</em> <code>num_elements</code> + <dd>Number of elements to be selected. + <dt><em>const hssize_t *</em><code>coord</code>[ ] + <dd>A 2-dimensional array specifying the coordinates of the + elements being selected. </dl> <dt><strong>Returns:</strong> - <dd>Number of elements in the dataspace, 0 on failure + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> + + + + <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-GetNdims">H5Sget_ndims</a> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentNpoints">H5Sextent_npoints</a> <dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Sget_ndims</code>(<em>hid_t</em> <code>space_id</code>) + <dd><em>hsize_t</em> <code>H5Sextent_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> - <dd>This function determines the dimensionality (or rank) of a dataspace. + <dd><code>H5Sextent_npoints</code> determines the number of elements + in a dataspace. For example, a simple 3-dimensional dataspace + with dimensions 2, 3, and 4 would have 24 elements. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> <dd>ID of the dataspace object to query </dl> <dt><strong>Returns:</strong> - <dd>Number of dimensions in the dataspace, negative on failure + <dd>Returns the number of elements in the dataspace if successful; + otherwise returns 0. </dl> + <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-GetDims">H5Sget_dims</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectNpoints">H5Sselect_npoints</a> <dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Sget_dims</code>(<em>hid_t</em> <code>space_id</code>, + <dd><em>hsize_t</em> <code>H5Sselect_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> + <dd><code>H5Sselect_npoints</code> determines the number of elements + in the current selection of a dataspace. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>Dataspace identifier. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a dataspace identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentNdims">H5Sextent_ndims</a> +<dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Sextent_ndims</code>(<em>hid_t</em> <code>space_id</code>) +<dt><strong>Purpose:</strong> + <dd>Determines the dimensionality of a dataspace. +<dt><strong>Description:</strong> + <dd><code>H5Sextent_ndims</code> determines the dimensionality (or rank) + of a dataspace. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>Identifier of the dataspace + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the number of dimensions in the dataspace if successful; + otherwise FAIL (-1) +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentDims">H5Sextent_dims</a> +<dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Sextent_dims</code>(<em>hid_t</em> <code>space_id</code>, <em>hsize_t *</em><code>dims</code>, <em>hsize_t *</em><code>maxdims</code> ) +<dt><strong>Purpose:</strong> + <dd>Retrieves dataspace dimension size and maximum size. <dt><strong>Description:</strong> - <dd>This function returns the size of each dimension in a dataspace through - the <code>dims</code> parameter. + <dd><code>H5Sextent_dims</code> returns the size and maximum sizes + of each dimension of a dataspace through the <code>dims</code> + and <code>maxdims</code> parameters. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to query + <dd>IN: Identifier of the dataspace object to query <dt><em>hsize_t *</em><code>dims</code> - <dd>Pointer to array to store the size of each dimension. + <dd>OUT: Pointer to array to store the size of each dimension. <dt><em>hsize_t *</em><code>maxdims</code> - <dd>Pointer to array to store the maximum size of each dimension. + <dd>OUT: Pointer to array to store the maximum size of each dimension. </dl> <dt><strong>Returns:</strong> - <dd>Number of dimensions in the dataspace, negative on failure + <dd>Returns the number of dimensions in the dataspace if successful; + otherwise FAIL (-1). </dl> + <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-IsSimple">H5Sis_simple</a> +<dt><strong>Name:</strong> <a name="Dataspace-SetExtentSimple">H5Sset_extent_simple</a> <dt><strong>Signature:</strong> - <dd><em>hbool_t </em><code>H5Sis_simple</code>(<em>hid_t </em><code>space_id</code>) + <dd><em>herr_t</em> <code>H5S_set_extent_simple</code>(<em>hid_t</em> <code>space_id</code>, + <em>int</em> <code>rank</code>, + <em>const hsize_t *</em><code>current_size</code>, + <em>const hsize_t *</em><code>maximum_size</code> + ) +<dt><strong>Purpose:</strong> + <dd>Sets or resets the size of an existing dataspace. <dt><strong>Description:</strong> - <dd>This function determines whether a dataspace object is a simple - dataspace or not. [Currently, all dataspace objects are simple - dataspaces, complex dataspace support will be added in the future] + <dd><code>H5S_set_extent_simple</code> sets or resets the size of + an existing dataspace. + <p> + <code>rank</code> is the dimensionality, or number of + dimensions, of the dataspace. + <p> + <code>current_size</code> is an array of size <code>rank</code> + which contains the new size of each dimension in the dataspace. + <code>maximum_size</code> is an array of size <code>rank</code> + which contains the maximum size of each dimension in the + dataspace. + <p> + Any previous extent is removed from the dataspace, the dataspace + type is set to <code>H5S_SIMPLE</code>, and the extent is set as + specified. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to query + <dd>Dataspace identifier. + <dt><em>int</em> <code>rank</code> + <dd>Rank, or dimensionality, of the dataspace. + <dt><em>const hsize_t *</em><code>current_size</code> + <dd>Array containing current size of dataspace. + <dt><em>const hsize_t *</em><code>maximum_size</code> + <dd>Array containing maximum size of dataspace. </dl> <dt><strong>Returns:</strong> - <dd>TRUE or FALSE on success, negative on failure + <dd>Returns a dataspace identifier if successful; + otherwise FAIL (-1). </dl> + <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SetSpace">H5Sset_space</a> +<dt><strong>Name:</strong> <a name="Dataspace-IsSimple">H5Sis_simple</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Sset_space</code>(<em>hid_t </em><code>space_id</code>, - <em>uint32 </em><code>rank</code>, - <em>uint32 *</em><code>dims</code> - ) + <dd><em>hbool_t </em><code>H5Sis_simple</code>(<em>hid_t </em><code>space_id</code>) +<dt><strong>Purpose:</strong> + <dd>Determines whether a dataspace is a simple dataspace. <dt><strong>Description:</strong> - <dd>This function determines the number of dimensions and the size of each - dimension for the space that a dataset is stored within. This function - only creates simple dataspace objects. Setting the rank to a - value of zero allows scalar objects to be created. Dimensions are - specified from slowest to fastest changing in the <code>dims</code> - array (i.e. 'C' order). Setting the size of a dimension to zero - indicates that the dimension is of unlimited size and should be allowed - to expand. Currently, only the first dimension in the array (the - slowest) may be unlimited in size. - [Currently, all dataspace objects are simple + <dd><code>H5Sis_simple</code> determines whether a dataspace is + a simple dataspace. [Currently, all dataspace objects are simple dataspaces, complex dataspace support will be added in the future] <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object. - <dt><em>uint32</em> <code>rank</code> - <dd>The number of dimensions the object is composed of. - <dt><em>uint32 *</em> <code>dims</code> - <dd>An array of the size of each dimension. (NULL for scalar objects) + <dd>Identifier of the dataspace to query </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns TRUE or FALSE if Successful; + otherwise FAIL (-1). </dl> + <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SetHyperslab">H5Sset_hyperslab</a> +<dt><strong>Name:</strong> <a name="Dataspace-GetClass">H5Sget_class</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Sset_hyperslab</code>(<em>hid_t</em> <code>space_id</code>, - <em>const hssize_t *</em><code>start</code>, - <em>const hsize_t *</em><code>count</code>, - <em>const hsize_t *</em><code>stride</code> - ) + <dd><em>H5S_class_t</em> <code>H5Sget_class</code>(<em>hid_t</em> <code>space_id</code>) +<dt><strong>Purpose:</strong> + <dd>Determine the current class of a dataspace. <dt><strong>Description:</strong> - <dd>This function selects a hyperslab from a simple dataspace. The stride - array may be used to sub-sample the hyperslab chosen, a value of 1 in each - position of the stride array selects contiguous elements in the array, - a value of 2 selects every other element, etc. If the stride parameter is - set to NULL, a contiguous hyperslab is chosen. The values in the start and - count arrays may be negative, to allow for selecting hyperslabs in chunked - datasets which extend in arbitrary directions. + <dd><code>H5Sget_class</code> queries a dataspace to determine the + current class of a dataspace. + <p> + The function returns a class name, one of the following: + <code>H5S_SCALAR</code>, + <code>H5S_SIMPLE</code>, or + <code>H5S_NONE</code>. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to set hyperslab in. - <dt><em>const hssize_t *</em><code>start</code> - <dd>Pointer to array of starting location for hyperslab. - <dt><em>const hsize_t *</em><code>count</code> - <dd>Pointer to array of magnitude of hyperslab. - <dt><em>const hsize_t *</em><code>stride</code> - <dd>Pointer to array of stride of hyperslab. + <dd>Dataspace identifier. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns a dataspace class name if successful; + otherwise FAIL (-1). </dl> + <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-GetHyperslab">H5Sget_hyperslab</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperslab">H5Sselect_hyperslab</a> <dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Sget_hyperslab</code>(<em>hid_t</em> <code>space_id</code>, - <em>hssize_t *</em><code>start</code>, - <em>hsize_t *</em><code>count</code>, - <em>hsize_t *</em><code>stride</code> + <dd><em>herr_t</em> <code>H5Sselect_hyperslab</code>(<em>hid_t</em> <code>space_id</code>, + <em>h5s_selopt_t</em><code>op</code>, + <em>const hssize_t *</em><code>start</code>, + <em>const hsize_t *</em><code>stride</code> + <em>const hsize_t *</em><code>count</code>, + <em>const hsize_t *</em><code>block</code> ) +<dt><strong>Purpose:</strong> + <dd>Selects a hyperslab region to add to the current selected region. <dt><strong>Description:</strong> - <dd>This function retrieves information about the hyperslab from a simple - dataspace. If no hyperslab has been defined then the hyperslab is the - same as the entire array. + <dd><code>H5Sselect_hyperslab</code> selects a hyperslab region + to add to the current selected region for the dataspace + specified by <code>space_id</code>. + <p> + The <code>start</code>, <code>stride</code>, <code>count</code>, + and <code>block</code> arrays must be the same size as the rank + of the dataspace. + <p> + The selection operator <code>op</code> determines how the new + selection is to be combined with the already existing selection + for the dataspace. + <p> + Currently, only the <code>H5S_SELECT_SET</code> operator is + supported; it replaces the existing selection with the + parameters from this call. Overlapping blocks are not + supported with the <code>H5S_SELECT_SET</code> operator. +<P> +The <code>start</code> array determines the starting coordinates +of the hyperslab +to select. +<p> +The <code>stride</code> array chooses array locations +from the dataspace +with each value in the <code>stride</code> array determining how +many elements to move +in each dimension. Setting a value in the <code>stride</code> +array to 1 moves to +each element in that dimension of the dataspace; setting a value of 2 in a +location in the <code>stride</code> array moves to every other +element in that +dimension of the dataspace. In other words, the <code>stride</code> +determines the +number of elements to move from the <code>start</code> location +in each dimension. +Stride values of 0 are not allowed. If the <code>stride</code> +parameter is <code>NULL</code>, +a contiguous hyperslab is selected (as if each value in the +<code>stride</code> array +was set to all 1's). +<p> +The <code>count</code> array determines how many blocks to +select from the dataspace, in each dimension. +<p> +The <code>block</code> array determines +the size of the element block selected from the dataspace. +If the <code>block</code> +parameter is set to <code>NULL</code>, the block size defaults +to a single element +in each dimension (as if the <code>block</code> array was set to all 1's). +<P> +For example, in a 2-dimensional dataspace, setting +<code>start</code> to [1,1], +<code>stride</code> to [4,4], <code>count</code> to [3,7], and +<code>block</code> to [2,2] selects +21 2x2 blocks of array elements starting with location (1,1) and selecting +blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc. +<P> +Regions selected with this function call default to C order iteration when +I/O is performed. <dt><strong>Parameters:</strong> - <dl> + <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to set hyperslab in. - <dt><em>hssize_t *</em><code>start</code> - <dd>Pointer to array to store starting location of hyperslab. - <dt><em>hsize_t *</em><code>count</code> - <dd>Pointer to array to store magnitude of hyperslab. - <dt><em>hsize_t *</em><code>stride</code> - <dd>Pointer to array to store stride of hyperslab. + <dd>IN: Identifier of dataspace selection to modify + <dt><em>H5S_seloper_t</em> <code>op</code> + <dd>IN: Operation to perform on current selection. + <dt><em>const hssize_t *</em><code>start</code> + <dd>IN: Offset of start of hyperslab + <dt><em>const hsize_t *</em><code>count</code> + <dd>IN: Number of blocks included in hyperslab. + <dt><em>const hsize_t *</em><code>stride</code> + <dd>IN: Hyperslab stride. + <dt><em>const hsize_t *</em><code>block</code> + <dd>IN: Size of block in hyperslab. </dl> <dt><strong>Returns:</strong> - <dd>Hyperslab dimensionality on success, negative on failure. + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Dataspace-Close">H5Sclose</a> <dt><strong>Signature:</strong> <dd><em>herr_t </em><code>H5Sclose</code>(<em>hid_t </em><code>space_id</code> ) +<dt><strong>Purpose:</strong> + <dd>Releases and terminates access to a dataspace. <dt><strong>Description:</strong> - <dd>This function releases a dataspace. Further access through the dataspace - ID is illegal. Failure to release a dataspace with this call will + <dd><code>H5Sclose</code> releases a dataspace. + Further access through the dataspace identifier is illegal. + Failure to release a dataspace with this call will result in resource leaks. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of dataspace to release. + <dd>Identifier of dataspace to release. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> + +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +H5S +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> <hr> <address> -<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> -<br> -<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 29 June 1998 +Last modified: 14 July 1998 </body> </html> diff --git a/doc/src/RM_H5T.html b/doc/src/RM_H5T.html index 4221e93..0fa5926 100644 --- a/doc/src/RM_H5T.html +++ b/doc/src/RM_H5T.html @@ -5,6 +5,23 @@ HDF5/H5T Draft API Specification <body> +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +H5T +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + <center> <h1>H5T: Datatype Interface</h1> </center> @@ -16,22 +33,17 @@ of a dataset. <table border=0> <tr><td valign=top> -<ul> +<i>General Datatype Operations</i> + <li><a href="#Datatype-Create">H5Tcreate</a> <li><a href="#Datatype-Open">H5Topen</a> <li><a href="#Datatype-Commit">H5Tcommit</a> <li><a href="#Datatype-Committed">H5Tcommitted</a> - <li><a href="#Datatype-InsertArray">H5Tinsert_array</a> - <li><a href="#Datatype-Share">H5Tshare</a> - <li><a href="#Datatype-Find">H5Tfind</a> - <li><a href="#Datatype-Convert">H5Tconvert</a> - <li><a href="#Datatype-SetOverflow">H5Tset_overflow</a> - <li><a href="#Datatype-GetOverflow">H5Tget_overflow</a> - <li> - - <li><a href="#Datatype-Create">H5Tcreate</a> <li><a href="#Datatype-Copy">H5Tcopy</a> <li><a href="#Datatype-Equal">H5Tequal</a> <li><a href="#Datatype-Lock">H5Tlock</a> + <li><a href="#Datatype-Close">H5Tclose</a> +<p> +<i>Atomic Datatype Properties</i> <li><a href="#Datatype-GetClass">H5Tget_class</a> <li><a href="#Datatype-GetSize">H5Tget_size</a> <li><a href="#Datatype-SetSize">H5Tset_size</a> @@ -41,10 +53,8 @@ of a dataset. <li><a href="#Datatype-SetPrecision">H5Tset_precision</a> <li><a href="#Datatype-GetOffset">H5Tget_offset</a> <li><a href="#Datatype-SetOffset">H5Tset_offset</a> - <li><a href="#Datatype-GetPad">H5Tget_pad</a> -</ul> </td><td> </td><td valign=top> -<ul> + <li><a href="#Datatype-GetPad">H5Tget_pad</a> <li><a href="#Datatype-SetPad">H5Tset_pad</a> <li><a href="#Datatype-GetSign">H5Tget_sign</a> <li><a href="#Datatype-SetSign">H5Tset_sign</a> @@ -59,10 +69,12 @@ of a dataset. <li><a href="#Datatype-GetCset">H5Tget_cset</a> <li><a href="#Datatype-SetCset">H5Tset_cset</a> <li><a href="#Datatype-GetStrpad">H5Tget_strpad</a> -</ul> -</td><td> </td><td valign=top> -<ul> <li><a href="#Datatype-SetStrpad">H5Tset_strpad</a> +<p> +<i>Properties of Compound Types</i> + <li><a href="#Datatype-GetClass">H5Tget_class</a> + <li><a href="#Datatype-GetSize">H5Tget_size</a> +</td><td> </td><td valign=top> <li><a href="#Datatype-GetNmembers">H5Tget_nmembers</a> <li><a href="#Datatype-GetMemberName">H5Tget_member_name</a> <li><a href="#Datatype-GetMemberOffset">H5Tget_member_offset</a> @@ -70,11 +82,16 @@ of a dataset. <li><a href="#Datatype-GetMemberType">H5Tget_member_type</a> <li><a href="#Datatype-Insert">H5Tinsert</a> <li><a href="#Datatype-Pack">H5Tpack</a> + <li><a href="#Datatype-InsertArray">H5Tinsert_array</a> +<p> +<i>Conversion Functions</i> + <li><a href="#Datatype-Convert">H5Tconvert</a> + <li><a href="#Datatype-Find">H5Tfind</a> + <li><a href="#Datatype-SetOverflow">H5Tset_overflow</a> + <li><a href="#Datatype-GetOverflow">H5Tget_overflow</a> <li><a href="#Datatype-RegisterHard">H5Tregister_hard</a> <li><a href="#Datatype-RegisterSoft">H5Tregister_soft</a> <li><a href="#Datatype-Unregister">H5Tunregister</a> - <li><a href="#Datatype-Close">H5Tclose</a> -</ul> </td></tr> </table> @@ -88,18 +105,18 @@ The Datatype interface, H5T, provides a mechanism to describe the according to the data space (the H5S interface). <p> -A data type is a collection of data type properties, all of +A datatype is a collection of datatype properties, all of which can be stored on disk, and which when taken as a whole, provide complete information for data conversion to or from that - data type. The interface provides functions to set and query - properties of a data type. + datatype. The interface provides functions to set and query + properties of a datatype. <p> A <em>data point</em> is an instance of a <em>datatype</em>, which is an instance of a <em>type class</em>. We have defined a set of type classes and properties which can be extended at a later time. The atomic type classes are those which describe - types which cannot be decomposed at the data type interface + types which cannot be decomposed at the datatype interface level; all other classes are compound. <p> @@ -117,13 +134,11 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Opens a named datatype. <dt><strong>Description:</strong> - <dd><b>From UG:</b> <code>H5Topen</code> opens a named datatype at the location - specified by <code>loc_id</code> and returns an identifier - for the data type. The identifier should eventually be closed - by calling <code>H5Tclose()</code> to release resources. - <code>loc_id</code> is either a file or group identifier. - <p> - <b>From SC:</b> Opens a named datatype. + <dd><code>H5Topen</code> opens a named datatype at the location + specified by <code>loc_id</code> and returns an identifier + for the datatype. <code>loc_id</code> is either a file or + group identifier. The identifier should eventually be closed + by calling <code>H5Tclose()</code> to release resources. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>loc_id</code> @@ -148,13 +163,11 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Commits a transient datatype to a file, creating a new named datatype. <dt><strong>Description:</strong> - <dd><b>From UG:</b> <code>H5Tcommit</code> commits a transient datatype (not immutable) - to a file, turned it into a named datatype. The <code>loc_id</code> - is either a file or group identifier which, when combined with - <code>name</code>, refers to a new named data type. - <p> - <b>From SC:</b> Saves a transient data type to a file and turns - the type identifier into a named, immutable type. + <dd><code>H5Tcommit</code> commits a transient datatype + (not immutable) to a file, turned it into a named datatype. + The <code>loc_id</code> is either a file or group identifier + which, when combined with <code>name</code>, refers to a new + named datatype. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>loc_id</code> @@ -178,24 +191,21 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Determines whether a datatype is a named type or a transient type. <dt><strong>Description:</strong> - <dd><b>From UG:</b> <code>H5Tcommitted</code> queries a type to determine whether - it is a named type or a transient type. If this function returns + <dd><code>H5Tcommitted</code> queries a type to determine whether + the type specified by the <code>type</code> identifier + is a named type or a transient type. If this function returns a positive value, then the type is named (that is, it has been committed, perhaps by some other application). Datasets which - return committed data types with <code>H5Dget_type()</code> are - able to share the data type with other datasets in the same file. - <p> - <b>From SC:</b> Determines whether a data type is committed. + return committed datatypes with <code>H5Dget_type()</code> are + able to share the datatype with other datasets in the same file. <dt><strong>Parameters:</strong> <dl> <dt>hid_t</em> <code>type</code> <dd>Datatype identifier. </dl> <dt><strong>Returns:</strong> - <dd><b>From UG:</b> Returns a datatype identifier if successful; - otherwise FAIL (-1). - <dd><b>From SC:</b> The successful returns values are TRUE if committed, - else FALSE. Otherwise returns FAIL (-1). + <dd>The successful return values are TRUE if committed, else FALSE. + Otherwise returns FAIL (-1). </dl> @@ -212,33 +222,35 @@ in the <cite>HDF5 User's Guide</cite> for further information. <em>hid_t</em> <code>member_id</code> ) <dt><strong>Purpose:</strong> - <dd>Adds a new member to a compound data type. + <dd>Adds an array member to a compound datatype. <dt><strong>Description:</strong> - <dd><b>From SC:</b> <code>H5Tinsert_array</code> adds a new member to the - compound data type <code>parent_id</code>. The new member's name, - <code>name</code>, must be unique within the compound data type. - The <code>offset</code> argument defines the start of - the member in an instance of the compound data type and - <code>member_id</code> is the type of the new member. + <dd><code>H5Tinsert_array</code> adds a new member to the + compound datatype <code>parent_id</code>. The member is an array with <code>ndims</code> dimensionality and the size of the array is </em><code>dim</code>. - The total member size should be relatively small + The new member's name, <code>name</code>, must be unique + within the compound datatype. + The <code>offset</code> argument defines the start of the + member in an instance of the compound datatype and + <code>member_id</code> is the type identifier of the new member. + The total member size should be relatively small. <dt><strong>Parameters:</strong> <dl> - <dt>hid_t</em> <code>parent_id</code> - <dd> + <dt><em>hid_t</em> <code>parent_id</code> + <dd>Identifier of the parent compound datatype. <dt><em>const char *</em><code>name</code> - <dd> + <dd>Name of new member. <dt><em>size_t</em> <code>offset</code> - <dd> + <dd>Offset to start of new member within compound datatype. <dt><em>int</em> <code>ndims</code> - <dd> + <dd>Dimensionality of new member. <dt><em>const size_t *</em><code>dim</code> - <dd> + <dd>Size of new member array. <dt><em>const int *</em><code>perm</code> - <dd> + <dd>Pointer to buffer to store the permutation vector of + the field. <dt><em>hid_t</em> <code>member_id</code> - <dd> + <dd>Identifier of the datatype of the new member. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -257,25 +269,25 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Finds a conversion function. <dt><strong>Description:</strong> - <dd><b>From SC:</b> <code>H5Tfind</code> finds a conversion function - that can handle a conversion from type <code>src_id</code> to - type <code>dst_id</code>. - The <code>pcdata</code> argument is a pointer - to a pointer to type conversion data which was created and - initialized by the soft type conversion function of this path - when the conversion function was installed on the path. + <dd><code>H5Tfind</code> finds a conversion function that can + handle a conversion from type <code>src_id</code> to type + <code>dst_id</code>. + The <code>pcdata</code> argument is a pointer to a pointer + to type conversion data which was created and initialized + by the soft type conversion function of this path when the + conversion function was installed on the path. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>src_id</code> - <dd> + <dd>Identifier for the source datatype. <dt><em>hid_t</em> <code>dst_id</code> - <dd> + <dd>Identifier for the destination datatype. <dt><em>H5T_cdata_t **</em><code>pcdata</code> - <dd> + <dd>Pointer to type conversion data. </dl> <dt><strong>Returns:</strong> <dd>Returns a pointer to a suitable conversion function if successful. - Otherwise returns FAIL (-1). + Otherwise returns NULL. </dl> @@ -292,8 +304,9 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Converts data from between specified datatypes. <dt><strong>Description:</strong> - <dd><b>From SC:</b> Convert <code>nelmts</code> elements from type - <code>src_id</code> to type <code>dst_id</code>. + <dd><code>H5Tconvert</code> converts <code>nelmts</code> elements + from the type specified by the <code>src_id</code> identifier + to type <code>dst_id</code>. The source elements are packed in <code>buf</code> and on return the destination will be packed in <code>buf</code>. That is, the conversion is performed in place. @@ -307,15 +320,15 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>src_id</code> - <dd> + <dd>Identifier for the source datatype. <dt><em>hid_t</em> <code>dst_id</code> - <dd> + <dd>Identifier for the destination datatype. <dt><em>size_t</em> <code>nelmts</code> - <dd> + <dd>Size of array <code>buf</code>. <dt><em>void *</em><code>buf</code> - <dd> + <dd>Array containing pre- and post-conversion values. <dt><em>void *</em><code>background</code> - <dd> + <dd>Optional background buffer. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -331,9 +344,9 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Sets the overflow handler to a specified function. <dt><strong>Description:</strong> - <dd><b>From SC:</b> <code>H5Tset_overflow</code> sets the overflow handler + <dd><code>H5Tset_overflow</code> sets the overflow handler to be the function specified by <code>func</code>. - <code>func</code> will be called for all data type conversions that + <code>func</code> will be called for all datatype conversions that result in an overflow. <p> See the definition of <code>H5T_overflow_t</code> in @@ -348,7 +361,7 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Parameters:</strong> <dl> <dt><em>H5T_overflow_t</em> <code>func</code> - <dd> + <dd>Overflow function. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -367,10 +380,10 @@ H5Tget_overflow () <dt><strong>Purpose:</strong> <dd>Returns a pointer to the current global overflow function. <dt><strong>Description:</strong> - <dd><b>From SC:</b> <code>H5Tset_overflow</code> returns a pointer + <dd><code>H5Tset_overflow</code> returns a pointer to the current global overflow function. This is an application-defined function that is called whenever a - data type conversion causes an overflow. + datatype conversion causes an overflow. <dt><strong>Parameters:</strong> <dl> <dt>None. @@ -392,12 +405,13 @@ H5Tget_overflow () <dt><strong>Purpose:</strong> <dd>Creates a new dataype. <dt><strong>Description:</strong> - <dd><code>H5Tcreate</code> creates a new dataype of the specified class with the - specified number of bytes. Currently, only the <code>H5T_COMPOUND</code> - datatype class is supported with this function, use <code>H5Tcopy</code> - to create integer or floating-point datatypes. The datatype ID - returned from this function should be released with H5Tclose or resource - leaks will result. + <dd><code>H5Tcreate</code> creates a new dataype of the specified + class with the specified number of bytes. + Currently, only the <code>H5T_COMPOUND</code> datatype class is + supported with this function. Use <code>H5Tcopy</code> + to create integer or floating-point datatypes. + The datatype identifier returned from this function should be + released with <code>H5Tclose</code> or resource leaks will result. <dt><strong>Parameters:</strong> <dl> <dt><em>H5T_class_t</em> <code>class</code> @@ -406,7 +420,8 @@ H5Tget_overflow () <dd>The number of bytes in the datatype to create. </dl> <dt><strong>Returns:</strong> - <dd>Datatype ID on success, negative on failure. + <dd>Returns datatype identifier if successful; + otherwise FAIL (-1). </dl> @@ -414,14 +429,25 @@ H5Tget_overflow () <dl> <dt><strong>Name:</strong> <a name="Datatype-Copy">H5Tcopy</a> <dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Tcopy</code>(<em>hid_t </em><code>type_id</code> - ) + <dd><em>hid_t </em><code>H5Tcopy</code>(<em>hid_t </em><code>type_id</code>) <dt><strong>Purpose:</strong> <dd>Copies an existing datatype. <dt><strong>Description:</strong> - <dd><code>H5Tcopy</code> copies an existing datatype. The datatype ID returned - should be released with H5Tclose or resource leaks will occur. Native - datatypes supported by the library are: + <dd><code>H5Tcopy</code> copies an existing datatype. + The returned type is always transient and unlocked. + <p> + The <code>type_id</code> argument can be either a datatype + identifier, a predefined datatype (defined in + <code>H5Tpublic.h</code>), or a dataset identifier. + If <code>type_id</code> is a dataset identifier instead of a + datatype identifier, then this function returns a transient, + modifiable datatype which is a copy of the dataset's datatype. + <p> + The datatype identifier returned should be released with + <code>H5Tclose</code> or resource leaks will occur. +<!-- + <p> + Native datatypes supported by the library are: <ul> <dl> <dt>H5T_NATIVE_CHAR <dd> Native character type, declare dataset array as 'char' @@ -464,13 +490,17 @@ H5Tget_overflow () <dt>H5T_NATIVE_DOUBLE <dd> Native double-precision float type, declare dataset array as 'double' </dl> </ul> +--> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to copy. + <dd>Identifier of datatype to copy. Can be a datatype + identifier, a predefined datatype (defined in + <code>H5Tpublic.h</code>), or a dataset identifier. </dl> <dt><strong>Returns:</strong> - <dd>Datatype ID on success, negative on failure. + <dd>Returns a datatype identifier if successful; + otherwise FAIL (-1) </dl> @@ -489,12 +519,14 @@ H5Tget_overflow () <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id1</code> - <dd>ID of datatype to compare. + <dd>Identifier of datatype to compare. <dt><em>hid_t</em> <code>type_id2</code> - <dd>ID of datatype to compare. + <dd>Identifier of datatype to compare. </dl> <dt><strong>Returns:</strong> - <dd>TRUE/FALSE/negative + <dd>When successful, returns TRUE if the datatype identifiers + refer to the same datatype, else FALSE. + Otherwise returns FAIL (-1). </dl> @@ -505,19 +537,22 @@ H5Tget_overflow () <dd><em>herr_t </em><code>H5Tlock</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Locks a type. + <dd>Locks a datatype. <dt><strong>Description:</strong> - <dd><code>H5Tlock</code> locks a type, making it read-only and non-destrucible. - This is normally done by the library for predefined data types so the - application doesn't inadvertently change or delete a predefined type. - Once a data type is locked it can never be unlocked. + <dd><code>H5Tlock</code> locks the datatype specified by the + <code>type_id</code> identifier, making it read-only and + non-destrucible. This is normally done by the library for + predefined datatypes so the application does not + inadvertently change or delete a predefined type. + Once a datatype is locked it can never be unlocked. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to lock. + <dd>Identifier of datatype to lock. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -528,16 +563,27 @@ H5Tget_overflow () <dd><em>H5T_class_t </em><code>H5Tget_class</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the base class of a datatype. + <dd>Returns the datatype class identifier. <dt><strong>Description:</strong> - <dd><code>H5Tget_class</code> returns the base class of a datatype. + <dd><code>H5Tget_class</code> returns the datatype class identifier. + <p> + Valid class identifiers, as defined in <code>H5Tpublic.h</code>, are: + <ul><li><code>H5T_INTEGER</code> (<code>0</code>) + <li><code>H5T_FLOAT</code> (<code>1</code>) + <li><code>H5T_TIME</code> (<code>2</code>) + <li><code>H5T_STRING</code> (<code>3</code>) + <li><code>H5T_BITFIELD</code> (<code>4</code>) + <li><code>H5T_OPAQUE</code> (<code>5</code>) + <li><code>H5T_COMPOUND</code> (<code>6</code>) + </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative type class on success, negative on failure. + <dd>Returns datatype class identifier if successful; + otherwise H5T_NO_CLASS (-1). </dl> @@ -554,10 +600,11 @@ H5Tget_overflow () <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Positve size in bytes on success, 0 on failure. + <dd>Returns the size of the datatype in bytes if successful; + otherwise 0. </dl> @@ -569,27 +616,28 @@ H5Tget_overflow () <em>size_t</em><code>size</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the total size for an atomic data type. + <dd>Sets the total size for an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_size</code> sets the total size in bytes for an - atomic data type (this - operation is not permitted on compound data types). If the size is - decreased so that the significant bits of the data type extend beyond + <dd><code>H5Tset_size</code> sets the total size in bytes, + <code>size</code>, for an atomic datatype (this operation + is not permitted on compound datatypes). If the size is + decreased so that the significant bits of the datatype extend beyond the edge of the new size, then the `offset' property is decreased toward zero. If the `offset' becomes zero and the significant - bits of the data type still hang over the edge of the new size, then + bits of the datatype still hang over the edge of the new size, then the number of significant bits is decreased. Adjusting the size of an H5T_STRING automatically sets the precision - to 8*size. All data types have a positive size. + to 8*size. All datatypes have a positive size. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to change size. + <dd>Identifier of datatype to change size. <dt><em>size_t</em> <code>size</code> <dd>Size in bytes to modify datatype. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -602,14 +650,26 @@ H5Tget_overflow () <dt><strong>Purpose:</strong> <dd>Returns the byte order of an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_order</code> returns the byte order of an atomic datatype. + <dd><code>H5Tget_order</code> returns the byte order of an + atomic datatype. + <p> + Possible return values are: + <ul><dl> + <dt><code>H5T_ORDER_LE</code> (<code>0</code>) + <dd>Little endian byte ordering (default). + <dt><code>H5T_ORDER_BE</code> (<code>1</code>) + <dd>Big endian byte ordering. + <dt><code>H5T_ORDER_VAX</code> (<code>2</code>) + <dd>VAX mixed byte ordering (not currently supported). + </dl></ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Byte order constant on success, negative on failure + <dd>Returns a byte order constant if successful; + otherwise <code>H5T_ORDER_ERROR</code> (-1). </dl> @@ -626,22 +686,23 @@ H5Tget_overflow () <dd><code>H5Tset_order</code> sets the byte ordering of an atomic datatype. Byte orderings currently supported are: <ul> <dl> - <dt>H5T_ORDER_LE - <dd> Little-endian byte ordering (default) - <dt>H5T_ORDER_BE - <dd> Big-endian byte ordering - <dt>H5T_ORDER_Vax - <dd> VAX-endianness byte ordering (not currently supported) + <dt>H5T_ORDER_LE (<code>0</code>) + <dd> Little-endian byte ordering (default). + <dt>H5T_ORDER_BE (<code>1</code>) + <dd> Big-endian byte ordering. + <dt>H5T_ORDER_VAX (<code>2</code>) + <dd>VAX mixed byte ordering (not currently supported). </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>H5T_order_t</em> <code>order</code> <dd>Byte ordering constant. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -652,18 +713,19 @@ H5Tget_overflow () <dd><em>size_t </em><code>H5Tget_precision</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the precision of an atomic data type. + <dd>Returns the precision of an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_precision</code> returns the precision of an atomic data type. The + <dd><code>H5Tget_precision</code> returns the precision of an atomic datatype. The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size(). <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Number of significant bits on success, 0 on failure + <dd>Returns the number of significant bits if successful; + otherwise 0. </dl> @@ -675,14 +737,14 @@ H5Tget_overflow () <em>size_t</em><code>precision</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the precision of an atomic data type. + <dd>Sets the precision of an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_precision</code> sets the precision of an atomic data type. + <dd><code>H5Tset_precision</code> sets the precision of an atomic datatype. The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size(). <P>If the precision is increased then the offset is decreased and then the size is increased to insure that significant bits do not "hang - over" the edge of the data type. + over" the edge of the datatype. <P>Changing the precision of an H5T_STRING automatically changes the size as well. The precision must be a multiple of 8. <P>When decreasing the precision of a floating point type, set the @@ -691,12 +753,13 @@ H5Tget_overflow () <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>size_t</em> <code>precision</code> <dd>Number of bits of precision for datatype. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -759,10 +822,11 @@ H5Tget_overflow () <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Positive offset value on success, 0 on failure. + <dd>Returns a positive offset value if successful; + otherwise 0. </dl> @@ -826,19 +890,20 @@ H5Tget_overflow () <P>If the offset is incremented then the total size is incremented also if necessary to prevent significant bits of -the value from hanging over the edge of the data type. +the value from hanging over the edge of the datatype. <P>The offset of an H5T_STRING cannot be set to anything but zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>size_t</em> <code>offset</code> <dd>Offset of first significant bit. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -856,24 +921,27 @@ zero. <dd><code>H5Tget_pad</code> retrieves the padding type of the least and most-significant bit padding. Valid types are: <ul> <dl> - <dt>H5T_PAD_ZERO + <dt>H5T_PAD_ZERO (<code>0</code>) <dd>Set background to zeros. - <dt>H5T_PAD_ONE + <dt>H5T_PAD_ONE (<code>1</code>) <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND + <dt>H5T_PAD_BACKGROUND (<code>2</code>) <dd>Leave background alone. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>IN: Identifier of datatype to query. <dt><em>H5T_pad_t *</em> <code>lsb</code> - <dd>Pointer to location to return least-significant bit padding type. + <dd>OUT: Pointer to location to return least-significant + bit padding type. <dt><em>H5T_pad_t *</em> <code>msb</code> - <dd>Pointer to location to return most-significant bit padding type. + <dd>OUT: Pointer to location to return most-significant + bit padding type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -890,24 +958,25 @@ zero. <dt><strong>Description:</strong> <dd><code>H5Tset_pad</code> sets the least and most-significant bits padding types. <ul> <dl> - <dt>H5T_PAD_ZERO + <dt>H5T_PAD_ZERO (<code>0</code>) <dd>Set background to zeros. - <dt>H5T_PAD_ONE + <dt>H5T_PAD_ONE (<code>1</code>) <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND + <dt>H5T_PAD_BACKGROUND (<code>2</code>) <dd>Leave background alone. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>H5T_pad_t</em> <code>lsb</code> <dd>Padding type for least-significant bits. <dt><em>H5T_pad_t</em> <code>msb</code> <dd>Padding type for most-significant bits. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -923,18 +992,19 @@ zero. <dd><code>H5Tget_sign</code> retrieves the sign type for an integer type. Valid types are: <ul> <dl> - <dt>H5T_SGN_NONE + <dt>H5T_SGN_NONE (<code>0</code>) <dd>Unsigned integer type. - <dt>H5T_SGN_2 + <dt>H5T_SGN_2 (<code>1</code>) <dd>Two's complement signed integer type. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative sign type on success, negative on failure + <dd>Returns a valid sign type if successful; + otherwise <code>H5T_SGN_ERROR</code> (-1). </dl> @@ -950,20 +1020,21 @@ zero. <dt><strong>Description:</strong> <dd><code>H5Tset_sign</code> sets the sign proprety for an integer type. <ul> <dl> - <dt>H5T_SGN_NONE + <dt>H5T_SGN_NONE (<code>0</code>) <dd>Unsigned integer type. - <dt>H5T_SGN_2 + <dt>H5T_SGN_2 (<code>1</code>) <dd>Two's complement signed integer type. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>H5T_sign_t</em> <code>sign</code> <dd>Sign type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -978,28 +1049,29 @@ zero. <em>size_t *</em> <code>msize</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves floating point data type bit field information. + <dd>Retrieves floating point datatype bit field information. <dt><strong>Description:</strong> <dd><code>H5Tget_fields</code> retrieves information about the locations of the various - bit fields of a floating point data type. The field positions are bit - positions in the significant region of the data type. Bits are + bit fields of a floating point datatype. The field positions are bit + positions in the significant region of the datatype. Bits are numbered with the least significant bit number zero. Any (or even all) of the arguments can be null pointers. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>IN: Identifier of datatype to query. <dt><em>size_t *</em> <code>epos</code> - <dd>Pointer to location to return exponent bit-position. + <dd>OUT: Pointer to location to return exponent bit-position. <dt><em>size_t *</em> <code>esize</code> - <dd>Pointer to location to return size of exponent in bits. + <dd>OUT: Pointer to location to return size of exponent in bits. <dt><em>size_t *</em> <code>mpos</code> - <dd>Pointer to location to return mantissa bit-position. + <dd>OUT: Pointer to location to return mantissa bit-position. <dt><em>size_t *</em> <code>msize</code> - <dd>Pointer to location to return size of mantissa in bits. + <dd>OUT: Pointer to location to return size of mantissa in bits. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1018,7 +1090,7 @@ zero. <dt><strong>Description:</strong> <dd><code>H5Tset_fields</code> sets the locations and sizes of the various floating point bit fields. The field positions are bit positions in the - significant region of the data type. Bits are numbered with the least + significant region of the datatype. Bits are numbered with the least significant bit number zero. <P>Fields are not allowed to extend beyond the number of bits of @@ -1026,7 +1098,7 @@ zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>size_t</em> <code>epos</code> <dd>Exponent bit position. <dt><em>size_t</em> <code>esize</code> @@ -1037,7 +1109,8 @@ zero. <dd>Size of mantissa in bits. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1054,10 +1127,11 @@ zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Positive value on success, 0 on failure. + <dd>Returns the bias if successful; + otherwise 0. </dl> @@ -1075,12 +1149,13 @@ zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>size_t</em> <code>ebias</code> <dd>Exponent bias value. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1093,23 +1168,24 @@ zero. <dt><strong>Purpose:</strong> <dd>Retrieves mantissa normalization of a floating-point datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_norm</code> retrieves the mantissa normalization of a floating-point - datatype. Valid normalization values are: + <dd><code>H5Tget_norm</code> retrieves the mantissa normalization of + a floating-point datatype. Valid normalization types are: <ul> <dl> - <dt>H5T_NORM_IMPLIED - <dd>MSB of mantissa isn't stored, always 1 - <dt>H5T_NORM_MSBSET + <dt>H5T_NORM_IMPLIED (<code>0</code>) + <dd>MSB of mantissa is not stored, always 1 + <dt>H5T_NORM_MSBSET (<code>1</code>) <dd>MSB of mantissa is always 1 - <dt>H5T_NORM_NONE + <dt>H5T_NORM_NONE (<code>2</code>) <dd>Mantissa is not normalized </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative normalization type on success, negative on failure + <dd>Returns a valid normalization type if successful; + otherwise <code>H5T_NORM_ERROR</code> (-1). </dl> @@ -1123,25 +1199,26 @@ zero. <dt><strong>Purpose:</strong> <dd>Sets the mantissa normalization of a floating-point datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_norm</code> sets the mantissa normalization of a floating-point - datatype. Valid normalization values are: + <dd><code>H5Tset_norm</code> sets the mantissa normalization of + a floating-point datatype. Valid normalization types are: <ul> <dl> - <dt>H5T_NORM_IMPLIED - <dd>MSB of mantissa isn't stored, always 1 - <dt>H5T_NORM_MSBSET + <dt>H5T_NORM_IMPLIED (<code>0</code>) + <dd>MSB of mantissa is not stored, always 1 + <dt>H5T_NORM_MSBSET (<code>1</code>) <dd>MSB of mantissa is always 1 - <dt>H5T_NORM_NONE + <dt>H5T_NORM_NONE (<code>2</code>) <dd>Mantissa is not normalized </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>H5T_norm_t</em> <code>norm</code> <dd>Mantissa normalization type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1156,22 +1233,23 @@ zero. <dt><strong>Description:</strong> <dd><code>H5Tget_inpad</code> retrieves the internal padding type for unused bits in floating-point datatypes. - Valid padding values are: + Valid padding types are: <ul> <dl> - <dt>H5T_PAD_ZERO + <dt>H5T_PAD_ZERO (<code>0</code>) <dd>Set background to zeros. - <dt>H5T_PAD_ONE + <dt>H5T_PAD_ONE (<code>1</code>) <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND + <dt>H5T_PAD_BACKGROUND (<code>2</code>) <dd>Leave background alone. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative padding type on success, negative on failure + <dd>Returns a valid padding type if successful; + otherwise <code>H5T_PAD_ERROR</code> (-1). </dl> @@ -1189,24 +1267,25 @@ zero. (that is, those significant bits which are not part of the sign, exponent, or mantissa), then <code>H5Tset_inpad</code> will be filled according to the value of the padding value property <code>inpad</code>. - Valid padding values are: + Valid padding types are: <ul> <dl> - <dt>H5T_PAD_ZERO + <dt>H5T_PAD_ZERO (<code>0</code>) <dd>Set background to zeros. - <dt>H5T_PAD_ONE + <dt>H5T_PAD_ONE (<code>1</code>) <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND + <dt>H5T_PAD_BACKGROUND (<code>2</code>) <dd>Leave background alone. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. + <dd>Identifier of datatype to modify. <dt><em>H5T_pad_t</em> <code>pad</code> <dd>Padding type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1219,19 +1298,20 @@ zero. <dt><strong>Purpose:</strong> <dd>Retrieves the character set type of a string datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_cset</code> retrieves the character set type of a string datatype. - Valid character set values are: + <dd><code>H5Tget_cset</code> retrieves the character set type + of a string datatype. Valid character set types are: <ul> <dl> - <dt>H5T_CSET_ASCII + <dt>H5T_CSET_ASCII (<code>0</code>) <dd>Character set is US ASCII </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative character set type on success, negative on failure + <dd>Returns a valid character set type if successful; + otherwise <code>H5T_CSET_ERROR</code> (-1). </dl> @@ -1243,24 +1323,27 @@ zero. <em>H5T_cset_t</em> <code>cset</code> ) <dt><strong>Purpose:</strong> - <dd> + <dd>Sets character set to be used. <dt><strong>Description:</strong> - <dd>HDF5 is able to distinguish between character sets of different + <dd><code>H5Tset_cset</code> the character set to be used. + <p> + HDF5 is able to distinguish between character sets of different nationalities and to convert between them to the extent possible. - Valid character set values are: + Valid character set types are: <ul> <dl> - <dt>H5T_CSET_ASCII - <dd>Character set is US ASCII + <dt>H5T_CSET_ASCII (<code>0</code>) + <dd>Character set is US ASCII. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. + <dd>Identifier of datatype to modify. <dt><em>H5T_cset_t</em> <code>cset</code> <dd>Character set type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1273,21 +1356,22 @@ zero. <dt><strong>Purpose:</strong> <dd>Retrieves the string padding method for a string datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_strpad</code> retrieves the string padding method for a string datatype. - Valid string padding values are: + <dd><code>H5Tget_strpad</code> retrieves the string padding method + for a string datatype. Valid string padding types are: <ul> <dl> - <dt>H5T_STR_NULL + <dt>H5T_STR_NULL (<code>0</code>) <dd>Pad with zeros (as C does) - <dt>H5T_STR_SPACE + <dt>H5T_STR_SPACE (<code>1</code>) <dd>Pad with spaces (as FORTRAN does) </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative string padding type on success, negative on failure + <dd>Returns a valid string padding type if successful; + otherwise <code>H5T_STR_ERROR</code> (-1). </dl> @@ -1307,20 +1391,21 @@ zero. <code>H5Tset_strpad</code> defines the storage mechanism for the string. Valid string padding values are: <ul> <dl> - <dt>H5T_STR_NULL + <dt>H5T_STR_NULL (<code>0</code>) <dd>Pad with zeros (as C does) - <dt>H5T_STR_SPACE + <dt>H5T_STR_SPACE (<code>1</code>) <dd>Pad with spaces (as FORTRAN does) </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. + <dd>Identifier of datatype to modify. <dt><em>H5T_str_t</em> <code>strpad</code> <dd>String padding type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1337,10 +1422,11 @@ zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Number of members datatype has on success, negative on failure + <dd>Returns number of members datatype has if successful; + otherwise FAIL (-1). </dl> @@ -1349,25 +1435,27 @@ zero. <dt><strong>Name:</strong> <a name="Datatype-GetMemberName">H5Tget_member_name</a> <dt><strong>Signature:</strong> <dd><em>char *</em> <code>H5Tget_member_name</code>(<em>hid_t </em><code>type_id</code>, - <em>intn</em> <code>fieldno</code> + <em>int</em> <code>field_idx</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the name of a field of a compound data type. + <dd>Retrieves the name of a field of a compound datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_member_name</code> retrieves the name of a field of a compound data type. - Fields are stored in no particular order with numbers 0 through N-1 - where N is the value returned by H5Tget_nmembers(). The name of the - field is allocated with malloc() and the caller is responsible for - freeing the memory used by the name. + <dd><code>H5Tget_member_name</code> retrieves the name of a field + of a compound datatype. Fields are stored in no particular + order, with indexes 0 through N-1, where N is the value returned + by <code>H5Tget_nmembers()</code>. The name of the field is + allocated with <code>malloc()</code> and the caller is responsible + for freeing the memory used by the name. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - <dt><em>intn</em> <code>fieldno</code> - <dd>Field number (indexed from 0) of the field name to retrieve. + <dd>Identifier of datatype to query. + <dt><em>int</em> <code>field_idx</code> + <dd>Field index (0-based) of the field name to retrieve. </dl> <dt><strong>Returns:</strong> - <dd>Valid pointer on success, NULL on failure + <dd>Returns a valid pointer if successful; + otherwise NULL. </dl> @@ -1376,30 +1464,35 @@ zero. <dt><strong>Name:</strong> <a name="Datatype-GetMemberDims">H5Tget_member_dims</a> <dt><strong>Signature:</strong> <dd><em>int</em> <code>H5Tget_member_dims</code>(<em>hid_t </em><code>type_id</code>, - <em>intn</em> <code>fieldno</code>, - <em>size_t *</em> <code>dims</code>, - <em>int *</em> <code>perm</code> + <em>int</em> <code>field_idx</code>, + <em>size_t *</em><code>dims</code>, + <em>int *</em><code>perm</code> ) <dt><strong>Purpose:</strong> <dd>Returns the dimensionality of the field. <dt><strong>Description:</strong> - <dd><code>H5Tget_member_dims</code> returns the dimensionality of the field. The dimensions - and permuation vector are returned through arguments <code>dims</code> - and <code>perm</code>, both arrays of at least four elements. Either - (or even both) may be null pointers. + <dd><code>H5Tget_member_dims</code> returns the dimensionality of + the field. The dimensions and permuation vector are returned + through arguments <code>dims</code> and <code>perm</code>, + both arrays of at least four elements. + Either (or even both) may be null pointers. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - <dt><em>intn</em> <code>fieldno</code> - <dd>Field number (indexed from 0) of the field dims to retrieve. + <dd>Identifier of datatype to query. + <dt><em>int</em> <code>field_idx</code> + <dd>Field index (0-based) of the field <code>dims</code> + to retrieve. <dt><em>size_t *</em> <code>dims</code> <dd>Pointer to buffer to store the dimensions of the field. <dt><em>int *</em> <code>perm</code> - <dd>Pointer to buffer to store the permutation vector of the field. + <dd>Pointer to buffer to store the permutation vector of + the field. </dl> <dt><strong>Returns:</strong> - <dd>Number of dimensions on success, negative on failure. + <dd>Returns the number of dimensions, a number from 0 to 4, + if successful. + Otherwise returns FAIL (-1). </dl> @@ -1408,22 +1501,24 @@ zero. <dt><strong>Name:</strong> <a name="Datatype-GetMemberType">H5Tget_member_type</a> <dt><strong>Signature:</strong> <dd><em>hid_t</em> <code>H5Tget_member_type</code>(<em>hid_t </em><code>type_id</code>, - <em>intn</em> <code>fieldno</code> + <em>int</em> <code>field_idx</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the data type of the specified member. + <dd>Returns the datatype of the specified member. <dt><strong>Description:</strong> - <dd><code>H5Tget_member_type</code> returns the data type of the specified member. The caller + <dd><code>H5Tget_member_type</code> returns the datatype of the specified member. The caller should invoke H5Tclose() to release resources associated with the type. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - <dt><em>intn</em> <code>fieldno</code> - <dd>Field number (indexed from 0) of the field type to retrieve. + <dd>Identifier of datatype to query. + <dt><em>int</em> <code>field_idx</code> + <dd>Field index (0-based) of the field type to retrieve. </dl> <dt><strong>Returns:</strong> - <dd>The ID of a copy of the datatype of the field, negative on failure. + <dd>Returns the identifier of a copy of the datatype of the field + if successful; + otherwise FAIL (-1). </dl> @@ -1437,30 +1532,32 @@ zero. <em>hid_t</em> <code>field_id</code> ) <dt><strong>Purpose:</strong> - <dd>Adds a new member to a compound data type. + <dd>Adds a new member to a compound datatype. <dt><strong>Description:</strong> - <dd><code>H5Tinsert</code> adds another member to the compound data type + <dd><code>H5Tinsert</code> adds another member to the compound datatype <code>type_id</code>. The new member has a <code>name</code> which - must be unique within the compound data type. The <code>offset</code> - argument defines the start of the member in an instance of the compound - data type, and <code>field_id</code> is the type of the new member. - - <P>Note: All members of a compound data type must be atomic; a - compound data type cannot have a member which is a compound data - type. + must be unique within the compound datatype. + The <code>offset</code> argument defines the start of the member + in an instance of the compound datatype, and <code>field_id</code> + is the datatype identifier of the new member. + <P> + Note: All members of a compound datatype must be atomic; a + compound datatype cannot have a member which is a compound + datatype. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of compound datatype to modify. + <dd>Identifier of compound datatype to modify. <dt><em>const char *</em> <code>name</code> <dd>Name of the field to insert. <dt><em>off_t</em> <code>offset</code> <dd>Offset in memory structure of the field to insert. <dt><em>hid_t</em> <code>field_id</code> - <dd>Datatype ID of the field to insert. + <dd>Datatype identifier of the field to insert. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1478,10 +1575,11 @@ zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. + <dd>Identifier of datatype to modify. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1497,32 +1595,40 @@ zero. <dt><strong>Purpose:</strong> <dd>Registers a hard conversion function. <dt><strong>Description:</strong> - <dd><code>H5Tregister_hard</code> registers a hard conversion function for a data type + <dd><code>H5Tregister_hard</code> registers a hard conversion function for a datatype conversion path. The path is specified by the source and destination datatypes <code>src_id</code> and <code>dst_id</code>. A conversion path can only have one hard function, so <code>func</code> replaces any previous hard function. - <P>If <code>func</code> is the null pointer then any hard function + <p> + If <code>func</code> is the null pointer then any hard function registered for this path is removed from this path. The soft functions are then used when determining which conversion function is appropriate for this path. The <code>name</code> argument is used only for debugging and should be a short identifier for the function. - <P>The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); + <p> + The type of the conversion function pointer is declared as: + <br> + <code>typedef</code> <em>herr_t </em>(<code>*H5T_conv_t</code>) (<em>hid_t </em><code>src_id</code>, + <em>hid_t </em><code>dst_id</code>, + <em>H5T_cdata_t *</em><code>cdata</code>, + <em>size_t </em><code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>bkg)</code>; <dt><strong>Parameters:</strong> <dl> <dt><em>const char *</em> <code>name</code> <dd>Name displayed in diagnostic output. <dt><em>hid_t</em> <code>src_id</code> - <dd>ID of source datatype. + <dd>Identifier of source datatype. <dt><em>hid_t</em> <code>dst_id</code> - <dd>ID of destination datatype. + <dd>Identifier of destination datatype. <dt><em>H5T_conv_t</em> <code>func</code> <dd>Function to convert between source and destination datatypes. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1531,8 +1637,8 @@ zero. <dt><strong>Name:</strong> <a name="Datatype-RegisterSoft">H5Tregister_soft</a> <dt><strong>Signature:</strong> <dd><em>herr_t</em> <code>H5Tregister_soft</code>(<em>const char - *</em> <code>name</code>, <em>hid_t </em><code>src_id</code>, - <em>hid_t</em> <code>dst_id</code>, + *</em> <code>name</code>, <em>H5T_class_t </em><code>src_cls</code>, + <em>H5T_class_t</em> <code>dst_cls</code>, <em>H5T_conv_t</em> <code>func</code> ) <dt><strong>Purpose:</strong> @@ -1543,22 +1649,29 @@ zero. applicable existing conversion paths. The <code>name</code> is used only for debugging and should be a short identifier for the function. - <P>The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); + <P> + The type of the conversion function pointer is declared as: + <br> + <code>typedef</code> <em>herr_t </em>(<code>*H5T_conv_t</code>) (<em>hid_t </em><code>src_id</code>, + <em>hid_t </em><code>dst_id</code>, + <em>H5T_cdata_t *</em><code>cdata</code>, + <em>size_t </em><code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>bkg)</code>; <dt><strong>Parameters:</strong> <dl> <dt><em>const char *</em> <code>name</code> <dd>Name displayed in diagnostic output. - <dt><em>hid_t</em> <code>src_id</code> - <dd>ID of source datatype. - <dt><em>hid_t</em> <code>dst_id</code> - <dd>ID of destination datatype. + <dt><em>H5T_class_t</em> <code>src_cls</code> + <dd>Identifier of source datatype class. + <dt><em>H5T_class_t</em> <code>dst_cls</code> + <dd>Identifier of destination datatype class. <dt><em>H5T_conv_t</em> <code>func</code> <dd>Function to convert between source and destination datatypes. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1572,16 +1685,23 @@ zero. <dd>Removes a conversion function from all conversion paths. <dt><strong>Description:</strong> <dd><code>H5Tunregister</code> removes a conversion function from all conversion paths. - <P>The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); + <P> + The type of the conversion function pointer is declared as: + <br> + <code>typedef</code> <em>herr_t </em>(<code>*H5T_conv_t</code>) (<em>hid_t </em><code>src_id</code>, + <em>hid_t </em><code>dst_id</code>, + <em>H5T_cdata_t *</em><code>cdata</code>, + <em>size_t </em><code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>bkg)</code>; <dt><strong>Parameters:</strong> <dl> <dt><em>H5T_conv_t</em> <code>func</code> <dd>Function to remove from conversion paths. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1594,170 +1714,42 @@ zero. <dt><strong>Purpose:</strong> <dd>Releases a datatype. <dt><strong>Description:</strong> - <dd><code>H5Tclose</code> releases a datatype. Further access through the datatype - ID is illegal. Failure to release a datatype with this call will - result in resource leaks. + <dd><code>H5Tclose</code> releases a datatype. Further access + through the datatype identifier is illegal. Failure to release + a datatype with this call will result in resource leaks. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to release. + <dd>Identifier of datatype to release. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> <hr> -<hr> - -<b>Aha!! And here is the reference to sharing and that command that had us -so buffaloed, <code>H5Tshare</code>!</b><br> -To quote Quincy: "The H5Tshare() and H5Tis_shared() will be removed. Data types -will not be stored in the global heap. A new type of shared -message header will be added to the object headers that points to -another object header instead of the global heap..." - -<hr> -<hr> -</b>UNUSED PORTIONS OF EMAIL NOTES.</b> -<br> -<code>....</code> in left margin indicates where material was - pulled out for inclusion above. -<HR> -<HR> -<pre> - -Elena> Datatype Interface: -Elena> Do we have description of the named datatypes somewhere? - ->From Datatypes.html... - -html> 7. Sharing Data Types among Datasets -html> -html> If a file has lots of datasets which have a common data type -html> then the file could be made smaller by having all the datasets -html> share a single data type. Instead of storing a copy of the data -html> type in each dataset object header, a single data type is stored -html> and the object headers point to it. The space savings is -html> probably only significant for datasets with a compound data type -html> since the simple data types can be described with just a few -html> bytes anyway. -html> -html> To create a bunch of datasets that share a single data type just -html> create the datasets with a committed (named) data type. -html> -html> To create two datasets that share a common data type one just -html> commits the data type, giving it a name, and then uses that -html> data type to create the datasets. -html> -html> hid_t t1 = ...some transient type...; -html> H5Tcommit (file, "shared_type", t1); -html> hid_t dset1 = H5Dcreate (file, "dset1", t1, space, H5P_DEFAULT); -html> hid_t dset2 = H5Dcreate (file, "dset2", t1, space, H5P_DEFAULT); -html> -html> -html> And to create two additional datasets later which share the -html> same type as the first two datasets: -html> -html> hid_t dset1 = H5Dopen (file, "dset1"); -html> hid_t t2 = H5Dget_type (dset1); -html> hid_t dset3 = H5Dcreate (file, "dset3", t2, space, H5P_DEFAULT); -html> hid_t dset4 = H5Dcreate (file, "dset4", t2, space, H5P_DEFAULT); -html> -html> -html> Example: Shared Types - -Mail from Quincey summarizing shared data types: - -Quincey> Hi Robb, -Quincey> Everything looks good, I just have a couple of minor comments below: -Quincey> -Quincey> > A very quick data types summary (so I can remember it next week :-) -Quincey> > -Quincey> > * Handles to named types are immutable. -Quincey> > -Quincey> > * A transient type handle can be converted to a named type handle -Quincey> > by calling H5Tcommit(). This can only be called for transient -Quincey> > types which are not locked or predefined. -Quincey> > -Quincey> > * H5Topen() returns a handle to a named immutable type. -Quincey> > -Quincey> > * H5Tcopy() returns a handle to a transient type. -Quincey> H5Tcreate also returns a handle to a transient type. -Quincey> -Quincey> > * Using a named type in H5Dcreate() causes the dataset object -Quincey> > header to point to the named type (shared). The link count on -Quincey> > the named type is incremented. -Quincey> > -Quincey> > * Using a transient type in H5Dcreate() causes the type to be -Quincey> > copied and stored in the dataset header (unshared). -Quincey> > -Quincey> > * Type handles returned from H5Dget_type() are immutable. -Quincey> > -Quincey> > * If the dataset is using a shared type (dataset object header -Quincey> > points to some other object header with a type message, e.g., a -Quincey> > named type) then H5Dget_type() returns a handle to that named -Quincey> > type. -Quincey> > -Quincey> > * If the dataset has a private type (data type is stored in the -Quincey> > dataset object header) then H5Dget_type() returns a handle to a -Quincey> > transient immutable type. -Quincey> > -Quincey> > * The name of a data type can be removed from a group, but unless -Quincey> > the reference count becomes zero the type continues to exist. -Quincey> > (Other objects work this way too). -Quincey> > -Quincey> > * H5Tcopy() applied to a dataset returns a transient, modifiable -Quincey> > copy of that dataset's data type. -Quincey> > -Quincey> > * H5Topen() applied to a dataset returns either a transient -Quincey> > immutable or named immutable data type depending on whether the -Quincey> > dataset has a shared data type. -Quincey> Hmm, do we want to allow this? It makes a certain amount of sense, but -Quincey> is a little unusual... :-) -Quincey> - -Elena, we decided not not to allow H5Topen() on a dataset. - -Quincey> -Quincey> > * The H5Tshare() and H5Tis_shared() will be removed. Data types -Quincey> > will not be stored in the global heap. A new type of shared -Quincey> > message header will be added to the object headers that points to -Quincey> > another object header instead of the global heap -Quincey> -Quincey> > * Still to discuss: Attributes on named data types? -Quincey> I think we should all them. -Quincey> - -Elena, attributes work for named data types just like they do for -datasets. - -Quincey> -Quincey> > * Still to discuss: compound types whose members point to other types. -Quincey> I like this concept a lot and this we should figure out a way to do it. -Quincey> This allows the "is a" relationship to be used very nicely for named datatypes. -Quincey> -Quincey> > * Still to discuss: datasets that point to data types in other -Quincey> > files by symbolic link. -Quincey> Probably a good idea also, just ugly to implement. -Quincey> - -</pre> -<hr> -<hr> - - - - +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +H5T +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> <hr> <address> -<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> -<br> -<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 9 July 1998 +Last modified: 14 July 1998 </body> </html> |