|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5DS H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5R H5S H5T H5Z Tools Datatypes Fortran Compatibility Macros (Printable PDF of this Reference Manual) |
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 The Datatype Interface (H5T) in the HDF5 User's Guide for further information, including a complete list of all supported datatypes.
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_typ_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 | C |
| 1.8.0 | 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 |
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.
If any of the groups specified in that path do not already exist,
the dataset must be created with
H5Tcommit_anon
and linked into the file structure with
H5Llink.
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.
hid_t loc_id |
IN: A file or group identifier. |
const char * name |
IN: A datatype name. |
hid_t dtype_id |
IN: A datatype identifier. |
H5Tcommit.
| Release | C |
| 1.8.0 |
The function H5Tcommit renamed to
H5Tcommit1 and deprecated in this release. |
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.
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 |
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. |
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 H5Llink
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 H5Llink,
which offers greater control over linking.
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
| Release | C |
| 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_id,
hid_t dst_id,
size_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.
hid_t src_id |
Identifier for the source datatype. |
hid_t dst_id |
Identifier for the destination datatype. |
size_t nelmts |
Size of array buf. |
void *buf |
Array containing pre- and post-conversion values. |
void *background |
Optional background buffer. |
hid_t plist_id |
Dataset transfer property list identifier. |
| Release | C |
| 1.6.3 |
nelmts parameter type changed to
size_t. |
| 1.4.0 |
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 |
Identifier of datatype to copy. Can be a datatype
identifier, a predefined datatype (defined in
H5Tpublic.h), or a dataset identifier. |
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.
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.
H5T_class_t class |
Class of datatype to create. |
size_t size |
The number of bytes in the datatype to create. |
SUBROUTINE h5tcreate_f(class, size, type_id, hdferr)
IMPLICIT NONE
INTEGER, INTENT(IN) :: class ! Datatype class can be one of
! H5T_COMPOUND_F (6)
! H5T_ENUM_F (8)
! H5T_OPAQUE_F (9)
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
H5Tdecode
(unsigned char *buf)
H5Tdecode reconstructs the HDF5 data type 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.
unsigned char *buf |
IN: Buffer for the data type 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 ID
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 |
Datatype identifier. |
H5T_class_t dtype_class |
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 data type object can be reconstructed
using H5Tdecode to return a new object handle
(hid_t) for this data type.
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
<\pre>
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.
hid_t parent_id |
IN: Datatype identifier for the base datatype. |
SUBROUTINE h5tenum_create_f(parent_id, new_type_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: parent_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(
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 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 is of the
datatype defined when the enumeration datatype was created.
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_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, name, namelen, value, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier CHARACTER(LEN=*), INTENT(OUT) :: name ! Name of the enumeration datatype INTEGER(SIZE_T), INTENT(IN) :: namelen ! Length of the name INTEGER, INTENT(IN) :: value ! Value of the enumeration datatype INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5tenum_nameof_f
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.
The value argument should be at least
as large as the value of H5Tget_size(type)
in order to hold the result.
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
H5Tequal(
hid_t dtype_id1,
hid_t dtype_id2
)
H5Tequal determines whether two datatype identifiers
refer to the same datatype.
hid_t dtype_id1 |
Identifier of datatype to compare. |
hid_t dtype_id2 |
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 |
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
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. |
hid_t dtype_id |
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 of padding type are:
! H5T_CSET_ASCII_F = 0
INTEGER, INTENT(OUT) :: hdferr ! Error code
END SUBROUTINE h5tget_cset_f
H5Tget_ebias(
hid_t dtype_id
)
H5Tget_ebias retrieves the exponent bias of a floating-point type.
hid_t dtype_id |
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 |
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 |
Identifier of datatype to query. |
const char * field_name |
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.
A buffer to receive the name of the field is
allocated with malloc() and the caller is responsible
for freeing the memory used.
hid_t tdype_id |
Identifier of datatype to query. |
unsigned field_idx |
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 |
membno 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 data type datum.
hid_t dtype_id |
Identifier of datatype to query. |
unsigned memb_no |
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 |
Identifier of datatype to query. |
unsigned field_idx |
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.
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
IN