|
Introduction to HDF5 HDF5 User Guide Other HDF5 documents and links |
And in this document, the
HDF5 Reference Manual
H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |
The C Interfaces:
|
General Datatype Operations
Conversion Functions |
Atomic Datatype Properties
Enumeration Datatypes |
Compound Datatype Properties
Array Datatypes Variable-length Datatypes Opaque Datatypes |
The FORTRAN90 Interfaces:
In general, each FORTRAN90 subroutine performs exactly the same task
as the corresponding C function. The links below go to the C function
descriptions, which serve as general descriptions for both. A button,
under Non-C API(s) at the end of the C function description,
opens an external browser window displaying the FORTRAN90-specific
information. You will probably want to adjust the size and location of
this external window so that both browser windows are visible and to
facilitate moving easily between them.
|
General Datatype Operations
Atomic Datatype Properties |
Atomic (continued)
|
Compound Datatype Properties
Enumeration Datatypes Opaque Datatypes |
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).
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.
A data point is an instance of a datatype, which is an instance of a type class. 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.
See The Datatype Interface (H5T) in the HDF5 User's Guide for further information, including a complete list of all supported datatypes.
H5Topen(hid_t loc_id,
const char * name
)
H5Topen opens a named datatype at the location
specified by loc_id and returns an identifier
for the datatype. loc_id is either a file or
group identifier. The identifier should eventually be closed
by calling H5Tclose() to release resources.
loc_id
name
loc_id.
H5Tcommit(hid_t loc_id,
const char * name,
hid_t type
)
H5Tcommit commits a transient datatype
(not immutable) to a file, turned it into a named datatype.
The loc_id is either a file or group identifier
which, when combined with name, refers to a new
named datatype.
loc_id
name
type
H5Tcommitted(hid_t type)
H5Tcommitted queries a type to determine whether
the type specified by the type 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 H5Dget_type() are
able to share the datatype with other datasets in the same file.
type
TRUE,
if the datatype has been committed, or 0 (zero),
for FALSE, if the datatype has not been committed.
Otherwise returns a negative value.
H5Tfind(hid_t src_id,
hid_t dst_id,
H5T_cdata_t **pcdata
)
H5Tfind finds a conversion function that can
handle a conversion from type src_id to type
dst_id.
The pcdata 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.
src_id
dst_id
pcdata
H5Tconvert(hid_t src_id,
hid_t dst_id,
hsize_t nelmts,
void *buf,
void *background,
hid_t plist_id
)
H5Tconvert converts nelmts elements
from the type specified by the src_id identifier
to type dst_id.
The source elements are packed in buf and on return
the destination will be packed in buf.
That is, the conversion is performed in place.
The optional background buffer is an array of nelmts
values of destination type which are merged with the converted
values to fill in cracks (for instance, background
might be an array of structs with the a and
b fields already initialized and the conversion
of buf supplies the c and d
field values).
The parameter plist_id contains the dataset transfer
property list identifier which is passed to the conversion functions.
As of Release 1.2, this parameter is only used to pass along the
variable-length datatype custom allocation information.
src_id
dst_id
nelmts
buf.
buf
background
plist_id
H5Tset_overflow(H5T_overflow_t func)
H5Tset_overflow sets the overflow handler
to be the function specified by func.
func will be called for all datatype conversions that
result in an overflow.
See the definition of H5T_overflow_t in
H5Tpublic.h for documentation
of arguments and return values.
The prototype for H5T_overflow_t is as follows:
herr_t (*H5T_overflow_t)(hid_t src_id, hid_t dst_id,
void *src_buf, void *dst_buf);
The NULL pointer may be passed to remove the overflow handler.
func
H5Tget_overflow(void)
H5Tset_overflow 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.
H5Tcreate(H5T_class_t class,
size_tsize
)
H5Tcreate creates a new dataype of the specified
class with the specified number of bytes.
The following datatype classes are supported with this function:
H5T_COMPOUND
H5T_OPAQUE
H5T_ENUM
Use H5Tcopy to create integer or floating-point datatypes.
The datatype identifier returned from this function should be
released with H5Tclose or resource leaks will result.
class
size
H5Tvlen_create(hid_t base_type_id
)
H5Tvlen_create creates a new variable-length (VL) dataype.
The base datatype will be the datatype that the sequence is composed of, characters for character strings, vertex coordinates for polygon lists, etc. The base type specified for the VL datatype can be of any HDF5 datatype, including another VL datatype, a compound datatype or an atomic datatype.
When necessary, use H5Tget_super to determine the base type
of the VL datatype.
The datatype identifier returned from this function should be
released with H5Tclose or resource leaks will result.
base_type_id
H5Tcopy(hid_t type_id)
H5Tcopy copies an existing datatype.
The returned type is always transient and unlocked.
The type_id argument can be either a datatype
identifier, a predefined datatype (defined in
H5Tpublic.h), or a dataset identifier.
If type_id 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.
The datatype identifier returned should be released with
H5Tclose or resource leaks will occur.
type_id
H5Tpublic.h), or a dataset identifier.
H5Tequal(hid_t type_id1,
hid_ttype_id2
)
H5Tequal determines whether two datatype identifiers
refer to the same datatype.
type_id1
type_id2
TRUE,
if the datatype identifiers refer to the same datatype,
or 0 (zero), for FALSE.
Otherwise returns a negative value.
H5Tlock(hid_t type_id
)
H5Tlock locks the datatype specified by the
type_id 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.
type_id
H5Tget_class(hid_t type_id
)
H5Tget_class returns the datatype class identifier.
Valid class identifiers, as defined in H5Tpublic.h, are:
H5T_INTEGER
H5T_FLOAT
H5T_TIME
H5T_STRING
H5T_BITFIELD
H5T_OPAQUE
H5T_COMPOUND
H5T_REFERENCE
H5T_ENUM
H5T_VLEN
H5T_ARRAY
type_id
H5T_NO_CLASS (-1).
H5Tget_size(hid_t type_id
)
H5Tget_size returns the size of a datatype in bytes.
type_id
H5Tset_size(hid_t type_id,
size_tsize
)
H5Tset_size sets the total size in bytes,
size, 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.
type_id
size
H5Tget_super(hid_t type
)
H5Tget_super returns the base datatype from which the
datatype type is derived.
In the case of an enumeration type, the return value is an integer type.
type
H5Tget_order(hid_t type_id
)
H5Tget_order returns the byte order of an
atomic datatype.
Possible return values are:
H5T_ORDER_LE (0)
H5T_ORDER_BE (1)
H5T_ORDER_VAX (2)
type_id
H5T_ORDER_ERROR (-1).
H5Tset_order(hid_t type_id,
H5T_order_torder
)
H5Tset_order sets the byte ordering of an atomic datatype.
Byte orderings currently supported are:
0)
1)
2)
type_id
order
H5Tget_precision(hid_t type_id
)
H5Tget_precision 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().
type_id
H5Tset_precision(hid_t type_id,
size_tprecision
)
H5Tset_precision 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().
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.
Changing the precision of an H5T_STRING automatically changes the size as well. The precision must be a multiple of 8.
When decreasing the precision of a floating point type, set the locations and sizes of the sign, mantissa, and exponent fields first.
type_id
precision
H5Tget_offset(hid_t type_id
)
H5Tget_offset 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):
| Byte Position | Big-Endian Offset=0 | Big-Endian Offset=16 | Little-Endian Offset=0 | Little-Endian Offset=16 |
|---|---|---|---|---|
| 0: | [ pad] | [0x11] | [0x22] | [ pad] |
| 1: | [ pad] | [0x22] | [0x11] | [ pad] |
| 2: | [0x11] | [ pad] | [ pad] | [0x22] |
| 3: | [0x22] | [ pad] | [ pad] | [0x11] |
type_id
H5Tset_offset(hid_t type_id,
size_t offset
)
H5Tset_offset 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):
| Byte Position | Big-Endian Offset=0 | Big-Endian Offset=16 | Little-Endian Offset=0 | Little-Endian Offset=16 |
|---|---|---|---|---|
| 0: | [ pad] | [0x11] | [0x22] | [ pad] |
| 1: | [ pad] | [0x22] | [0x11] | [ pad] |
| 2: | [0x11] | [ pad] | [ pad] | [0x22] |
| 3: | [0x22] | [ pad] | [ pad] | [0x11] |
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.
The offset of an H5T_STRING cannot be set to anything but zero.
type_id
offset
H5Tget_pad(hid_t type_id,
H5T_pad_t * lsb,
H5T_pad_t * msb
)
H5Tget_pad retrieves the padding type of the least and most-significant
bit padding. Valid types are:
0)
1)
2)
type_id
lsb
msb
H5Tset_pad(hid_t type_id,
H5T_pad_t lsb,
H5T_pad_t msb
)
H5Tset_pad sets the least and most-significant bits padding types.
0)
1)
2)
type_id
lsb
msb
H5Tget_sign(hid_t type_id
)
H5Tget_sign retrieves the sign type for an integer type.
Valid types are:
0)
1)
type_id
H5T_SGN_ERROR (-1).
H5Tset_sign(hid_t type_id,
H5T_sign_t sign
)
H5Tset_sign sets the sign proprety for an integer type.
0)
1)
type_id
sign
H5Tget_fields(hid_t type_id,
size_t *spos,
size_t *epos,
size_t *esize,
size_t *mpos,
size_t *msize
)
H5Tget_fields 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.
type_id
spos
epos
esize
mpos
msize
H5Tset_fields(hid_t type_id,
size_t spos,
size_t epos,
size_t esize,
size_t mpos,
size_t msize
)
H5Tset_fields 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.
Fields are not allowed to extend beyond the number of bits of precision, nor are they allowed to overlap with one another.
type_id
spos
epos
esize
mpos
msize
H5Tget_ebias(hid_t type_id
)
H5Tget_ebias retrieves the exponent bias of a floating-point type.
type_id
H5Tset_ebias(hid_t type_id,
size_t ebias
)
H5Tset_ebias sets the exponent bias of a floating-point type.
type_id
ebias
H5Tget_norm(hid_t type_id
)
H5Tget_norm retrieves the mantissa normalization of
a floating-point datatype. Valid normalization types are:
0)
1)
2)
type_id
H5T_NORM_ERROR (-1).
H5Tset_norm(hid_t type_id,
H5T_norm_t norm
)
H5Tset_norm sets the mantissa normalization of
a floating-point datatype. Valid normalization types are:
0)
1)
2)
type_id
norm
H5Tget_inpad(hid_t type_id
)
H5Tget_inpad retrieves the internal padding type for
unused bits in floating-point datatypes.
Valid padding types are:
0)
1)
2)
type_id
H5T_PAD_ERROR (-1).
H5Tset_inpad(hid_t type_id,
H5T_pad_t inpad
)
H5Tset_inpad will be filled
according to the value of the padding value property inpad.
Valid padding types are:
0)
1)
2)
type_id
pad
H5Tget_cset(hid_t type_id
)
H5Tget_cset retrieves the character set type
of a string datatype. Valid character set types are:
0)
type_id
H5T_CSET_ERROR (-1).
H5Tset_cset(hid_t type_id,
H5T_cset_t cset
)
H5Tset_cset the character set to be used.
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:
0)
type_id
cset
H5Tget_strpad(hid_t type_id
)
H5Tget_strpad retrieves the storage mechanism
for a string datatype, as defined in
H5Tset_strpad.
type_id
H5T_STR_ERROR (-1).
H5Tset_strpad(hid_t type_id,
H5T_str_t strpad
)
H5Tset_strpad defines the storage mechanism for the string.
The method used to store character strings differs with the programming language:
strpad, are as follows:
0)
1)
2)
When converting from a longer string to a shorter string,
the behavior is as follows.
If the short string is H5T_STR_NULLPAD or
H5T_STR_SPACEPAD, then the string is simply truncated.
If the short string is H5T_STR_NULLTERM, it is
truncated and a null terminator is appended.
When converting from a shorter string to a longer string, the long string is padded on the end by appending nulls or spaces.
type_id
strpad
H5Tget_nmembers(hid_t type_id
)
H5Tget_nmembers retrieves the number of fields a compound datatype has.
type_id
H5Tget_member_class(
hid_t cdtype_id,
int member_no
)
cdtype_id, the function
H5Tget_member_class returns the datatype class of
the compound datatype member specified by member_no.
cdtype_id
member_no
H5Tget_member_name(hid_t type_id,
int field_idx
)
H5Tget_member_name 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 H5Tget_nmembers(). The name of the field is
allocated with malloc() and the caller is responsible
for freeing the memory used by the name.
type_id
field_idx
H5Tget_member_offset(hid_t type_id,
int memb_no
)
H5Tget_member_offset retrieves the
byte offset of the beginning of a field within a
compound datatype with respect to the beginning
of the compound data type datum.
type_id
memb_no
0 (zero).
Note that zero is a valid offset and that this function
will fail only if a call to H5Tget_member_class()
fails with the same arguments.
H5Tget_member_type(hid_t type_id,
int field_idx
)
H5Tget_member_type returns the datatype of the specified member. The caller
should invoke H5Tclose() to release resources associated with the type.
type_id
field_idx
H5Tinsert(hid_t type_id,
const char * name,
size_t offset,
hid_t field_id
)
H5Tinsert adds another member to the compound datatype
type_id. The new member has a name which
must be unique within the compound datatype.
The offset argument defines the start of the member
in an instance of the compound datatype, and field_id
is the datatype identifier of the new member.
Note: Members of a compound datatype do not have to be atomic datatypes; a compound datatype can have a member which is a compound datatype.
type_id
name
offset
field_id
H5Tpack(hid_t type_id
)
H5Tpack recursively removes padding from within a compound
datatype to make it more efficient (space-wise) to store that data.
type_id
H5Tregister(H5T_pers_t pers,
const char * name,
hid_t src_id,
hid_t dst_id,
H5T_conv_t func
)
H5Tregister registers a hard or soft conversion function
for a datatype conversion path.
The parameter pers indicates whether a conversion function
is hard (H5T_PERS_HARD)
or soft (H5T_PERS_SOFT).
A conversion path can have only one hard function.
When pers is H5T_PERS_HARD,
func replaces any previous hard function.
If pers is H5T_PERS_HARD and
func is the null pointer, then any hard function
registered for this path is removed.
When pers is H5T_PERS_SOFT,
H5Tregister
adds the function to the end of the master soft list and replaces
the soft function in all applicable existing conversion paths.
Soft functions are used when determining which conversion function
is appropriate for this path.
The name is used only for debugging and should be a
short identifier for the function.
The path is specified by the source and destination datatypes
src_id and dst_id.
For soft conversion functions, only the class of these types is important.
The type of the conversion function pointer is declared as:
typedefherr_t (*H5T_conv_t) (hid_tsrc_id, hid_tdst_id, H5T_cdata_t *cdata, hsize_tnelmts, size_tbuf_stride, size_tbkg_stride, void *buf, void *bkg, hid_tdset_xfer_plist)
The H5T_cdata_t struct is declared as:
typedefstruct*H5T_cdata_t(H5T_cmd_tcommand, H5T_bkg_tneed_bkg, hbool_t *recalc, void *priv)
The H5T_conv_t parameters and
the elements of the H5T_cdata_t struct
are described more fully in the
“Data Conversion”
section of “The Datatype Interface (H5T)”
in the HDF5 User's Guide.
pers
H5T_PERS_HARD for hard conversion functions;
H5T_PERS_SOFT for soft conversion functions.
name
src_id
dst_id
func
H5Tunregister(H5T_conv_t func
)
H5Tunregister removes a conversion function from all conversion paths.
The conversion function pointer type declaration is described in H5Tregister.
func
H5Tenum_create(hid_t parent_id
)
H5Tenum_create creates a new enumeration datatype
based on the specified base datatype, parent_id,
which must be an integer type.
parent_id
H5Tenum_insert(hid_t type,
const char *name,
void *value
)
H5Tenum_insert inserts a
new enumeration datatype member into an enumeration datatype.
type is the enumeration datatype,
name is the name of the new member, and
value points to the value of the new member.
name and value must both
be unique within type.
value points to data which is of the
datatype defined when the enumeration datatype was created.
type
name
value
H5Tenum_nameof(hid_t type
void *value,
char *name,
size_t size
)
H5Tenum_nameof finds the symbol name that
corresponds to the specified value
of the enumeration datatype type.
At most size characters of the symbol
name are copied into the name buffer.
If the entire symbol name and null terminator
do not fit in the name buffer, then as
many characters as possible are copied
(not null terminated) and the function fails.
type
value,
name,
size
size allows it,
the first character of name is
set to NULL.
H5Tenum_valueof(hid_t type
char *name,
void *value
)
H5Tenum_valueof finds the value that
corresponds to the specified name
of the enumeration datatype type.
The value argument should be at least
as large as the value of H5Tget_size(type)
in order to hold the result.
type
name,
value,
H5Tget_member_value(hid_t type
int memb_no,
void *value
)
H5Tget_member_value returns the value of
the enumeration datatype member memb_no.
The member value is returned in a user-supplied buffer
pointed to by value.
type
memb_no,
value
H5Tset_tag(hid_t type_id
const char *tag
)
H5Tset_tag tags an opaque datatype type_id
with a unique ASCII identifier tag.
type_id
tag
H5Tget_tag(hid_t type_id
)
H5Tget_tag returns the tag associated with
the opaque datatype type_id.
The tag is returned via a pointer to an allocated string, which the caller must free.
type_id
NULL.
H5Tarray_create(
hid_t base,
int rank,
const hsize_t dims[/*rank*/],
const int perm[/*rank*/]
)
H5Tarray_create creates a new array datatype object.
base is the datatype of every element of the array,
i.e., of the number at each position in the array.
rank is the number of dimensions and the
size of each dimension is specified in the array dims.
The value of rank is currently limited to
H5S_MAX_RANK and must be greater than 0
(zero).
All dimension sizes specified in dims must be greater
than 0 (zero).
The array perm is designed to contain the dimension
permutation, i.e. C versus FORTRAN array order.
(The parameter perm is currently unused and is not yet implemented.)
base
rank
dims[/*rank*/]
perm[/*rank*/]
H5Tget_array_ndims(
hid_t adtype_id
)
H5Tget_array_ndims returns the rank,
the number of dimensions, of an array datatype object.
adtype_id
H5Tget_array_dims(
hid_t adtype_id,
hsize_t *dims[],
int *perm[]
)
H5Tget_array_dims returns the sizes of the dimensions
and the dimension permutations of the specified array datatype object.
The sizes of the dimensions are returned in the array dims.
The dimension permutations, i.e., C versus FORTRAN array order,
are returned in the array perm.
adtype_id
dims[]
perm[]
H5Tclose(hid_t type_id
)
H5Tclose releases a datatype. Further access
through the datatype identifier is illegal. Failure to release
a datatype with this call will result in resource leaks.
type_id
|
Introduction to HDF5 HDF5 User Guide Other HDF5 documents and links |
And in this document, the
HDF5 Reference Manual
H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |