hdf5/doc/html/RM_H5T.html
Frank Baker c8e75d27b0 [svn-r503] HDF5 Reference Manual
Updated for Alpha2.
1998-07-14 23:51:50 -05:00

1756 lines
66 KiB
HTML

<html>
<head><title>
HDF5/H5T Draft API Specification
</title></head>
<body>
<hr>
<center>
<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;
<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
<a href="RM_H5E.html">H5E</a>&nbsp;&nbsp;
<a href="RM_H5F.html">H5F</a>&nbsp;&nbsp;
<a href="RM_H5G.html">H5G</a>&nbsp;&nbsp;
<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
<a href="RM_H5S.html">H5S</a>&nbsp;&nbsp;
H5T&nbsp;&nbsp;
<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
<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>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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>&nbsp;
<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
<a href="RM_H5E.html">H5E</a>&nbsp;&nbsp;
<a href="RM_H5F.html">H5F</a>&nbsp;&nbsp;
<a href="RM_H5G.html">H5G</a>&nbsp;&nbsp;
<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
<a href="RM_H5S.html">H5S</a>&nbsp;&nbsp;
H5T&nbsp;&nbsp;
<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
<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>