diff options
Diffstat (limited to 'doc/html/RM_H5T.html')
| -rw-r--r-- | doc/html/RM_H5T.html | 2665 |
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> </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. + + <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. + + <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> </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> </td><td> - <code>H5T_DIR_DESCEND</code> </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> </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> </td><td> + <code>H5T_DIR_DESCEND</code> </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. - - <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. - - <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> |