summaryrefslogtreecommitdiffstats
path: root/doc/html/RM_H5T.html
diff options
context:
space:
mode:
authorFrank Baker <fbaker@hdfgroup.org>2003-10-08 21:48:44 (GMT)
committerFrank Baker <fbaker@hdfgroup.org>2003-10-08 21:48:44 (GMT)
commitdc4212e15c46716ad05739e7d40d61b95b94c9a2 (patch)
tree19cf2927d88894f70d253944766b2a8895e9216f /doc/html/RM_H5T.html
parentcccd86aa0edc1698478178ae90476281ac1caf5d (diff)
downloadhdf5-dc4212e15c46716ad05739e7d40d61b95b94c9a2.zip
hdf5-dc4212e15c46716ad05739e7d40d61b95b94c9a2.tar.gz
hdf5-dc4212e15c46716ad05739e7d40d61b95b94c9a2.tar.bz2
[svn-r7577]
Purpose: Alphabetic sort of RM function entries Additional and modified HTML coding to accomodate HTMLdoc and automated PDF generation Minor copy edits Platforms tested: IE 5, Safari
Diffstat (limited to 'doc/html/RM_H5T.html')
-rw-r--r--doc/html/RM_H5T.html2665
1 files changed, 1364 insertions, 1301 deletions
diff --git a/doc/html/RM_H5T.html b/doc/html/RM_H5T.html
index 62e858b..4031bc3 100644
--- a/doc/html/RM_H5T.html
+++ b/doc/html/RM_H5T.html
@@ -25,6 +25,7 @@ HDF5/H5T API Specification
<!-- #EndLibraryItem --></head>
<body bgcolor="#FFFFFF">
+<!-- HEADER RIGHT " " -->
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
@@ -60,8 +61,7 @@ And in this document, the
</td></tr>
</table>
</center>
-<hr>
-<!-- #EndLibraryItem --><center>
+<hr><!-- #EndLibraryItem --><center>
<h1>H5T: Datatype Interface</h1>
</center>
@@ -244,20 +244,20 @@ of a dataset.
</tr>
</table>
-<p>
+<br>
<strong>The FORTRAN90 Interfaces:</strong>
<br>
<font size=-1>
<i>In general, each FORTRAN90 subroutine performs exactly the same task
-as the corresponding C function. The links below go to the C function
+as the corresponding C function. The links below (electronic versions only) go to the C function
descriptions, which serve as general descriptions for both. A button,
under <strong>Non-C API(s)</strong> at the end of the C function description,
opens an external browser window displaying the FORTRAN90-specific
information. You will probably want to adjust the size and location of
this external window so that both browser windows are visible and to
facilitate moving easily between them.</i>
-</font>
+</font><br>
<table border=0>
<tr><td valign=top width=32%>
@@ -315,16 +315,16 @@ facilitate moving easily between them.</i>
<!-- </td></tr></table> -->
<p>
<i>Array Datatypes</i>
- <li><a href="#Datatype-ArrayCreate">H5Tarray_create_f</a>
- <li><a href="#Datatype-GetArrayNdims">H5Tget_array_ndims_f</a>
- <li><a href="#Datatype-GetArrayDims">H5Tget_array_dims_f</a>
+ <li><a href="#Datatype-ArrayCreate">h5tarray_create_f</a>
+ <li><a href="#Datatype-GetArrayNdims">h5tget_array_ndims_f</a>
+ <li><a href="#Datatype-GetArrayDims">h5tget_array_dims_f</a>
<!--<p> -->
<!--<i>Variable-length Datatypes</i> -->
<!--<li><a href="#Datatype-VLCreate">h5tvlen_create_f</a> -->
</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top width=32%>
<i>Compound Datatype Properties</i>
<li><a href="#Datatype-GetNmembers">h5tget_nmembers_f</a>
-<!--<li><a href="#Datatype-GetMemberClass">H5Tget_member_class_f</a> -->
+<!--<li><a href="#Datatype-GetMemberClass">h5tget_member_class_f</a> -->
<li><a href="#Datatype-GetMemberName">h5tget_member_name_f</a>
<!--<li><a href="#Datatype-GetMemberIndex">h5tget_member_index_f</a> -->
<li><a href="#Datatype-GetMemberOffset">h5tget_member_offset_f</a>
@@ -383,34 +383,58 @@ A <em>data point</em> is an instance of a <em>datatype</em>,
See <a href="Datatypes.html"><cite>The Datatype Interface (H5T)</cite></a>
in the <cite>HDF5 User's Guide</cite> for further information, including a complete list of all supported datatypes.
-
+<!-- NEW PAGE -->
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tarray_create" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-Open">H5Topen</a>
+<dt><strong>Name:</strong> <a name="Datatype-ArrayCreate">H5Tarray_create</a>
<dt><strong>Signature:</strong>
- <dd><em>hid_t</em><code>H5Topen</code>(<em>hid_t</em> <code>loc_id</code>,
- <em>const char *</em> <code>name</code>
+ <dd><em>hid_t</em> <code>H5Tarray_create</code>(
+ <em>hid_t</em> <code>base</code>,
+ <em>int</em> <code>rank</code>,
+ <em>const hsize_t</em> <code>dims[/*rank*/]</code>,
+ <em>const int</em> <code>perm[/*rank*/]</code>
)
<dt><strong>Purpose:</strong>
- <dd>Opens a named datatype.
+ <dd>Creates an array datatype object.
<dt><strong>Description:</strong>
- <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.
+ <dd><code>H5Tarray_create</code> creates a new array datatype object.
+ <p>
+ <code>base</code> is the datatype of every element of the array,
+ i.e., of the number at each position in the array.
+ <p>
+ <code>rank</code> is the number of dimensions and the
+ size of each dimension is specified in the array <code>dims</code>.
+ The value of <code>rank</code> is currently limited to
+ <code>H5S_MAX_RANK</code> and must be greater than <code>0</code>
+ (zero).
+ All dimension sizes specified in <code>dims</code> must be greater
+ than <code>0</code> (zero).
+ <p>
+ The array <code>perm</code> is designed to contain the dimension
+ permutation, i.e. C versus FORTRAN array order.
+ &nbsp;
+ <b><i>(The parameter </i><code>perm</code><i> is currently unused and is not yet implemented.)</i></b>
+ <p>
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>loc_id</code>
- <dd>IN: A file or group identifier.
- <dt><em>const char *</em> <code>name</code>
- <dd>IN: A datatype name, defined within the file or group identified by <code>loc_id</code>.
+ <dt><em>hid_t</em> <code>base</code>
+ <dd>IN: Datatype identifier for the array base datatype.
+ <dt><em>int</em> <code>rank</code>
+ <dd>IN: Rank of the array.
+ <dt><em>const hsize_t</em> <code>dims[/*rank*/]</code>
+ <dd>IN: Size of each array dimension.
+ <dt><em>const int</em> <code>perm[/*rank*/]</code>
+ <dd>IN: Dimension permutation.
+ &nbsp;
+ <b><i>(Currently not implemented.)</i></b>
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a named datatype identifier if successful;
+ <dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5topen_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tarray_create_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -418,7 +442,39 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tclose" -->
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Datatype-Close">H5Tclose</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t </em><code>H5Tclose</code>(<em>hid_t </em><code>type_id</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Releases a datatype.
+<dt><strong>Description:</strong>
+ <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>Identifier of datatype to release.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+<dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tclose_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tcommit" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Datatype-Commit">H5Tcommit</a>
@@ -456,7 +512,8 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tcommitted" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Datatype-Committed">H5Tcommitted</a>
@@ -491,48 +548,8 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl
-->
</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Datatype-Find">H5Tfind</a>
-<dt><strong>Signature:</strong>
- <dd><em>H5T_conv_t</em> <code>H5Tfind</code>(<em>hid_t</em> <code>src_id</code>,
- <em>hid_t</em> <code>dst_id</code>,
- <em>H5T_cdata_t **</em><code>pcdata</code>
- )
-<dt><strong>Purpose:</strong>
- <dd>Finds a conversion function.
-<dt><strong>Description:</strong>
- <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>IN: Identifier for the source datatype.
- <dt><em>hid_t</em> <code>dst_id</code>
- <dd>IN: Identifier for the destination datatype.
- <dt><em>H5T_cdata_t **</em><code>pcdata</code>
- <dd>OUT: Pointer to type conversion data.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Returns a pointer to a suitable conversion function if successful.
- Otherwise returns NULL.
-<!--
-<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tfind_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
---> <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tconvert" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Datatype-Convert">H5Tconvert</a>
@@ -593,200 +610,8 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl
-->
</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetOverflow">H5Tset_overflow</a>
-<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Tset_overflow</code>(<em>H5T_overflow_t</em> <code>func</code>)
-<dt><strong>Purpose:</strong>
- <dd>Sets the overflow handler to a specified function.
-<dt><strong>Description:</strong>
- <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 datatype conversions that
- result in an overflow.
- <p>
- See the definition of <code>H5T_overflow_t</code> in
- <code>H5Tpublic.h</code> for documentation
- of arguments and return values.
- The prototype for <code>H5T_overflow_t</code> is as follows:<br>
- <code>herr_t (*H5T_overflow_t)(hid_t src_id, hid_t dst_id,
- void *src_buf, void *dst_buf);
- </code>
- <p>
- The NULL pointer may be passed to remove the overflow handler.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>H5T_overflow_t</em> <code>func</code>
- <dd>Overflow function.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
-<!--
-<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_overflow_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
---> <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetOverflow">H5Tget_overflow</a>
-<dt><strong>Signature:</strong>
-
-
-H5Tget_overflow ()
- <dd><em>H5T_overflow_t</em> <code>H5Tget_overflow</code>(<code>void</code>)
-<dt><strong>Purpose:</strong>
- <dd>Returns a pointer to the current global overflow function.
-<dt><strong>Description:</strong>
- <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
- datatype conversion causes an overflow.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt>None.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Returns a pointer to an application-defined function if successful.
- Otherwise returns NULL; this can happen if no overflow handling
- function is registered.
-<!--
-<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_overflow_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
---> <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Datatype-Create">H5Tcreate</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Tcreate</code>(<em>H5T_class_t </em><code>class</code>,
- <em>size_t</em><code>size</code>
- )
-<dt><strong>Purpose:</strong>
- <dd>Creates a new datatype.
-<dt><strong>Description:</strong>
- <dd><code>H5Tcreate</code> creates a new datatype of the specified
- class with the specified number of bytes.
- <p>
- The following datatype classes are supported with this function:
- <ul>
- <li><code>H5T_COMPOUND</code>
- <li><code>H5T_OPAQUE</code>
- <li><code>H5T_ENUM</code>
- </ul>
- <p>
- Use <code>H5Tcopy</code> to create integer or floating-point datatypes.
- <p>
- 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>
- <dd>Class of datatype to create.
- <dt><em>size_t</em> <code>size</code>
- <dd>The number of bytes in the datatype to create.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Returns datatype identifier if successful;
- otherwise returns a negative value.
-<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tcreate_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Datatype-VLCreate">H5Tvlen_create</a>
-<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Tvlen_create</code>(<em>hid_t </em><code>base_type_id</code>
- )
-<dt><strong>Purpose:</strong>
- <dd>Creates a new variable-length datatype.
-<dt><strong>Description:</strong>
- <dd><code>H5Tvlen_create</code> creates a new variable-length (VL) datatype.
- <p>
- The base datatype will be the datatype that the sequence is composed of,
- characters for character strings, vertex coordinates for polygon lists, etc.
- The base type specified for the VL datatype can be of any HDF5 datatype,
- including another VL datatype, a compound datatype or an atomic datatype.
- <p>
- When necessary, use <code>H5Tget_super</code> to determine the base type
- of the VL datatype.
- <p>
- 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>hid_t</em> <code>base_type_id</code>
- <dd>Base type of datatype to create.
- </dl>
-<dt><strong>See Also:</strong>
- <dd><a href="RM_H5D.html#Dataset-GetVLBuf">H5Dget_vlen_buf_size</a>
- <dd><a href="RM_H5D.html#Dataset-VLReclaim">H5Dvlen_reclaim</a>
-<dt><strong>Returns:</strong>
- <dd>Returns datatype identifier if successful;
- otherwise returns a negative value.
-<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tvlen_create_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Datatype-IsVariableString">H5Tis_variable_str</a>
-<dt><strong>Signature:</strong>
- <dd><em>htri_t </em><code>H5Tis_variable_str</code>(<em>hid_t </em><code>dtype_id</code>
- )
-<dt><strong>Purpose:</strong>
- <dd>Determines whether datatype is a variable-length string.
-<dt><strong>Description:</strong>
- <dd><code>H5Tvlen_create</code> determines whether the datatype
- identified in <code>dtype_id</code> is a variable-length string.
- <p>
- This function can be used to distinguish between
- fixed and variable-length string datatypes.
-<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dtype_id</code>
- <dd>Datatype identifier.
- </dl>
-<dt><strong>Returns:</strong>
- <dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful;
- otherwise returns a negative value.
-<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tis_variable_str_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tcopy" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Datatype-Copy">H5Tcopy</a>
@@ -880,33 +705,44 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tcreate" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-Equal">H5Tequal</a>
+<dt><strong>Name:</strong> <a name="Datatype-Create">H5Tcreate</a>
<dt><strong>Signature:</strong>
- <dd><em>htri_t </em><code>H5Tequal</code>(<em>hid_t </em><code>type_id1</code>,
- <em>hid_t</em><code>type_id2</code>
+ <dd><em>hid_t </em><code>H5Tcreate</code>(<em>H5T_class_t </em><code>class</code>,
+ <em>size_t</em><code>size</code>
)
<dt><strong>Purpose:</strong>
- <dd>Determines whether two datatype identifiers refer to the same datatype.
+ <dd>Creates a new datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tequal</code> determines whether two datatype identifiers
- refer to the same datatype.
+ <dd><code>H5Tcreate</code> creates a new datatype of the specified
+ class with the specified number of bytes.
+ <p>
+ The following datatype classes are supported with this function:
+ <ul>
+ <li><code>H5T_COMPOUND</code>
+ <li><code>H5T_OPAQUE</code>
+ <li><code>H5T_ENUM</code>
+ </ul>
+ <p>
+ Use <code>H5Tcopy</code> to create integer or floating-point datatypes.
+ <p>
+ 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>hid_t</em> <code>type_id1</code>
- <dd>Identifier of datatype to compare.
- <dt><em>hid_t</em> <code>type_id2</code>
- <dd>Identifier of datatype to compare.
+ <dt><em>H5T_class_t</em> <code>class</code>
+ <dd>Class of datatype to create.
+ <dt><em>size_t</em> <code>size</code>
+ <dd>The number of bytes in the datatype to create.
</dl>
<dt><strong>Returns:</strong>
- <dd>When successful, returns a positive value, for <code>TRUE</code>,
- if the datatype identifiers refer to the same datatype,
- or <code>0</code> (zero), for <code>FALSE</code>.
- Otherwise returns a negative value.
+ <dd>Returns datatype identifier if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tequal_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tcreate_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -914,33 +750,41 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tdetect_class" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-Lock">H5Tlock</a>
+<dt><strong>Name:</strong> <a name="Datatype-DetectClass">H5Tdetect_class</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tlock</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>htri_t </em><code>H5Tdetect_class</code>(<em>hid_t</em> <code>dtype_id</code>,
+ <em>H5T_class_t</em><code>dtype_class</code>
)
<dt><strong>Purpose:</strong>
- <dd>Locks a datatype.
+ <dd>Determines whether a datatype contains any datatypes of the
+ given datatype class.
<dt><strong>Description:</strong>
- <dd><code>H5Tlock</code> locks the datatype specified by the
- <code>type_id</code> identifier, making it read-only and
- non-destructible. 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.
+ <dd><code>H5Tdetect_class</code> determines whether the datatype
+ specified in <code>dtype_id</code> contains any datatypes of the
+ datatype class specified in <code>dtype_class</code>.
+ <p>
+ This function is useful primarily in recursively examining
+ all the fields and/or base types
+ of compound, array, and variable-length datatypes.
+ <p>
+ Valid class identifiers are as defined in
+ <a href="#Datatype-GetClass"><code>H5Tget_class</code></a>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to lock.
+ <dt><em>hid_t</em> <code>dtype_id</code>
+ <dd>Datatype identifier.
+ <dt><em>H5T_class_t</em><code>dtype_class</code>
+ <dd>Datatype class.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
+ <dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful;
otherwise returns a negative value.
-<!--
-<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tlock_f"
+<!--<dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tdetect_class_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
--> <!--
<img src="Graphics/Java.gif">
@@ -948,41 +792,30 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tenum_create" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetClass">H5Tget_class</a>
+<dt><strong>Name:</strong> <a name="Datatype-EnumCreate">H5Tenum_create</a>
<dt><strong>Signature:</strong>
- <dd><em>H5T_class_t </em><code>H5Tget_class</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>hid_t</em> <code>H5Tenum_create</code>(<em>hid_t</em> <code>parent_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the datatype class identifier.
+ <dd>Creates a new enumeration datatype.
<dt><strong>Description:</strong>
- <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>
- <li><code>H5T_FLOAT</code>
- <li><code>H5T_TIME</code>
- <li><code>H5T_STRING</code>
- <li><code>H5T_BITFIELD</code>
- <li><code>H5T_OPAQUE</code>
- <li><code>H5T_COMPOUND</code>
- <li><code>H5T_REFERENCE</code>
- <li><code>H5T_ENUM</code>
- <li><code>H5T_VLEN</code>
- <li><code>H5T_ARRAY</code>
- </ul>
+ <dd><code>H5Tenum_create</code> creates a new enumeration datatype
+ based on the specified base datatype, <code>parent_id</code>,
+ which must be an integer type.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to query.
+ <dt><em>hid_t</em> <code>parent_id</code>
+ <dd>IN: Datatype identifier for the base datatype.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns datatype class identifier if successful;
- otherwise <code>H5T_NO_CLASS</code> (-1).
+ <dd>Returns the datatype identifier for the new enumeration datatype if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_class_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_create_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -990,68 +823,95 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tenum_insert" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-DetectClass">H5Tdetect_class</a>
+<dt><strong>Name:</strong> <a name="Datatype-EnumInsert">H5Tenum_insert</a>
<dt><strong>Signature:</strong>
- <dd><em>htri_t </em><code>H5Tdetect_class</code>(<em>hid_t</em> <code>dtype_id</code>,
- <em>H5T_class_t</em><code>dtype_class</code>
+ <dd><em>herr_t</em> <code>H5Tenum_insert</code>(<em>hid_t</em> <code>type</code>,
+ <em>const char</em> *<code>name</code>,
+ <em>void</em> *<code>value</code>
)
<dt><strong>Purpose:</strong>
- <dd>Determines whether a datatype contains any datatypes of the
- given datatype class.
+ <dd>Inserts a new enumeration datatype member.
<dt><strong>Description:</strong>
- <dd><code>H5Tdetect_class</code> determines whether the datatype
- specified in <code>dtype_id</code> contains any datatypes of the
- datatype class specified in <code>dtype_class</code>.
+ <dd><code>H5Tenum_insert</code> inserts a
+ new enumeration datatype member into an enumeration datatype.
<p>
- This function is useful primarily in recursively examining
- all the fields and/or base types
- of compound, array, and variable-length datatypes.
+ <code>type</code> is the enumeration datatype,
+ <code>name</code> is the name of the new member, and
+ <code>value</code> points to the value of the new member.
<p>
- Valid class identifiers are as defined in
- <a href="#Datatype-GetClass"><code>H5Tget_class</code></a>.
+ <code>name</code> and <code>value</code> must both
+ be unique within <code>type</code>.
+ <p>
+ <code>value</code> points to data which is of the
+ datatype defined when the enumeration datatype was created.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>dtype_id</code>
- <dd>Datatype identifier.
- <dt><em>H5T_class_t</em><code>dtype_class</code>
- <dd>Datatype class.
+ <dt><em>hid_t</em> <code>type</code>
+ <dd>IN: Datatype identifier for the enumeration datatype.
+ <dt><em>const char</em> *<code>name</code>
+ <dd>IN: Name of the new member.
+ <dt><em>void</em> *<code>value</code>
+ <dd>IN: Pointer to the value of the new member.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful;
+ <dd>Returns a non-negative value if successful;
otherwise returns a negative value.
-<!--<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tdetect_class_f"
+<dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_insert_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
---> <!--
+ <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tenum_nameof" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetSize">H5Tget_size</a>
+<dt><strong>Name:</strong> <a name="Datatype-EnumNameOf">H5Tenum_nameof</a>
<dt><strong>Signature:</strong>
- <dd><em>size_t </em><code>H5Tget_size</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>herr_t</em> <code>H5Tenum_nameof</code>(<em>hid_t</em> <code>type</code>
+ <em>void</em> *<code>value</code>,
+ <em>char</em> *<code>name</code>,
+ <em>size_t</em> <code>size</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the size of a datatype.
+ <dd>Returns the symbol name corresponding to a specified member of an enumeration datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_size</code> returns the size of a datatype in bytes.
+ <dd><code>H5Tenum_nameof</code> finds the symbol name that
+ corresponds to the specified <code>value</code>
+ of the enumeration datatype <code>type</code>.
+ <p>
+ At most <code>size</code> characters of the symbol
+ name are copied into the <code>name</code> buffer.
+ If the entire symbol name and null terminator
+ do not fit in the <code>name</code> buffer, then as
+ many characters as possible are copied
+ (not null terminated) and the function fails.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to query.
+ <dt><em>hid_t</em> <code>type</code>
+ <dd>IN: Enumeration datatype identifier.
+ <dt><em>void</em> *<code>value</code>,
+ <dd>IN: Value of the enumeration datatype.
+ <dt><em>char</em> *<code>name</code>,
+ <dd>OUT: Buffer for output of the symbol name.
+ <dt><em>size_t</em> <code>size</code>
+ <dd>IN: Anticipated size of the symbol name, in bytes (characters).
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the size of the datatype in bytes if successful;
- otherwise 0.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value
+ and, if <code>size</code> allows it,
+ the first character of <code>name</code> is
+ set to <code>NULL</code>.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_size_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_nameof_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1059,41 +919,40 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tenum_valueof" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetSize">H5Tset_size</a>
+<dt><strong>Name:</strong> <a name="Datatype-EnumValueOf">H5Tenum_valueof</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_size</code>(<em>hid_t </em><code>type_id</code>,
- <em>size_t</em><code>size</code>
+ <dd><em>herr_t</em> <code>H5Tenum_valueof</code>(<em>hid_t</em> <code>type</code>
+ <em>char</em> *<code>name</code>,
+ <em>void</em> *<code>value</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the total size for an atomic datatype.
+ <dd>Returns the value corresponding to a specified member of an enumeration datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tset_size</code> sets the total size in bytes,
- <code>size</code>, for a datatype. If the datatype is atomic and 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 datatype still hang over the edge of the new size, then
- the number of significant bits is decreased.
- The size set for a string should include space for the null-terminator
- character, otherwise it will not be stored on (or retrieved from) disk.
- Adjusting the size of an string automatically sets the precision
- to 8*size. A compound datatype may increase in size, but may not
- shrink. All datatypes must have a positive size.
+ <dd><code>H5Tenum_valueof</code> finds the value that
+ corresponds to the specified <code>name</code>
+ of the enumeration datatype <code>type</code>.
+ <p>
+ The <code>value</code> argument should be at least
+ as large as the value of <code>H5Tget_size(type)</code>
+ in order to hold the result.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to change size.
- <dt><em>size_t</em> <code>size</code>
- <dd>Size in bytes to modify datatype.
+ <dt><em>hid_t</em> <code>type</code>
+ <dd>IN: Enumeration datatype identifier.
+ <dt><em>const char</em> *<code>name</code>,
+ <dd>IN: Symbol name of the enumeration datatype.
+ <dt><em>void</em> *<code>value</code>,
+ <dd>OUT: Buffer for output of the value of the enumeration datatype.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_size_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_valueof_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1101,30 +960,34 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tequal" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetSuper">H5Tget_super</a>
+<dt><strong>Name:</strong> <a name="Datatype-Equal">H5Tequal</a>
<dt><strong>Signature:</strong>
- <dd><em>hid_t</em> <code>H5Tget_super</code>(<em>hid_t</em> <code>type</code>
+ <dd><em>htri_t </em><code>H5Tequal</code>(<em>hid_t </em><code>type_id1</code>,
+ <em>hid_t</em><code>type_id2</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the base datatype from which a datatype is derived.
+ <dd>Determines whether two datatype identifiers refer to the same datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_super</code> returns the base datatype from which the
- datatype <code>type</code> is derived.
- <P>
- In the case of an enumeration type, the return value is an integer type.
+ <dd><code>H5Tequal</code> determines whether two datatype identifiers
+ refer to the same datatype.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type</code>
- <dd>Datatype identifier for the derived datatype.
+ <dt><em>hid_t</em> <code>type_id1</code>
+ <dd>Identifier of datatype to compare.
+ <dt><em>hid_t</em> <code>type_id2</code>
+ <dd>Identifier of datatype to compare.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the datatype identifier for the base datatype if successful;
- otherwise returns a negative value.
+ <dd>When successful, returns a positive value, for <code>TRUE</code>,
+ if the datatype identifiers refer to the same datatype,
+ or <code>0</code> (zero), for <code>FALSE</code>.
+ Otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_super_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tequal_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1132,87 +995,41 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tfind" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetNativeType">H5Tget_native_type</a>
+<dt><strong>Name:</strong> <a name="Datatype-Find">H5Tfind</a>
<dt><strong>Signature:</strong>
- <dd><em>hid_t</em> <code>H5Tget_native_type</code>(<em>hid_t</em> <code>type_id</code>,
- <em>H5T_direction_t</em> <code>direction</code>
+ <dd><em>H5T_conv_t</em> <code>H5Tfind</code>(<em>hid_t</em> <code>src_id</code>,
+ <em>hid_t</em> <code>dst_id</code>,
+ <em>H5T_cdata_t **</em><code>pcdata</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the native datatype of a specified datatype.
+ <dd>Finds a conversion function.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_native_type</code> returns the equivalent native datatype
- for the datatype specified in <code>type_id</code>.
- <p>
- <code>H5Tget_native_type</code> is a high-level function designed
- primarily to facilitate use of the <code>H5Dread</code> function,
- for which users otherwise must undertake a multi-step process to
- determine the native datatype of a dataset prior to reading it
- into memory.
- It can be used not only to determine
- the native datatype for atomic datatypes,
- but also to determine the native datatypes of the individual components of
- a compound datatype, an enumerated datatype, an array datatype, or
- a variable-length datatype.
- <p>
- <code>H5Tget_native_type</code> selects the matching native datatype
- from the following list:
- <pre> H5T_NATIVE_CHAR
- H5T_NATIVE_SHORT
- H5T_NATIVE_INT
- H5T_NATIVE_LONG
- H5T_NATIVE_LLONG
-
- H5T_NATIVE_UCHAR
- H5T_NATIVE_USHORT
- H5T_NATIVE_UINT
- H5T_NATIVE_ULONG
- H5T_NATIVE_ULLONG
-
- H5T_NATIVE_FLOAT
- H5T_NATIVE_DOUBLE
- H5T_NATIVE_LDOUBLE</pre>
- <p>
- The <code>direction</code> parameter indicates the order
- in which the library searches for a native datatype match.
- Valid values for <code>direction</code> are as follows:
- <table border=0>
- <tr valign=top><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>H5T_DIR_ASCEND</code></td><td>
- Searches the above list in ascending size of the datatype,<br>
- i.e., from top to bottom. (Default)
- </td></tr>
- <tr valign=top><td>&nbsp;</td><td>
- <code>H5T_DIR_DESCEND</code>&nbsp;&nbsp;</td><td>
- Searches the above list in descending size of the datatype,<br>
- i.e., from bottom to top.
- </td></tr>
- </table>
- <p>
- <code>H5Tget_native_type</code> is designed primarily for
- use with intenger and floating point datatypes.
- Time, bifield, opaque, and reference datatypes are returned
- as a copy of <code>type_id</code>.
- <p>
- The identifier returned by <code>H5Tget_native_type</code>
- should eventually be closed by calling <code>H5Tclose</code>
- to release resources.
+ <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>type_id</code>
- <dd>Datatype identifier for the dataset datatype.
- <dt><em>H5T_direction_t</em> <code>direction</code>
- <dd>Direction of search.
+ <dt><em>hid_t</em> <code>src_id</code>
+ <dd>IN: Identifier for the source datatype.
+ <dt><em>hid_t</em> <code>dst_id</code>
+ <dd>IN: Identifier for the destination datatype.
+ <dt><em>H5T_cdata_t **</em><code>pcdata</code>
+ <dd>OUT: Pointer to type conversion data.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the native datatype identifier for the
- specified dataset datatype if successful;
- otherwise returns a negative value.
+ <dd>Returns a pointer to a suitable conversion function if successful.
+ Otherwise returns NULL.
<!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_native_type_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tfind_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
--> <!--
<img src="Graphics/Java.gif">
@@ -1220,38 +1037,40 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_array_dims" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetOrder">H5Tget_order</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetArrayDims">H5Tget_array_dims</a>
<dt><strong>Signature:</strong>
- <dd><em>H5T_order_t </em><code>H5Tget_order</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>int</em> <code>H5Tget_array_dims</code>(
+ <em>hid_t</em> <code>adtype_id</code>,
+ <em>hsize_t *</em><code>dims[]</code>,
+ <em>int *</em><code>perm[]</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the byte order of an atomic datatype.
+ <dd>Retrieves sizes of array dimensions and dimension permutations.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_order</code> returns the byte order of an
- atomic datatype.
+ <dd><code>H5Tget_array_dims</code> returns the sizes of the dimensions
+ and the dimension permutations of the specified array datatype object.
<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>
+ The sizes of the dimensions are returned in the array <code>dims</code>.
+ The dimension permutations, i.e., C versus FORTRAN array order,
+ are returned in the array <code>perm</code>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to query.
+ <dt><em>hid_t</em> <code>adtype_id</code>
+ <dd>IN: Datatype identifier of array object.
+ <dt><em>hsize_t *</em><code>dims[]</code>
+ <dd>OUT: Sizes of array dimensions.
+ <dt><em>int *</em><code>perm[]</code>
+ <dd>OUT: Dimension permutations.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a byte order constant if successful;
- otherwise <code>H5T_ORDER_ERROR</code> (-1).
+ <dd>Returns the non-negative number of dimensions of the array type if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_order_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_array_dims_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1259,39 +1078,30 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_array_ndims" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetOrder">H5Tset_order</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetArrayNdims">H5Tget_array_ndims</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_order</code>(<em>hid_t </em><code>type_id</code>,
- <em>H5T_order_t</em><code>order</code>
+ <dd><em>int</em> <code>H5Tget_array_ndims</code>(
+ <em>hid_t</em> <code>adtype_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the byte ordering of an atomic datatype.
+ <dd>Returns the rank of an array datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tset_order</code> sets the byte ordering of an atomic datatype.
- Byte orderings currently supported are:
- <ul> <dl>
- <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>
+ <dd><code>H5Tget_array_ndims</code> returns the rank,
+ the number of dimensions, of an array datatype object.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to set.
- <dt><em>H5T_order_t</em> <code>order</code>
- <dd>Byte ordering constant.
+ <dt><em>hid_t</em> <code>adtype_id</code>
+ <dd>IN: Datatype identifier of array object.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
+ <dd>Returns the rank of the array if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_order_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_array_ndims_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1299,29 +1109,42 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_class" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetPrecision">H5Tget_precision</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetClass">H5Tget_class</a>
<dt><strong>Signature:</strong>
- <dd><em>size_t </em><code>H5Tget_precision</code>(<em>hid_t </em><code>type_id</code>
+ <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 precision of an atomic datatype.
+ <dd>Returns the datatype class identifier.
<dt><strong>Description:</strong>
- <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().
+ <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>
+ <li><code>H5T_FLOAT</code>
+ <li><code>H5T_TIME</code>
+ <li><code>H5T_STRING</code>
+ <li><code>H5T_BITFIELD</code>
+ <li><code>H5T_OPAQUE</code>
+ <li><code>H5T_COMPOUND</code>
+ <li><code>H5T_REFERENCE</code>
+ <li><code>H5T_ENUM</code>
+ <li><code>H5T_VLEN</code>
+ <li><code>H5T_ARRAY</code>
+ </ul>
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
<dd>Identifier of datatype to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the number of significant bits if successful;
- otherwise 0.
+ <dd>Returns datatype class identifier if successful;
+ otherwise <code>H5T_NO_CLASS</code> (-1).
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_precision_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_class_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1329,40 +1152,33 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_cset" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetPrecision">H5Tset_precision</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetCset">H5Tget_cset</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_precision</code>(<em>hid_t </em><code>type_id</code>,
- <em>size_t</em><code>precision</code>
+ <dd><em>H5T_cset_t </em><code>H5Tget_cset</code>(<em>hid_t </em><code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the precision of an atomic datatype.
+ <dd>Retrieves the character set type of a string datatype.
<dt><strong>Description:</strong>
- <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 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
- locations and sizes of the sign, mantissa, and exponent fields
- first.
+ <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 (<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>Identifier of datatype to set.
- <dt><em>size_t</em> <code>precision</code>
- <dd>Number of bits of precision for datatype.
+ <dd>Identifier of datatype to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a valid character set type if successful;
+ otherwise <code>H5T_CSET_ERROR</code> (-1).
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_precision_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_cset_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1370,73 +1186,28 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_ebias" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetOffset">H5Tget_offset</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetEbias">H5Tget_ebias</a>
<dt><strong>Signature:</strong>
- <dd><em>int </em><code>H5Tget_offset</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>size_t </em><code>H5Tget_ebias</code>(<em>hid_t </em><code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the bit offset of the first significant bit.
+ <dd>Retrieves the exponent bias of a floating-point type.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_offset</code> retrieves the bit offset of the first significant bit.
- The significant bits of an atomic datum can be offset from the beginning
- of the memory for that datum by an amount of padding. The `offset'
- property specifies the number of bits of padding that appear to the
- "right of" the value. That is, if we have a 32-bit datum with 16-bits
- of precision having the value 0x1122 then it will be laid out in
- memory as (from small byte address toward larger byte addresses):
- <br>
- <br>
-
- <table border align=center cellpadding=4 width="80%">
- <tr align=center>
- <th width="20%">Byte Position</th>
- <th width="20%">Big-Endian Offset=0</th>
- <th width="20%">Big-Endian Offset=16</th>
- <th width="20%">Little-Endian Offset=0</th>
- <th width="20%">Little-Endian Offset=16</th>
- </tr>
- <tr align=center>
- <td>0:</td>
- <td>[ pad]</td>
- <td>[0x11]</td>
- <td>[0x22]</td>
- <td>[ pad]</td>
- </tr>
- <tr align=center>
- <td>1:</td>
- <td>[ pad]</td>
- <td>[0x22]</td>
- <td>[0x11]</td>
- <td>[ pad]</td>
- </tr>
- <tr align=center>
- <td>2:</td>
- <td>[0x11]</td>
- <td>[ pad]</td>
- <td>[ pad]</td>
- <td>[0x22]</td>
- </tr>
- <tr align=center>
- <td>3:</td>
- <td>[0x22]</td>
- <td>[ pad]</td>
- <td>[ pad]</td>
- <td>[0x11]</td>
- </tr>
- </table>
+ <dd><code>H5Tget_ebias</code> retrieves the exponent bias of a floating-point type.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
<dd>Identifier of datatype to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns an offset value if successful;
- otherwise returns a negative value.
+ <dd>Returns the bias if successful;
+ otherwise 0.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_offset_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_ebiass_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1444,83 +1215,47 @@ H5Tget_overflow ()
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_fields" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetOffset">H5Tset_offset</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetFields">H5Tget_fields</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_offset</code>(<em>hid_t </em><code>type_id</code>,
- <em>size_t</em> <code>offset</code>
+ <dd><em>herr_t </em><code>H5Tget_fields</code>(<em>hid_t </em><code>type_id</code>,
+ <em>size_t *</em><code>spos</code>,
+ <em>size_t *</em><code>epos</code>,
+ <em>size_t *</em><code>esize</code>,
+ <em>size_t *</em><code>mpos</code>,
+ <em>size_t *</em><code>msize</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the bit offset of the first significant bit.
+ <dd>Retrieves floating point datatype bit field information.
<dt><strong>Description:</strong>
- <dd><code>H5Tset_offset</code> sets the bit offset of the first significant bit. The
- significant bits of an atomic datum can be offset from the beginning of
- the memory for that datum by an amount of padding. The `offset'
- property specifies the number of bits of padding that appear to the
- "right of" the value. That is, if we have a 32-bit datum with 16-bits
- of precision having the value 0x1122 then it will be laid out in
- memory as (from small byte address toward larger byte addresses):
- <br>
- <br>
-
- <table border align=center cellpadding=4 width="80%">
- <tr align=center>
- <th width="20%">Byte Position</th>
- <th width="20%">Big-Endian Offset=0</th>
- <th width="20%">Big-Endian Offset=16</th>
- <th width="20%">Little-Endian Offset=0</th>
- <th width="20%">Little-Endian Offset=16</th>
- </tr>
- <tr align=center>
- <td>0:</td>
- <td>[ pad]</td>
- <td>[0x11]</td>
- <td>[0x22]</td>
- <td>[ pad]</td>
- </tr>
- <tr align=center>
- <td>1:</td>
- <td>[ pad]</td>
- <td>[0x22]</td>
- <td>[0x11]</td>
- <td>[ pad]</td>
- </tr>
- <tr align=center>
- <td>2:</td>
- <td>[0x11]</td>
- <td>[ pad]</td>
- <td>[ pad]</td>
- <td>[0x22]</td>
- </tr>
- <tr align=center>
- <td>3:</td>
- <td>[0x22]</td>
- <td>[ pad]</td>
- <td>[ pad]</td>
- <td>[0x11]</td>
- </tr>
- </table>
-
-<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 datatype.
-
-<P>The offset of an H5T_STRING cannot be set to anything but
-zero.
+ <dd><code>H5Tget_fields</code> retrieves information about the locations of the various
+ 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>Identifier of datatype to set.
- <dt><em>size_t</em> <code>offset</code>
- <dd>Offset of first significant bit.
+ <dd>IN: Identifier of datatype to query.
+ <dt><em>size_t *</em><code>spos</code>
+ <dd>OUT: Pointer to location to return floating-point sign bit.
+ <dt><em>size_t *</em><code>epos</code>
+ <dd>OUT: Pointer to location to return exponent bit-position.
+ <dt><em>size_t *</em><code>esize</code>
+ <dd>OUT: Pointer to location to return size of exponent in bits.
+ <dt><em>size_t *</em><code>mpos</code>
+ <dd>OUT: Pointer to location to return mantissa bit-position.
+ <dt><em>size_t *</em><code>msize</code>
+ <dd>OUT: Pointer to location to return size of mantissa in bits.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_offset_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_fields_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1528,20 +1263,20 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_inpad" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetPad">H5Tget_pad</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetInpad">H5Tget_inpad</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tget_pad</code>(<em>hid_t </em><code>type_id</code>,
- <em>H5T_pad_t *</em> <code>lsb</code>,
- <em>H5T_pad_t *</em> <code>msb</code>
+ <dd><em>H5T_pad_t </em><code>H5Tget_inpad</code>(<em>hid_t </em><code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the padding type of the least and most-significant bit padding.
+ <dd>Retrieves the internal padding type for unused bits in floating-point datatypes.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_pad</code> retrieves the padding type of the least and most-significant
- bit padding. Valid types are:
+ <dd><code>H5Tget_inpad</code> retrieves the internal padding type for
+ unused bits in floating-point datatypes.
+ Valid padding types are:
<ul> <dl>
<dt>H5T_PAD_ZERO (<code>0</code>)
<dd>Set background to zeros.
@@ -1553,19 +1288,13 @@ zero.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
- <dd>IN: Identifier of datatype to query.
- <dt><em>H5T_pad_t *</em> <code>lsb</code>
- <dd>OUT: Pointer to location to return least-significant
- bit padding type.
- <dt><em>H5T_pad_t *</em> <code>msb</code>
- <dd>OUT: Pointer to location to return most-significant
- bit padding type.
+ <dd>Identifier of datatype to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a valid padding type if successful;
+ otherwise <code>H5T_PAD_ERROR</code> (-1).
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_pad_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_inpad_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1573,76 +1302,124 @@ zero.
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_member_class" -->
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Datatype-GetMemberClass">H5Tget_member_class</a>
+<dt><strong>Signature:</strong>
+ <dd><em>H5T_class_t</em> <code>H5Tget_member_class</code>(
+ <em>hid_t</em> <code>cdtype_id</code>,
+ <em>int </em><code>member_no</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Returns datatype class of compound datatype member.
+<dt><strong>Description:</strong>
+ <dd>Given a compound datatype, <code>cdtype_id</code>, the function
+ <code>H5Tget_member_class</code> returns the datatype class of
+ the compound datatype member specified by <code>member_no</code>.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>cdtype_id</code>
+ <dd>IN: Datatype identifier of compound object.
+ <dt><em>int</em> <code>member_no</code>
+ <dd>IN: Compound object member number.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns the datatype class, a non-negative value, if successful;
+ otherwise returns a negative value.
+<!--
+<dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5t_FORTRAN.html#h5txxx_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+-->
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_member_index" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetPad">H5Tset_pad</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetMemberIndex">H5Tget_member_index</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_pad</code>(<em>hid_t </em><code>type_id</code>,
- <em>H5T_pad_t</em> <code>lsb</code>,
- <em>H5T_pad_t</em> <code>msb</code>
+ <dd><em>int</em> <code>H5Tget_member_index</code>(<em>hid_t </em><code>type_id</code>,
+ <em>const char *</em> <code>field_name</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the least and most-significant bits padding types.
+ <dd>Retrieves the index of a compound or enumeration datatype member.
<dt><strong>Description:</strong>
- <dd><code>H5Tset_pad</code> sets the least and most-significant bits padding types.
- <ul> <dl>
- <dt>H5T_PAD_ZERO (<code>0</code>)
- <dd>Set background to zeros.
- <dt>H5T_PAD_ONE (<code>1</code>)
- <dd>Set background to ones.
- <dt>H5T_PAD_BACKGROUND (<code>2</code>)
- <dd>Leave background alone.
- </dl> </ul>
+ <dd><code>H5Tget_member_index</code> retrieves the index of a field
+ of a compound datatype or an element of an enumeration datatype.
+ <p>
+ The name of the target field or element is specified in
+ <code>field_name</code>.
+ <p>
+ Fields are stored in no particular order
+ with index values of 0 through <em>N</em>-1, where <em>N</em> is
+ the value returned by <code>H5Tget_nmembers</code>.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
- <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.
+ <dd>Identifier of datatype to query.
+ <dt><em>const char *</em> <code>field_name</code>
+ <dd>Name of the field or member whose index is to be retrieved.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
+ <dd>Returns a valid field or member index if successful;
otherwise returns a negative value.
+<!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_pad_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_index_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+-->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_member_name" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetSign">H5Tget_sign</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetMemberName">H5Tget_member_name</a>
<dt><strong>Signature:</strong>
- <dd><em>H5T_sign_t </em><code>H5Tget_sign</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>char *</em> <code>H5Tget_member_name</code>(<em>hid_t </em><code>type_id</code>,
+ <em>int</em> <code>field_idx</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the sign type for an integer type.
+ <dd>Retrieves the name of a compound or enumeration datatype member.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_sign</code> retrieves the sign type for an integer type.
- Valid types are:
- <ul> <dl>
- <dt>H5T_SGN_NONE (<code>0</code>)
- <dd>Unsigned integer type.
- <dt>H5T_SGN_2 (<code>1</code>)
- <dd>Two's complement signed integer type.
- </dl> </ul>
+ <dd><code>H5Tget_member_name</code> retrieves the name of a field
+ of a compound datatype or an element of an enumeration datatype.
+ <p>
+ The index of the target field or element is specified in
+ <code>field_idx</code>.
+ Compound datatype fields and enumeration datatype elements
+ are stored in no particular order
+ with index values of 0 through <em>N</em>-1, where <em>N</em>
+ is the value returned by <code>H5Tget_nmembers</code>.
+ <p>
+ A buffer to receive the name of the field is
+ allocated with <code>malloc()</code> and the caller is responsible
+ for freeing the memory used.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
<dd>Identifier of datatype to query.
+ <dt><em>int</em> <code>field_idx</code>
+ <dd>Zero-based index of the field or element whose name
+ is to be retrieved.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a valid sign type if successful;
- otherwise <code>H5T_SGN_ERROR</code> (-1).
+ <dd>Returns a valid pointer to a string allocated with
+ <code>malloc()</code> if successful;
+ otherwise returns NULL.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_sign_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_name_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1650,36 +1427,37 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_member_offset" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetSign">H5Tset_sign</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetMemberOffset">H5Tget_member_offset</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_sign</code>(<em>hid_t </em><code>type_id</code>,
- <em>H5T_sign_t</em> <code>sign</code>
+ <dd><em>size_t</em> <code>H5Tget_member_offset</code>(<em>hid_t </em><code>type_id</code>,
+ <em>int</em> <code>memb_no</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the sign property for an integer type.
+ <dd>Retrieves the offset of a field of a compound datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tset_sign</code> sets the sign property for an integer type.
- <ul> <dl>
- <dt>H5T_SGN_NONE (<code>0</code>)
- <dd>Unsigned integer type.
- <dt>H5T_SGN_2 (<code>1</code>)
- <dd>Two's complement signed integer type.
- </dl> </ul>
+ <dd><code>H5Tget_member_offset</code> retrieves the
+ byte offset of the beginning of a field within a
+ compound datatype with respect to the beginning
+ of the compound data type datum.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to set.
- <dt><em>H5T_sign_t</em> <code>sign</code>
- <dd>Sign type.
+ <dd>Identifier of datatype to query.
+ <dt><em>int</em> <code>memb_no</code>
+ <dd>Number of the field whose offset is requested.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns the byte offset of the field if successful;
+ otherwise returns <code>0</code> (zero).
+ Note that zero is a valid offset and that this function
+ will fail only if a call to <code>H5Tget_member_class()</code>
+ fails with the same arguments.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_sign_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_offset_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1687,46 +1465,33 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_member_type" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetFields">H5Tget_fields</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetMemberType">H5Tget_member_type</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tget_fields</code>(<em>hid_t </em><code>type_id</code>,
- <em>size_t *</em><code>spos</code>,
- <em>size_t *</em><code>epos</code>,
- <em>size_t *</em><code>esize</code>,
- <em>size_t *</em><code>mpos</code>,
- <em>size_t *</em><code>msize</code>
+ <dd><em>hid_t</em> <code>H5Tget_member_type</code>(<em>hid_t </em><code>type_id</code>,
+ <em>int</em> <code>field_idx</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves floating point datatype bit field information.
+ <dd>Returns the datatype of the specified member.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_fields</code> retrieves information about the locations of the various
- 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.
+ <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>IN: Identifier of datatype to query.
- <dt><em>size_t *</em><code>spos</code>
- <dd>OUT: Pointer to location to return floating-point sign bit.
- <dt><em>size_t *</em><code>epos</code>
- <dd>OUT: Pointer to location to return exponent bit-position.
- <dt><em>size_t *</em><code>esize</code>
- <dd>OUT: Pointer to location to return size of exponent in bits.
- <dt><em>size_t *</em><code>mpos</code>
- <dd>OUT: Pointer to location to return mantissa bit-position.
- <dt><em>size_t *</em><code>msize</code>
- <dd>OUT: Pointer to location to return size of mantissa in bits.
+ <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>Returns a non-negative value if successful;
+ <dd>Returns the identifier of a copy of the datatype of the field
+ if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_fields_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_type_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1734,49 +1499,39 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_member_value" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetFields">H5Tset_fields</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetMemberValue">H5Tget_member_value</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_fields</code>(<em>hid_t </em><code>type_id</code>,
- <em>size_t</em> <code>spos</code>,
- <em>size_t</em> <code>epos</code>,
- <em>size_t</em> <code>esize</code>,
- <em>size_t</em> <code>mpos</code>,
- <em>size_t</em> <code>msize</code>
+ <dd><em>hid_t</em> <code>H5Tget_member_value</code>(<em>hid_t</em> <code>type</code>
+ <em>int</em> <code>memb_no</code>,
+ <em>void</em> *<code>value</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets locations and sizes of floating point bit fields.
+ <dd>Returns the value of an enumeration datatype member.
<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 datatype. Bits are numbered with the least
- significant bit number zero.
-
- <P>Fields are not allowed to extend beyond the number of bits of
- precision, nor are they allowed to overlap with one another.
+ <dd><code>H5Tget_member_value</code> returns the value of
+ the enumeration datatype member <code>memb_no</code>.
+ <p>
+ The member value is returned in a user-supplied buffer
+ pointed to by <code>value</code>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to set.
- <dt><em>size_t</em> <code>spos</code>
- <dd>Sign position, i.e., the bit offset of the floating-point
- sign bit.
- <dt><em>size_t</em> <code>epos</code>
- <dd>Exponent bit position.
- <dt><em>size_t</em> <code>esize</code>
- <dd>Size of exponent in bits.
- <dt><em>size_t</em> <code>mpos</code>
- <dd>Mantissa bit position.
- <dt><em>size_t</em> <code>msize</code>
- <dd>Size of mantissa in bits.
+ <dt><em>hid_t</em> <code>type</code>
+ <dd>IN: Datatype identifier for the enumeration datatype.
+ <dt><em>int</em> <code>memb_no</code>,
+ <dd>IN: Number of the enumeration datatype member.
+ <dt><em>void</em> *<code>value</code>
+ <dd>OUT: Pointer to a buffer for output of the
+ value of the enumeration datatype member.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_fields_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_value_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1784,58 +1539,119 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_native_type" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetEbias">H5Tget_ebias</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetNativeType">H5Tget_native_type</a>
<dt><strong>Signature:</strong>
- <dd><em>size_t </em><code>H5Tget_ebias</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>hid_t</em> <code>H5Tget_native_type</code>(<em>hid_t</em> <code>type_id</code>,
+ <em>H5T_direction_t</em> <code>direction</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the exponent bias of a floating-point type.
+ <dd>Returns the native datatype of a specified datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_ebias</code> retrieves the exponent bias of a floating-point type.
+ <dd><code>H5Tget_native_type</code> returns the equivalent native datatype
+ for the datatype specified in <code>type_id</code>.
+ <p>
+ <code>H5Tget_native_type</code> is a high-level function designed
+ primarily to facilitate use of the <code>H5Dread</code> function,
+ for which users otherwise must undertake a multi-step process to
+ determine the native datatype of a dataset prior to reading it
+ into memory.
+ It can be used not only to determine
+ the native datatype for atomic datatypes,
+ but also to determine the native datatypes of the individual components of
+ a compound datatype, an enumerated datatype, an array datatype, or
+ a variable-length datatype.
+ <p>
+ <code>H5Tget_native_type</code> selects the matching native datatype
+ from the following list:
+ <pre> H5T_NATIVE_CHAR
+ H5T_NATIVE_SHORT
+ H5T_NATIVE_INT
+ H5T_NATIVE_LONG
+ H5T_NATIVE_LLONG
+
+ H5T_NATIVE_UCHAR
+ H5T_NATIVE_USHORT
+ H5T_NATIVE_UINT
+ H5T_NATIVE_ULONG
+ H5T_NATIVE_ULLONG
+
+ H5T_NATIVE_FLOAT
+ H5T_NATIVE_DOUBLE
+ H5T_NATIVE_LDOUBLE</pre>
+ <p>
+ The <code>direction</code> parameter indicates the order
+ in which the library searches for a native datatype match.
+ Valid values for <code>direction</code> are as follows:
+ <table border=0>
+ <tr valign=top><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>H5T_DIR_ASCEND</code></td><td>
+ Searches the above list in ascending size of the datatype,<br>
+ i.e., from top to bottom. (Default)
+ </td></tr>
+ <tr valign=top><td>&nbsp;</td><td>
+ <code>H5T_DIR_DESCEND</code>&nbsp;&nbsp;</td><td>
+ Searches the above list in descending size of the datatype,<br>
+ i.e., from bottom to top.
+ </td></tr>
+ </table>
+ <p>
+ <code>H5Tget_native_type</code> is designed primarily for
+ use with intenger and floating point datatypes.
+ Time, bifield, opaque, and reference datatypes are returned
+ as a copy of <code>type_id</code>.
+ <p>
+ The identifier returned by <code>H5Tget_native_type</code>
+ should eventually be closed by calling <code>H5Tclose</code>
+ to release resources.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to query.
+ <dd>Datatype identifier for the dataset datatype.
+ <dt><em>H5T_direction_t</em> <code>direction</code>
+ <dd>Direction of search.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the bias if successful;
- otherwise 0.
+ <dd>Returns the native datatype identifier for the
+ specified dataset datatype if successful;
+ otherwise returns a negative value.
+<!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_ebiass_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_native_type_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
+--> <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_nmembers" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetEbias">H5Tset_ebias</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetNmembers">H5Tget_nmembers</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_ebias</code>(<em>hid_t </em><code>type_id</code>,
- <em>size_t</em> <code>ebias</code>
+ <dd><em>int </em><code>H5Tget_nmembers</code>(<em>hid_t </em><code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the exponent bias of a floating-point type.
+ <dd>Retrieves the number of elements in a compound or enumeration datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tset_ebias</code> sets the exponent bias of a floating-point type.
+ <dd><code>H5Tget_nmembers</code> retrieves
+ the number of fields in a compound datatype or
+ the number of members of an enumeration datatype.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to set.
- <dt><em>size_t</em> <code>ebias</code>
- <dd>Exponent bias value.
+ <dd>Identifier of datatype to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
+ <dd>Returns the number of elements if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_ebiass_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_nmembers_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1843,7 +1659,8 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_norm" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Datatype-GetNorm">H5Tget_norm</a>
@@ -1880,39 +1697,74 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_offset" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetNorm">H5Tset_norm</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetOffset">H5Tget_offset</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_norm</code>(<em>hid_t </em><code>type_id</code>,
- <em>H5T_norm_t</em> <code>norm</code>
+ <dd><em>int </em><code>H5Tget_offset</code>(<em>hid_t </em><code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the mantissa normalization of a floating-point datatype.
+ <dd>Retrieves the bit offset of the first significant bit.
<dt><strong>Description:</strong>
- <dd><code>H5Tset_norm</code> sets the mantissa normalization of
- a floating-point datatype. Valid normalization types are:
- <ul> <dl>
- <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 (<code>2</code>)
- <dd>Mantissa is not normalized
- </dl> </ul>
+ <dd><code>H5Tget_offset</code> retrieves the bit offset of the first significant bit.
+ The significant bits of an atomic datum can be offset from the beginning
+ of the memory for that datum by an amount of padding. The `offset'
+ property specifies the number of bits of padding that appear to the
+ "right of" the value. That is, if we have a 32-bit datum with 16-bits
+ of precision having the value 0x1122 then it will be laid out in
+ memory as (from small byte address toward larger byte addresses):
+ <br>
+ <br>
+
+ <table border align=center cellpadding=4 width="80%">
+ <tr align=center>
+ <th width="20%">Byte Position</th>
+ <th width="20%">Big-Endian Offset=0</th>
+ <th width="20%">Big-Endian Offset=16</th>
+ <th width="20%">Little-Endian Offset=0</th>
+ <th width="20%">Little-Endian Offset=16</th>
+ </tr>
+ <tr align=center>
+ <td>0:</td>
+ <td>[ pad]</td>
+ <td>[0x11]</td>
+ <td>[0x22]</td>
+ <td>[ pad]</td>
+ </tr>
+ <tr align=center>
+ <td>1:</td>
+ <td>[ pad]</td>
+ <td>[0x22]</td>
+ <td>[0x11]</td>
+ <td>[ pad]</td>
+ </tr>
+ <tr align=center>
+ <td>2:</td>
+ <td>[0x11]</td>
+ <td>[ pad]</td>
+ <td>[ pad]</td>
+ <td>[0x22]</td>
+ </tr>
+ <tr align=center>
+ <td>3:</td>
+ <td>[0x22]</td>
+ <td>[ pad]</td>
+ <td>[ pad]</td>
+ <td>[0x11]</td>
+ </tr>
+ </table>
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to set.
- <dt><em>H5T_norm_t</em> <code>norm</code>
- <dd>Mantissa normalization type.
+ <dd>Identifier of datatype to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
+ <dd>Returns an offset value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_norm_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_offset_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1920,37 +1772,39 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_order" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetInpad">H5Tget_inpad</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetOrder">H5Tget_order</a>
<dt><strong>Signature:</strong>
- <dd><em>H5T_pad_t </em><code>H5Tget_inpad</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>H5T_order_t </em><code>H5Tget_order</code>(<em>hid_t </em><code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the internal padding type for unused bits in floating-point datatypes.
+ <dd>Returns the byte order of an atomic datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_inpad</code> retrieves the internal padding type for
- unused bits in floating-point datatypes.
- Valid padding types are:
- <ul> <dl>
- <dt>H5T_PAD_ZERO (<code>0</code>)
- <dd>Set background to zeros.
- <dt>H5T_PAD_ONE (<code>1</code>)
- <dd>Set background to ones.
- <dt>H5T_PAD_BACKGROUND (<code>2</code>)
- <dd>Leave background alone.
- </dl> </ul>
+ <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>Identifier of datatype to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a valid padding type if successful;
- otherwise <code>H5T_PAD_ERROR</code> (-1).
+ <dd>Returns a byte order constant if successful;
+ otherwise <code>H5T_ORDER_ERROR</code> (-1).
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_inpad_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_order_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1958,75 +1812,80 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_overflow" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetInpad">H5Tset_inpad</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetOverflow">H5Tget_overflow</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_inpad</code>(<em>hid_t </em><code>type_id</code>,
- <em>H5T_pad_t</em> <code>inpad</code>
- )
+
+
+H5Tget_overflow ()
+ <dd><em>H5T_overflow_t</em> <code>H5Tget_overflow</code>(<code>void</code>)
<dt><strong>Purpose:</strong>
- <dd>Fills unused internal floating point bits.
+ <dd>Returns a pointer to the current global overflow function.
<dt><strong>Description:</strong>
- <dd>If any internal bits of a floating point type are unused
- (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 types are:
- <ul> <dl>
- <dt>H5T_PAD_ZERO (<code>0</code>)
- <dd>Set background to zeros.
- <dt>H5T_PAD_ONE (<code>1</code>)
- <dd>Set background to ones.
- <dt>H5T_PAD_BACKGROUND (<code>2</code>)
- <dd>Leave background alone.
- </dl> </ul>
+ <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
+ datatype conversion causes an overflow.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to modify.
- <dt><em>H5T_pad_t</em> <code>pad</code>
- <dd>Padding type.
+ <dt>None.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a pointer to an application-defined function if successful.
+ Otherwise returns NULL; this can happen if no overflow handling
+ function is registered.
+<!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_inpad_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_overflow_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
+--> <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_pad" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetCset">H5Tget_cset</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetPad">H5Tget_pad</a>
<dt><strong>Signature:</strong>
- <dd><em>H5T_cset_t </em><code>H5Tget_cset</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>herr_t </em><code>H5Tget_pad</code>(<em>hid_t </em><code>type_id</code>,
+ <em>H5T_pad_t *</em> <code>lsb</code>,
+ <em>H5T_pad_t *</em> <code>msb</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the character set type of a string datatype.
+ <dd>Retrieves the padding type of the least and most-significant bit padding.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_cset</code> retrieves the character set type
- of a string datatype. Valid character set types are:
+ <dd><code>H5Tget_pad</code> retrieves the padding type of the least and most-significant
+ bit padding. Valid types are:
<ul> <dl>
- <dt>H5T_CSET_ASCII (<code>0</code>)
- <dd>Character set is US ASCII
+ <dt>H5T_PAD_ZERO (<code>0</code>)
+ <dd>Set background to zeros.
+ <dt>H5T_PAD_ONE (<code>1</code>)
+ <dd>Set background to ones.
+ <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>Identifier of datatype to query.
+ <dd>IN: Identifier of datatype to query.
+ <dt><em>H5T_pad_t *</em> <code>lsb</code>
+ <dd>OUT: Pointer to location to return least-significant
+ bit padding type.
+ <dt><em>H5T_pad_t *</em> <code>msb</code>
+ <dd>OUT: Pointer to location to return most-significant
+ bit padding type.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a valid character set type if successful;
- otherwise <code>H5T_CSET_ERROR</code> (-1).
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_cset_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_pad_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2034,38 +1893,30 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_precision" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetCset">H5Tset_cset</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetPrecision">H5Tget_precision</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_cset</code>(<em>hid_t </em><code>type_id</code>,
- <em>H5T_cset_t</em> <code>cset</code>
+ <dd><em>size_t </em><code>H5Tget_precision</code>(<em>hid_t </em><code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets character set to be used.
+ <dd>Returns the precision of an atomic datatype.
<dt><strong>Description:</strong>
- <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 types are:
- <ul> <dl>
- <dt>H5T_CSET_ASCII (<code>0</code>)
- <dd>Character set is US ASCII.
- </dl> </ul>
+ <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>Identifier of datatype to modify.
- <dt><em>H5T_cset_t</em> <code>cset</code>
- <dd>Character set type.
+ <dd>Identifier of datatype to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns the number of significant bits if successful;
+ otherwise 0.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_cset_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_precision_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2073,29 +1924,35 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_sign" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetStrpad">H5Tget_strpad</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetSign">H5Tget_sign</a>
<dt><strong>Signature:</strong>
- <dd><em>H5T_str_t </em><code>H5Tget_strpad</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>H5T_sign_t </em><code>H5Tget_sign</code>(<em>hid_t </em><code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the storage mechanism for a string datatype.
+ <dd>Retrieves the sign type for an integer type.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_strpad</code> retrieves the storage mechanism
- for a string datatype, as defined in
- <a href="#Datatype-SetStrpad"><code>H5Tset_strpad</code></a>.
+ <dd><code>H5Tget_sign</code> retrieves the sign type for an integer type.
+ Valid types are:
+ <ul> <dl>
+ <dt>H5T_SGN_NONE (<code>0</code>)
+ <dd>Unsigned integer type.
+ <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>Identifier of datatype to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a valid string storage mechanism if successful;
- otherwise <code>H5T_STR_ERROR</code> (-1).
+ <dd>Returns a valid sign type if successful;
+ otherwise <code>H5T_SGN_ERROR</code> (-1).
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_strpad_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_sign_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2103,59 +1960,28 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_size" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetStrpad">H5Tset_strpad</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetSize">H5Tget_size</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tset_strpad</code>(<em>hid_t </em><code>type_id</code>,
- <em>H5T_str_t</em> <code>strpad</code>
+ <dd><em>size_t </em><code>H5Tget_size</code>(<em>hid_t </em><code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Defines the storage mechanism for character strings.
+ <dd>Returns the size of a datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tset_strpad</code> defines the storage mechanism for the string.
- <p>
- The method used to store character strings differs with the
- programming language:
- <ul>
- <li>C usually null terminates strings while
- <li>Fortran left-justifies and space-pads strings.
- </ul>
- Valid string padding values, as passed in the parameter
- <code>strpad</code>, are as follows:
- <ul> <dl>
- <dt>H5T_STR_NULLTERM (<code>0</code>)
- <dd>Null terminate (as C does)
- <dt>H5T_STR_NULLPAD (<code>1</code>)
- <dd>Pad with zeros
- <dt>H5T_STR_SPACEPAD (<code>2</code>)
- <dd>Pad with spaces (as FORTRAN does)
- </dl> </ul>
- <p>
- When converting from a longer string to a shorter string,
- the behavior is as follows.
- If the short string is <code>H5T_STR_NULLPAD</code> or
- <code>H5T_STR_SPACEPAD</code>, then the string is simply truncated.
- If the short string is <code>H5T_STR_NULLTERM</code>, it is
- truncated and a null terminator is appended.
- <p>
- When converting from a shorter string to a longer string,
- the long string is padded on the end by appending nulls or spaces.
-
-
+ <dd><code>H5Tget_size</code> returns the size of a datatype in bytes.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to modify.
- <dt><em>H5T_str_t</em> <code>strpad</code>
- <dd>String padding type.
+ <dd>Identifier of datatype to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns the size of the datatype in bytes if successful;
+ otherwise 0.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_strpad_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_size_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2163,29 +1989,30 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_strpad" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetNmembers">H5Tget_nmembers</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetStrpad">H5Tget_strpad</a>
<dt><strong>Signature:</strong>
- <dd><em>int </em><code>H5Tget_nmembers</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>H5T_str_t </em><code>H5Tget_strpad</code>(<em>hid_t </em><code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the number of elements in a compound or enumeration datatype.
+ <dd>Retrieves the storage mechanism for a string datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_nmembers</code> retrieves
- the number of fields in a compound datatype or
- the number of members of an enumeration datatype.
+ <dd><code>H5Tget_strpad</code> retrieves the storage mechanism
+ for a string datatype, as defined in
+ <a href="#Datatype-SetStrpad"><code>H5Tset_strpad</code></a>.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
<dd>Identifier of datatype to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the number of elements if successful;
- otherwise returns a negative value.
+ <dd>Returns a valid string storage mechanism if successful;
+ otherwise <code>H5T_STR_ERROR</code> (-1).
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_nmembers_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_strpad_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2193,80 +2020,64 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_super" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetMemberClass">H5Tget_member_class</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetSuper">H5Tget_super</a>
<dt><strong>Signature:</strong>
- <dd><em>H5T_class_t</em> <code>H5Tget_member_class</code>(
- <em>hid_t</em> <code>cdtype_id</code>,
- <em>int </em><code>member_no</code>
+ <dd><em>hid_t</em> <code>H5Tget_super</code>(<em>hid_t</em> <code>type</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns datatype class of compound datatype member.
+ <dd>Returns the base datatype from which a datatype is derived.
<dt><strong>Description:</strong>
- <dd>Given a compound datatype, <code>cdtype_id</code>, the function
- <code>H5Tget_member_class</code> returns the datatype class of
- the compound datatype member specified by <code>member_no</code>.
+ <dd><code>H5Tget_super</code> returns the base datatype from which the
+ datatype <code>type</code> is derived.
+ <P>
+ In the case of an enumeration type, the return value is an integer type.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>cdtype_id</code>
- <dd>IN: Datatype identifier of compound object.
- <dt><em>int</em> <code>member_no</code>
- <dd>IN: Compound object member number.
+ <dt><em>hid_t</em> <code>type</code>
+ <dd>Datatype identifier for the derived datatype.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the datatype class, a non-negative value, if successful;
+ <dd>Returns the datatype identifier for the base datatype if successful;
otherwise returns a negative value.
-<!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5txxx_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_super_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
--->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tget_tag" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetMemberName">H5Tget_member_name</a>
+<dt><strong>Name:</strong> <a name="Datatype-GetTag">H5Tget_tag</a>
<dt><strong>Signature:</strong>
- <dd><em>char *</em> <code>H5Tget_member_name</code>(<em>hid_t </em><code>type_id</code>,
- <em>int</em> <code>field_idx</code>
+ <dd><em>char</em> *<code>H5Tget_tag</code>(<em>hid_t</em> <code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the name of a compound or enumeration datatype member.
+ <dd>Gets the tag associated with an opaque datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_member_name</code> retrieves the name of a field
- of a compound datatype or an element of an enumeration datatype.
- <p>
- The index of the target field or element is specified in
- <code>field_idx</code>.
- Compound datatype fields and enumeration datatype elements
- are stored in no particular order
- with index values of 0 through <em>N</em>-1, where <em>N</em>
- is the value returned by <code>H5Tget_nmembers</code>.
- <p>
- A buffer to receive the name of the field is
- allocated with <code>malloc()</code> and the caller is responsible
- for freeing the memory used.
+ <dd><code>H5Tget_tag</code> returns the tag associated with
+ the opaque datatype <code>type_id</code>.
+ <P>
+ The tag is returned via a pointer to an
+ allocated string, which the caller must free.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to query.
- <dt><em>int</em> <code>field_idx</code>
- <dd>Zero-based index of the field or element whose name
- is to be retrieved.
+ <dd>Datatype identifier for the opaque datatype.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a valid pointer to a string allocated with
- <code>malloc()</code> if successful;
- otherwise returns NULL.
+ <dd>Returns a pointer to an allocated string if successful;
+ otherwise returns <code>NULL</code>.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_name_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tget_tag_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2274,77 +2085,78 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tinsert" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetMemberIndex">H5Tget_member_index</a>
+<dt><strong>Name:</strong> <a name="Datatype-Insert">H5Tinsert</a>
<dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Tget_member_index</code>(<em>hid_t </em><code>type_id</code>,
- <em>const char *</em> <code>field_name</code>
+ <dd><em>herr_t</em> <code>H5Tinsert</code>(<em>hid_t </em><code>type_id</code>,
+ <em>const char *</em> <code>name</code>,
+ <em>size_t</em> <code>offset</code>,
+ <em>hid_t</em> <code>field_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the index of a compound or enumeration datatype member.
+ <dd>Adds a new member to a compound datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_member_index</code> retrieves the index of a field
- of a compound datatype or an element of an enumeration datatype.
- <p>
- The name of the target field or element is specified in
- <code>field_name</code>.
- <p>
- Fields are stored in no particular order
- with index values of 0 through <em>N</em>-1, where <em>N</em> is
- the value returned by <code>H5Tget_nmembers</code>.
+ <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 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: Members of a compound datatype do not have to be atomic datatypes;
+ a compound datatype can have a member which is a compound datatype.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to query.
- <dt><em>const char *</em> <code>field_name</code>
- <dd>Name of the field or member whose index is to be retrieved.
+ <dd>Identifier of compound datatype to modify.
+ <dt><em>const char *</em> <code>name</code>
+ <dd>Name of the field to insert.
+ <dt><em>size_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 identifier of the field to insert.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a valid field or member index if successful;
+ <dd>Returns a non-negative value if successful;
otherwise returns a negative value.
-<!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_index_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tinsert_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
--->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tis_variable_str" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetMemberOffset">H5Tget_member_offset</a>
+<dt><strong>Name:</strong> <a name="Datatype-IsVariableString">H5Tis_variable_str</a>
<dt><strong>Signature:</strong>
- <dd><em>size_t</em> <code>H5Tget_member_offset</code>(<em>hid_t </em><code>type_id</code>,
- <em>int</em> <code>memb_no</code>
+ <dd><em>htri_t </em><code>H5Tis_variable_str</code>(<em>hid_t </em><code>dtype_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the offset of a field of a compound datatype.
+ <dd>Determines whether datatype is a variable-length string.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_member_offset</code> retrieves the
- byte offset of the beginning of a field within a
- compound datatype with respect to the beginning
- of the compound data type datum.
+ <dd><code>H5Tvlen_create</code> determines whether the datatype
+ identified in <code>dtype_id</code> is a variable-length string.
+ <p>
+ This function can be used to distinguish between
+ fixed and variable-length string datatypes.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to query.
- <dt><em>int</em> <code>memb_no</code>
- <dd>Number of the field whose offset is requested.
+ <dt><em>hid_t</em> <code>dtype_id</code>
+ <dd>Datatype identifier.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the byte offset of the field if successful;
- otherwise returns <code>0</code> (zero).
- Note that zero is a valid offset and that this function
- will fail only if a call to <code>H5Tget_member_class()</code>
- fails with the same arguments.
+ <dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_offset_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tis_variable_str_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2352,77 +2164,70 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tlock" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetMemberType">H5Tget_member_type</a>
+<dt><strong>Name:</strong> <a name="Datatype-Lock">H5Tlock</a>
<dt><strong>Signature:</strong>
- <dd><em>hid_t</em> <code>H5Tget_member_type</code>(<em>hid_t </em><code>type_id</code>,
- <em>int</em> <code>field_idx</code>
+ <dd><em>herr_t </em><code>H5Tlock</code>(<em>hid_t </em><code>type_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the datatype of the specified member.
+ <dd>Locks a datatype.
<dt><strong>Description:</strong>
- <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.
+ <dd><code>H5Tlock</code> locks the datatype specified by the
+ <code>type_id</code> identifier, making it read-only and
+ non-destructible. 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>Identifier of datatype to query.
- <dt><em>int</em> <code>field_idx</code>
- <dd>Field index (0-based) of the field type to retrieve.
+ <dd>Identifier of datatype to lock.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the identifier of a copy of the datatype of the field
- if successful;
+ <dd>Returns a non-negative value if successful;
otherwise returns a negative value.
+<!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_type_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tlock_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
+--> <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Topen" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-Insert">H5Tinsert</a>
+<dt><strong>Name:</strong> <a name="Datatype-Open">H5Topen</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Tinsert</code>(<em>hid_t </em><code>type_id</code>,
- <em>const char *</em> <code>name</code>,
- <em>size_t</em> <code>offset</code>,
- <em>hid_t</em> <code>field_id</code>
+ <dd><em>hid_t</em><code>H5Topen</code>(<em>hid_t</em> <code>loc_id</code>,
+ <em>const char *</em> <code>name</code>
)
<dt><strong>Purpose:</strong>
- <dd>Adds a new member to a compound datatype.
+ <dd>Opens a named datatype.
<dt><strong>Description:</strong>
- <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 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: Members of a compound datatype do not have to be atomic datatypes;
- a compound datatype can have a member which is a compound 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>type_id</code>
- <dd>Identifier of compound datatype to modify.
+ <dt><em>hid_t</em> <code>loc_id</code>
+ <dd>IN: A file or group identifier.
<dt><em>const char *</em> <code>name</code>
- <dd>Name of the field to insert.
- <dt><em>size_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 identifier of the field to insert.
+ <dd>IN: A datatype name, defined within the file or group identified by <code>loc_id</code>.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
+ <dd>Returns a named datatype identifier if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tinsert_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5topen_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2430,7 +2235,8 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tpack" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Datatype-Pack">H5Tpack</a>
@@ -2459,7 +2265,8 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tregister" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Datatype-Register">H5Tregister</a>
@@ -2556,61 +2363,71 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_cset" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-Unregister">H5Tunregister</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetCset">H5Tset_cset</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Tunregister</code>(<em>H5T_conv_t</em> <code>func</code>
+ <dd><em>herr_t </em><code>H5Tset_cset</code>(<em>hid_t </em><code>type_id</code>,
+ <em>H5T_cset_t</em> <code>cset</code>
)
<dt><strong>Purpose:</strong>
- <dd>Removes a conversion function from all conversion paths.
+ <dd>Sets character set to be used.
<dt><strong>Description:</strong>
- <dd><code>H5Tunregister</code> removes a conversion function from all conversion paths.
- <P>
- The conversion function pointer type declaration is described in
- <a href="#Datatype-Register">H5Tregister</a>.
+ <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 types are:
+ <ul> <dl>
+ <dt>H5T_CSET_ASCII (<code>0</code>)
+ <dd>Character set is US ASCII.
+ </dl> </ul>
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>H5T_conv_t</em> <code>func</code>
- <dd>Function to remove from conversion paths.
+ <dt><em>hid_t</em> <code>type_id</code>
+ <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>Returns a non-negative value if successful;
otherwise returns a negative value.
-<!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tunregister_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_cset_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
---> <!--
+ <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_ebias" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-EnumCreate">H5Tenum_create</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetEbias">H5Tset_ebias</a>
<dt><strong>Signature:</strong>
- <dd><em>hid_t</em> <code>H5Tenum_create</code>(<em>hid_t</em> <code>parent_id</code>
+ <dd><em>herr_t </em><code>H5Tset_ebias</code>(<em>hid_t </em><code>type_id</code>,
+ <em>size_t</em> <code>ebias</code>
)
<dt><strong>Purpose:</strong>
- <dd>Creates a new enumeration datatype.
+ <dd>Sets the exponent bias of a floating-point type.
<dt><strong>Description:</strong>
- <dd><code>H5Tenum_create</code> creates a new enumeration datatype
- based on the specified base datatype, <code>parent_id</code>,
- which must be an integer type.
+ <dd><code>H5Tset_ebias</code> sets the exponent bias of a floating-point type.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>parent_id</code>
- <dd>IN: Datatype identifier for the base datatype.
+ <dt><em>hid_t</em> <code>type_id</code>
+ <dd>Identifier of datatype to set.
+ <dt><em>size_t</em> <code>ebias</code>
+ <dd>Exponent bias value.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the datatype identifier for the new enumeration datatype if successful;
+ <dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_create_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_ebiass_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2618,44 +2435,50 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_fields" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-EnumInsert">H5Tenum_insert</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetFields">H5Tset_fields</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Tenum_insert</code>(<em>hid_t</em> <code>type</code>,
- <em>const char</em> *<code>name</code>,
- <em>void</em> *<code>value</code>
+ <dd><em>herr_t </em><code>H5Tset_fields</code>(<em>hid_t </em><code>type_id</code>,
+ <em>size_t</em> <code>spos</code>,
+ <em>size_t</em> <code>epos</code>,
+ <em>size_t</em> <code>esize</code>,
+ <em>size_t</em> <code>mpos</code>,
+ <em>size_t</em> <code>msize</code>
)
<dt><strong>Purpose:</strong>
- <dd>Inserts a new enumeration datatype member.
+ <dd>Sets locations and sizes of floating point bit fields.
<dt><strong>Description:</strong>
- <dd><code>H5Tenum_insert</code> inserts a
- new enumeration datatype member into an enumeration datatype.
- <p>
- <code>type</code> is the enumeration datatype,
- <code>name</code> is the name of the new member, and
- <code>value</code> points to the value of the new member.
- <p>
- <code>name</code> and <code>value</code> must both
- be unique within <code>type</code>.
- <p>
- <code>value</code> points to data which is of the
- datatype defined when the enumeration datatype was created.
+ <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 datatype. Bits are numbered with the least
+ significant bit number zero.
+
+ <P>Fields are not allowed to extend beyond the number of bits of
+ precision, nor are they allowed to overlap with one another.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type</code>
- <dd>IN: Datatype identifier for the enumeration datatype.
- <dt><em>const char</em> *<code>name</code>
- <dd>IN: Name of the new member.
- <dt><em>void</em> *<code>value</code>
- <dd>IN: Pointer to the value of the new member.
+ <dt><em>hid_t</em> <code>type_id</code>
+ <dd>Identifier of datatype to set.
+ <dt><em>size_t</em> <code>spos</code>
+ <dd>Sign position, i.e., the bit offset of the floating-point
+ sign bit.
+ <dt><em>size_t</em> <code>epos</code>
+ <dd>Exponent bit position.
+ <dt><em>size_t</em> <code>esize</code>
+ <dd>Size of exponent in bits.
+ <dt><em>size_t</em> <code>mpos</code>
+ <dd>Mantissa bit position.
+ <dt><em>size_t</em> <code>msize</code>
+ <dd>Size of mantissa in bits.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_insert_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_fields_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2663,48 +2486,43 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_inpad" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-EnumNameOf">H5Tenum_nameof</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetInpad">H5Tset_inpad</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Tenum_nameof</code>(<em>hid_t</em> <code>type</code>
- <em>void</em> *<code>value</code>,
- <em>char</em> *<code>name</code>,
- <em>size_t</em> <code>size</code>
+ <dd><em>herr_t </em><code>H5Tset_inpad</code>(<em>hid_t </em><code>type_id</code>,
+ <em>H5T_pad_t</em> <code>inpad</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the symbol name corresponding to a specified member of an enumeration datatype.
+ <dd>Fills unused internal floating point bits.
<dt><strong>Description:</strong>
- <dd><code>H5Tenum_nameof</code> finds the symbol name that
- corresponds to the specified <code>value</code>
- of the enumeration datatype <code>type</code>.
- <p>
- At most <code>size</code> characters of the symbol
- name are copied into the <code>name</code> buffer.
- If the entire symbol name and null terminator
- do not fit in the <code>name</code> buffer, then as
- many characters as possible are copied
- (not null terminated) and the function fails.
+ <dd>If any internal bits of a floating point type are unused
+ (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 types are:
+ <ul> <dl>
+ <dt>H5T_PAD_ZERO (<code>0</code>)
+ <dd>Set background to zeros.
+ <dt>H5T_PAD_ONE (<code>1</code>)
+ <dd>Set background to ones.
+ <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</code>
- <dd>IN: Enumeration datatype identifier.
- <dt><em>void</em> *<code>value</code>,
- <dd>IN: Value of the enumeration datatype.
- <dt><em>char</em> *<code>name</code>,
- <dd>OUT: Buffer for output of the symbol name.
- <dt><em>size_t</em> <code>size</code>
- <dd>IN: Anticipated size of the symbol name, in bytes (characters).
+ <dt><em>hid_t</em> <code>type_id</code>
+ <dd>Identifier of datatype to modify.
+ <dt><em>H5T_pad_t</em> <code>pad</code>
+ <dd>Padding type.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value
- and, if <code>size</code> allows it,
- the first character of <code>name</code> is
- set to <code>NULL</code>.
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_nameof_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_inpad_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2712,39 +2530,40 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_norm" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-EnumValueOf">H5Tenum_valueof</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetNorm">H5Tset_norm</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Tenum_valueof</code>(<em>hid_t</em> <code>type</code>
- <em>char</em> *<code>name</code>,
- <em>void</em> *<code>value</code>
+ <dd><em>herr_t </em><code>H5Tset_norm</code>(<em>hid_t </em><code>type_id</code>,
+ <em>H5T_norm_t</em> <code>norm</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the value corresponding to a specified member of an enumeration datatype.
+ <dd>Sets the mantissa normalization of a floating-point datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tenum_valueof</code> finds the value that
- corresponds to the specified <code>name</code>
- of the enumeration datatype <code>type</code>.
- <p>
- The <code>value</code> argument should be at least
- as large as the value of <code>H5Tget_size(type)</code>
- in order to hold the result.
+ <dd><code>H5Tset_norm</code> sets the mantissa normalization of
+ a floating-point datatype. Valid normalization types are:
+ <ul> <dl>
+ <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 (<code>2</code>)
+ <dd>Mantissa is not normalized
+ </dl> </ul>
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>type</code>
- <dd>IN: Enumeration datatype identifier.
- <dt><em>const char</em> *<code>name</code>,
- <dd>IN: Symbol name of the enumeration datatype.
- <dt><em>void</em> *<code>value</code>,
- <dd>OUT: Buffer for output of the value of the enumeration datatype.
+ <dt><em>hid_t</em> <code>type_id</code>
+ <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>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_valueof_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_norm_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2752,38 +2571,84 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_offset" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetMemberValue">H5Tget_member_value</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetOffset">H5Tset_offset</a>
<dt><strong>Signature:</strong>
- <dd><em>hid_t</em> <code>H5Tget_member_value</code>(<em>hid_t</em> <code>type</code>
- <em>int</em> <code>memb_no</code>,
- <em>void</em> *<code>value</code>
+ <dd><em>herr_t </em><code>H5Tset_offset</code>(<em>hid_t </em><code>type_id</code>,
+ <em>size_t</em> <code>offset</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the value of an enumeration datatype member.
+ <dd>Sets the bit offset of the first significant bit.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_member_value</code> returns the value of
- the enumeration datatype member <code>memb_no</code>.
- <p>
- The member value is returned in a user-supplied buffer
- pointed to by <code>value</code>.
+ <dd><code>H5Tset_offset</code> sets the bit offset of the first significant bit. The
+ significant bits of an atomic datum can be offset from the beginning of
+ the memory for that datum by an amount of padding. The `offset'
+ property specifies the number of bits of padding that appear to the
+ "right of" the value. That is, if we have a 32-bit datum with 16-bits
+ of precision having the value 0x1122 then it will be laid out in
+ memory as (from small byte address toward larger byte addresses):
+ <br>
+ <br>
+
+ <table border align=center cellpadding=4 width="80%">
+ <tr align=center>
+ <th width="20%">Byte Position</th>
+ <th width="20%">Big-Endian Offset=0</th>
+ <th width="20%">Big-Endian Offset=16</th>
+ <th width="20%">Little-Endian Offset=0</th>
+ <th width="20%">Little-Endian Offset=16</th>
+ </tr>
+ <tr align=center>
+ <td>0:</td>
+ <td>[ pad]</td>
+ <td>[0x11]</td>
+ <td>[0x22]</td>
+ <td>[ pad]</td>
+ </tr>
+ <tr align=center>
+ <td>1:</td>
+ <td>[ pad]</td>
+ <td>[0x22]</td>
+ <td>[0x11]</td>
+ <td>[ pad]</td>
+ </tr>
+ <tr align=center>
+ <td>2:</td>
+ <td>[0x11]</td>
+ <td>[ pad]</td>
+ <td>[ pad]</td>
+ <td>[0x22]</td>
+ </tr>
+ <tr align=center>
+ <td>3:</td>
+ <td>[0x22]</td>
+ <td>[ pad]</td>
+ <td>[ pad]</td>
+ <td>[0x11]</td>
+ </tr>
+ </table>
+
+<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 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</code>
- <dd>IN: Datatype identifier for the enumeration datatype.
- <dt><em>int</em> <code>memb_no</code>,
- <dd>IN: Number of the enumeration datatype member.
- <dt><em>void</em> *<code>value</code>
- <dd>OUT: Pointer to a buffer for output of the
- value of the enumeration datatype member.
+ <dt><em>hid_t</em> <code>type_id</code>
+ <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>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_value_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_offset_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2791,32 +2656,40 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_order" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-SetTag">H5Tset_tag</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetOrder">H5Tset_order</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Tset_tag</code>(<em>hid_t</em> <code>type_id</code>
- <em>const char</em> *<code>tag</code>
+ <dd><em>herr_t </em><code>H5Tset_order</code>(<em>hid_t </em><code>type_id</code>,
+ <em>H5T_order_t</em><code>order</code>
)
<dt><strong>Purpose:</strong>
- <dd>Tags an opaque datatype.
+ <dd>Sets the byte ordering of an atomic datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tset_tag</code> tags an opaque datatype <code>type_id</code>
- with a descriptive ASCII identifier,<code> tag</code>.
+ <dd><code>H5Tset_order</code> sets the byte ordering of an atomic datatype.
+ Byte orderings currently supported are:
+ <ul> <dl>
+ <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>IN: Datatype identifier for the opaque datatype to be tagged.
- <dt><em>const char</em> *<code>tag</code>
- <dd>IN: Descriptive ASCII string with which the
- opaque datatype is to be tagged.
+ <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>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tset_tag_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_order_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2824,31 +2697,84 @@ zero.
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_overflow" -->
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Datatype-SetOverflow">H5Tset_overflow</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Tset_overflow</code>(<em>H5T_overflow_t</em> <code>func</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Sets the overflow handler to a specified function.
+<dt><strong>Description:</strong>
+ <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 datatype conversions that
+ result in an overflow.
+ <p>
+ See the definition of <code>H5T_overflow_t</code> in
+ <code>H5Tpublic.h</code> for documentation
+ of arguments and return values.
+ The prototype for <code>H5T_overflow_t</code> is as follows:<br>
+ <code>herr_t (*H5T_overflow_t)(hid_t src_id, hid_t dst_id,
+ void *src_buf, void *dst_buf);
+ </code>
+ <p>
+ The NULL pointer may be passed to remove the overflow handler.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>H5T_overflow_t</em> <code>func</code>
+ <dd>Overflow function.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+<!--
+<dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_overflow_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+--> <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_pad" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetTag">H5Tget_tag</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetPad">H5Tset_pad</a>
<dt><strong>Signature:</strong>
- <dd><em>char</em> *<code>H5Tget_tag</code>(<em>hid_t</em> <code>type_id</code>
+ <dd><em>herr_t </em><code>H5Tset_pad</code>(<em>hid_t </em><code>type_id</code>,
+ <em>H5T_pad_t</em> <code>lsb</code>,
+ <em>H5T_pad_t</em> <code>msb</code>
)
<dt><strong>Purpose:</strong>
- <dd>Gets the tag associated with an opaque datatype.
+ <dd>Sets the least and most-significant bits padding types.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_tag</code> returns the tag associated with
- the opaque datatype <code>type_id</code>.
- <P>
- The tag is returned via a pointer to an
- allocated string, which the caller must free.
+ <dd><code>H5Tset_pad</code> sets the least and most-significant bits padding types.
+ <ul> <dl>
+ <dt>H5T_PAD_ZERO (<code>0</code>)
+ <dd>Set background to zeros.
+ <dt>H5T_PAD_ONE (<code>1</code>)
+ <dd>Set background to ones.
+ <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>Datatype identifier for the opaque datatype.
+ <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>Returns a pointer to an allocated string if successful;
- otherwise returns <code>NULL</code>.
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_tag_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_pad_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2856,56 +2782,41 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_precision" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-ArrayCreate">H5Tarray_create</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetPrecision">H5Tset_precision</a>
<dt><strong>Signature:</strong>
- <dd><em>hid_t</em> <code>H5Tarray_create</code>(
- <em>hid_t</em> <code>base</code>,
- <em>int</em> <code>rank</code>,
- <em>const hsize_t</em> <code>dims[/*rank*/]</code>,
- <em>const int</em> <code>perm[/*rank*/]</code>
+ <dd><em>herr_t </em><code>H5Tset_precision</code>(<em>hid_t </em><code>type_id</code>,
+ <em>size_t</em><code>precision</code>
)
<dt><strong>Purpose:</strong>
- <dd>Creates an array datatype object.
+ <dd>Sets the precision of an atomic datatype.
<dt><strong>Description:</strong>
- <dd><code>H5Tarray_create</code> creates a new array datatype object.
- <p>
- <code>base</code> is the datatype of every element of the array,
- i.e., of the number at each position in the array.
- <p>
- <code>rank</code> is the number of dimensions and the
- size of each dimension is specified in the array <code>dims</code>.
- The value of <code>rank</code> is currently limited to
- <code>H5S_MAX_RANK</code> and must be greater than <code>0</code>
- (zero).
- All dimension sizes specified in <code>dims</code> must be greater
- than <code>0</code> (zero).
- <p>
- The array <code>perm</code> is designed to contain the dimension
- permutation, i.e. C versus FORTRAN array order.
- &nbsp;
- <b><i>(The parameter </i><code>perm</code><i> is currently unused and is not yet implemented.)</i></b>
- <p>
+ <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 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
+ locations and sizes of the sign, mantissa, and exponent fields
+ first.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>base</code>
- <dd>IN: Datatype identifier for the array base datatype.
- <dt><em>int</em> <code>rank</code>
- <dd>IN: Rank of the array.
- <dt><em>const hsize_t</em> <code>dims[/*rank*/]</code>
- <dd>IN: Size of each array dimension.
- <dt><em>const int</em> <code>perm[/*rank*/]</code>
- <dd>IN: Dimension permutation.
- &nbsp;
- <b><i>(Currently not implemented.)</i></b>
+ <dt><em>hid_t</em> <code>type_id</code>
+ <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>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tarray_create_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_precision_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2913,29 +2824,37 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_sign" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetArrayNdims">H5Tget_array_ndims</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetSign">H5Tset_sign</a>
<dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Tget_array_ndims</code>(
- <em>hid_t</em> <code>adtype_id</code>
+ <dd><em>herr_t </em><code>H5Tset_sign</code>(<em>hid_t </em><code>type_id</code>,
+ <em>H5T_sign_t</em> <code>sign</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the rank of an array datatype.
+ <dd>Sets the sign property for an integer type.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_array_ndims</code> returns the rank,
- the number of dimensions, of an array datatype object.
+ <dd><code>H5Tset_sign</code> sets the sign property for an integer type.
+ <ul> <dl>
+ <dt>H5T_SGN_NONE (<code>0</code>)
+ <dd>Unsigned integer type.
+ <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>adtype_id</code>
- <dd>IN: Datatype identifier of array object.
+ <dt><em>hid_t</em> <code>type_id</code>
+ <dd>Identifier of datatype to set.
+ <dt><em>H5T_sign_t</em> <code>sign</code>
+ <dd>Sign type.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the rank of the array if successful;
+ <dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_array_ndims_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_sign_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2943,39 +2862,103 @@ zero.
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_size" -->
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Datatype-SetSize">H5Tset_size</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t </em><code>H5Tset_size</code>(<em>hid_t </em><code>type_id</code>,
+ <em>size_t</em><code>size</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Sets the total size for an atomic datatype.
+<dt><strong>Description:</strong>
+ <dd><code>H5Tset_size</code> sets the total size in bytes,
+ <code>size</code>, for a datatype. If the datatype is atomic and 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 datatype still hang over the edge of the new size, then
+ the number of significant bits is decreased.
+ The size set for a string should include space for the null-terminator
+ character, otherwise it will not be stored on (or retrieved from) disk.
+ Adjusting the size of a string automatically sets the precision
+ to 8*<code>size</code>. A compound datatype may increase in size,
+ but may not shrink. All datatypes must have a positive size.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>type_id</code>
+ <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>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+<dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_size_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_strpad" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-GetArrayDims">H5Tget_array_dims</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetStrpad">H5Tset_strpad</a>
<dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Tget_array_dims</code>(
- <em>hid_t</em> <code>adtype_id</code>,
- <em>hsize_t *</em><code>dims[]</code>,
- <em>int *</em><code>perm[]</code>
+ <dd><em>herr_t </em><code>H5Tset_strpad</code>(<em>hid_t </em><code>type_id</code>,
+ <em>H5T_str_t</em> <code>strpad</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves sizes of array dimensions and dimension permutations.
+ <dd>Defines the storage mechanism for character strings.
<dt><strong>Description:</strong>
- <dd><code>H5Tget_array_dims</code> returns the sizes of the dimensions
- and the dimension permutations of the specified array datatype object.
+ <dd><code>H5Tset_strpad</code> defines the storage mechanism for the string.
<p>
- The sizes of the dimensions are returned in the array <code>dims</code>.
- The dimension permutations, i.e., C versus FORTRAN array order,
- are returned in the array <code>perm</code>.
+ The method used to store character strings differs with the
+ programming language:
+ <ul>
+ <li>C usually null terminates strings while
+ <li>Fortran left-justifies and space-pads strings.
+ </ul>
+ Valid string padding values, as passed in the parameter
+ <code>strpad</code>, are as follows:
+ <ul> <dl>
+ <dt>H5T_STR_NULLTERM (<code>0</code>)
+ <dd>Null terminate (as C does)
+ <dt>H5T_STR_NULLPAD (<code>1</code>)
+ <dd>Pad with zeros
+ <dt>H5T_STR_SPACEPAD (<code>2</code>)
+ <dd>Pad with spaces (as FORTRAN does)
+ </dl> </ul>
+ <p>
+ When converting from a longer string to a shorter string,
+ the behavior is as follows.
+ If the short string is <code>H5T_STR_NULLPAD</code> or
+ <code>H5T_STR_SPACEPAD</code>, then the string is simply truncated.
+ If the short string is <code>H5T_STR_NULLTERM</code>, it is
+ truncated and a null terminator is appended.
+ <p>
+ When converting from a shorter string to a longer string,
+ the long string is padded on the end by appending nulls or spaces.
+
+
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>adtype_id</code>
- <dd>IN: Datatype identifier of array object.
- <dt><em>hsize_t *</em><code>dims[]</code>
- <dd>OUT: Sizes of array dimensions.
- <dt><em>int *</em><code>perm[]</code>
- <dd>OUT: Dimension permutations.
+ <dt><em>hid_t</em> <code>type_id</code>
+ <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>Returns the non-negative number of dimensions of the array type if successful;
+ <dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tget_array_dims_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_strpad_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2983,29 +2966,33 @@ zero.
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tset_tag" -->
<hr>
<dl>
-<dt><strong>Name:</strong> <a name="Datatype-Close">H5Tclose</a>
+<dt><strong>Name:</strong> <a name="Datatype-SetTag">H5Tset_tag</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Tclose</code>(<em>hid_t </em><code>type_id</code>
+ <dd><em>herr_t</em> <code>H5Tset_tag</code>(<em>hid_t</em> <code>type_id</code>
+ <em>const char</em> *<code>tag</code>
)
<dt><strong>Purpose:</strong>
- <dd>Releases a datatype.
+ <dd>Tags an opaque datatype.
<dt><strong>Description:</strong>
- <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.
+ <dd><code>H5Tset_tag</code> tags an opaque datatype <code>type_id</code>
+ with a descriptive ASCII identifier,<code> tag</code>.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>type_id</code>
- <dd>Identifier of datatype to release.
+ <dd>IN: Datatype identifier for the opaque datatype to be tagged.
+ <dt><em>const char</em> *<code>tag</code>
+ <dd>IN: Descriptive ASCII string with which the
+ opaque datatype is to be tagged.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5t_FORTRAN.html#h5tclose_f"
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tset_tag_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -3013,6 +3000,81 @@ zero.
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tunregister" -->
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Datatype-Unregister">H5Tunregister</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Tunregister</code>(<em>H5T_conv_t</em> <code>func</code>
+ )
+<dt><strong>Purpose:</strong>
+ <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 conversion function pointer type declaration is described in
+ <a href="#Datatype-Register">H5Tregister</a>.
+<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>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+<!--
+<dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tunregister_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+--> <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Tvlen_create" -->
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Datatype-VLCreate">H5Tvlen_create</a>
+<dt><strong>Signature:</strong>
+ <dd><em>hid_t </em><code>H5Tvlen_create</code>(<em>hid_t </em><code>base_type_id</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Creates a new variable-length datatype.
+<dt><strong>Description:</strong>
+ <dd><code>H5Tvlen_create</code> creates a new variable-length (VL) datatype.
+ <p>
+ The base datatype will be the datatype that the sequence is composed of,
+ characters for character strings, vertex coordinates for polygon lists, etc.
+ The base type specified for the VL datatype can be of any HDF5 datatype,
+ including another VL datatype, a compound datatype or an atomic datatype.
+ <p>
+ When necessary, use <code>H5Tget_super</code> to determine the base type
+ of the VL datatype.
+ <p>
+ 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>hid_t</em> <code>base_type_id</code>
+ <dd>Base type of datatype to create.
+ </dl>
+<dt><strong>See Also:</strong>
+ <dd><a href="RM_H5D.html#Dataset-GetVLBuf">H5Dget_vlen_buf_size</a>
+ <dd><a href="RM_H5D.html#Dataset-VLReclaim">H5Dvlen_reclaim</a>
+<dt><strong>Returns:</strong>
+ <dd>Returns datatype identifier if successful;
+ otherwise returns a negative value.
+<dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5t_FORTRAN.html#h5tvlen_create_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
<center>
@@ -3047,14 +3109,15 @@ And in this document, the
</td></tr>
</table>
</center>
-<hr>
-<!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
+<hr><!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
<br>
Describes HDF5 Release 1.6.0, July 2003
-</address><!-- #EndLibraryItem -->
-
-Last modified: 3 July 2003
+</address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT">
+<!--
+document.writeln("Last modified: 8 October 2003");
+-->
+</SCRIPT>
</body>
</html>
generated by cgit v0.12 at 2024-10-31 08:00:38 (GMT)