The C Interfaces:
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 “HDF5 Datatypes” in the HDF5 User’s Guide for more information.
Last modified: 25 September 2012 |
As the term implies, variable-length strings are strings of varying lengths; they can be arbitrarily long, anywhere from 1 character to thousands of characters.
HDF5 provides the ability to create a variable-length string datatype.
Like all string datatypes, this type is based on the
atomic string datatype:
H5T_C_S1
in C or
H5T_FORTRAN_S1
in Fortran.
While these datatypes default to one character in size,
they can be resized to specific fixed lengths
or to variable length.
Variable-length strings will transparently accommodate ASCII strings
or UTF-8 strings. This characteristic is set with
H5Tset_cset
in the process of creating the datatype.
The following HDF5 calls create a
C-style variable-length string datatype,
vls_type_c_id
:
vls_type_c_id = H5Tcopy(H5T_C_S1) status = H5Tset_size(vls_type_c_id, H5T_VARIABLE)In a C environment, variable-length strings will always be NULL-terminated, so the buffer to hold such a string must be one byte larger than the string itself to accommodate the NULL terminator.
In Fortran, strings are normally of fixed length.
Variable-length strings come into play only when data
is shared with a C application that uses them.
For such situations, the datatype class H5T_STRING
is
predefined by the HDF5 Library to accommodate variable-length strings.
The first HDF5 call below creates a Fortran string,
vls_type_f_id
, that will handle variable-length string data.
The second call sets the string padding value to space padding:
h5tcopy_f(H5T_STRING, vls_type_f_id, hdferr) h5tset_strpad_f(vls_type_f_id, H5T_STR_SPACEPAD_F, hdferr)While Fortran-style strings are generally space-padded, they may be NULL-terminated in cases where the data is also used in a C environment.
Note: Under the covers, variable-length strings are stored in a heap, potentially impacting efficiency in the following ways:
H5Tarray_create
is a macro that is mapped to either
H5Tarray_create1
or
H5Tarray_create2
,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. For example:
H5Tarray_create
macro
will be mapped to H5Tarray_create1
and
will use the H5Tarray_create1
syntax
(first signature above)
if an application is coded for HDF5 Release 1.6.x.
H5Tarray_create
macro
mapped to H5Tarray_create2
and
will use the H5Tarray_create2
syntax
(second signature above)
if an application is coded for HDF5 Release 1.8.x.
Macro use and mappings are fully described in “API Compatibility Macros in HDF5”; we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Tarray_create
is mapped to the most recent version of
the function, currently
H5Tarray_create2
.
If the library and/or application is compiled for Release 1.6
emulation, H5Tarray_create
will be mapped to
H5Tarray_create1
.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
Compatibility setting | H5Tarray_create mapping |
---|---|
Global settings |
|
No compatibility flag | H5Tarray_create2 |
Enable deprecated symbols | H5Tarray_create2 |
Disable deprecated symbols | H5Tarray_create2 |
Emulate Release 1.6 interface | H5Tarray_create1 |
Function-level macros |
|
H5Tarray_create_vers = 2 |
H5Tarray_create2 |
H5Tarray_create_vers = 1 |
H5Tarray_create1 |
H5Tarray_create
interface
and the only interface available prior to HDF5 Release 1.8.0.
This signature and the corresponding function are now deprecated
but will remain directly callable as
H5Tarray_create1
.
Signature [2] above was introduced with HDF5 Release 1.8.0
and is the recommended and default interface.
It is directly callable as
H5Tarray_create2
.
See “API Compatibility Macros in HDF5” for circumstances under which either of these functions might not be available in an installed instance of the HDF5 Library.
SUBROUTINE h5tarray_create_f(base_id, rank, dims, type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: base_id ! Identifier of array base datatype INTEGER, INTENT(IN) :: rank ! Rank of the array INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: dims ! Sizes of each array dimension INTEGER(HID_T), INTENT(OUT) :: type_id ! Identifier of the array datatype INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tarray_create_f
Release | C |
1.8.0 | The function
H5Tarray_create renamed to
H5Tarray_create1
and deprecated in this release.
The macro H5Tarray_create
and the function H5Tarray_create2
introduced in this release. |
H5Tarray_create1
(
hid_t base_type_id
,
int rank
,
const hsize_t dims[/*rank*/]
,
const int perm[/*rank*/]
)
H5Tarray_create
and
deprecated in favor of the function
H5Tarray_create2
or the new macro
H5Tarray_create
.
H5Tarray_create1
creates a new array datatype object.
base_type_id
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.)
hid_t base_type_id |
IN: Datatype identifier for the array base datatype. |
int rank |
IN: Rank of the array. |
const hsize_t dims[/*rank*/] |
IN: Size of each array dimension. |
const int perm[/*rank*/] |
IN: Dimension permutation. (Currently not implemented.) |
SUBROUTINE h5tarray_create_f(base_id, rank, dims, type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: base_id ! Identifier of array base datatype INTEGER, INTENT(IN) :: rank ! Rank of the array INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: dims ! Sizes of each array dimension INTEGER(HID_T), INTENT(OUT) :: type_id ! Identifier of the array datatype INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tarray_create_f
Release | C |
1.4.0 | Function introduced in this release. |
1.8.0 |
Function H5Tarray_create renamed to
H5Tarray_create1 and deprecated
in this release. |
H5Tarray_create2
(
hid_t base_type_id
,
unsigned rank
,
const hsize_t dims[/*rank*/]
)
H5Tarray_create2
creates a new array datatype object.
base_type_id
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).
hid_t base_type_id |
IN: Datatype identifier for the array base datatype. |
unsigned rank |
IN: Rank of the array. |
const hsize_t dims[/*rank*/] |
IN: Size of each array dimension. |
Release | Change |
1.8.0 | C function introduced in this release. |
H5Tclose
(
hid_t dtype_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.
hid_t dtype_id |
IN: Identifier of datatype to release. |
SUBROUTINE h5tclose_f(type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tclose_f
H5Tcommit
(
hid_t loc_id
,
const char *name
,
hid_t dtype_id
)
H5Tcommit
(
hid_t loc_id
,
const char *name
,
hid_t dtype_id
,
hid_t lcpl_id
,
hid_t tcpl_id
,
hid_t tapl_id
)
H5Tcommit
is a macro that is mapped to either
H5Tcommit1
or
H5Tcommit2
,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in “API Compatibility Macros in HDF5”; we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Tcommit
is mapped to the most recent version of
the function, currently
H5Tcommit2
.
If the library and/or application is compiled for Release 1.6
emulation, H5Tcommit
will be mapped to
H5Tcommit1
.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
Compatibility setting | H5Tcommit mapping |
---|---|
Global settings |
|
No compatibility flag | H5Tcommit2 |
Enable deprecated symbols | H5Tcommit2 |
Disable deprecated symbols | H5Tcommit2 |
Emulate Release 1.6 interface |
H5Tcommit1 |
Function-level macros |
|
H5Tcommit_vers = 2 |
H5Tcommit2 |
H5Tcommit_vers = 1 |
H5Tcommit1 |
SUBROUTINE h5tcommit_f(loc_id, name, type_id, hdferr, & lcpl_id, tcpl_id, tapl_id ) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier CHARACTER(LEN=*), INTENT(IN) :: name ! Datatype name within file or group INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id ! Link creation property list INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tcpl_id ! Datatype creation property list INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tapl_id ! Datatype access property list END SUBROUTINE h5tcommit_f
Release | C |
1.8.0 |
The function H5Tcommit renamed to
H5Tcommit1 and deprecated in this release.
The macro H5Tcommit
and the function H5Tcommit2
introduced in this release. |
H5Tcommit1
(
hid_t loc_id
,
const char * name
,
hid_t dtype_id
)
H5Tcommit2
.
H5Tcommit1
commits the transient datatype
(not immutable) to a file, turning it into a named datatype.
The datatype dtype_id
is committed as a named datatype
at the location loc_id
, which is either a file or group
identifier, with the name name
.
name
can be a relative path based at loc_id
or an absolute path from the root of the file.
Use of this function requires that any intermediate groups
specified in the path already exist.
As is the case for any object in a group, the length of the name of a named datatype is not limited.
See H5Tcommit_anon
for a discussion of the differences between H5Tcommit
and H5Tcommit_anon
.
This function will not accept a datatype that cannot actually hold data. This currently includes compound datatypes with no fields and enumerated datatypes with no members.
hid_t loc_id |
IN: File or group identifier |
const char * name |
IN: Name given to committed datatype |
hid_t dtype_id |
IN: Identifier of datatype to be committed and, upon function’s return, identifier for the committed datatype |
H5Tcommit
.
Release | C |
1.8.0 |
The function H5Tcommit renamed to
H5Tcommit1 and deprecated in this release. |
1.8.7 | Function modified in this release to reject datatypes that will not accomodate actual data, such as a compound datatype with no fields or an enumerated datatype with no members. |
H5Tcommit2
(
hid_t loc_id
,
const char *name
,
hid_t dtype_id
,
hid_t lcpl_id
,
hid_t tcpl_id
,
hid_t tapl_id
)
H5Tcommit2
saves a transient datatype
as an immutable named datatype in a file.
The datatype specified by dtype_id
is committed to the file
with the name name
at the location
specified by loc_id
and with the
datatype creation and access property lists
tcpl_id
and tapl_id
,
respectively.
loc_id
may be a file identifier,
or a group identifier within that file.
name
may be either an absolute path in the file
or a relative path from loc_id
naming the
newly-commited datatype.
The link creation property list, lcpl_id
,
governs creation of the link(s) by which the new named datatype
is accessed and the creation of any intermediate groups that
may be missing.
Once commited, this datatype may be used to define the datatype of any other dataset or attribute in the file.
This function will not accept a datatype that cannot actually hold data. This currently includes compound datatypes with no fields and enumerated datatypes with no members.
hid_t loc_id
|
IN: Location identifier |
const char *name
|
IN: Name given to committed datatype |
hid_t dtype_id
|
IN: Identifier of datatype to be committed and, upon function’s return, identifier for the committed datatype |
hid_t lcpl_id
|
IN: Link creation property list |
hid_t tcpl_id
|
IN: Datatype creation property list |
hid_t tapl_id
|
IN: Datatype access property list |
H5Tcommit
.
Release | C |
1.8.0 | Function introduced in this release. |
1.8.7 | Function modified in this release to reject datatypes that will not accomodate actual data, such as a compound datatype with no fields or an enumerated datatype with no members. |
H5Tcommit_anon
(
hid_t loc_id
,
hid_t dtype_id
,
hid_t tcpl_id
,
hid_t tapl_id
)
H5Tcommit_anon
commits a transient datatype
(not immutable) to a file, turning it into a named datatype
with the specified creation and property lists.
With default property lists, H5P_DEFAULT
,
H5Tcommit_anon
provides similar functionality
to that of H5Tcommit
, with the differences
described below.
The datatype access property list identifier, tapl_id
,
is provided for future functionality and is not used at this time.
This parameter should always be passed as the value
H5P_DEFAULT
.
Note that H5Tcommit_anon
does not link this
newly-committed datatype into the file.
After the H5Tcommit_anon
call,
the datatype identifier dtype_id
must be linked into the HDF5 file structure
with H5Olink
or it will be deleted from the file when the file is closed.
The differences between this function and
H5Tcommit
are as follows:
H5Tcommit_anon
explicitly includes property
lists, which provides for greater control of the creation process
and of the properties of the new named datatype.
H5Tcommit
always uses default properties.
H5Tcommit_anon
neither provides the new
named datatype’s name nor links it into the HDF5 file
structure; those actions must be performed separately through a
call to
H5Olink
,
which offers greater control over linking.
This function will not accept a datatype that cannot actually hold data. This currently includes compound datatypes with no fields and enumerated datatypes with no members.
hid_t loc_id |
IN: A file or group identifier specifying the file in which the new named datatype is to be created. |
hid_t dtype_id |
IN: A datatype identifier. |
hid_t tcpl_id |
IN: A datatype creation property list
identifier.
( H5P_DEFAULT for the default property list.)
|
hid_t tapl_id |
IN: A datatype access property list identifier.
Currently unused; should always be passed as the value H5P_DEFAULT . |
SUBROUTINE h5tcommit_anon_f(loc_id, dtype_id, hdferr, tcpl_id, tapl_id) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: loc_id ! A file or group identifier specifying ! the file in which the new named ! datatype is to be created. INTEGER(HID_T), INTENT(IN) :: dtype_id ! Datatype identifier INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tcpl_id ! A datatype creation property ! list identifier. ! H5P_DEFAULT_F = default property list INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tapl_id ! A datatype access property list id END SUBROUTINE h5tcommit_anon_f
H5Olink
H5Tcommit
Release | C |
1.8.7 | Function modified in this release to reject datatypes that will not accomodate actual data, such as a compound datatype with no fields or an enumerated datatype with no members. |
1.8.0 | Function introduced in this release. |
H5Tcommitted
(
hid_t dtype_id
)
H5Tcommitted
queries a type to determine whether
the type specified by the dtype_id
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.
hid_t dtype_id |
IN: Datatype identifier. |
TRUE
,
if the datatype has been committed, or 0
(zero),
for FALSE
, if the datatype has not been committed.
Otherwise returns a negative value.
SUBROUTINE h5tcommitted_f(dtype_id, committed, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dtype_id ! A datatype identifier LOGICAL, INTENT(OUT) :: committed ! .TRUE., if the datatype committed ! .FALSE., if the datatype not committed. INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tcommitted_f
H5Tcompiler_conv
(hid_t
src_id
, hid_t dst_id
)
H5Tcompiler_conv
finds out whether the library’s
conversion function from type src_id
to type
dst_id
is a compiler (hard) conversion. A compiler
conversion uses compiler’s casting; a library (soft) conversion uses
the library’s own conversion function.
hid_t src_id |
IN: Identifier for the source datatype. |
hid_t dst_id |
IN: Identifier for the destination datatype. |
SUBROUTINE h5tcompiler_conv_f( src_id, dst_id, flag, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: src_id ! Id for the source datatype. INTEGER(HID_T), INTENT(IN) :: dst_id ! Id for the destination datatype. LOGICAL, INTENT(OUT) :: flag ! .TRUE. for compiler conversion, ! .FALSE. for library conversion INTEGER, INTENT(OUT) :: hdferr ! Error code: ! 0 on success and -1 on failure END SUBROUTINE h5tcompiler_conv_f
H5Tconvert
(
hid_t src_type_id
,
hid_t dest_type_id
,
size_t nelmts
,
void *buf
,
void *background
,
hid_t plist_id
)
H5Tconvert
converts nelmts
elements
from a source datatype, specified by src_type_id
,
to a destination datatype, dest_type_id
.
The source elements are packed in buf
and on return
the destination elements will be packed in buf
.
That is, the conversion is performed in place.
The optional background buffer is for use with compound datatypes.
It is an array of nelmts
values for the
destination datatype which can then be merged with the converted
values to recreate the compound datatype.
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.
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb
and H5Pset_type_conv_cb
and functions such as H5Tconvert
and
H5Ewalk2
.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
hid_t src_type_id |
IN: Identifier for the source datatype. |
hid_t dest_type_id |
IN: Identifier for the destination datatype. |
size_t nelmts |
IN: Size of array buf . |
void *buf |
IN/OUT: Array containing pre- and post-conversion
values.
H5Tconvert will not resize this buffer; it must be
large enough to hold the larger of the input and output data.
|
void *background |
IN: Optional background buffer. |
hid_t plist_id |
IN: Dataset transfer property list identifier. |
SUBROUTINE h5tconvert_f(src_id, dst_id, nelmts, buf, hdferr, background, plist_id) INTEGER(HID_T) , INTENT(IN) :: src_id INTEGER(HID_T) , INTENT(IN) :: dst_id INTEGER(SIZE_T), INTENT(IN) :: nelmts TYPE(C_PTR) , INTENT(INOUT) :: buf INTEGER , INTENT(OUT) :: hdferr TYPE(C_PTR) , INTENT(INOUT), OPTIONAL :: background INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: plist_id
Inputs:
src_id - Identifier for the source datatype. dst_id - Identifier for the destination datatype. nelmts - Size of array buf. buf - Array containing pre-conversion values. background - Optional background buffer. plist_id - Dataset transfer property list identifier.
Outputs:
buf - Array containing post-conversion values. hdferr - error code: 0 on success and -1 on failure
Release | Change |
1.8.8 | Fortran subroutine added. |
1.6.3 |
In C function, nelmts parameter type changed to
size_t. |
1.4.0 |
In C function, nelmts parameter type changed to
hsize_t. |
H5Tcopy
(
hid_t dtype_id
)
H5Tcopy
copies an existing datatype.
The returned type is always transient and unlocked.
The dtype_id
argument can be either a datatype
identifier, a predefined datatype (defined in
H5Tpublic.h
), or a dataset identifier.
If dtype_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.
hid_t dtype_id |
IN: Identifier of datatype to copy.
Can be a datatype identifier, a predefined datatype (defined in
H5Tpublic.h ), or a dataset identifier. |
dtype_id
is to be a variable-length string datatype,
see “Creating
variable-length string datatypes.”
SUBROUTINE h5tcopy_f(type_id, new_type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(HID_T), INTENT(OUT) :: new_type_id ! Identifier of datatype's copy INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tcopy_f
H5Tcreate
(
H5T_class_t class
,
size_tsize
)
H5Tcreate
creates a new datatype of the specified
class with the specified number of bytes.
This function is used only with the following datatype classes:
H5T_COMPOUND
H5T_OPAQUE
H5T_ENUM
H5T_STRING
H5Tcopy
to copy and modify a predefined
datatype.
When creating a variable-length string datatype,
size
must be H5T_VARIABLE
;
see “Creating
variable-length string datatypes.”
When creating a fixed-length string datatype, size
will be the length of the string in bytes.
The length of the string in characters will depend on the encoding
used; see
H5Pset_char_encoding
.
ENUMs created with this function have
a signed native integer base datatype.
Use H5Tenum_create
if a different integer base datatype is required.
The datatype identifier returned from this function should be
released with H5Tclose
or resource leaks will result.
H5T_class_t class |
IN: Class of datatype to create;
valid values include:
H5T_COMPOUND
H5T_OPAQUE
H5T_ENUM
H5T_STRING
|
size_t size |
IN: Size, in bytes, of the datatype being created |
H5Pset_char_encoding
H5Tcopy
H5Tenum_create
| |
Creating
variable-length string datatypes
HDF5 Predefined Datatypes |
SUBROUTINE h5tcreate_f(class, size, type_id, hdferr) IMPLICIT NONE INTEGER, INTENT(IN) :: class ! Datatype class can be one of ! H5T_COMPOUND_F ! H5T_OPAQUE_F ! H5T_ENUM_F ! H5T_STRING_F INTEGER(SIZE_T), INTENT(IN) :: size ! Size of the datatype INTEGER(HID_T), INTENT(OUT) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tcreate_f
Release | Change |
1.8.8 | String datatype capability added to function in this release. |
H5Tdecode
(unsigned char *buf
)
H5Tdecode
reconstructs the HDF5 datatype object and
returns a new object handle for it. The binary description of the
object is encoded by H5Tencode
. User is responsible
for passing in the right buffer.
The datatype identifier returned by this function can be
released with H5Tclose
when the identifier is
no longer needed so that resource leaks will not develop.
unsigned char *buf |
IN: Buffer for the datatype object to be decoded. |
SUBROUTINE h5tdecode_f(buf, obj_id, hdferr) IMPLICIT NONE CHARACTER(LEN=*), INTENT(IN) :: buf ! Data space object buffer to be decoded INTEGER(HID_T), INTENT(OUT) :: obj_id! Object identifier INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tdecode_f
H5Tdetect_class
(
hid_t dtype_id
,
H5T_class_tdtype_class
)
H5Tdetect_class
determines whether the datatype
specified in dtype_id
contains any datatypes of the
datatype class specified in dtype_class
.
This function is useful primarily in recursively examining all the fields and/or base types of compound, array, and variable-length datatypes.
Valid class identifiers are as defined in
H5Tget_class
.
hid_t dtype_id |
IN: Datatype identifier. |
H5T_class_t dtype_class |
IN: Datatype class. |
TRUE
or FALSE
if successful;
otherwise returns a negative value.
Release | C |
1.6.0 | Function introduced in this release. |
H5Tencode
(hid_t
obj_id
, unsigned char *buf
,
size_t *nalloc
)
H5Tencode
converts a data
type description into binary form in a buffer. Using this
binary form in the buffer, a datatype object can be reconstructed
using H5Tdecode
to return a new object handle
(hid_t) for this datatype.
A preliminary H5Tencode
call can be made to find
out the size of the buffer needed. This value is returned as
nalloc
. That value can then be assigned to
nalloc
for a second H5Tencode
call,
which will retrieve the actual encoded object.
If the library finds out nalloc
is not big
enough for the object, it simply returns the size of the buffer
needed through nalloc
without encoding the provided buffer.
hid_t obj_id |
IN: Identifier of the object to be encoded. |
unsigned char *buf |
IN/OUT: Buffer for the object to be
encoded into. If the provided buffer is NULL, only
the size of buffer needed is returned through nalloc .
|
size_t *nalloc |
IN: The size of the allocated buffer.
OUT: The size of the buffer needed. |
SUBROUTINE h5tencode_f(obj_id, buf, nalloc, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: obj_id ! Identifier of the object to be encoded CHARACTER(LEN=*), INTENT(OUT) :: buf ! Buffer object to be encoded into INTEGER(SIZE_T), INTENT(INOUT) :: nalloc ! The size of the allocated buffer INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tencode_f
H5Tenum_create
(
hid_t dtype_id
)
H5Tenum_create
creates a new enumeration datatype
based on the specified base datatype, dtype_id
,
which must be an integer datatype.
If a particular architecture datatype is required,
a little endian or big endian datatype for example,
use a native datatype as the base datatype and use
H5Tconvert
on values as they are read from or written to a dataset.
hid_t dtype_id |
IN: Datatype identifier for the base datatype.
Must be an integer datatype. |
SUBROUTINE h5tenum_create_f(dtype_id, new_type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dtype_id ! Datatype identifier for ! the base datatype INTEGER(HID_T), INTENT(OUT) :: new_type_id ! Datatype identifier for the ! new enumeration datatype INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tenum_create_f
H5Tenum_insert
H5Tenum_valueof
H5Tenum_nameof
H5Tget_member_value
| |
H5Tconvert
H5Tcreate
|
H5Tenum_insert
(
hid_t dtype_id
,
const char *name
,
void *value
)
H5Tenum_insert
inserts a
new enumeration datatype member into an enumeration datatype.
dtype_id
is the datatype identifier for 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 dtype_id
.
value
points to data which must be of the
integer base datatype used when the enumeration datatype was created.
If a particular architecture datatype is required,
a little endian or big endian datatype for example,
use a native datatype as the base datatype and use
H5Tconvert
on values as they are read from or written to a dataset.
hid_t dtype_id |
IN: Datatype identifier for the enumeration datatype. |
const char *name |
IN: Name of the new member. |
void *value |
IN: Pointer to the value of the new member. |
SUBROUTINE h5tenum_insert_f(type_id, name, value, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the new member INTEGER, INTENT(IN) :: value ! Value of the new member INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tenum_insert_f
H5Tenum_create
H5Tenum_valueof
H5Tenum_nameof
H5Tget_member_value
H5Tconvert
H5Tenum_nameof
(
hid_t dtype_id
,
void *value
,
char *name
,
size_t size
)
H5Tenum_nameof
finds the symbol name that
corresponds to the specified value
of the enumeration datatype dtype_id
.
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.
hid_t dtype_id |
IN: Enumeration datatype identifier. |
void *value |
IN: Value of the enumeration datatype. |
char *name |
OUT: Buffer for output of the symbol name. |
size_t size |
IN: Anticipated size of the symbol name, in bytes (characters). |
size
allows it,
the first character of name
is
set to NULL
.
SUBROUTINE h5tenum_nameof_f(type_id, value, namelen, name, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: value ! Value of the enumeration datatype INTEGER(SIZE_T), INTENT(IN) :: namelen ! Length of the name CHARACTER(LEN=*), INTENT(OUT) :: name ! Name of the enumeration datatype INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tenum_nameof_f
H5Tenum_create
H5Tenum_insert
H5Tenum_valueof
H5Tget_member_value
H5Tconvert
H5Tenum_valueof
(
hid_t dtype_id
,
char *name
,
void *value
)
H5Tenum_valueof
finds the value that
corresponds to the specified name
of the enumeration datatype dtype_id
.
Values returned in value
will be of the
enumerated type’s base type, that is, the datatype used by
H5Tenum_create
when the enumerated type was created.
The value
buffer must be at least large enough to
hold a value of that base type.
If the size is unknown, you can determine it with
H5Tget_size(dtype_id)
,
where dtype_id
is set to the base type.
hid_t dtype_id |
IN: Enumeration datatype identifier. |
const char *name |
IN: Symbol name of the enumeration datatype. |
void *value |
OUT: Buffer for output of the value of the enumeration datatype. |
SUBROUTINE h5tenum_valueof_f(type_id, name, value, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the enumeration datatype INTEGER, INTENT(OUT) :: value ! Value of the enumeration datatype INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tenum_valueof_f
H5Tenum_create
H5Tenum_insert
H5Tenum_nameof
H5Tget_member_value
H5Tconvert
H5Tequal
(
hid_t dtype_id1
,
hid_t dtype_id2
)
H5Tequal
determines whether two datatype identifiers
refer to the same datatype.
hid_t dtype_id1 |
IN: Identifier of datatype to compare. |
hid_t dtype_id2 |
IN: Identifier of datatype to compare. |
TRUE
,
if the datatype identifiers refer to the same datatype,
or 0
(zero), for FALSE
.
Otherwise returns a negative value.
SUBROUTINE h5tequal_f(type1_id, type2_id, flag, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type1_id ! Datatype identifier INTEGER(HID_T), INTENT(IN) :: type2_id ! Datatype identifier LOGICAL, INTENT(OUT) :: flag ! TRUE/FALSE flag to indicate ! if two datatypes are equal INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tequal_f
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.
hid_t src_id |
IN: Identifier for the source datatype. |
hid_t dst_id |
IN: Identifier for the destination datatype. |
H5T_cdata_t **pcdata |
OUT: Pointer to type conversion data. |
int H5Tget_array_dims (
hid_t adtype_id ,
hsize_t dims[] ,
int perm[] )
| [1] |
int H5Tget_array_dims (
hid_t adtype_id ,
hsize_t dims[] )
| [2] |
H5Tget_array_dims
is a macro that is mapped to either
H5Tget_array_dims1
or
H5Tget_array_dims2
,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. For example:
H5Tget_array_dims
macro
will be mapped to H5Tget_array_dims1
and
will use the H5Tget_array_dims1
syntax
(first signature above)
if an application is coded for HDF5 Release 1.6.x.
H5Tget_array_dims
macro
mapped to H5Tget_array_dims2
and
will use the H5Tget_array_dims2
syntax
(second signature above)
if an application is coded for HDF5 Release 1.8.x.
Macro use and mappings are fully described in “API Compatibility Macros in HDF5”; we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Tget_array_dims
is mapped to the most recent version of
the function, currently
H5Tget_array_dims2
.
If the library and/or application is compiled for Release 1.6
emulation, H5Tget_array_dims
will be mapped to
H5Tget_array_dims1
.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
Compatibility setting | H5Tget_array_dims mapping |
---|---|
Global settings |
|
No compatibility flag | H5Tget_array_dims2 |
Enable deprecated symbols | H5Tget_array_dims2 |
Disable deprecated symbols | H5Tget_array_dims2 |
Emulate Release 1.6 interface | H5Tget_array_dims1 |
Function-level macros |
|
H5Tget_array_dims_vers = 2 |
H5Tget_array_dims2 |
H5Tget_array_dims_vers = 1 |
H5Tget_array_dims1 |
H5Tget_array_dims
interface
and the only interface available prior to HDF5 Release 1.8.0.
This signature and the corresponding function are now deprecated
but will remain directly callable as
H5Tget_array_dims1
.
Signature [2] above was introduced with HDF5 Release 1.8.0
and is the recommended and default interface.
It is directly callable as
H5Tget_array_dims2
.
See “API Compatibility Macros in HDF5” for circumstances under which either of these functions might not be available in an installed instance of the HDF5 Library.
SUBROUTINE h5tarray_create_f(base_id, rank, dims, type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: base_id ! Identifier of array base datatype INTEGER, INTENT(IN) :: rank ! Rank of the array INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: dims ! Sizes of each array dimension INTEGER(HID_T), INTENT(OUT) :: type_id ! Identifier of the array datatype INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tarray_create_f
Release | C |
1.8.0 | The function
H5Tget_array_dims renamed to
H5Tget_array_dims1
and deprecated in this release.
The macro H5Tget_array_dims
and the function H5Tget_array_dims2
introduced in this release. |
H5Tget_array_dims1
(
hid_t adtype_id
,
hsize_t dims[]
,
int perm[]
)
H5Tget_array_dims
and
deprecated in favor of the function
H5Tget_array_dims2
or the new macro
H5Tget_array_dims
.
H5Tget_array_dims1
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 parameter perm
is not used.
hid_t adtype_id |
IN: Datatype identifier of array object. |
hsize_t dims[] |
OUT: Sizes of array dimensions. |
int perm[] |
OUT: Dimension permutations.
(This parameter is not used.) |
SUBROUTINE h5tget_array_dims_f(type_id, dims, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Identifier of the array datatype INTEGER(HSIZE_T), DIMENSION(*), INTENT(OUT) :: dims ! Buffer to store array datatype INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_array_dims_f
Release | C |
1.4.0 | Function introduced in this release. |
1.8.0 |
The function H5Tget_array_dims renamed to
H5Tget_array_dims1
and deprecated in this release. |
H5Tget_array_dims2
(
hid_t adtype_id
,
hsize_t dims[]
)
H5Tget_array_dims2
returns the sizes of the dimensions
of the specified array datatype object.
The sizes of the dimensions are returned in the array dims
.
hid_t adtype_id |
IN: Datatype identifier of array object. |
hsize_t dims[] |
OUT: Sizes of array dimensions. |
Release | C |
1.8.0 | Function introduced in this release. |
H5Tget_array_ndims
(
hid_t adtype_id
)
H5Tget_array_ndims
returns the rank,
the number of dimensions, of an array datatype object.
hid_t adtype_id |
IN: Datatype identifier of array object. |
SUBROUTINE h5tget_array_ndims_f(type_id, ndims, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Identifier of the array datatype INTEGER, INTENT(OUT) :: ndims ! Number of array dimensions INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_array_ndims_f
Release | C |
1.4.0 | Function introduced in this release. |
H5Tget_class
(
hid_t dtype_id
)
H5Tget_class
returns the datatype class identifier.
Valid class identifiers, as defined in H5Tpublic.h
, are:
H5T_INTEGER
H5T_FLOAT
H5T_STRING
H5T_BITFIELD
H5T_OPAQUE
H5T_COMPOUND
H5T_REFERENCE
H5T_ENUM
H5T_VLEN
H5T_ARRAY
Note that the library returns H5T_STRING
for both fixed-length and variable-length strings.
Unsupported datatype:
The time datatype class, H5T_TIME
, is not supported.
If H5T_TIME
is used, the resulting data will be
readable and modifiable only on the originating computing platform;
it will not be portable to other platforms.
hid_t dtype_id |
IN: Identifier of datatype to query. |
H5T_NO_CLASS
(-1).
SUBROUTINE h5tget_class_f(type_id, class, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: class ! Datatype class, possible values are: ! H5T_NO_CLASS_F ! H5T_INTEGER_F ! H5T_FLOAT_F ! H5T_STRING_F ! H5T_BITFIELD_F ! H5T_OPAQUE_F ! H5T_COMPOUND_F ! H5T_REFERENCE_F ! H5T_ENUM_F ! H5T_VLEN_F ! H5T_ARRAY_F INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tget_class_f
H5Tget_create_plist
(
hid_t dtype_id
)
H5Tget_create_plist
returns a
property list identifier for the
datatype creation property list associated with the
datatype specified by dtype_id
.
The creation property list identifier should be released with
H5Pclose
.
hid_t dtype_id
|
IN: Datatype identifier. |
SUBROUTINE h5tget_create_plist_f(dtype_id, dtpl_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dtype_id ! Datatype identifier INTEGER(HID_T), INTENT(OUT) :: dtpl_id ! Datatype property list identifier. INTEGER, INTENT(OUT) :: hdferr ! Error code: ! 0 on success and -1 on failure END SUBROUTINE h5tget_create_plist_f
Release | C |
1.8.0 | Function introduced in this release. |
H5Tget_cset
(
hid_t dtype_id
)
H5Tget_cset
retrieves the character set type
of a string datatype. Valid character set types are:
H5T_CSET_ASCII
| (0 )
| Character set is US ASCII. | ||
H5T_CSET_UTF8
| (1 )
| Character set is UTF-8, enabling Unicode encoding. |
hid_t dtype_id |
IN: Identifier of datatype to query. |
H5T_CSET_ERROR
(-1).
SUBROUTINE h5tget_cset_f(type_id, cset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: cset ! Character set type of a string ! datatype ! Possible values are: ! H5T_CSET_ASCII_F = 0 ! H5T_CSET_UTF8_F = 1 INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_cset_f
H5Tset_cset
Release | Change |
1.8.0 | UTF-8 Unicode encoding introduced in this release. |
H5Tget_ebias
(
hid_t dtype_id
)
H5Tget_ebias
retrieves the exponent bias of a floating-point type.
hid_t dtype_id |
IN: Identifier of datatype to query. |
SUBROUTINE h5tget_ebias_f(type_id, ebias, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(SIZE_T), INTENT(OUT) :: ebias ! Datatype exponent bias ! of a floating-point type INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_ebias_f
H5Tget_fields
(
hid_t dtype_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.
hid_t dtype_id |
IN: Identifier of datatype to query. |
size_t *spos |
OUT: Pointer to location to return floating-point sign bit. |
size_t *epos |
OUT: Pointer to location to return exponent bit-position. |
size_t *esize |
OUT: Pointer to location to return size of exponent in bits. |
size_t *mpos |
OUT: Pointer to location to return mantissa bit-position. |
size_t *msize |
OUT: Pointer to location to return size of mantissa in bits. |
SUBROUTINE h5tget_fields_f(type_id, spos, epos, esize, mpos, msize, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(SIZE_T), INTENT(OUT) :: spos ! sign bit-position INTEGER(SIZE_T), INTENT(OUT) :: epos ! exponent bit-position INTEGER(SIZE_T), INTENT(OUT) :: esize ! size of exponent in bits INTEGER(SIZE_T), INTENT(OUT) :: mpos ! mantissa bit-position INTEGER(SIZE_T), INTENT(OUT) :: msize ! size of mantissa in bits INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_fields_f
H5Tget_inpad
(
hid_t dtype_id
)
H5Tget_inpad
retrieves the internal padding type for
unused bits in floating-point datatypes.
Valid padding types are:
0
)
1
)
2
)
hid_t dtype_id |
IN: Identifier of datatype to query. |
H5T_PAD_ERROR
(-1).
SUBROUTINE h5tget_inpad_f(type_id, padtype, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: padtype ! Padding type for unused bits ! in floating-point datatypes ! Possible values of padding type are: ! H5T_PAD_ZERO_F = 0 ! H5T_PAD_ONE_F = 1 ! H5T_PAD_BACKGROUND_F = 2 INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_inpad_f
H5Tget_member_class
(
hid_t cdtype_id
,
unsigned member_no
)
cdtype_id
, the function
H5Tget_member_class
returns the datatype class of
the compound datatype member specified by member_no
.
Valid class identifiers are as defined in
H5Tget_class
.
hid_t cdtype_id |
IN: Datatype identifier of compound object. |
unsigned member_no |
IN: Compound object member number. |
SUBROUTINE h5tget_member_class_f(type_id, member_no, class, hdferr) INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: member_no ! Member number INTEGER, INTENT(OUT) :: class ! Member class INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_member_class_f
Release | C |
1.6.4 |
membno parameter type changed to
unsigned. |
H5Tget_member_index
(
hid_t dtype_id
,
const char * field_name
)
H5Tget_member_index
retrieves the index of a field
of a compound datatype or an element of an enumeration datatype.
The name of the target field or element is specified in
field_name
.
Fields are stored in no particular order
with index values of 0 through N-1, where N is
the value returned by H5Tget_nmembers
.
hid_t dtype_id |
IN: Identifier of datatype to query. |
const char * field_name |
IN: Name of the field or member whose index is to be retrieved. |
SUBROUTINE h5tget_member_index_f(type_id, name, index, hdferr) INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier CHARACTER(LEN=*), INTENT(IN) :: name ! Member name INTEGER, INTENT(OUT) :: index ! Member index INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_member_index_f
Release | C | Fortran90 | |
1.4.5 | Function introduced in this release. | ||
1.4.4 | Function introduced in this release. |
H5Tget_member_name
(
hid_t dtype_id
,
unsigned field_idx
)
H5Tget_member_name
retrieves the name of a field
of a compound datatype or an element of an enumeration datatype.
The index of the target field or element is specified in
field_idx
.
Compound datatype fields and enumeration datatype elements
are stored in no particular order
with index values of 0 through N-1, where N
is the value returned by H5Tget_nmembers
.
The HDF5 Library allocates a buffer to receive the name of the field.
The caller must subsequently free the buffer with
H5free_memory
.
hid_t tdype_id |
IN: Identifier of datatype to query. |
unsigned field_idx |
IN: Zero-based index of the field or element whose name is to be retrieved. |
malloc()
if successful;
otherwise returns NULL.
SUBROUTINE h5tget_member_name_f(type_id,index, member_name, namelen, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: index ! Field index (0-based) of ! the field name to retrieve CHARACTER(LEN=*), INTENT(OUT) :: member_name ! Name of a field of ! a compound datatype INTEGER, INTENT(OUT) :: namelen ! Length of the name INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_member_name_f
Release | C |
1.6.4 |
field_idx parameter type changed to
unsigned. |
H5Tget_member_offset
(
hid_t dtype_id
,
unsigned 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 datatype datum.
hid_t dtype_id |
IN: Identifier of datatype to query. |
unsigned memb_no |
IN: Number of the field whose offset is requested. |
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.
SUBROUTINE h5tget_member_offset_f(type_id, member_no, offset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: member_no ! Number of the field ! whose offset is requested INTEGER(SIZE_T), INTENT(OUT) :: offset ! Byte offset of the the ! beginning of the field INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_member_offset_f
Release | C |
1.6.4 |
membno parameter type changed to
unsigned. |
H5Tget_member_type
(
hid_t dtype_id
,
unsigned field_idx
)
H5Tget_member_type
returns the datatype of the specified member. The caller
should invoke H5Tclose() to release resources associated with the type.
hid_t dtype_id |
IN: Identifier of datatype to query. |
unsigned field_idx |
IN: Field index (0-based) of the field type to retrieve. |
SUBROUTINE h5tget_member_type_f(type_id, field_idx, datatype, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: field_idx ! Field index (0-based) of the ! field type to retrieve INTEGER(HID_T), INTENT(OUT) :: datatype ! Identifier of a copy of ! the datatype of the field INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_member_type_f
Release | C |
1.6.4 |
membno parameter type changed to
unsigned. |
H5Tget_member_value
(
hid_t dtype_id
,
unsigned 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
.
Values returned in value
will be of the
enumerated type’s base type, that is, the datatype used by
H5Tenum_create
when the enumerated type was created.
The value
buffer must be at least large enough to
hold a value of that base type.
If the size is unknown, you can determine it with
H5Tget_size(dtype_id)
,
where dtype_id
is set to the base type.
hid_t dtype_id |
IN: Datatype identifier for the enumeration datatype. |
unsigned memb_no |
IN: Number of the enumeration datatype member. |
void *value |
OUT: Pointer to a buffer for output of the value of the enumeration datatype member. |
SUBROUTINE h5tget_member_value_f(type_id, member_no, value, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: member_no ! Number of the enumeration ! datatype member INTEGER, INTENT(OUT) :: value ! Value of the enumeration datatype INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_member_value_f
H5Tenum_create
H5Tenum_insert
H5Tenum_valueof
H5Tenum_nameof
H5Tconvert
Release | C |
1.6.4 |
membno parameter type changed to
unsigned. |
H5Tget_native_type
(
hid_t dtype_id
,
H5T_direction_t direction
)
H5Tget_native_type
returns the equivalent native datatype
for the datatype specified in dtype_id
.
H5Tget_native_type
is a high-level function designed
primarily to facilitate use of the H5Dread
function,
for which users otherwise must undertake a multi-step process to
determine the native datatype of a dataset prior to reading it
into memory.
This function can be used for the following purposes:
dtype_id
is a compound datatype,
the returned datatype identifier will be for
a similar compound datatype with
each element converted to the corresponding native datatype;
nested compound datatypes will be unwound.
If dtype_id
is an array,
the returned datatype identifier will be for
the native datatype of a single array element.
H5Tget_native_type
selects the first matching native
datatype from the following list:
H5T_NATIVE_CHAR H5T_NATIVE_SHORT H5T_NATIVE_INT H5T_NATIVE_LONG H5T_NATIVE_LLONG H5T_NATIVE_UCHAR H5T_NATIVE_USHORT H5T_NATIVE_UINT H5T_NATIVE_ULONG H5T_NATIVE_ULLONG H5T_NATIVE_FLOAT H5T_NATIVE_DOUBLE H5T_NATIVE_LDOUBLE H5T_NATIVE_B8 H5T_NATIVE_B16 H5T_NATIVE_B32 H5T_NATIVE_B64
The direction
parameter indicates the order
in which the library searches for a native datatype match.
Valid values for direction
are as follows:
H5T_DIR_ASCEND |
Searches the above list in ascending size of the datatype, i.e., from top to bottom. (Default) | |
H5T_DIR_DESCEND |
Searches the above list in descending size of the datatype, i.e., from bottom to top. |
H5Tget_native_type
is designed primarily for
use with integer, floating point, and bitfield datatypes.
String, time, opaque, and reference datatypes are returned
as a copy of dtype_id
.
See above for compound, array, enumerated,
and variable-length datatypes.
The identifier returned by H5Tget_native_type
should eventually be closed by calling H5Tclose
to release resources.
hid_t dtype_id |
IN: Datatype identifier for the dataset datatype. |
H5T_direction_t direction |
IN: Direction of search. |
SUBROUTINE h5tget_native_type_f(dtype_id, direction, native_dtype_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dtype_id ! Datatype identifier INTEGER, INTENT(IN) :: direction ! Direction of search: ! H5T_DIR_ASCEND_F = 1 in inscendent order ! H5T_DIR_DESCEND_F= 2 in descendent order INTEGER(HID_T), INTENT(OUT) :: native_dtype_id ! The native datatype identifier INTEGER, INTENT(OUT) :: hdferr ! Error code: ! 0 on success and -1 on failure END SUBROUTINE h5tget_native_type_f
Release | C |
1.6.0 | Function introduced in this release. |
H5Tget_nmembers
(
hid_t dtype_id
)
H5Tget_nmembers
retrieves
the number of fields in a compound datatype or
the number of members of an enumeration datatype.
hid_t dtype_id |
IN: Identifier of datatype to query. |
SUBROUTINE h5tget_nmembers_f(type_id, num_members, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: num_members ! Number of fields in a ! compound datatype INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_nmembers_f
H5Tget_norm
(
hid_t dtype_id
)
H5Tget_norm
retrieves the mantissa normalization of
a floating-point datatype. Valid normalization types are:
0
)
1
)
2
)
hid_t dtype_id |
IN: Identifier of datatype to query. |
H5T_NORM_ERROR
(-1).
SUBROUTINE h5tget_norm_f(type_id, norm, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: norm ! Mantissa normalization of a ! floating-point datatype ! Valid normalization types are: ! H5T_NORM_IMPLIED_F(0) ! MSB of mantissa is not ! stored, always 1 ! H5T_NORM_MSBSET_F(1) ! MSB of mantissa is always 1 ! H5T_NORM_NONE_F(2) ! Mantissa is not normalized INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_norm_f
H5Tget_offset
(
hid_t dtype_id
)
H5Tget_offset
retrieves the bit offset of the first significant bit.
The significant bits of an atomic datum can be offset from the beginning
of the memory for that datum by an amount of padding. The `offset'
property specifies the number of bits of padding that appear to the
"right of" the value. That is, if we have a 32-bit datum with 16-bits
of precision having the value 0x1122 then it will be laid out in
memory as (from small byte address toward larger byte addresses):
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] |
hid_t dtype_id |
IN: Identifier of datatype to query. |
SUBROUTINE h5tget_offset_f(type_id, offset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(SIZE_T), INTENT(OUT) :: offset ! Datatype bit offset of the ! first significant bit INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tget_offset_f
H5Tget_order
(
hid_t dtype_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
)
H5T_ORDER_MIXED
(3
)
H5T_ORDER_NONE
(4
)
Members of a compound datatype need not have the same byte order.
If members of a compound datatype have more than one of
little endian, big endian, or VAX byte order,
H5Tget_order
will return H5T_ORDER_MIXED
for the compound datatype.
A byte order of H5T_ORDER_NONE
will, however, be
ignored; for example, if one or more members of a compound datatype
have byte order H5T_ORDER_NONE
but all other members
have byte order H5T_ORDER_LE
,
H5Tget_order
will return H5T_ORDER_LE
for the compound datatype.
hid_t dtype_id |
IN: Identifier of datatype to query. |
H5T_ORDER_ERROR
(-1).
SUBROUTINE h5tget_order_f(type_id, order, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: order ! Datatype byte order ! Possible values are: ! H5T_ORDER_LE_F ! H5T_ORDER_BE_F ! H5T_ORDER_VAX_F ! H5T_ORDER_MIXED_F ! (not implemented) ! H5T_ORDER_NONE_F INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tget_order_f
Release | Change |
1.8.6 |
Function modified to work with all datatypes.
H5T_ORDER_MIXED added to
H5T_order_t . |
H5Tget_pad
(
hid_t dtype_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
)
hid_t dtype_id |
IN: Identifier of datatype to query. |
H5T_pad_t * lsb |
OUT: Pointer to location to return least-significant bit padding type. |
H5T_pad_t * msb |
OUT: Pointer to location to return most-significant bit padding type. |
SUBROUTINE h5tget_pad_f(type_id, lsbpad, msbpad, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: lsbpad ! Padding type of the ! least significant bit INTEGER, INTENT(OUT) :: msbpad ! Padding type of the ! most significant bit ! Possible values of ! padding type are: ! H5T_PAD_ZERO_F = 0 ! H5T_PAD_ONE_F = 1 ! H5T_PAD_BACKGROUND_F = 2 ! H5T_PAD_ERROR_F = -1 ! H5T_PAD_NPAD_F = 3 INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_pad_f
H5Tget_precision
(
hid_t dtype_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
.
hid_t dtype_id |
IN: Identifier of datatype to query. |
SUBROUTINE h5tget_precision_f(type_id, precision, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(SIZE_T), INTENT(OUT) :: precision ! Datatype precision INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_precision_f
H5Tget_sign
(
hid_t dtype_id
)
H5Tget_sign
retrieves the sign type for an integer type.
Valid types are:
0
)
1
)
hid_t dtype_id |
IN: Identifier of datatype to query. |
H5T_SGN_ERROR
(-1).
SUBROUTINE h5tget_sign_f(type_id, sign, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: sign ! Sign type for an integer type ! Possible values are: ! Unsigned integer type ! H5T_SGN_NONE_F = 0 ! Two's complement signed ! integer type ! H5T_SGN_2_F = 1 ! or error value ! H5T_SGN_ERROR_F = -1 INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tget_sign_f
H5Tget_size
(
hid_t dtype_id
)
H5Tget_size
returns the size of a datatype in bytes.
For atomic datatypes, array datatypes, compound datatypes, and other datatypes of a constant size, the returned value is the size of the actual datatype in bytes.
For variable-length string datatypes
(see “Creating variable-length string
datatypes”),
the returned value is the size of the pointer to the actual string,
or sizeof(char *)
.
This function does not return the size of actual
variable-length string data.
For variable-length sequence datatypes
(see
H5Tvlen_create
),
the returned value is the size of the hvl_t
struct,
or sizeof(hvl_t)
.
The hvl_t
struct contains a pointer to the actual data
and a size value.
This function does not return the size of actual
variable-length sequence data.
hid_t dtype_id |
IN: Identifier of datatype to query. |
SUBROUTINE h5tget_size_f(type_id, size, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(SIZE_T), INTENT(OUT) :: size ! Datatype size INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tget_size_f
H5Tget_strpad
(
hid_t dtype_id
)
H5Tget_strpad
retrieves the type of padding used
for a string datatype.
The string padding type is set with
H5Tset_strpad
and valid settings are described in that entry.
hid_t dtype_id |
IN: Identifier of datatype to query. |
H5T_STR_ERROR
(-1).
SUBROUTINE h5tget_strpad_f(type_id, strpad, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: strpad ! String padding method for a string datatype ! Possible values of padding type are: ! Pad with zeros (as C does): ! H5T_STR_NULLPAD_F(0) ! Pad with spaces (as FORTRAN does): ! H5T_STR_SPACEPAD_F(1) INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tget_strpad_f
H5Tget_super
(
hid_t dtype_id
)
H5Tget_super
returns the base datatype from which the
datatype dtype_id
is derived.
In the case of an enumeration type, the return value is an integer type.
The datatype identifier returned by this function can be
released with H5Tclose
when the identifier is
no longer needed so that resource leaks will not develop.
hid_t dtype_id |
IN: Datatype identifier for the derived datatype. |
SUBROUTINE h5tget_super_f(type_id, base_type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(HID_T), INTENT(OUT) :: type_id ! Base datatype identifier INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tget_super_f
H5Tget_tag
(
hid_t dtype_id
)
H5Tget_tag
returns the tag associated with
the opaque datatype dtype_id
.
The tag is returned via a pointer to an allocated string, which the caller must free.
hid_t dtype_id |
IN: Datatype identifier for the opaque datatype. |
NULL
.
SUBROUTINE h5tget_tag_f(type_id, tag,taglen, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier CHARACTER(LEN=*), INTENT(OUT) :: tag ! Unique ASCII string with which the ! opaque datatype is to be tagged INTEGER, INTENT(OUT) :: taglen ! Length of tag INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tget_tag_f
H5Tinsert
(
hid_t dtype_id
,
const char * name
,
size_t offset
,
hid_t field_id
)
H5Tinsert
adds another member to the compound datatype
dtype_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.
hid_t dtype_id |
IN: Identifier of compound datatype to modify. |
const char * name |
IN: Name of the field to insert. |
size_t offset |
IN: Offset in memory structure of the field to insert. |
hid_t field_id |
IN: Datatype identifier of the field to insert. |
SUBROUTINE h5tinsert_f(type_id, name, offset, field_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the field to insert INTEGER(SIZE_T), INTENT(IN) :: offset ! Offset in memory structure ! of the field to insert INTEGER(HID_T), INTENT(IN) :: field_id ! Datatype identifier of the ! new member INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tinsert_f
H5Tis_variable_str
(
hid_t dtype_id
)
H5Tis_variable_str
determines whether the datatype
identified in dtype_id
is a variable-length string.
This function can be used to distinguish between fixed and variable-length string datatypes.
hid_t dtype_id |
IN: Datatype identifier. |
TRUE
or FALSE
if successful;
otherwise returns a negative value.
SUBROUTINE h5tis_variable_str_f(type_id, status, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier LOGICAL, INTENT(OUT) :: status ! Logical flag: ! .TRUE. if datatype is a ! variable string ! .FALSE. otherwise INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tis_variable_str_f
Release | C |
1.6.0 | Function introduced in this release. |
H5Tlock
(
hid_t dtype_id
)
H5Tlock
locks the datatype specified by the
dtype_id
identifier, making it read-only and
non-destructible. This is normally done by the library for
predefined datatypes so the application does not
inadvertently change or delete a predefined type.
Once a datatype is locked it can never be unlocked.
hid_t dtype_id |
IN: Identifier of datatype to lock. |
H5Topen
(
hid_t loc_id
,
const char * name
)
H5Topen
(
hid_t loc_id
,
const char * name
,
hid_t tapl_id
)
H5Topen
is a macro that is mapped to either
H5Topen1
or
H5Topen2
,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in “API Compatibility Macros in HDF5”; we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Topen
is mapped to the most recent version of
the function, currently
H5Topen2
.
If the library and/or application is compiled for Release 1.6
emulation, H5Topen
will be mapped to
H5Topen1
.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
Compatibility setting | H5Topen mapping |
---|---|
Global settings |
|
No compatibility flag | H5Topen2 |
Enable deprecated symbols | H5Topen2 |
Disable deprecated symbols | H5Topen2 |
Emulate Release 1.6 interface |
H5Topen1 |
Function-level macros |
|
H5Topen_vers = 2 |
H5Topen2 |
H5Topen_vers = 1 |
H5Topen1 |
The datatype identifier returned by this macro can be
released with H5Tclose
when the identifier is
no longer needed so that resource leaks will not develop.
SUBROUTINE h5topen_f(loc_id, name, type_id, hdferr, tapl_id) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier CHARACTER(LEN=*), INTENT(IN) :: name ! Datatype name within file or group INTEGER(HID_T), INTENT(OUT) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tapl_id ! Datatype access property list id END SUBROUTINE h5topen_f
Release | C |
1.8.0 |
The function H5Topen renamed to
H5Topen1 and deprecated in this release.
The macro H5Topen
and the function H5Topen2
introduced in this release. |
H5Topen1
(
hid_t loc_id
,
const char * name
)
H5Topen2
.
H5Topen1
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.
hid_t loc_id |
IN: A file or group identifier. |
const char * name |
IN: A datatype name, defined within the file
or group identified by loc_id . |
H5Topen
.
Release | C |
1.8.0 |
The function H5Topen renamed to
H5Topen1 and deprecated in this release. |
H5Topen2
(
hid_t loc_id
,
const char * name
,
hid_t tapl_id
)
H5Topen2
opens a committed 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.
The committed datatype is opened with the datatype access property list
tapl_id
.
hid_t loc_id |
IN: A file or group identifier. |
const char * name |
IN: A datatype name, defined within the file
or group identified by loc_id . |
hid_t tapl_id |
IN: Datatype access property list identifier. |
H5Topen
.Release | C |
1.8.0 | Function introduced in this release. |
H5Tpack
(
hid_t dtype_id
)
H5Tpack
recursively removes padding from within a compound
datatype to make it more efficient (space-wise) to store that data.
hid_t dtype_id |
IN: Identifier of datatype to modify. |
SUBROUTINE h5tpack_f(type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tpack_f
H5Tregister
(
H5T_pers_t type
,
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 type
indicates whether a conversion function
is hard (H5T_PERS_HARD
)
or soft (H5T_PERS_SOFT
).
User-defined functions employing compiler casting are designated as
hard;
other user-defined conversion functions registered with the
HDF5 Library (with H5Tregister
) are designated
as soft.
The HDF5 Library also has its own hard and soft
conversion functions.
A conversion path can have only one hard function.
When type
is H5T_PERS_HARD
,
func
replaces any previous hard function.
When type
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:
typedef
herr_t (*H5T_conv_t
) (hid_tsrc_id
, hid_tdst_id
, H5T_cdata_t *cdata
, size_tnelmts
, size_tbuf_stride
, size_tbkg_stride
, void *buf
, void *bkg
, hid_tdset_xfer_plist
)
The H5T_cdata_t
struct is declared as:
typedef
struct*H5T_cdata_t
(H5T_cmd_tcommand
, H5T_bkg_tneed_bkg
, hbool_t *recalc
, void *priv
)
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb
and H5Pset_type_conv_cb
and functions such as H5Tconvert
and
H5Ewalk2
.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
H5T_pers_t type |
IN: Conversion function type: H5T_PERS_HARD
for hard conversion functions
H5T_PERS_SOFT
for soft conversion functions
|
const char * name |
IN: Name displayed in diagnostic output |
hid_t src_id |
IN: Identifier of source datatype |
hid_t dst_id |
IN: Identifier of destination datatype |
H5T_conv_t func |
IN: Function to convert between source and destination datatypes |
Release | C |
1.6.3 |
The following change occurred in the
H5Tconv_t function:nelmts parameter type changed to
size_t. |
H5Tset_cset
(
hid_t dtype_id
,
H5T_cset_t cset
)
H5Tset_cset
sets the character set to be used
in a dataset with a string or character datatype.
Valid values for cset
include the following:
H5T_CSET_ASCII
| Character set is US ASCII. | ||
H5T_CSET_UTF8
| Character set is UTF-8, enabling UTF-8 Unicode encoding. |
For example, if the character set for the datatype
dtype_id
is set to
H5T_CSET_UTF8
,
string or character data of datatype dtype_id
will be encoded using the UTF-8 Unicode character set.
ASCII and UTF-8 Unicode are the only currently supported character encodings. Extended ASCII encodings (for example, ISO 8859) are not supported. This encoding policy is not enforced by the HDF5 Library. Using encodings other than ASCII and UTF-8 can lead to compatibility and usability problems.
Note that H5Tset_cset
sets the character set for
a character or string datatype while
H5Pset_char_encoding
sets the character set used for an HDF5 link or attribute name.
hid_t dtype_id |
IN: Identifier of datatype to modify. |
H5T_cset_t cset |
IN: Character set type. |
SUBROUTINE h5tset_cset_f(type_id, cset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: cset ! Character set type of a string datatype ! Possible values are: ! H5T_CSET_ASCII_F = 0 ! H5T_CSET_UTF8_F = 1 INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tset_cset_f
Release | Change |
1.8.0 | UTF-8 Unicode encoding introduced in this release. |
H5Tset_ebias
(
hid_t dtype_id
,
size_t ebias
)
H5Tset_ebias
sets the exponent bias of a floating-point
type.
hid_t dtype_id |
IN: Identifier of datatype to set. |
size_t ebias |
IN: Exponent bias value. |
SUBROUTINE h5tset_ebias_f(type_id, ebias, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(SIZE_T), INTENT(IN) :: ebias ! Datatype exponent bias ! of a floating-point type, ! which cannot be 0 INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tset_ebias_f
H5Tset_fields
(
hid_t dtype_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.
hid_t dtype_id |
IN: Identifier of datatype to set. |
size_t spos |
IN: Sign position, i.e., the bit offset of the floating-point sign bit. |
size_t epos |
IN: Exponent bit position. |
size_t esize |
IN: Size of exponent in bits. |
size_t mpos |
IN: Mantissa bit position. |
size_t msize |
IN: Size of mantissa in bits. |
SUBROUTINE h5tset_fields_f(type_id, spos, epos, esize, mpos, msize, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(SIZE_T), INTENT(IN) :: spos ! sign bit-position INTEGER(SIZE_T), INTENT(IN) :: epos ! exponent bit-position INTEGER(SIZE_T), INTENT(IN) :: esize ! size of exponent in bits INTEGER(SIZE_T), INTENT(IN) :: mpos ! mantissa bit-position INTEGER(SIZE_T), INTENT(IN) :: msize ! size of mantissa in bits INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tset_fields_f
H5Tset_inpad
(
hid_t dtype_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
)
hid_t dtype_id |
Identifier of datatype to modify. |
H5T_pad_t pad |
Padding type. |
SUBROUTINE h5tset_inpad_f(type_id, padtype, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: padtype ! Padding type for unused bits ! in floating-point datatypes. ! Possible values of padding type are: ! H5T_PAD_ZERO_F = 0 ! H5T_PAD_ONE_F = 1 ! H5T_PAD_BACKGROUND_F = 2 INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tset_inpad_f
H5Tset_norm
(
hid_t dtype_id
,
H5T_norm_t norm
)
H5Tset_norm
sets the mantissa normalization of
a floating-point datatype. Valid normalization types are:
0
)
1
)
2
)
hid_t dtype_id |
IN: Identifier of datatype to set. |
H5T_norm_t norm |
IN: Mantissa normalization type. |
SUBROUTINE h5tset_norm_f(type_id, norm, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: norm ! Mantissa normalization of a ! floating-point datatype ! Valid normalization types are: ! H5T_NORM_IMPLIED_F(0) ! MSB of mantissa is not stored, ! always 1 ! H5T_NORM_MSBSET_F(1) ! MSB of mantissa is always 1 ! H5T_NORM_NONE_F(2) ! Mantissa is not normalized INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tset_norm_f
H5Tset_offset
(
hid_t dtype_id
,
size_t offset
)
H5Tset_offset
sets the bit offset of the first significant
bit. The significant bits of an atomic datum can be offset from the
beginning of the memory for that datum by an amount of padding.
The offset
property specifies the number of bits of
padding that appear “to the right of” the value.
That is, if we have a 32-bit datum with 16-bits of precision having
the value 0x1122
, then it will be laid out in
memory as (from small byte address toward larger byte addresses):
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.
hid_t dtype_id |
IN: Identifier of datatype to set. |
size_t offset |
IN: Offset of first significant bit. |
SUBROUTINE h5tset_offset_f(type_id, offset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(SIZE_T), INTENT(IN) :: offset ! Datatype bit offset of ! the first significant bit INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tset_offset_f
H5Tset_order
(
hid_t dtype_id
,
H5T_order_t order
)
H5Tset_order
sets the byte order of a datatype.
Byte order can currently be set to any of the following:
H5T_ORDER_LE
(0
)
H5T_ORDER_BE
(1
)
H5T_ORDER_VAX
(2
)
H5T_ORDER_MIXED
(3
) is a valid value
for order
only when returned by the function
H5Tget_order
;
it cannot be set with H5Tset_order
.
H5T_ORDER_NONE
(4
) is a valid value
for order
, but it has no effect.
It is valid only for fixed-length strings and object and region references
and specifies “no particular order.”
The byte order of a derived datatype is initially the same as that
of the parent type, but can be changed with H5Tset_order
.
This function cannot be used with a datatype after it has been committed.
Special considerations:
ENUM datatypes: Byte order must be set before any member
on an ENUM is defined.
Compound datatypes: Byte order is set individually on each member of a compound datatype; members of a compound datatype need not have the same byte order.
Opaque datatypes: Byte order can be set but has no effect.
hid_t dtype_id |
IN: Identifier of datatype to set. |
H5T_order_t order |
IN: Byte order constant. |
SUBROUTINE h5tset_order_f(type_id, order, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: order ! Datatype byte order ! Possible values are: ! H5T_ORDER_LE_F ! H5T_ORDER_BE_F ! H5T_ORDER_VAX_F ! H5T_ORDER_NONE_F INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tset_order_f
Release | Change |
1.8.6 |
Function modified to work with all datatypes.
H5T_ORDER_MIXED added to
H5T_order_t . |
H5Tset_pad
(
hid_t dtype_id
,
H5T_pad_t lsb
,
H5T_pad_t msb
)
H5Tset_pad
sets the least and most-significant bits
padding types.
0
)
1
)
2
)
hid_t dtype_id |
IN: Identifier of datatype to set. |
H5T_pad_t lsb |
IN: Padding type for least-significant bits. |
H5T_pad_t msb |
IN: Padding type for most-significant bits. |
SUBROUTINE h5tset_pad_f(type_id, lsbpad, msbpad, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: lsbpad ! Padding type of the ! least significant bit INTEGER, INTENT(IN) :: msbpad ! Padding type of the ! most significant bit ! Possible values of padding ! type are: ! H5T_PAD_ZERO_F = 0 ! H5T_PAD_ONE_F = 1 ! H5T_PAD_BACKGROUND_F = 2 ! H5T_PAD_ERROR_F = -1 ! H5T_PAD_NPAD_F = 3 INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tset_pad_f
H5Tset_precision
(
hid_t dtype_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.
hid_t dtype_id |
IN: Identifier of datatype to set. |
size_t precision |
IN: Number of bits of precision for datatype. |
SUBROUTINE h5tset_precision_f(type_id, precision, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(SIZE_T), INTENT(IN) :: precision ! Datatype precision INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tset_precision_f
H5Tset_sign
(
hid_t dtype_id
,
H5T_sign_t sign
)
H5Tset_sign
sets the sign property for an integer type:
H5T_SGN_NONE (0 )
| Unsigned integer type | |
H5T_SGN_2 (1 )
| Two's complement signed integer type |
hid_t dtype_id |
IN: Identifier of datatype to set. |
H5T_sign_t sign |
IN: Sign type. |
SUBROUTINE h5tset_sign_f(type_id, sign, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: sign ! Sign type for an integer type ! Possible values are: ! Unsigned integer type ! H5T_SGN_NONE_F = 0 ! Two's complement signed integer type ! H5T_SGN_2_F = 1 ! or error value ! H5T_SGN_ERROR_F=-1 INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tset_sign_f
H5Tset_size
(
hid_t dtype_id
,
size_tsize
)
H5Tset_size
sets the total size in bytes,
size
, for a datatype.
The parameter size
must have a positive value,
unless it is passed as H5T_VARIABLE
and
the datatype is a string datatype.
Numeric datatypes:
If the datatype is atomic and the size is decreased so that
significant bits of the datatype extend beyond the edge of the
new size, then the offset
property of the datatype
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.
String or character datatypes:
The size
set for a string datatype should include space
for the null-terminator character, otherwise it will not be stored on
(or retrieved from) disk.
Adjusting the size
of a string automatically sets the
precision to 8*size
.
Variable-length string datatypes:
If dtype_id
is a variable-length string,
size
must normally be set to H5T_VARIABLE
.
See “Creating
variable-length string datatypes”.
Compound datatypes: This function may be used to increase or decrease the size of a compound datatype, but the function will fail if the new size is too small to accommodate all member fields.
Ineligible datatypes:
This function cannot be used with
enumerated datatypes (H5T_ENUM
),
array datatypes (H5T_ARRAY
),
variable-length array datatypes (H5T_VLEN
),
or reference datatypes (H5T_REFERENCE
).
hid_t dtype_id |
IN: Identifier of datatype for which the size is being changed |
size_t size |
IN: New datatype size in bytes
or H5T_VARIABLE
|
SUBROUTINE h5tset_size_f(type_id, size, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER(SIZE_T), INTENT(IN) :: size ! Datatype size INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5tset_size_f
H5Tset_strpad
(
hid_t dtype_id
,
H5T_str_t strpad
)
H5Tset_strpad
defines the type of padding used for
a string datatype.
The method used to store character strings differs with the programming language:
Valid values of strpad
are as follows:
H5T_STR_NULLTERM
(0
)
H5T_STR_NULLPAD
(1
)
H5T_STR_SPACEPAD
(2
)
When converting from a longer string to a shorter string,
the behavior is as follows.
If the shorter 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 longer string is padded on the end by appending nulls or spaces.
hid_t dtype_id |
IN: Identifier of datatype to modify. |
H5T_str_t strpad |
IN: String padding type. |
SUBROUTINE h5tset_strpad_f(type_id, strpad, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier INTEGER, INTENT(IN) :: strpad ! String padding method for a string datatype ! Possible values of padding type are: ! Pad with zeros (as C does): ! H5T_STR_NULLPAD_F(0) ! Pad with spaces (as FORTRAN does): ! H5T_STR_SPACEPAD_F(1) INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tset_strpad_f
H5Tset_tag
(
hid_t dtype_id
const char *tag
)
H5Tset_tag
tags an opaque datatype dtype_id
with a descriptive ASCII identifier, tag
.
tag
is intended to provide a concise description;
the maximum size is hard-coded in the HDF5 Library as 256 bytes
(H5T_OPAQUE_TAG_MAX
).
hid_t dtype_id |
IN: Datatype identifier for the opaque datatype to be tagged. |
const char *tag |
IN: Descriptive ASCII string with which the opaque datatype is to be tagged. |
SUBROUTINE h5tset_tag_f(type_id, tag, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier CHARACTER(LEN=*), INTENT(IN) :: tag ! Unique ASCII string with which the ! opaque datatype is to be tagged INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tset_tag_f
Release | C |
1.6.5 |
The H5T_OPAQUE_TAG_MAX macro constant,
specifying the maximum size of an opaque datatype tag,
was added in H5Tpublic.h . |
H5Tunregister
(
H5T_pers_t type
,
const char *name
,
hid_t src_id
,
hid_t dst_id
,
H5T_conv_t func
)
H5Tunregister
removes a conversion function matching
criteria such as soft or hard conversion, source and destination types,
and the conversion function.
If a user is trying to remove a conversion function he registered,
all parameters can be used. If he is trying to remove a library’s
default conversion function, there is no guarantee the name
and func
parameters will match the user’s chosen values.
Passing in some values may cause this function to fail. A good practice
is to pass in NULL as their values.
All parameters are optional. The missing parameters will be used to generalize the search criteria.
The conversion function pointer type declaration is described in
H5Tregister
.
H5T_pers_t type |
IN: Conversion function type:H5T_PERS_HARD for hard conversion functions or H5T_PERS_SOFT for soft conversion functions. |
const char *name |
IN: Name displayed in diagnostic output. |
hid_t src_id |
IN: Identifier of source datatype. |
hid_t dst_id |
IN: Identifier of destination datatype. |
H5T_conv_t func |
IN: Function to convert between source and destination datatypes. |
Release | C |
1.6.3 |
The following change occurred in the
H5Tconv_t function:nelmts parameter type changed to
size_t. |
H5Tvlen_create
(
hid_t base_type_id
)
H5Tvlen_create
creates a new one-dimensional array datatype
of variable-length (VL) with the base datatype base_type_id
.
This one-dimensional array often represents a data sequence of the base datatype, such as characters for character sequences or vertex coordinates for polygon lists. The base type specified for the VL datatype can be 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.
Under certain circumstances,
H5Dvlen_reclaim
must also be used.
H5Tvlen_create
cannot be used to create a
variable-length string datatype.
H5Tvlen_create
called with a string or character
base type creates a variable-length sequence of strings
(a variable-length, 1-dimensional array), with each element
of the array being of the string or character base type.
To create a variable-length string datatype, see “Creating variable-length string datatypes.”
hid_t base_type_id |
IN: Base type of datatype to create. |
H5Dvlen_get_buf_size
H5Dvlen_reclaim
SUBROUTINE h5tvlen_create_f(type_id, vltype_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier of base type ! Base type can only be atomic INTEGER(HID_T), INTENT(OUT) :: vltype_id ! VL datatype identifier INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tvlen_create_f
Release | Change |
1.4.5 | Fortran subroutine introduced in this release. |
The HDF Group Help Desk:
Describes HDF5 Release 1.8.18, November 2016. |
Copyright by
The HDF Group
and the Board of Trustees of the University of Illinois |