diff options
Diffstat (limited to 'doc/html/RM_H5T.html')
| -rw-r--r-- | doc/html/RM_H5T.html | 1755 |
1 files changed, 1755 insertions, 0 deletions
diff --git a/doc/html/RM_H5T.html b/doc/html/RM_H5T.html new file mode 100644 index 0000000..0fa5926 --- /dev/null +++ b/doc/html/RM_H5T.html @@ -0,0 +1,1755 @@ +<html> +<head><title> +HDF5/H5T Draft API Specification +</title></head> + +<body> + +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +H5T +<a href="RM_H5Z.html">H5Z</a> +<a href="Glossary.html">Glossary</a> +</center> +<hr> + +<center> +<h1>H5T: Datatype Interface</h1> +</center> + +<h2>Datatype Object API Functions</h2> + +These functions create and manipulate the datatype which describes elements +of a dataset. + +<table border=0> +<tr><td valign=top> +<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-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> + <li><a href="#Datatype-GetOrder">H5Tget_order</a> + <li><a href="#Datatype-SetOrder">H5Tset_order</a> + <li><a href="#Datatype-GetPrecision">H5Tget_precision</a> + <li><a href="#Datatype-SetPrecision">H5Tset_precision</a> + <li><a href="#Datatype-GetOffset">H5Tget_offset</a> + <li><a href="#Datatype-SetOffset">H5Tset_offset</a> +</td><td> </td><td valign=top> + <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> + <li><a href="#Datatype-GetFields">H5Tget_fields</a> + <li><a href="#Datatype-SetFields">H5Tset_fields</a> + <li><a href="#Datatype-GetEbias">H5Tget_ebias</a> + <li><a href="#Datatype-SetEbias">H5Tset_ebias</a> + <li><a href="#Datatype-GetNorm">H5Tget_norm</a> + <li><a href="#Datatype-SetNorm">H5Tset_norm</a> + <li><a href="#Datatype-GetInpad">H5Tget_inpad</a> + <li><a href="#Datatype-SetInpad">H5Tset_inpad</a> + <li><a href="#Datatype-GetCset">H5Tget_cset</a> + <li><a href="#Datatype-SetCset">H5Tset_cset</a> + <li><a href="#Datatype-GetStrpad">H5Tget_strpad</a> + <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> + <li><a href="#Datatype-GetMemberDims">H5Tget_member_dims</a> + <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> +</td></tr> +</table> + +<p> +The Datatype interface, H5T, provides a mechanism to describe the + storage format of individual data points of a data set and is + hopefully designed in such a way as to allow new features to be + easily added without disrupting applications that use the data + type interface. A dataset (the H5D interface) is composed of a + collection or raw data points of homogeneous type organized + according to the data space (the H5S interface). + +<p> +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 + 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 datatype interface + level; all other classes are compound. + +<p> +See <a href="Datatypes.html"><cite>The Datatype Interface (H5T)</cite></a> +in the <cite>HDF5 User's Guide</cite> for further information. + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Open">H5Topen</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> + ) +<dt><strong>Purpose:</strong> + <dd>Opens a named datatype. +<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. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>A file or group identifier. + <dt><em>const char *</em> <code>name</code> + <dd>A datatype name. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a named datatype identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Commit">H5Tcommit</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em><code>H5Tcommit</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em> <code>name</code>, + <em>hid_t</em> <code>type</code> + ) +<dt><strong>Purpose:</strong> + <dd>Commits a transient datatype to a file, creating a new named datatype. +<dt><strong>Description:</strong> + <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> + <dd>A file or group identifier. + <dt><em>const char *</em> <code>name</code> + <dd>A datatype name. + <dt><em>hid_t</em> <code>type</code> + <dd>A datatype identifier. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Committed">H5Tcommitted</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t</em><code>H5Tcommitted</code>(<em>hid_t</em> <code>type</code>) +<dt><strong>Purpose:</strong> + <dd>Determines whether a datatype is a named type or a transient type. +<dt><strong>Description:</strong> + <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 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>The successful return values are TRUE if committed, else FALSE. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-InsertArray">H5Tinsert_array</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em><code>H5Tinsert_array</code>(<em>hid_t</em> <code>parent_id</code>, + <em>const char *</em><code>name</code>, + <em>size_t</em> <code>offset</code>, + <em>int</em> <code>ndims</code>, + <em>const size_t *</em><code>dim</code>, + <em>const int *</em><code>perm</code>, + <em>hid_t</em> <code>member_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Adds an array member to a compound datatype. +<dt><strong>Description:</strong> + <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 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><em>hid_t</em> <code>parent_id</code> + <dd>Identifier of the parent compound datatype. + <dt><em>const char *</em><code>name</code> + <dd>Name of new member. + <dt><em>size_t</em> <code>offset</code> + <dd>Offset to start of new member within compound datatype. + <dt><em>int</em> <code>ndims</code> + <dd>Dimensionality of new member. + <dt><em>const size_t *</em><code>dim</code> + <dd>Size of new member array. + <dt><em>const int *</em><code>perm</code> + <dd>Pointer to buffer to store the permutation vector of + the field. + <dt><em>hid_t</em> <code>member_id</code> + <dd>Identifier of the datatype of the new member. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</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>Identifier for the source datatype. + <dt><em>hid_t</em> <code>dst_id</code> + <dd>Identifier for the destination datatype. + <dt><em>H5T_cdata_t **</em><code>pcdata</code> + <dd>Pointer to type conversion data. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a pointer to a suitable conversion function if successful. + Otherwise returns NULL. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Convert">H5Tconvert</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tconvert</code>(<em>hid_t</em> <code>src_id</code>, + <em>hid_t</em> <code>dst_id</code>, + <em>size_t</em> <code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>background</code> + ) +<dt><strong>Purpose:</strong> + <dd>Converts data from between specified datatypes. +<dt><strong>Description:</strong> + <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. + The optional background buffer is an array of <code>nelmts</code> + values of destination type which are merged with the converted + values to fill in cracks (for instance, <code>background</code> + might be an array of structs with the <code>a</code> and + <code>b</code> fields already initialized and the conversion + of <code>buf</code> supplies the <code>c</code> and <code>d</code> + field values). +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>src_id</code> + <dd>Identifier for the source datatype. + <dt><em>hid_t</em> <code>dst_id</code> + <dd>Identifier for the destination datatype. + <dt><em>size_t</em> <code>nelmts</code> + <dd>Size of array <code>buf</code>. + <dt><em>void *</em><code>buf</code> + <dd>Array containing pre- and post-conversion values. + <dt><em>void *</em><code>background</code> + <dd>Optional background buffer. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</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. +</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 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 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 FAIL (-1). +</dl> + + +<hr> +<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>) +<dt><strong>Purpose:</strong> + <dd>Copies an existing datatype. +<dt><strong>Description:</strong> + <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' + <dt>H5T_NATIVE_UCHAR + <dd> Native unsigned character type, declare dataset array as 'unsigned char' + <dt>H5T_NATIVE_SHORT + <dd> Native short type, declare dataset array as 'short' + <dt>H5T_NATIVE_USHORT + <dd> Native unsigned short type, declare dataset array as 'unsigned short' + <dt>H5T_NATIVE_INT + <dd> Native int type, declare dataset array as 'int' + <dt>H5T_NATIVE_UINT + <dd> Native unsigned int type, declare dataset array as 'unsigned int' + <dt>H5T_NATIVE_LONG + <dd> Native long type, declare dataset array as 'unsigned long' + <dt>H5T_NATIVE_ULONG + <dd> Native unsigned long type, declare dataset array as 'unsigned long' + <dt>H5T_NATIVE_LLONG + <dd> Native long long type, declare dataset array as 'unsigned long long' + <dt>H5T_NATIVE_ULLONG + <dd> Native unsigned long long type, declare dataset array as 'unsigned long long' + <dt>H5T_NATIVE_INT8 + <dd> Native signed 8-bit type, declare dataset array as 'int8' + <dt>H5T_NATIVE_UINT8 + <dd> Native unsigned 8-bit type, declare dataset array as 'uint8' + <dt>H5T_NATIVE_INT16 + <dd> Native signed 16-bit type, declare dataset array as 'int16' + <dt>H5T_NATIVE_UINT16 + <dd> Native unsigned 16-bit type, declare dataset array as 'uint16' + <dt>H5T_NATIVE_INT32 + <dd> Native signed 32-bit type, declare dataset array as 'int32' + <dt>H5T_NATIVE_UINT32 + <dd> Native unsigned 32-bit type, declare dataset array as 'uint32' + <dt>H5T_NATIVE_INT64 + <dd> Native signed 64-bit type, declare dataset array as 'uint64' + <dt>H5T_NATIVE_UINT64 + <dd> Native unsigned 64-bit type, declare dataset array as 'uint64' + <dt>H5T_NATIVE_FLOAT + <dd> Native single-precision float type, declare dataset array as 'float' + <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>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>Returns a datatype identifier if successful; + otherwise FAIL (-1) +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Equal">H5Tequal</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_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>Determines whether two datatype identifiers refer to the same datatype. +<dt><strong>Description:</strong> + <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_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>When successful, returns TRUE if the datatype identifiers + refer to the same datatype, else FALSE. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Lock">H5Tlock</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tlock</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Locks a datatype. +<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-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>Identifier of datatype to lock. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetClass">H5Tget_class</a> +<dt><strong>Signature:</strong> + <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 datatype class identifier. +<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> (<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>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns datatype class identifier if successful; + otherwise H5T_NO_CLASS (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetSize">H5Tget_size</a> +<dt><strong>Signature:</strong> + <dd><em>size_t </em><code>H5Tget_size</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns the size of a datatype. +<dt><strong>Description:</strong> + <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 query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the size of the datatype in bytes if successful; + otherwise 0. +</dl> + + +<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 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 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 datatypes 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetOrder">H5Tget_order</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_order_t </em><code>H5Tget_order</code>(<em>hid_t </em><code>type_id</code> + ) +<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. + <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 byte order constant if successful; + otherwise <code>H5T_ORDER_ERROR</code> (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetOrder">H5Tset_order</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> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the byte ordering of an atomic 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> +<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. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetPrecision">H5Tget_precision</a> +<dt><strong>Signature:</strong> + <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 datatype. +<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(). +<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. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetPrecision">H5Tset_precision</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> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the precision of an atomic 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. +<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. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetOffset">H5Tget_offset</a> +<dt><strong>Signature:</strong> + <dd><em>size_t </em><code>H5Tget_offset</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the bit offset of the first significant bit. +<dt><strong>Description:</strong> + <dd><code>H5Tget_offset</code> retrieves the bit offset of the first significant bit. + The signficant 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 layed 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 query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a positive offset value if successful; + otherwise 0. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetOffset">H5Tset_offset</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> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the bit offset of the first significant bit. +<dt><strong>Description:</strong> + <dd><code>H5Tset_offset</code> sets the bit offset of the first significant bit. The + signficant 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 layed 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_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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetPad">H5Tget_pad</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> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the padding type of the least and most-significant bit padding. +<dt><strong>Description:</strong> + <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 (<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>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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetPad">H5Tset_pad</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> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the least and most-significant bits padding types. +<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> +<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. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetSign">H5Tget_sign</a> +<dt><strong>Signature:</strong> + <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 sign type for an integer type. +<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> +<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 sign type if successful; + otherwise <code>H5T_SGN_ERROR</code> (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetSign">H5Tset_sign</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> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the sign proprety for an integer type. +<dt><strong>Description:</strong> + <dd><code>H5Tset_sign</code> sets the sign proprety 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>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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetFields">H5Tget_fields</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>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>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 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>IN: Identifier of datatype to query. + <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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetFields">H5Tset_fields</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>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 locations and sizes of floating point bit fields. +<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. +<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>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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetEbias">H5Tget_ebias</a> +<dt><strong>Signature:</strong> + <dd><em>size_t </em><code>H5Tget_ebias</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the exponent bias of a floating-point type. +<dt><strong>Description:</strong> + <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 the bias if successful; + otherwise 0. +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetEbias">H5Tset_ebias</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> + ) +<dt><strong>Purpose:</strong> + <dd>Sets the exponent bias of a floating-point type. +<dt><strong>Description:</strong> + <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>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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetNorm">H5Tget_norm</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_norm_t </em><code>H5Tget_norm</code>(<em>hid_t </em><code>type_id</code> + ) +<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 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_id</code> + <dd>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a valid normalization type if successful; + otherwise <code>H5T_NORM_ERROR</code> (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetNorm">H5Tset_norm</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> + ) +<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 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_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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetInpad">H5Tget_inpad</a> +<dt><strong>Signature:</strong> + <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 internal padding type for unused bits in floating-point datatypes. +<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> +<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). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetInpad">H5Tset_inpad</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> + ) +<dt><strong>Purpose:</strong> + <dd>Fills unused internal floating point bits. +<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> +<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. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetCset">H5Tget_cset</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_cset_t </em><code>H5Tget_cset</code>(<em>hid_t </em><code>type_id</code> + ) +<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 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 query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a valid character set type if successful; + otherwise <code>H5T_CSET_ERROR</code> (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetCset">H5Tset_cset</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> + ) +<dt><strong>Purpose:</strong> + <dd>Sets character set to be used. +<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> +<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. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetStrpad">H5Tget_strpad</a> +<dt><strong>Signature:</strong> + <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 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 types are: + <ul> <dl> + <dt>H5T_STR_NULL (<code>0</code>) + <dd>Pad with zeros (as C does) + <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>Identifier of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a valid string padding type if successful; + otherwise <code>H5T_STR_ERROR</code> (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetStrpad">H5Tset_strpad</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> + ) +<dt><strong>Purpose:</strong> + <dd>Defines the storage mechanism for character strings. +<dt><strong>Description:</strong> + <dd>The method used to store character strings differs with the + programming language: C usually null terminates strings while + Fortran left-justifies and space-pads strings. + <code>H5Tset_strpad</code> defines the storage mechanism for the string. + Valid string padding values are: + <ul> <dl> + <dt>H5T_STR_NULL (<code>0</code>) + <dd>Pad with zeros (as C does) + <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>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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetNmembers">H5Tget_nmembers</a> +<dt><strong>Signature:</strong> + <dd><em>intn </em><code>H5Tget_nmembers</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the number of fields in a compound datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tget_nmembers</code> retrieves the number of fields a compound datatype has. +<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 number of members datatype has if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<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>int</em> <code>field_idx</code> + ) +<dt><strong>Purpose:</strong> + <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 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>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>Returns a valid pointer if successful; + otherwise NULL. +</dl> + + +<hr> +<dl> +<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>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. +<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 <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. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the number of dimensions, a number from 0 to 4, + if successful. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> +<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>int</em> <code>field_idx</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns the datatype of the specified member. +<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. +<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. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the identifier of a copy of the datatype of the field + if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Insert">H5Tinsert</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>off_t</em> <code>offset</code>, + <em>hid_t</em> <code>field_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Adds a new member to a compound 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: 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>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 identifier of the field to insert. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Pack">H5Tpack</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tpack</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Recursively removes padding from within a compound datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tpack</code> recursively removes padding from within a compound + datatype to make it more efficient (space-wise) to store that data. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to modify. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-RegisterHard">H5Tregister_hard</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tregister_hard</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>H5T_conv_t</em> <code>func</code> + ) +<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 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 + 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: + <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>Identifier of source datatype. + <dt><em>hid_t</em> <code>dst_id</code> + <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>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<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>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> + <dd>Registers a soft conversion function. +<dt><strong>Description:</strong> + <dd><code>H5Tregister_soft</code> registers a soft conversion function by adding it to the + end of the master soft list and replacing the soft function in all + 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: + <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>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>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<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 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>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<center> +<a href="RM_H5Front.html">HDF5 Reference Manual</a> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +<a href="RM_H5E.html">H5E</a> +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<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:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> + +<br> +Last modified: 14 July 1998 + +</body> +</html> |