diff options
Diffstat (limited to 'doc/src/RM_H5T.html')
| -rw-r--r-- | doc/src/RM_H5T.html | 898 |
1 files changed, 445 insertions, 453 deletions
diff --git a/doc/src/RM_H5T.html b/doc/src/RM_H5T.html index 4221e93..0fa5926 100644 --- a/doc/src/RM_H5T.html +++ b/doc/src/RM_H5T.html @@ -5,6 +5,23 @@ HDF5/H5T Draft API Specification <body> +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +H5T +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + <center> <h1>H5T: Datatype Interface</h1> </center> @@ -16,22 +33,17 @@ of a dataset. <table border=0> <tr><td valign=top> -<ul> +<i>General Datatype Operations</i> + <li><a href="#Datatype-Create">H5Tcreate</a> <li><a href="#Datatype-Open">H5Topen</a> <li><a href="#Datatype-Commit">H5Tcommit</a> <li><a href="#Datatype-Committed">H5Tcommitted</a> - <li><a href="#Datatype-InsertArray">H5Tinsert_array</a> - <li><a href="#Datatype-Share">H5Tshare</a> - <li><a href="#Datatype-Find">H5Tfind</a> - <li><a href="#Datatype-Convert">H5Tconvert</a> - <li><a href="#Datatype-SetOverflow">H5Tset_overflow</a> - <li><a href="#Datatype-GetOverflow">H5Tget_overflow</a> - <li> - - <li><a href="#Datatype-Create">H5Tcreate</a> <li><a href="#Datatype-Copy">H5Tcopy</a> <li><a href="#Datatype-Equal">H5Tequal</a> <li><a href="#Datatype-Lock">H5Tlock</a> + <li><a href="#Datatype-Close">H5Tclose</a> +<p> +<i>Atomic Datatype Properties</i> <li><a href="#Datatype-GetClass">H5Tget_class</a> <li><a href="#Datatype-GetSize">H5Tget_size</a> <li><a href="#Datatype-SetSize">H5Tset_size</a> @@ -41,10 +53,8 @@ of a dataset. <li><a href="#Datatype-SetPrecision">H5Tset_precision</a> <li><a href="#Datatype-GetOffset">H5Tget_offset</a> <li><a href="#Datatype-SetOffset">H5Tset_offset</a> - <li><a href="#Datatype-GetPad">H5Tget_pad</a> -</ul> </td><td> </td><td valign=top> -<ul> + <li><a href="#Datatype-GetPad">H5Tget_pad</a> <li><a href="#Datatype-SetPad">H5Tset_pad</a> <li><a href="#Datatype-GetSign">H5Tget_sign</a> <li><a href="#Datatype-SetSign">H5Tset_sign</a> @@ -59,10 +69,12 @@ of a dataset. <li><a href="#Datatype-GetCset">H5Tget_cset</a> <li><a href="#Datatype-SetCset">H5Tset_cset</a> <li><a href="#Datatype-GetStrpad">H5Tget_strpad</a> -</ul> -</td><td> </td><td valign=top> -<ul> <li><a href="#Datatype-SetStrpad">H5Tset_strpad</a> +<p> +<i>Properties of Compound Types</i> + <li><a href="#Datatype-GetClass">H5Tget_class</a> + <li><a href="#Datatype-GetSize">H5Tget_size</a> +</td><td> </td><td valign=top> <li><a href="#Datatype-GetNmembers">H5Tget_nmembers</a> <li><a href="#Datatype-GetMemberName">H5Tget_member_name</a> <li><a href="#Datatype-GetMemberOffset">H5Tget_member_offset</a> @@ -70,11 +82,16 @@ of a dataset. <li><a href="#Datatype-GetMemberType">H5Tget_member_type</a> <li><a href="#Datatype-Insert">H5Tinsert</a> <li><a href="#Datatype-Pack">H5Tpack</a> + <li><a href="#Datatype-InsertArray">H5Tinsert_array</a> +<p> +<i>Conversion Functions</i> + <li><a href="#Datatype-Convert">H5Tconvert</a> + <li><a href="#Datatype-Find">H5Tfind</a> + <li><a href="#Datatype-SetOverflow">H5Tset_overflow</a> + <li><a href="#Datatype-GetOverflow">H5Tget_overflow</a> <li><a href="#Datatype-RegisterHard">H5Tregister_hard</a> <li><a href="#Datatype-RegisterSoft">H5Tregister_soft</a> <li><a href="#Datatype-Unregister">H5Tunregister</a> - <li><a href="#Datatype-Close">H5Tclose</a> -</ul> </td></tr> </table> @@ -88,18 +105,18 @@ The Datatype interface, H5T, provides a mechanism to describe the according to the data space (the H5S interface). <p> -A data type is a collection of data type properties, all of +A datatype is a collection of datatype properties, all of which can be stored on disk, and which when taken as a whole, provide complete information for data conversion to or from that - data type. The interface provides functions to set and query - properties of a data type. + datatype. The interface provides functions to set and query + properties of a datatype. <p> A <em>data point</em> is an instance of a <em>datatype</em>, which is an instance of a <em>type class</em>. We have defined a set of type classes and properties which can be extended at a later time. The atomic type classes are those which describe - types which cannot be decomposed at the data type interface + types which cannot be decomposed at the datatype interface level; all other classes are compound. <p> @@ -117,13 +134,11 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Opens a named datatype. <dt><strong>Description:</strong> - <dd><b>From UG:</b> <code>H5Topen</code> opens a named datatype at the location - specified by <code>loc_id</code> and returns an identifier - for the data type. The identifier should eventually be closed - by calling <code>H5Tclose()</code> to release resources. - <code>loc_id</code> is either a file or group identifier. - <p> - <b>From SC:</b> Opens a named datatype. + <dd><code>H5Topen</code> opens a named datatype at the location + specified by <code>loc_id</code> and returns an identifier + for the datatype. <code>loc_id</code> is either a file or + group identifier. The identifier should eventually be closed + by calling <code>H5Tclose()</code> to release resources. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>loc_id</code> @@ -148,13 +163,11 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Commits a transient datatype to a file, creating a new named datatype. <dt><strong>Description:</strong> - <dd><b>From UG:</b> <code>H5Tcommit</code> commits a transient datatype (not immutable) - to a file, turned it into a named datatype. The <code>loc_id</code> - is either a file or group identifier which, when combined with - <code>name</code>, refers to a new named data type. - <p> - <b>From SC:</b> Saves a transient data type to a file and turns - the type identifier into a named, immutable type. + <dd><code>H5Tcommit</code> commits a transient datatype + (not immutable) to a file, turned it into a named datatype. + The <code>loc_id</code> is either a file or group identifier + which, when combined with <code>name</code>, refers to a new + named datatype. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>loc_id</code> @@ -178,24 +191,21 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Determines whether a datatype is a named type or a transient type. <dt><strong>Description:</strong> - <dd><b>From UG:</b> <code>H5Tcommitted</code> queries a type to determine whether - it is a named type or a transient type. If this function returns + <dd><code>H5Tcommitted</code> queries a type to determine whether + the type specified by the <code>type</code> identifier + is a named type or a transient type. If this function returns a positive value, then the type is named (that is, it has been committed, perhaps by some other application). Datasets which - return committed data types with <code>H5Dget_type()</code> are - able to share the data type with other datasets in the same file. - <p> - <b>From SC:</b> Determines whether a data type is committed. + return committed datatypes with <code>H5Dget_type()</code> are + able to share the datatype with other datasets in the same file. <dt><strong>Parameters:</strong> <dl> <dt>hid_t</em> <code>type</code> <dd>Datatype identifier. </dl> <dt><strong>Returns:</strong> - <dd><b>From UG:</b> Returns a datatype identifier if successful; - otherwise FAIL (-1). - <dd><b>From SC:</b> The successful returns values are TRUE if committed, - else FALSE. Otherwise returns FAIL (-1). + <dd>The successful return values are TRUE if committed, else FALSE. + Otherwise returns FAIL (-1). </dl> @@ -212,33 +222,35 @@ in the <cite>HDF5 User's Guide</cite> for further information. <em>hid_t</em> <code>member_id</code> ) <dt><strong>Purpose:</strong> - <dd>Adds a new member to a compound data type. + <dd>Adds an array member to a compound datatype. <dt><strong>Description:</strong> - <dd><b>From SC:</b> <code>H5Tinsert_array</code> adds a new member to the - compound data type <code>parent_id</code>. The new member's name, - <code>name</code>, must be unique within the compound data type. - The <code>offset</code> argument defines the start of - the member in an instance of the compound data type and - <code>member_id</code> is the type of the new member. + <dd><code>H5Tinsert_array</code> adds a new member to the + compound datatype <code>parent_id</code>. The member is an array with <code>ndims</code> dimensionality and the size of the array is </em><code>dim</code>. - The total member size should be relatively small + The new member's name, <code>name</code>, must be unique + within the compound datatype. + The <code>offset</code> argument defines the start of the + member in an instance of the compound datatype and + <code>member_id</code> is the type identifier of the new member. + The total member size should be relatively small. <dt><strong>Parameters:</strong> <dl> - <dt>hid_t</em> <code>parent_id</code> - <dd> + <dt><em>hid_t</em> <code>parent_id</code> + <dd>Identifier of the parent compound datatype. <dt><em>const char *</em><code>name</code> - <dd> + <dd>Name of new member. <dt><em>size_t</em> <code>offset</code> - <dd> + <dd>Offset to start of new member within compound datatype. <dt><em>int</em> <code>ndims</code> - <dd> + <dd>Dimensionality of new member. <dt><em>const size_t *</em><code>dim</code> - <dd> + <dd>Size of new member array. <dt><em>const int *</em><code>perm</code> - <dd> + <dd>Pointer to buffer to store the permutation vector of + the field. <dt><em>hid_t</em> <code>member_id</code> - <dd> + <dd>Identifier of the datatype of the new member. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -257,25 +269,25 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Finds a conversion function. <dt><strong>Description:</strong> - <dd><b>From SC:</b> <code>H5Tfind</code> finds a conversion function - that can handle a conversion from type <code>src_id</code> to - type <code>dst_id</code>. - The <code>pcdata</code> argument is a pointer - to a pointer to type conversion data which was created and - initialized by the soft type conversion function of this path - when the conversion function was installed on the path. + <dd><code>H5Tfind</code> finds a conversion function that can + handle a conversion from type <code>src_id</code> to type + <code>dst_id</code>. + The <code>pcdata</code> argument is a pointer to a pointer + to type conversion data which was created and initialized + by the soft type conversion function of this path when the + conversion function was installed on the path. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>src_id</code> - <dd> + <dd>Identifier for the source datatype. <dt><em>hid_t</em> <code>dst_id</code> - <dd> + <dd>Identifier for the destination datatype. <dt><em>H5T_cdata_t **</em><code>pcdata</code> - <dd> + <dd>Pointer to type conversion data. </dl> <dt><strong>Returns:</strong> <dd>Returns a pointer to a suitable conversion function if successful. - Otherwise returns FAIL (-1). + Otherwise returns NULL. </dl> @@ -292,8 +304,9 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Converts data from between specified datatypes. <dt><strong>Description:</strong> - <dd><b>From SC:</b> Convert <code>nelmts</code> elements from type - <code>src_id</code> to type <code>dst_id</code>. + <dd><code>H5Tconvert</code> converts <code>nelmts</code> elements + from the type specified by the <code>src_id</code> identifier + to type <code>dst_id</code>. The source elements are packed in <code>buf</code> and on return the destination will be packed in <code>buf</code>. That is, the conversion is performed in place. @@ -307,15 +320,15 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>src_id</code> - <dd> + <dd>Identifier for the source datatype. <dt><em>hid_t</em> <code>dst_id</code> - <dd> + <dd>Identifier for the destination datatype. <dt><em>size_t</em> <code>nelmts</code> - <dd> + <dd>Size of array <code>buf</code>. <dt><em>void *</em><code>buf</code> - <dd> + <dd>Array containing pre- and post-conversion values. <dt><em>void *</em><code>background</code> - <dd> + <dd>Optional background buffer. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -331,9 +344,9 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Purpose:</strong> <dd>Sets the overflow handler to a specified function. <dt><strong>Description:</strong> - <dd><b>From SC:</b> <code>H5Tset_overflow</code> sets the overflow handler + <dd><code>H5Tset_overflow</code> sets the overflow handler to be the function specified by <code>func</code>. - <code>func</code> will be called for all data type conversions that + <code>func</code> will be called for all datatype conversions that result in an overflow. <p> See the definition of <code>H5T_overflow_t</code> in @@ -348,7 +361,7 @@ in the <cite>HDF5 User's Guide</cite> for further information. <dt><strong>Parameters:</strong> <dl> <dt><em>H5T_overflow_t</em> <code>func</code> - <dd> + <dd>Overflow function. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -367,10 +380,10 @@ H5Tget_overflow () <dt><strong>Purpose:</strong> <dd>Returns a pointer to the current global overflow function. <dt><strong>Description:</strong> - <dd><b>From SC:</b> <code>H5Tset_overflow</code> returns a pointer + <dd><code>H5Tset_overflow</code> returns a pointer to the current global overflow function. This is an application-defined function that is called whenever a - data type conversion causes an overflow. + datatype conversion causes an overflow. <dt><strong>Parameters:</strong> <dl> <dt>None. @@ -392,12 +405,13 @@ H5Tget_overflow () <dt><strong>Purpose:</strong> <dd>Creates a new dataype. <dt><strong>Description:</strong> - <dd><code>H5Tcreate</code> creates a new dataype of the specified class with the - specified number of bytes. Currently, only the <code>H5T_COMPOUND</code> - datatype class is supported with this function, use <code>H5Tcopy</code> - to create integer or floating-point datatypes. The datatype ID - returned from this function should be released with H5Tclose or resource - leaks will result. + <dd><code>H5Tcreate</code> creates a new dataype of the specified + class with the specified number of bytes. + Currently, only the <code>H5T_COMPOUND</code> datatype class is + supported with this function. Use <code>H5Tcopy</code> + to create integer or floating-point datatypes. + The datatype identifier returned from this function should be + released with <code>H5Tclose</code> or resource leaks will result. <dt><strong>Parameters:</strong> <dl> <dt><em>H5T_class_t</em> <code>class</code> @@ -406,7 +420,8 @@ H5Tget_overflow () <dd>The number of bytes in the datatype to create. </dl> <dt><strong>Returns:</strong> - <dd>Datatype ID on success, negative on failure. + <dd>Returns datatype identifier if successful; + otherwise FAIL (-1). </dl> @@ -414,14 +429,25 @@ H5Tget_overflow () <dl> <dt><strong>Name:</strong> <a name="Datatype-Copy">H5Tcopy</a> <dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Tcopy</code>(<em>hid_t </em><code>type_id</code> - ) + <dd><em>hid_t </em><code>H5Tcopy</code>(<em>hid_t </em><code>type_id</code>) <dt><strong>Purpose:</strong> <dd>Copies an existing datatype. <dt><strong>Description:</strong> - <dd><code>H5Tcopy</code> copies an existing datatype. The datatype ID returned - should be released with H5Tclose or resource leaks will occur. Native - datatypes supported by the library are: + <dd><code>H5Tcopy</code> copies an existing datatype. + The returned type is always transient and unlocked. + <p> + The <code>type_id</code> argument can be either a datatype + identifier, a predefined datatype (defined in + <code>H5Tpublic.h</code>), or a dataset identifier. + If <code>type_id</code> is a dataset identifier instead of a + datatype identifier, then this function returns a transient, + modifiable datatype which is a copy of the dataset's datatype. + <p> + The datatype identifier returned should be released with + <code>H5Tclose</code> or resource leaks will occur. +<!-- + <p> + Native datatypes supported by the library are: <ul> <dl> <dt>H5T_NATIVE_CHAR <dd> Native character type, declare dataset array as 'char' @@ -464,13 +490,17 @@ H5Tget_overflow () <dt>H5T_NATIVE_DOUBLE <dd> Native double-precision float type, declare dataset array as 'double' </dl> </ul> +--> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to copy. + <dd>Identifier of datatype to copy. Can be a datatype + identifier, a predefined datatype (defined in + <code>H5Tpublic.h</code>), or a dataset identifier. </dl> <dt><strong>Returns:</strong> - <dd>Datatype ID on success, negative on failure. + <dd>Returns a datatype identifier if successful; + otherwise FAIL (-1) </dl> @@ -489,12 +519,14 @@ H5Tget_overflow () <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id1</code> - <dd>ID of datatype to compare. + <dd>Identifier of datatype to compare. <dt><em>hid_t</em> <code>type_id2</code> - <dd>ID of datatype to compare. + <dd>Identifier of datatype to compare. </dl> <dt><strong>Returns:</strong> - <dd>TRUE/FALSE/negative + <dd>When successful, returns TRUE if the datatype identifiers + refer to the same datatype, else FALSE. + Otherwise returns FAIL (-1). </dl> @@ -505,19 +537,22 @@ H5Tget_overflow () <dd><em>herr_t </em><code>H5Tlock</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Locks a type. + <dd>Locks a datatype. <dt><strong>Description:</strong> - <dd><code>H5Tlock</code> locks a type, making it read-only and non-destrucible. - This is normally done by the library for predefined data types so the - application doesn't inadvertently change or delete a predefined type. - Once a data type is locked it can never be unlocked. + <dd><code>H5Tlock</code> locks the datatype specified by the + <code>type_id</code> identifier, making it read-only and + non-destrucible. This is normally done by the library for + predefined datatypes so the application does not + inadvertently change or delete a predefined type. + Once a datatype is locked it can never be unlocked. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to lock. + <dd>Identifier of datatype to lock. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -528,16 +563,27 @@ H5Tget_overflow () <dd><em>H5T_class_t </em><code>H5Tget_class</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the base class of a datatype. + <dd>Returns the datatype class identifier. <dt><strong>Description:</strong> - <dd><code>H5Tget_class</code> returns the base class of a datatype. + <dd><code>H5Tget_class</code> returns the datatype class identifier. + <p> + Valid class identifiers, as defined in <code>H5Tpublic.h</code>, are: + <ul><li><code>H5T_INTEGER</code> (<code>0</code>) + <li><code>H5T_FLOAT</code> (<code>1</code>) + <li><code>H5T_TIME</code> (<code>2</code>) + <li><code>H5T_STRING</code> (<code>3</code>) + <li><code>H5T_BITFIELD</code> (<code>4</code>) + <li><code>H5T_OPAQUE</code> (<code>5</code>) + <li><code>H5T_COMPOUND</code> (<code>6</code>) + </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative type class on success, negative on failure. + <dd>Returns datatype class identifier if successful; + otherwise H5T_NO_CLASS (-1). </dl> @@ -554,10 +600,11 @@ H5Tget_overflow () <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Positve size in bytes on success, 0 on failure. + <dd>Returns the size of the datatype in bytes if successful; + otherwise 0. </dl> @@ -569,27 +616,28 @@ H5Tget_overflow () <em>size_t</em><code>size</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the total size for an atomic data type. + <dd>Sets the total size for an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_size</code> sets the total size in bytes for an - atomic data type (this - operation is not permitted on compound data types). If the size is - decreased so that the significant bits of the data type extend beyond + <dd><code>H5Tset_size</code> sets the total size in bytes, + <code>size</code>, for an atomic datatype (this operation + is not permitted on compound datatypes). If the size is + decreased so that the significant bits of the datatype extend beyond the edge of the new size, then the `offset' property is decreased toward zero. If the `offset' becomes zero and the significant - bits of the data type still hang over the edge of the new size, then + bits of the datatype still hang over the edge of the new size, then the number of significant bits is decreased. Adjusting the size of an H5T_STRING automatically sets the precision - to 8*size. All data types have a positive size. + to 8*size. All datatypes have a positive size. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to change size. + <dd>Identifier of datatype to change size. <dt><em>size_t</em> <code>size</code> <dd>Size in bytes to modify datatype. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -602,14 +650,26 @@ H5Tget_overflow () <dt><strong>Purpose:</strong> <dd>Returns the byte order of an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_order</code> returns the byte order of an atomic datatype. + <dd><code>H5Tget_order</code> returns the byte order of an + atomic datatype. + <p> + Possible return values are: + <ul><dl> + <dt><code>H5T_ORDER_LE</code> (<code>0</code>) + <dd>Little endian byte ordering (default). + <dt><code>H5T_ORDER_BE</code> (<code>1</code>) + <dd>Big endian byte ordering. + <dt><code>H5T_ORDER_VAX</code> (<code>2</code>) + <dd>VAX mixed byte ordering (not currently supported). + </dl></ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Byte order constant on success, negative on failure + <dd>Returns a byte order constant if successful; + otherwise <code>H5T_ORDER_ERROR</code> (-1). </dl> @@ -626,22 +686,23 @@ H5Tget_overflow () <dd><code>H5Tset_order</code> sets the byte ordering of an atomic datatype. Byte orderings currently supported are: <ul> <dl> - <dt>H5T_ORDER_LE - <dd> Little-endian byte ordering (default) - <dt>H5T_ORDER_BE - <dd> Big-endian byte ordering - <dt>H5T_ORDER_Vax - <dd> VAX-endianness byte ordering (not currently supported) + <dt>H5T_ORDER_LE (<code>0</code>) + <dd> Little-endian byte ordering (default). + <dt>H5T_ORDER_BE (<code>1</code>) + <dd> Big-endian byte ordering. + <dt>H5T_ORDER_VAX (<code>2</code>) + <dd>VAX mixed byte ordering (not currently supported). </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>H5T_order_t</em> <code>order</code> <dd>Byte ordering constant. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -652,18 +713,19 @@ H5Tget_overflow () <dd><em>size_t </em><code>H5Tget_precision</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the precision of an atomic data type. + <dd>Returns the precision of an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_precision</code> returns the precision of an atomic data type. The + <dd><code>H5Tget_precision</code> returns the precision of an atomic datatype. The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size(). <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Number of significant bits on success, 0 on failure + <dd>Returns the number of significant bits if successful; + otherwise 0. </dl> @@ -675,14 +737,14 @@ H5Tget_overflow () <em>size_t</em><code>precision</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the precision of an atomic data type. + <dd>Sets the precision of an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_precision</code> sets the precision of an atomic data type. + <dd><code>H5Tset_precision</code> sets the precision of an atomic datatype. The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size(). <P>If the precision is increased then the offset is decreased and then the size is increased to insure that significant bits do not "hang - over" the edge of the data type. + over" the edge of the datatype. <P>Changing the precision of an H5T_STRING automatically changes the size as well. The precision must be a multiple of 8. <P>When decreasing the precision of a floating point type, set the @@ -691,12 +753,13 @@ H5Tget_overflow () <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>size_t</em> <code>precision</code> <dd>Number of bits of precision for datatype. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -759,10 +822,11 @@ H5Tget_overflow () <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Positive offset value on success, 0 on failure. + <dd>Returns a positive offset value if successful; + otherwise 0. </dl> @@ -826,19 +890,20 @@ H5Tget_overflow () <P>If the offset is incremented then the total size is incremented also if necessary to prevent significant bits of -the value from hanging over the edge of the data type. +the value from hanging over the edge of the datatype. <P>The offset of an H5T_STRING cannot be set to anything but zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>size_t</em> <code>offset</code> <dd>Offset of first significant bit. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -856,24 +921,27 @@ zero. <dd><code>H5Tget_pad</code> retrieves the padding type of the least and most-significant bit padding. Valid types are: <ul> <dl> - <dt>H5T_PAD_ZERO + <dt>H5T_PAD_ZERO (<code>0</code>) <dd>Set background to zeros. - <dt>H5T_PAD_ONE + <dt>H5T_PAD_ONE (<code>1</code>) <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND + <dt>H5T_PAD_BACKGROUND (<code>2</code>) <dd>Leave background alone. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>IN: Identifier of datatype to query. <dt><em>H5T_pad_t *</em> <code>lsb</code> - <dd>Pointer to location to return least-significant bit padding type. + <dd>OUT: Pointer to location to return least-significant + bit padding type. <dt><em>H5T_pad_t *</em> <code>msb</code> - <dd>Pointer to location to return most-significant bit padding type. + <dd>OUT: Pointer to location to return most-significant + bit padding type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -890,24 +958,25 @@ zero. <dt><strong>Description:</strong> <dd><code>H5Tset_pad</code> sets the least and most-significant bits padding types. <ul> <dl> - <dt>H5T_PAD_ZERO + <dt>H5T_PAD_ZERO (<code>0</code>) <dd>Set background to zeros. - <dt>H5T_PAD_ONE + <dt>H5T_PAD_ONE (<code>1</code>) <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND + <dt>H5T_PAD_BACKGROUND (<code>2</code>) <dd>Leave background alone. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>H5T_pad_t</em> <code>lsb</code> <dd>Padding type for least-significant bits. <dt><em>H5T_pad_t</em> <code>msb</code> <dd>Padding type for most-significant bits. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -923,18 +992,19 @@ zero. <dd><code>H5Tget_sign</code> retrieves the sign type for an integer type. Valid types are: <ul> <dl> - <dt>H5T_SGN_NONE + <dt>H5T_SGN_NONE (<code>0</code>) <dd>Unsigned integer type. - <dt>H5T_SGN_2 + <dt>H5T_SGN_2 (<code>1</code>) <dd>Two's complement signed integer type. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative sign type on success, negative on failure + <dd>Returns a valid sign type if successful; + otherwise <code>H5T_SGN_ERROR</code> (-1). </dl> @@ -950,20 +1020,21 @@ zero. <dt><strong>Description:</strong> <dd><code>H5Tset_sign</code> sets the sign proprety for an integer type. <ul> <dl> - <dt>H5T_SGN_NONE + <dt>H5T_SGN_NONE (<code>0</code>) <dd>Unsigned integer type. - <dt>H5T_SGN_2 + <dt>H5T_SGN_2 (<code>1</code>) <dd>Two's complement signed integer type. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>H5T_sign_t</em> <code>sign</code> <dd>Sign type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -978,28 +1049,29 @@ zero. <em>size_t *</em> <code>msize</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves floating point data type bit field information. + <dd>Retrieves floating point datatype bit field information. <dt><strong>Description:</strong> <dd><code>H5Tget_fields</code> retrieves information about the locations of the various - bit fields of a floating point data type. The field positions are bit - positions in the significant region of the data type. Bits are + bit fields of a floating point datatype. The field positions are bit + positions in the significant region of the datatype. Bits are numbered with the least significant bit number zero. Any (or even all) of the arguments can be null pointers. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>IN: Identifier of datatype to query. <dt><em>size_t *</em> <code>epos</code> - <dd>Pointer to location to return exponent bit-position. + <dd>OUT: Pointer to location to return exponent bit-position. <dt><em>size_t *</em> <code>esize</code> - <dd>Pointer to location to return size of exponent in bits. + <dd>OUT: Pointer to location to return size of exponent in bits. <dt><em>size_t *</em> <code>mpos</code> - <dd>Pointer to location to return mantissa bit-position. + <dd>OUT: Pointer to location to return mantissa bit-position. <dt><em>size_t *</em> <code>msize</code> - <dd>Pointer to location to return size of mantissa in bits. + <dd>OUT: Pointer to location to return size of mantissa in bits. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1018,7 +1090,7 @@ zero. <dt><strong>Description:</strong> <dd><code>H5Tset_fields</code> sets the locations and sizes of the various floating point bit fields. The field positions are bit positions in the - significant region of the data type. Bits are numbered with the least + significant region of the datatype. Bits are numbered with the least significant bit number zero. <P>Fields are not allowed to extend beyond the number of bits of @@ -1026,7 +1098,7 @@ zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>size_t</em> <code>epos</code> <dd>Exponent bit position. <dt><em>size_t</em> <code>esize</code> @@ -1037,7 +1109,8 @@ zero. <dd>Size of mantissa in bits. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1054,10 +1127,11 @@ zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Positive value on success, 0 on failure. + <dd>Returns the bias if successful; + otherwise 0. </dl> @@ -1075,12 +1149,13 @@ zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>size_t</em> <code>ebias</code> <dd>Exponent bias value. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1093,23 +1168,24 @@ zero. <dt><strong>Purpose:</strong> <dd>Retrieves mantissa normalization of a floating-point datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_norm</code> retrieves the mantissa normalization of a floating-point - datatype. Valid normalization values are: + <dd><code>H5Tget_norm</code> retrieves the mantissa normalization of + a floating-point datatype. Valid normalization types are: <ul> <dl> - <dt>H5T_NORM_IMPLIED - <dd>MSB of mantissa isn't stored, always 1 - <dt>H5T_NORM_MSBSET + <dt>H5T_NORM_IMPLIED (<code>0</code>) + <dd>MSB of mantissa is not stored, always 1 + <dt>H5T_NORM_MSBSET (<code>1</code>) <dd>MSB of mantissa is always 1 - <dt>H5T_NORM_NONE + <dt>H5T_NORM_NONE (<code>2</code>) <dd>Mantissa is not normalized </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative normalization type on success, negative on failure + <dd>Returns a valid normalization type if successful; + otherwise <code>H5T_NORM_ERROR</code> (-1). </dl> @@ -1123,25 +1199,26 @@ zero. <dt><strong>Purpose:</strong> <dd>Sets the mantissa normalization of a floating-point datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_norm</code> sets the mantissa normalization of a floating-point - datatype. Valid normalization values are: + <dd><code>H5Tset_norm</code> sets the mantissa normalization of + a floating-point datatype. Valid normalization types are: <ul> <dl> - <dt>H5T_NORM_IMPLIED - <dd>MSB of mantissa isn't stored, always 1 - <dt>H5T_NORM_MSBSET + <dt>H5T_NORM_IMPLIED (<code>0</code>) + <dd>MSB of mantissa is not stored, always 1 + <dt>H5T_NORM_MSBSET (<code>1</code>) <dd>MSB of mantissa is always 1 - <dt>H5T_NORM_NONE + <dt>H5T_NORM_NONE (<code>2</code>) <dd>Mantissa is not normalized </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to set. + <dd>Identifier of datatype to set. <dt><em>H5T_norm_t</em> <code>norm</code> <dd>Mantissa normalization type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1156,22 +1233,23 @@ zero. <dt><strong>Description:</strong> <dd><code>H5Tget_inpad</code> retrieves the internal padding type for unused bits in floating-point datatypes. - Valid padding values are: + Valid padding types are: <ul> <dl> - <dt>H5T_PAD_ZERO + <dt>H5T_PAD_ZERO (<code>0</code>) <dd>Set background to zeros. - <dt>H5T_PAD_ONE + <dt>H5T_PAD_ONE (<code>1</code>) <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND + <dt>H5T_PAD_BACKGROUND (<code>2</code>) <dd>Leave background alone. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative padding type on success, negative on failure + <dd>Returns a valid padding type if successful; + otherwise <code>H5T_PAD_ERROR</code> (-1). </dl> @@ -1189,24 +1267,25 @@ zero. (that is, those significant bits which are not part of the sign, exponent, or mantissa), then <code>H5Tset_inpad</code> will be filled according to the value of the padding value property <code>inpad</code>. - Valid padding values are: + Valid padding types are: <ul> <dl> - <dt>H5T_PAD_ZERO + <dt>H5T_PAD_ZERO (<code>0</code>) <dd>Set background to zeros. - <dt>H5T_PAD_ONE + <dt>H5T_PAD_ONE (<code>1</code>) <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND + <dt>H5T_PAD_BACKGROUND (<code>2</code>) <dd>Leave background alone. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. + <dd>Identifier of datatype to modify. <dt><em>H5T_pad_t</em> <code>pad</code> <dd>Padding type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1219,19 +1298,20 @@ zero. <dt><strong>Purpose:</strong> <dd>Retrieves the character set type of a string datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_cset</code> retrieves the character set type of a string datatype. - Valid character set values are: + <dd><code>H5Tget_cset</code> retrieves the character set type + of a string datatype. Valid character set types are: <ul> <dl> - <dt>H5T_CSET_ASCII + <dt>H5T_CSET_ASCII (<code>0</code>) <dd>Character set is US ASCII </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative character set type on success, negative on failure + <dd>Returns a valid character set type if successful; + otherwise <code>H5T_CSET_ERROR</code> (-1). </dl> @@ -1243,24 +1323,27 @@ zero. <em>H5T_cset_t</em> <code>cset</code> ) <dt><strong>Purpose:</strong> - <dd> + <dd>Sets character set to be used. <dt><strong>Description:</strong> - <dd>HDF5 is able to distinguish between character sets of different + <dd><code>H5Tset_cset</code> the character set to be used. + <p> + HDF5 is able to distinguish between character sets of different nationalities and to convert between them to the extent possible. - Valid character set values are: + Valid character set types are: <ul> <dl> - <dt>H5T_CSET_ASCII - <dd>Character set is US ASCII + <dt>H5T_CSET_ASCII (<code>0</code>) + <dd>Character set is US ASCII. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. + <dd>Identifier of datatype to modify. <dt><em>H5T_cset_t</em> <code>cset</code> <dd>Character set type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1273,21 +1356,22 @@ zero. <dt><strong>Purpose:</strong> <dd>Retrieves the string padding method for a string datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_strpad</code> retrieves the string padding method for a string datatype. - Valid string padding values are: + <dd><code>H5Tget_strpad</code> retrieves the string padding method + for a string datatype. Valid string padding types are: <ul> <dl> - <dt>H5T_STR_NULL + <dt>H5T_STR_NULL (<code>0</code>) <dd>Pad with zeros (as C does) - <dt>H5T_STR_SPACE + <dt>H5T_STR_SPACE (<code>1</code>) <dd>Pad with spaces (as FORTRAN does) </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Non-negative string padding type on success, negative on failure + <dd>Returns a valid string padding type if successful; + otherwise <code>H5T_STR_ERROR</code> (-1). </dl> @@ -1307,20 +1391,21 @@ zero. <code>H5Tset_strpad</code> defines the storage mechanism for the string. Valid string padding values are: <ul> <dl> - <dt>H5T_STR_NULL + <dt>H5T_STR_NULL (<code>0</code>) <dd>Pad with zeros (as C does) - <dt>H5T_STR_SPACE + <dt>H5T_STR_SPACE (<code>1</code>) <dd>Pad with spaces (as FORTRAN does) </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. + <dd>Identifier of datatype to modify. <dt><em>H5T_str_t</em> <code>strpad</code> <dd>String padding type. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1337,10 +1422,11 @@ zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Number of members datatype has on success, negative on failure + <dd>Returns number of members datatype has if successful; + otherwise FAIL (-1). </dl> @@ -1349,25 +1435,27 @@ zero. <dt><strong>Name:</strong> <a name="Datatype-GetMemberName">H5Tget_member_name</a> <dt><strong>Signature:</strong> <dd><em>char *</em> <code>H5Tget_member_name</code>(<em>hid_t </em><code>type_id</code>, - <em>intn</em> <code>fieldno</code> + <em>int</em> <code>field_idx</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the name of a field of a compound data type. + <dd>Retrieves the name of a field of a compound datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_member_name</code> retrieves the name of a field of a compound data type. - Fields are stored in no particular order with numbers 0 through N-1 - where N is the value returned by H5Tget_nmembers(). The name of the - field is allocated with malloc() and the caller is responsible for - freeing the memory used by the name. + <dd><code>H5Tget_member_name</code> retrieves the name of a field + of a compound datatype. Fields are stored in no particular + order, with indexes 0 through N-1, where N is the value returned + by <code>H5Tget_nmembers()</code>. The name of the field is + allocated with <code>malloc()</code> and the caller is responsible + for freeing the memory used by the name. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - <dt><em>intn</em> <code>fieldno</code> - <dd>Field number (indexed from 0) of the field name to retrieve. + <dd>Identifier of datatype to query. + <dt><em>int</em> <code>field_idx</code> + <dd>Field index (0-based) of the field name to retrieve. </dl> <dt><strong>Returns:</strong> - <dd>Valid pointer on success, NULL on failure + <dd>Returns a valid pointer if successful; + otherwise NULL. </dl> @@ -1376,30 +1464,35 @@ zero. <dt><strong>Name:</strong> <a name="Datatype-GetMemberDims">H5Tget_member_dims</a> <dt><strong>Signature:</strong> <dd><em>int</em> <code>H5Tget_member_dims</code>(<em>hid_t </em><code>type_id</code>, - <em>intn</em> <code>fieldno</code>, - <em>size_t *</em> <code>dims</code>, - <em>int *</em> <code>perm</code> + <em>int</em> <code>field_idx</code>, + <em>size_t *</em><code>dims</code>, + <em>int *</em><code>perm</code> ) <dt><strong>Purpose:</strong> <dd>Returns the dimensionality of the field. <dt><strong>Description:</strong> - <dd><code>H5Tget_member_dims</code> returns the dimensionality of the field. The dimensions - and permuation vector are returned through arguments <code>dims</code> - and <code>perm</code>, both arrays of at least four elements. Either - (or even both) may be null pointers. + <dd><code>H5Tget_member_dims</code> returns the dimensionality of + the field. The dimensions and permuation vector are returned + through arguments <code>dims</code> and <code>perm</code>, + both arrays of at least four elements. + Either (or even both) may be null pointers. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - <dt><em>intn</em> <code>fieldno</code> - <dd>Field number (indexed from 0) of the field dims to retrieve. + <dd>Identifier of datatype to query. + <dt><em>int</em> <code>field_idx</code> + <dd>Field index (0-based) of the field <code>dims</code> + to retrieve. <dt><em>size_t *</em> <code>dims</code> <dd>Pointer to buffer to store the dimensions of the field. <dt><em>int *</em> <code>perm</code> - <dd>Pointer to buffer to store the permutation vector of the field. + <dd>Pointer to buffer to store the permutation vector of + the field. </dl> <dt><strong>Returns:</strong> - <dd>Number of dimensions on success, negative on failure. + <dd>Returns the number of dimensions, a number from 0 to 4, + if successful. + Otherwise returns FAIL (-1). </dl> @@ -1408,22 +1501,24 @@ zero. <dt><strong>Name:</strong> <a name="Datatype-GetMemberType">H5Tget_member_type</a> <dt><strong>Signature:</strong> <dd><em>hid_t</em> <code>H5Tget_member_type</code>(<em>hid_t </em><code>type_id</code>, - <em>intn</em> <code>fieldno</code> + <em>int</em> <code>field_idx</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the data type of the specified member. + <dd>Returns the datatype of the specified member. <dt><strong>Description:</strong> - <dd><code>H5Tget_member_type</code> returns the data type of the specified member. The caller + <dd><code>H5Tget_member_type</code> returns the datatype of the specified member. The caller should invoke H5Tclose() to release resources associated with the type. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to query. - <dt><em>intn</em> <code>fieldno</code> - <dd>Field number (indexed from 0) of the field type to retrieve. + <dd>Identifier of datatype to query. + <dt><em>int</em> <code>field_idx</code> + <dd>Field index (0-based) of the field type to retrieve. </dl> <dt><strong>Returns:</strong> - <dd>The ID of a copy of the datatype of the field, negative on failure. + <dd>Returns the identifier of a copy of the datatype of the field + if successful; + otherwise FAIL (-1). </dl> @@ -1437,30 +1532,32 @@ zero. <em>hid_t</em> <code>field_id</code> ) <dt><strong>Purpose:</strong> - <dd>Adds a new member to a compound data type. + <dd>Adds a new member to a compound datatype. <dt><strong>Description:</strong> - <dd><code>H5Tinsert</code> adds another member to the compound data type + <dd><code>H5Tinsert</code> adds another member to the compound datatype <code>type_id</code>. The new member has a <code>name</code> which - must be unique within the compound data type. The <code>offset</code> - argument defines the start of the member in an instance of the compound - data type, and <code>field_id</code> is the type of the new member. - - <P>Note: All members of a compound data type must be atomic; a - compound data type cannot have a member which is a compound data - type. + must be unique within the compound datatype. + The <code>offset</code> argument defines the start of the member + in an instance of the compound datatype, and <code>field_id</code> + is the datatype identifier of the new member. + <P> + Note: All members of a compound datatype must be atomic; a + compound datatype cannot have a member which is a compound + datatype. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of compound datatype to modify. + <dd>Identifier of compound datatype to modify. <dt><em>const char *</em> <code>name</code> <dd>Name of the field to insert. <dt><em>off_t</em> <code>offset</code> <dd>Offset in memory structure of the field to insert. <dt><em>hid_t</em> <code>field_id</code> - <dd>Datatype ID of the field to insert. + <dd>Datatype identifier of the field to insert. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1478,10 +1575,11 @@ zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to modify. + <dd>Identifier of datatype to modify. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1497,32 +1595,40 @@ zero. <dt><strong>Purpose:</strong> <dd>Registers a hard conversion function. <dt><strong>Description:</strong> - <dd><code>H5Tregister_hard</code> registers a hard conversion function for a data type + <dd><code>H5Tregister_hard</code> registers a hard conversion function for a datatype conversion path. The path is specified by the source and destination datatypes <code>src_id</code> and <code>dst_id</code>. A conversion path can only have one hard function, so <code>func</code> replaces any previous hard function. - <P>If <code>func</code> is the null pointer then any hard function + <p> + If <code>func</code> is the null pointer then any hard function registered for this path is removed from this path. The soft functions are then used when determining which conversion function is appropriate for this path. The <code>name</code> argument is used only for debugging and should be a short identifier for the function. - <P>The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); + <p> + The type of the conversion function pointer is declared as: + <br> + <code>typedef</code> <em>herr_t </em>(<code>*H5T_conv_t</code>) (<em>hid_t </em><code>src_id</code>, + <em>hid_t </em><code>dst_id</code>, + <em>H5T_cdata_t *</em><code>cdata</code>, + <em>size_t </em><code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>bkg)</code>; <dt><strong>Parameters:</strong> <dl> <dt><em>const char *</em> <code>name</code> <dd>Name displayed in diagnostic output. <dt><em>hid_t</em> <code>src_id</code> - <dd>ID of source datatype. + <dd>Identifier of source datatype. <dt><em>hid_t</em> <code>dst_id</code> - <dd>ID of destination datatype. + <dd>Identifier of destination datatype. <dt><em>H5T_conv_t</em> <code>func</code> <dd>Function to convert between source and destination datatypes. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1531,8 +1637,8 @@ zero. <dt><strong>Name:</strong> <a name="Datatype-RegisterSoft">H5Tregister_soft</a> <dt><strong>Signature:</strong> <dd><em>herr_t</em> <code>H5Tregister_soft</code>(<em>const char - *</em> <code>name</code>, <em>hid_t </em><code>src_id</code>, - <em>hid_t</em> <code>dst_id</code>, + *</em> <code>name</code>, <em>H5T_class_t </em><code>src_cls</code>, + <em>H5T_class_t</em> <code>dst_cls</code>, <em>H5T_conv_t</em> <code>func</code> ) <dt><strong>Purpose:</strong> @@ -1543,22 +1649,29 @@ zero. applicable existing conversion paths. The <code>name</code> is used only for debugging and should be a short identifier for the function. - <P>The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); + <P> + The type of the conversion function pointer is declared as: + <br> + <code>typedef</code> <em>herr_t </em>(<code>*H5T_conv_t</code>) (<em>hid_t </em><code>src_id</code>, + <em>hid_t </em><code>dst_id</code>, + <em>H5T_cdata_t *</em><code>cdata</code>, + <em>size_t </em><code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>bkg)</code>; <dt><strong>Parameters:</strong> <dl> <dt><em>const char *</em> <code>name</code> <dd>Name displayed in diagnostic output. - <dt><em>hid_t</em> <code>src_id</code> - <dd>ID of source datatype. - <dt><em>hid_t</em> <code>dst_id</code> - <dd>ID of destination datatype. + <dt><em>H5T_class_t</em> <code>src_cls</code> + <dd>Identifier of source datatype class. + <dt><em>H5T_class_t</em> <code>dst_cls</code> + <dd>Identifier of destination datatype class. <dt><em>H5T_conv_t</em> <code>func</code> <dd>Function to convert between source and destination datatypes. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1572,16 +1685,23 @@ zero. <dd>Removes a conversion function from all conversion paths. <dt><strong>Description:</strong> <dd><code>H5Tunregister</code> removes a conversion function from all conversion paths. - <P>The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); + <P> + The type of the conversion function pointer is declared as: + <br> + <code>typedef</code> <em>herr_t </em>(<code>*H5T_conv_t</code>) (<em>hid_t </em><code>src_id</code>, + <em>hid_t </em><code>dst_id</code>, + <em>H5T_cdata_t *</em><code>cdata</code>, + <em>size_t </em><code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>bkg)</code>; <dt><strong>Parameters:</strong> <dl> <dt><em>H5T_conv_t</em> <code>func</code> <dd>Function to remove from conversion paths. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> @@ -1594,170 +1714,42 @@ zero. <dt><strong>Purpose:</strong> <dd>Releases a datatype. <dt><strong>Description:</strong> - <dd><code>H5Tclose</code> releases a datatype. Further access through the datatype - ID is illegal. Failure to release a datatype with this call will - result in resource leaks. + <dd><code>H5Tclose</code> releases a datatype. Further access + through the datatype identifier is illegal. Failure to release + a datatype with this call will result in resource leaks. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>ID of datatype to release. + <dd>Identifier of datatype to release. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> <hr> -<hr> - -<b>Aha!! And here is the reference to sharing and that command that had us -so buffaloed, <code>H5Tshare</code>!</b><br> -To quote Quincy: "The H5Tshare() and H5Tis_shared() will be removed. Data types -will not be stored in the global heap. A new type of shared -message header will be added to the object headers that points to -another object header instead of the global heap..." - -<hr> -<hr> -</b>UNUSED PORTIONS OF EMAIL NOTES.</b> -<br> -<code>....</code> in left margin indicates where material was - pulled out for inclusion above. -<HR> -<HR> -<pre> - -Elena> Datatype Interface: -Elena> Do we have description of the named datatypes somewhere? - ->From Datatypes.html... - -html> 7. Sharing Data Types among Datasets -html> -html> If a file has lots of datasets which have a common data type -html> then the file could be made smaller by having all the datasets -html> share a single data type. Instead of storing a copy of the data -html> type in each dataset object header, a single data type is stored -html> and the object headers point to it. The space savings is -html> probably only significant for datasets with a compound data type -html> since the simple data types can be described with just a few -html> bytes anyway. -html> -html> To create a bunch of datasets that share a single data type just -html> create the datasets with a committed (named) data type. -html> -html> To create two datasets that share a common data type one just -html> commits the data type, giving it a name, and then uses that -html> data type to create the datasets. -html> -html> hid_t t1 = ...some transient type...; -html> H5Tcommit (file, "shared_type", t1); -html> hid_t dset1 = H5Dcreate (file, "dset1", t1, space, H5P_DEFAULT); -html> hid_t dset2 = H5Dcreate (file, "dset2", t1, space, H5P_DEFAULT); -html> -html> -html> And to create two additional datasets later which share the -html> same type as the first two datasets: -html> -html> hid_t dset1 = H5Dopen (file, "dset1"); -html> hid_t t2 = H5Dget_type (dset1); -html> hid_t dset3 = H5Dcreate (file, "dset3", t2, space, H5P_DEFAULT); -html> hid_t dset4 = H5Dcreate (file, "dset4", t2, space, H5P_DEFAULT); -html> -html> -html> Example: Shared Types - -Mail from Quincey summarizing shared data types: - -Quincey> Hi Robb, -Quincey> Everything looks good, I just have a couple of minor comments below: -Quincey> -Quincey> > A very quick data types summary (so I can remember it next week :-) -Quincey> > -Quincey> > * Handles to named types are immutable. -Quincey> > -Quincey> > * A transient type handle can be converted to a named type handle -Quincey> > by calling H5Tcommit(). This can only be called for transient -Quincey> > types which are not locked or predefined. -Quincey> > -Quincey> > * H5Topen() returns a handle to a named immutable type. -Quincey> > -Quincey> > * H5Tcopy() returns a handle to a transient type. -Quincey> H5Tcreate also returns a handle to a transient type. -Quincey> -Quincey> > * Using a named type in H5Dcreate() causes the dataset object -Quincey> > header to point to the named type (shared). The link count on -Quincey> > the named type is incremented. -Quincey> > -Quincey> > * Using a transient type in H5Dcreate() causes the type to be -Quincey> > copied and stored in the dataset header (unshared). -Quincey> > -Quincey> > * Type handles returned from H5Dget_type() are immutable. -Quincey> > -Quincey> > * If the dataset is using a shared type (dataset object header -Quincey> > points to some other object header with a type message, e.g., a -Quincey> > named type) then H5Dget_type() returns a handle to that named -Quincey> > type. -Quincey> > -Quincey> > * If the dataset has a private type (data type is stored in the -Quincey> > dataset object header) then H5Dget_type() returns a handle to a -Quincey> > transient immutable type. -Quincey> > -Quincey> > * The name of a data type can be removed from a group, but unless -Quincey> > the reference count becomes zero the type continues to exist. -Quincey> > (Other objects work this way too). -Quincey> > -Quincey> > * H5Tcopy() applied to a dataset returns a transient, modifiable -Quincey> > copy of that dataset's data type. -Quincey> > -Quincey> > * H5Topen() applied to a dataset returns either a transient -Quincey> > immutable or named immutable data type depending on whether the -Quincey> > dataset has a shared data type. -Quincey> Hmm, do we want to allow this? It makes a certain amount of sense, but -Quincey> is a little unusual... :-) -Quincey> - -Elena, we decided not not to allow H5Topen() on a dataset. - -Quincey> -Quincey> > * The H5Tshare() and H5Tis_shared() will be removed. Data types -Quincey> > will not be stored in the global heap. A new type of shared -Quincey> > message header will be added to the object headers that points to -Quincey> > another object header instead of the global heap -Quincey> -Quincey> > * Still to discuss: Attributes on named data types? -Quincey> I think we should all them. -Quincey> - -Elena, attributes work for named data types just like they do for -datasets. - -Quincey> -Quincey> > * Still to discuss: compound types whose members point to other types. -Quincey> I like this concept a lot and this we should figure out a way to do it. -Quincey> This allows the "is a" relationship to be used very nicely for named datatypes. -Quincey> -Quincey> > * Still to discuss: datasets that point to data types in other -Quincey> > files by symbolic link. -Quincey> Probably a good idea also, just ugly to implement. -Quincey> - -</pre> -<hr> -<hr> - - - - +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +H5T +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> <hr> <address> -<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> -<br> -<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 9 July 1998 +Last modified: 14 July 1998 </body> </html> |