The C Interfaces:
Struct:
| * These functions have been deprecated. | |||
Fortran2003
Derived Type:
|
||||
Accessing objects by location and name:
To work with an HDF5 object, an application needs the object's location identifier. An object's location identifier is returned to an application after the object is opened.
To open an object, an application uses a function with three parameters:
the location identifier of an already opened object, a path from the already
opened object to the object that will be opened, and a property list. The
location identifier of an already opened object is its loc_id.
An already opened object might be a file or a group. The path from the
already opened object to the object that will be opened is kept in
the name parameter. The path will be one or more links.
For the rest of this discussion, we will assume that the default property
list, H5P_DEFAULT, is used.
See the HDF5 Reference Manual entries for the H5Dopen,
H5Gopen, H5Oopen, and H5Topen
functions for more information on opening datasets, groups, objects, and
datatypes.
loc_id. loc_id is short for
location identifier. The path from the identifer is
*
??????? The process of identifying an object is to specify a path to the object from a known location.
Suppose we wanted to read the dataset that is the target of the
dset3 link in the figure below. The H5Dread
function call needs an identifier for the dataset. How does an application
go about getting that identifier?
The identifier that is returned from this process
can then be used when the object is operated on.
The loc_id and name
parameters are used in many HDF5 function calls to specify a known
location
???????
Many HDF5 function calls use a combination of a location and name to identify an HDF5 object.
The location will be specified by a location identifier, loc_id,
and will be an HDF5 file or object such as a group, dataset, or committed
datatype*.
The name parameter, name, will be a character string and
will specify the links to an object in an HDF5 file.
The link or links to the object will be either an absolute path
or a relative path. An absolute path will include all of the links from
the root group to the object. A relative path will include all of the
links from any other group to the object.
|
|
| Figure 1: File structure for DATA_FILE1 |
Several loc_id and name combinations are
possible. To illustrate, the following combinations all identify
dset3 in the file structure in the figure.
loc_id is a file identifier,
name must specify the object from the file’s
root group.
loc_id specifies the file DATA_FILE1.
name = '/group2/group3/dset3'
loc_id is a group identifier
and the object of interest is a member of that group,
name will simply be the name of the link to the object.
loc_id specifies group3.
name = 'dset3'
loc_id is a group identifier
but the object of interest is not a direct member of that group,
name would specify the object by a path relative
to that group.
loc_id specifies group2.
name = 'group3/dset3'
Alternatively, name could specify the object
with an absolute path in the file containing loc_id.
loc_id specifies group2.
name = '/group2/group3/dset3'
loc_id is the identifier of the object itself,
name should be a dot ( . ).
For those familiar with a UNIX shell, this works in much the
same manner as a dot ( . )
specifying the current working directory.
loc_id specifies dset3, the dataset itself.
name = '.'
Many HDF5 functions accept loc_id and name
in all of the above combinations.
When accepted combinations are limited for a specific function,
the limitations are mentioned in the function’s reference manual entry.
For a related discussion of the structure of HDF5 files and HDF5 path names, see “The Structure of an HDF5 File” (particularly the sub-section “HDF5 Path Names and Navigation”) in the “HDF5 Data Model and File Structure” chapter of the HDF5 User’s Guide.
* In the past, a committed datatype was known as a named datatype.
herr_t H5Oare_mdc_flushes_enabled(
hid_t object_id,
hbool_t *are_disabled
)H5O/H5Fenable/disable_mdc_flushes() and associated
H5Xflush() functions can be used to control the flushing
of entries from a file’s metadata cache. Metadata cache entries
can be controlled at both the individual HDF5 object level (datasets,
groups, committed datatypes) and the entire metadata cache level.
hid_t identifiers that represent these objects
can be passed to the function.
Passing in a hid_t identifier that represents any
other HDF5 entity is considered an error.
It is an error to pass an HDF5 file identifier (obtained from
H5Fopen() or H5Fcreate()) to this function.
Use H5Fare_mdc_flushes_disabled instead.
hid_t object_id |
IN: Identifier of an object in the cache (See the above notes for restrictions). |
hbool_t *are_disabled |
OUT: Flushes enabled/disabled. |
are_disabled will be set to
TRUE if an object has had flushes disabled and
FALSE if it has not had flushes disabled.
Returns a non-negative value if successful; otherwise returns a negative value.
| Release | Change |
| 1.10.0 | C function introduced with this release. |
H5Oclose(
hid_t object_id
)
H5Oclose closes the group, dataset, or named datatype
specified by object_id.
This function is the companion to H5Oopen,
and has the same effect as calling H5Gclose,
H5Dclose, or H5Tclose.
H5Oclose is not used to close a
dataspace, attribute, property list, or file.
hid_t object_id
|
IN: Object identifier |
SUBROUTINE h5oclose_f(object_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: object_id
INTEGER , INTENT(OUT) :: hdferr
Inputs:
object_id - Object identifier.
Outputs:
hdferr - Returns 0 if successful and -1 if fails.
| Release | C |
| 1.8.8 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
H5Ocopy(
hid_t src_loc_id,
const char *src_name,
hid_t dst_loc_id,
const char *dst_name,
hid_t ocpypl_id,
hid_t lcpl_id
)
H5Ocopy copies the group, dataset or committed datatype
specified by src_name
from the file or group specified by src_loc_id
to the destination location dst_loc_id.
The destination location, as specified in dst_loc_id,
may be a group in the current file or a location in a different file.
If dst_loc_id is a file identifier, the copy will
be placed in that file’s root group.
The copy will be created with the path specified in
dst_name, which must not pre-exist in the destination
location. If dst_name already exists at the location
dst_loc_id, H5Ocopy will fail.
If dst_name is an absolute path,
the copy will be created relative to the file’s root group.
The copy of the object is created with the creation property lists
specified by ocpypl_id and lcpl_id.
H5Ocopy will always try to make a copy of the object
specified in src_name.
src_name is a
group containing a soft or external link,
the default is that the new copy will contain a
soft or external link with the same value as the original.
See
H5Pset_copy_object for optional settings.
src_name
is or contains a soft link or an external link,
H5Ocopy will copy the target object.
Use H5Lcopy
if the intent is to create a new soft or external link
with the same value as the original link.
Several flags are available to govern the behavior of
H5Ocopy:
lcpl_id with
H5Pset_create_intermediate_group.
H5Pset_copy_object,
H5Padd_merge_committed_dtype_path,
H5Pset_mcdt_search_cb,
and related functions.
ocpypl_id with
H5Pset_copy_object.
H5Ocopy can be used to copy an object in an HDF5 file.
If an object has been changed since it was opened, it should be
written back to the file before using H5Ocopy. The
object can be written back either by closing the object
(H5Gclose,
H5Oclose,
H5Dclose,
or H5Tclose)
or by flushing the HDF5 file
(H5Fflush).
hid_t src_loc_id
|
IN: Object identifier indicating the location of the source object to be copied |
const char *src_name
|
IN: Name of the source object to be copied |
hid_t dst_loc_id
|
IN: Location identifier specifying the destination |
const char *dst_name
|
IN: Name to be assigned to the new copy |
hid_t ocpypl_id
|
IN: Object copy property list |
hid_t lcpl_id
|
IN: Link creation property list for the new hard link |
H5Pset_copy_object
H5Pset_create_intermediate_group
|
H5Padd_merge_committed_dtype_path
H5Pset_mcdt_search_cb
|
|
Copying Committed Datatypes with H5Ocopy
|
A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5 |
SUBROUTINE h5ocopy_f(src_loc_id, src_name, dst_loc_id, &
dst_name, hdferr, ocpypl_id, lcpl_id)
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: src_loc_id
CHARACTER(LEN=*), INTENT(IN) :: src_name
INTEGER(HID_T) , INTENT(IN) :: dst_loc_id
CHARACTER(LEN=*), INTENT(IN) :: dst_name
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN), OPTIONAL :: ocpypl_id
INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lcpl_id
Inputs:
src_loc_id - Object identifier indicating the location of the
source object to be copied.
src_name - Name of the source object to be copied.
dst_loc_id - Location identifier specifying the destination.
dst_name - Name to be assigned to the new copy.
Outputs:
hdferr - Returns 0 if successful and -1 if fails.
Optional parameters:
ocpypl_id - Object copy property list. lcpl_id - Link creation property list for the new hard link.
| Release | C |
| 1.8.0 | Function introduced in this release. |
| 1.8.9 | Fortran subroutine introduced in this release. |
H5Odecr_refcount(
hid_t object_id
)
H5Odecr_refcount decrements the hard link reference count
for an object. It should be used any time a user-defined link
that references an object by address is deleted.
In general, H5Oincr_refcount will have been used
previously, when the link was created.
An object’s reference count is the number of hard links in the file that point to that object. See the “Programming Model” section of the “HDF5 Groups” chapter in the HDF5 User’s Guide for a more complete discussion of reference counts.
If a user application needs to determine an object’s
reference count, an
H5Oget_info
call is required; the reference count is returned in the
rc field of the H5O_info_t struct.
|
Warning: This function must be used with care!
Improper use can lead to inaccessible data, wasted space in the file, or file corruption. |
hid_t object_id
|
IN: Object identifier |
SUBROUTINE h5odecr_refcount_f(object_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: object_id
INTEGER , INTENT(OUT) :: hdferr
Inputs:
object_id - Object identifier.
Outputs:
hdferr - Returns 0 if successful and -1 if fails.
| Release | Change |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
herr_t H5Odisable_mdc_flushes(
hid_t object_id
)
H5O/H5Fenable/disable_mdc_flushes() and associated
H5Xflush() functions can be used to control the flushing
of entries from a file’s metadata cache.
This function prevents an object’s or cache’s
dirty metadata entries from being flushed from the cache by the usual
cache eviction/flush policy. Instead, users must manually flush
the cache or entries for individual objects via the appropriate
H5F/H5D/H5G/H5T/H5Oflush() calls.
Metadata cache entries can be controlled at both the individual HDF5 object level (datasets, groups, committed datatypes) and the entire metadata cache level.
hid_t identifiers that represent these objects
can be passed to this function.
Passing in a hid_t identifier that represents any
other HDF5 entity is considered an error.
It is an error to pass an HDF5 file identifier (obtained from
H5Fopen() or H5Fcreate()) to this function.
Use H5Fdisable_mdc_flushes instead.
Misuse of this function can cause the cache to exhaust available memory.
Objects can be returned to the default automatic flush behavior
with H5Oenable_mdc_flushes().
Flush prevention only pertains to new or dirty metadata entries. Clean entries can be evicted from the cache.
Calling this function on an object that has already had flushes disabled will return an error.
hid_t object_id
|
IN: Identifier of the object that will have flushes
disabled.
See the above notes for restrictions. |
| Release | Change |
| 1.10.0 | C function introduced with this release. |
herr_t H5Oenable_mdc_flushes(
hid_t object_id
)H5O/H5Fenable/disable_mdc_flushes() and associated
H5Xflush() functions can be used to control the flushing
of entries from a file’s metadata cache.
This function allows an object or cache’s dirty metadata entries to be flushed from the cache by the usual cache eviction/flush policy.
Metadata cache entries can be controlled at both the individual HDF5 object level (datasets, groups, committed datatypes) and the entire metadata cache level.
hid_t identifiers that represent these objects
can be passed to the function.
Passing in an hid_t identifier that represents any
other HDF5 entity is considered an error.
It is an error to pass an HDF5 file identifier (obtained from
H5Fopen() or H5Fcreate()) to this function.
Use H5Fenable_mdc_flushes instead.
Using this function on an object that has not had flushes disabled
is considered an error. The state of an object can be determined with
H5Oare_flushes_disabled().
Individual objects can be returned to the default flush algorithm
with this function after H5Fdisable_mdc_flushes() has
been used to globally prevent flushes.
An object will be returned to the default flush algorithm when it is closed.
All objects will be returned to the default flush algorithm when the file is closed.
An object’s entries will not necessarily be flushed as a result of calling this function.
hid_t object_id
|
IN: Identifier of the object that will have flushes
re-enabled.
See the above notes for restrictions. |
| Release | Change |
| 1.10.0 | C function introduced with this release. |
H5Oexists_by_name(
hid_t loc_id,
const char * name,
hid_t lapl_id
)
H5Oexists_by_name
is used by an application to check that an existing link resolves
to an object. Primarily, it is designed to check for dangling
soft, external, or user-defined links.
H5Oexists_by_name allows an application to determine
whether the link name in the group or file specified
with loc_id resolves to an HDF5 object to open or
if the link dangles. The link may be of any type, but hard links
will always resolve to objects and do not need to be verified.
Note that H5Oexists_by_name verifies only that the target
object exists.
If name includes either a relative path or
an absolute path to the target link, intermediate steps along the
path must be verified before the existence of the target link
can be safely checked.
If the path is not verified and an intermediate element of the path
does not exist, H5Oexists_by_name will fail.
The example in the next paragraph illustrates one step-by-step
method for verifying the existence of a link with a relative
or absolute path.
Example: Use the following steps to verify the existence
of the link datasetD
in the group group1/group2/softlink_to_group3/,
where group1 is a member of
the group specified by loc_id:
H5Lexists to verify that
a link named group1 exists.
group1 exists,
use H5Oexists_by_name to verify that
the link group1 resolves to an object.
group1 exists,
use H5Lexists again, this time
with name set to group1/group2,
to verify that the link group2 exists
in group1.
group2 link exists,
use H5Oexists_by_name to verify that
group1/group2 resolves to an object.
group2 exists,
use H5Lexists again,
this time with name set to
group1/group2/softlink_to_group3,
to verify that the link softlink_to_group3 exists
in group2.
softlink_to_group3 link exists,
use H5Oexists_by_name to verify that
group1/group2/softlink_to_group3 resolves to
an object.
softlink_to_group3 exists,
you can now safely use H5Lexists
with name set to
group1/group2/softlink_to_group3/datasetD
to verify that the target link, datasetD, exists.
datasetD exists,
use H5Oexists_by_name to verify that
group1/group2/softlink_to_group3/datasetD
resolves to an object.
If the link to be verified is specified with an absolute path,
the same approach should be used, but starting with the
first link in the file’s root group.
For instance, if datasetD were in
/group1/group2/softlink_to_group3, the first call to
H5Lexists would have name set to
/group1.
Note that this is an outline and does not include all necessary details. Depending on circumstances, for example, an application may need to verify the type of an object also.
hid_t loc_id
| IN: Identifier of the file or group to query. | |
const char *name
| IN: The name of the link to check. | |
hid_t lapl_id
| IN: Link access property list identifier. |
loc_id and name combination exists.
loc_id and
name combination does not exist.
loc_id and name both exist but the
combination does not resolve to an object, the function will return
0 (zero); the function does not fail in this case.
If either the location or the link specified by the
loc_id and name combination does not
exist, the function will fail, returning a negative value.
Note that verifying the existence of an object within an HDF5
file is a multistep process. An application can be certain the
object does not exist only if H5Lexists and
H5Oexists_by_name have been used to verify the
existence of the links and groups in the hierarchy above that object.
The example above, in the function description, provides a
step-by-step description of that verification process.
H5Lexists
“Discovering Objects in a Group” in the “Groups” chapter of the HDF5 User’s Guide
SUBROUTINE h5oexists_by_name_f(loc_id, name, link_exists, &
hdferr, lapl_id)
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*), INTENT(IN) :: name
LOGICAL , INTENT(OUT) :: link_exists
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lapl_id
Inputs:
loc_id - Identifier of the file or group to query. name - The name of the link to check.
Outputs:
link_exists - Existing link resolves to an object. hdferr - Returns 0 if successful and -1 if fails.
Optional parameters:
lapl_id - Link access property list identifier.
| Release | Change |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.5 | C function introduced in this release. |
herr_t H5Oflush(hid_t object_id)
H5Oflush causes all buffers associated with an
object to be immediately flushed to disk without removing the
data from the cache.
object_id can be any named object associated with an
HDF5 file including a dataset, a group, or a committed datatype.
H5Oflush flushes the internal HDF5 buffers and then
asks the operating system (the OS) to flush the system buffers
for the open files. After that, the OS is responsible for
ensuring that the data is actually flushed to disk.
hid_t object_id
|
IN: Identifier of the object to be flushed. |
| Release | Change |
| 1.10.0 | C function introduced with this release. |
H5Oget_comment(
hid_t object_id,
char *comment,
size_t bufsize
)
H5Oget_comment retrieves the comment for the
specified object in the buffer comment.
The target object is specified by an identifier, object_id.
The size in bytes of the buffer comment, including
the NULL terminator, is specified in
bufsize. If bufsize is unknown,
a preliminary H5Oget_comment call
with the pointer comment set to NULL
will return the size of the comment
without the NULL terminator.
If bufsize is set to a smaller value than described above,
only bufsize bytes of the comment,
without a NULL terminator, are returned in
comment.
If an object does not have a comment, the empty string
is returned in comment.
hid_t object_id |
IN: Identifier for the target object. |
char *comment |
OUT: The comment. |
size_t bufsize |
IN: Anticipated required size of the
comment buffer. |
NULL terminator,
or zero (0) if the object has no comment.
The value returned may be larger than bufsize.
Otherwise returns a negative value.
SUBROUTINE h5oget_comment_f(obj_id, comment, &
hdferr, bufsize)
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: obj_id
CHARACTER(LEN=*) , INTENT(OUT) :: comment
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HSSIZE_T), INTENT(OUT), OPTIONAL :: bufsize
Inputs:
obj_id - Identifier for the target object.
Outputs:
comment - The comment. hdferr - Returns 0 if successful and -1 if fails.
Optional parameters:
bufsize - Size of the comment buffer.
| Release | C |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
H5Oget_comment_by_name(
hid_t loc_id,
const char *name,
char *comment,
size_t bufsize,
hid_t lapl_id
)
H5Oget_comment_by_name retrieves the comment for an
object in the buffer comment.
The target object is specified by loc_id and
name.
loc_id can specify any object in the file.
name can be one of the following:
— The name of the object relative to
loc_id
— An absolute name of the object,
starting from /, the file’s root group
— A dot (.),
if loc_id fully specifies the object
The size in bytes of the comment, including the NULL
terminator, is specified in bufsize.
If bufsize is unknown,
a preliminary H5Oget_comment_by_name call
with the pointer comment set to NULL
will return the size of the comment
without the NULL terminator.
If bufsize is set to a smaller value than described above,
only bufsize bytes of the comment,
without a NULL terminator, are returned in
comment.
If an object does not have a comment, the empty string
is returned in comment.
lapl_id contains a link access property list identifier.
A link access propety list can come into play when traversing links
to access an object.
hid_t loc_id |
IN: Identifier of a file, group, dataset, or named datatype. |
const char *name |
IN: Name of the object whose comment is to be
retrieved, specified as a path relative to loc_id.
name can be '.' (a dot) if loc_id
fully specifies the object for which the associated comment
is to be retrieved.
|
char *comment |
OUT: The comment. |
size_t bufsize |
IN: Anticipated required size of the
comment buffer. |
hid_t lapl_id |
IN: Link access property list identifier. |
NULL terminator,
or zero (0) if the object has no comment.
The value returned may be larger than bufsize.
Otherwise returns a negative value.
SUBROUTINE h5oget_comment_by_name_f(loc_id, name, &
comment, hdferr, bufsize, lapl_id)
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*), INTENT(IN) :: name
CHARACTER(LEN=*), INTENT(OUT) :: comment
INTEGER , INTENT(OUT) :: hdferr
INTEGER(SIZE_T) , INTENT(OUT), OPTIONAL :: bufsize
INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: lapl_id
Inputs:
loc_id - Identifier of a file, group, dataset, or named datatype.
name - Name of the object whose comment is to be retrieved,
specified as a path relative to loc_id.
Outputs:
comment - The comment. hdferr - Returns 0 if successful and -1 if fails.
Optional parameters:
bufsize - Size of the comment buffer.
| Release | C |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
H5Oget_info(
hid_t object_id,
H5O_info_t *object_info
)
H5Oget_info specifies an object by its identifier,
object_id, and retrieves the metadata describing that object
in object_info, an H5O_info_t struct.
An H5O_info_t struct is defined (in H5Opublic.h)
as follows :
typedef struct H5O_info_t {
unsigned long fileno; /* Number of file where object is */
/* located */
haddr_t addr; /* Object address in file */
H5O_type_t type; /* Basic object type */
/* (See H5O_type_t below) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* # of attributes attached to object */
H5O_hdr_info_t hdr /* Object header information */
/* (See H5O_hdr_info_t below) */
struct {
/* Extra metadata storage for obj & */
/* attributes */
H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal heap */
/* for groups, B-tree for chunked */
/* datasets. */
/* For internal library use only. */
H5_ih_info_t attr; /* v2 B-tree & heap for attributes. */
/* For internal library use only. */
} meta_size;
} H5O_info_t;
Note the following about H50_info_t:
Of the four time fields (atime, mtime,
ctime, and btime) only ctime
has been implemented.
The atime value is the last time the object was read
or written.
The mtime value is the last time the raw data in
the object was changed.
The ctime value is the last time the metadata for
the object was changed.
The btime value is the time the object was created.
The fields nested in the meta_size field are for
internal library use only.
An H5O_type_t enum indicates the object type and is defined
(in H5Opublic.h) as follows:
typedef enum H5O_type_t {
H5O_TYPE_UNKNOWN = -1, /* Unknown object type */
H5O_TYPE_GROUP, /* Object is a group */
H5O_TYPE_DATASET, /* Object is a dataset */
H5O_TYPE_NAMED_DATATYPE, /* Object is a committed (named) datatype */
H5O_TYPE_NTYPES /* Number of different object types (must */
/* be last!) */
} H5O_type_t;
Note that object_id refers only to the types
specified by H5O_type_t.
An H5O_hdr_info_t struct holds object header metadata and is
defined (in H5Opublic.h) as follows:
typedef struct H5O_hdr_info_t {
unsigned version; /* Version number of header format in file */
unsigned nmesgs; /* Number of object header messages */
unsigned nchunks; /* Number of object header chunks */
unsigned flags; /* Object header status flags */
struct {
hsize_t total; /* Total space for storing object header in */
/* file */
hsize_t meta; /* Space within header for object header */
/* metadata information */
hsize_t mesg; /* Space within header for actual message */
/* information */
hsize_t free; /* Free space within object header */
} space;
struct {
uint64_t present; /* Flags to indicate presence of message */
/* type in header */
uint64_t shared; /* Flags to indicate message type is */
/* shared in header */
} mesg;
} H5O_hdr_info_t;
Valid values for the version field are
H5O_VERSION_1 and H5O_VERSION_2.
Version 2 of the object header is smaller and more efficient
than version 1.
Note that the information held by H5O_hdr_info_t might be useful only to developers with extensive HDF5 experience.
hid_t object_id |
IN: Identifier for object of type specified
by H5O_type_t |
H5O_info_t *object_info |
OUT: Buffer in which to return object information |
SUBROUTINE h5oget_info_f(object_id, object_info, hdferr)
USE, INTRINSIC :: ISO_C_BINDING
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: object_id
TYPE(h5o_info_t), INTENT(OUT), TARGET :: object_info
INTEGER , INTENT(OUT) :: hdferr
Inputs:
object_id - Identifier for target object.
Outputs:
object_info - Buffer in which to return object information. hdferr - Returns 0 if successful and -1 if fails.
Related Fortran2003 Derived Type: h5o_info_t
TYPE, BIND(C) :: space_t
INTEGER(hsize_t) :: total ! Total space for storing object header in file
INTEGER(hsize_t) :: meta ! Space within header for object header metadata
! information
INTEGER(hsize_t) :: mesg ! Space within header for actual message
! information
INTEGER(hsize_t) :: free ! Free space within object header
END TYPE space_t
TYPE, BIND(C) :: mesg_t
INTEGER(c_int64_t) :: present ! Flags to indicate presence of message type
! in header
INTEGER(c_int64_t) :: shared ! Flags to indicate message type is shared
! in header
END TYPE mesg_t
TYPE, BIND(C) :: hdr_t
INTEGER :: version ! Version number of header format in file
INTEGER :: nmesgs ! Number of object header messages
INTEGER :: nchunks ! Number of object header chunks
INTEGER :: flags ! Object header status flags
TYPE(space_t) :: space
TYPE(mesg_t) :: mesg
END TYPE hdr_t
! Extra metadata storage for obj & attributes
TYPE, BIND(C) :: H5_ih_info_t
INTEGER(hsize_t) :: index_size ! btree and/or list
INTEGER(hsize_t) :: heap_size
END TYPE H5_ih_info_t
TYPE, BIND(C) :: meta_size_t
TYPE(H5_ih_info_t) :: obj ! v1/v2 B-tree & local/fractal heap for
! groups, B-tree for chunked datasets
TYPE(H5_ih_info_t) :: attr ! v2 B-tree & heap for attributes
ENDTYPE meta_size_t
TYPE, BIND(C) :: h5o_info_t
INTEGER(C_LONG) :: fileno ! File number that object is located in
INTEGER(haddr_t) :: addr ! Object address in file
INTEGER(C_INT) :: type ! Basic object type (group, dataset, etc.)
INTEGER :: rc ! Reference count of object
INTEGER, DIMENSION(8) :: atime ! Access time ! -- NOTE --
INTEGER, DIMENSION(8) :: mtime ! Modification time ! Returns an integer
INTEGER, DIMENSION(8) :: ctime ! Change time ! array as specified
INTEGER, DIMENSION(8) :: btime ! Birth time ! in Fortran intrinsic
! DATE_AND_TIME(VALUES)
INTEGER(hsize_t) :: num_attrs ! # of attributes attached to object
TYPE(hdr_t) :: hdr
TYPE(meta_size_t) :: meta_size
END TYPE h5o_info_t
| Release | Change |
| 1.8.15 |
Added a note about the valid values for the version
field in the H5O_hdr_info_t structure. |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.10 |
Added H5O_type_t structure to the Description section. Separated H5O_hdr_info_t structure from H5O_info_t in the Description section. Clarified the definition and implementation of the time fields. |
| 1.8.0 | Function introduced in this release. |
H5Oget_info_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_field,
H5_iter_order_t order,
hsize_t n,
H5O_info_t *object_info,
hid_t lapl_id
)
H5Oget_info_by_idx specifies a location,
loc_id;
a group name, group_name;
an index by which obects in that group are tracked,
index_field;
the order by which the index is to be traversed, order;
and an object’s position n within that index
and retrieves the metadata describing that object
in the struct object_info.
object_info, in which the object information is returned,
is a struct of type H5O_info_t. This struct type is
described in the H5Oget_info
function entry.
If loc_id fully specifies the group in which the object
resides, group_name can be a dot (.).
The link access property list, lapl_id,
is not currently used; it should be passed in as NULL.
hid_t loc_id |
IN: File or group identifier specifying location of group in which object is located |
const char *group_name |
IN: Name of group in which object is located |
H5_index_t index_field |
IN: Index or field that determines the order |
H5_iter_order_t order |
IN: Order within field or index |
hsize_t n |
IN: Object for which information is to be returned |
H5O_info_t *object_info |
OUT: Buffer in which to return object information |
hid_t lapl_id |
IN: Link access property list (Not currently used; pass as NULL.) |
SUBROUTINE h5oget_info_by_idx_f(loc_id, group_name, index_field, order, n, &
object_info, hdferr, lapl_id)
USE, INTRINSIC :: ISO_C_BINDING
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*), INTENT(IN) :: group_name
INTEGER , INTENT(IN) :: index_field
INTEGER , INTENT(IN) :: order
INTEGER(HSIZE_T), INTENT(IN) :: n
TYPE(h5o_info_t), INTENT(OUT), TARGET :: object_info
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: lapl_id
Inputs:
loc_id - File or group identifier specifying location of group
in which object is located.
group_name - Name of group in which object is located.
index_field - Index or field that determines the order.
order - Order within field or index.
n - Object for which information is to be returned
Outputs:
object_info - Buffer in which to return object information. hdferr - Returns 0 if successful and -1 if fails.
Optional parameters:
lapl_id - Link access property list. (Not currently used.)
Related Fortran2003 Derived Type: h5o_info_t
TYPE, BIND(C) :: space_t
INTEGER(hsize_t) :: total ! Total space for storing object header in file
INTEGER(hsize_t) :: meta ! Space within header for object header metadata
! information
INTEGER(hsize_t) :: mesg ! Space within header for actual message
! information
INTEGER(hsize_t) :: free ! Free space within object header
END TYPE space_t
TYPE, BIND(C) :: mesg_t
INTEGER(c_int64_t) :: present ! Flags to indicate presence of message type
! in header
INTEGER(c_int64_t) :: shared ! Flags to indicate message type is shared
! in header
END TYPE mesg_t
TYPE, BIND(C) :: hdr_t
INTEGER :: version ! Version number of header format in file
INTEGER :: nmesgs ! Number of object header messages
INTEGER :: nchunks ! Number of object header chunks
INTEGER :: flags ! Object header status flags
TYPE(space_t) :: space
TYPE(mesg_t) :: mesg
END TYPE hdr_t
! Extra metadata storage for obj & attributes
TYPE, BIND(C) :: H5_ih_info_t
INTEGER(hsize_t) :: index_size ! btree and/or list
INTEGER(hsize_t) :: heap_size
END TYPE H5_ih_info_t
TYPE, BIND(C) :: meta_size_t
TYPE(H5_ih_info_t) :: obj ! v1/v2 B-tree & local/fractal heap for
! groups, B-tree for chunked datasets
TYPE(H5_ih_info_t) :: attr ! v2 B-tree & heap for attributes
ENDTYPE meta_size_t
TYPE, BIND(C) :: h5o_info_t
INTEGER(C_LONG) :: fileno ! File number that object is located in
INTEGER(haddr_t) :: addr ! Object address in file
INTEGER(C_INT) :: type ! Basic object type (group, dataset, etc.)
INTEGER :: rc ! Reference count of object
INTEGER, DIMENSION(8) :: atime ! Access time ! -- NOTE --
INTEGER, DIMENSION(8) :: mtime ! Modification time ! Returns an integer
INTEGER, DIMENSION(8) :: ctime ! Change time ! array as specified
INTEGER, DIMENSION(8) :: btime ! Birth time ! in Fortran intrinsic
! DATE_AND_TIME(VALUES)
INTEGER(hsize_t) :: num_attrs ! # of attributes attached to object
TYPE(hdr_t) :: hdr
TYPE(meta_size_t) :: meta_size
END TYPE h5o_info_t
| Release | C |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
H5Oget_info_by_name(
hid_t loc_id,
const char *object_name,
H5O_info_t *object_info,
hid_t lapl_id
)
H5Oget_info_by_name specifies an object’s
location and name, loc_id and object_name,
respectively, and retrieves the metadata describing that object
in object_info, an H5O_info_t struct.
The struct H5O_info_t is defined in H5Opublic.h
and described in the
H5Oget_info function entry.
The link access property list, lapl_id,
is not currently used; it should be passed in as H5P_DEFAULT.
hid_t loc_id |
IN: File or group identifier specifying location of group in which object is located |
const char *name |
IN: Name of group, relative to
loc_id |
H5O_info_t *object_info |
OUT: Buffer in which to return object information |
hid_t lapl_id |
IN: Link access property list (Not currently used; pass as H5P_DEFAULT.) |
SUBROUTINE h5oget_info_by_name_f(loc_id, name, object_info, hdferr, &
lapl_id)
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*), INTENT(IN) :: name
TYPE(h5o_info_t), INTENT(OUT), TARGET :: object_info
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: lapl_id
Inputs:
loc_id - File or group identifier specifying location of group
in which object is located.
name - Name of group, relative to loc_id.
Outputs:
object_info - Buffer in which to return object information. hdferr - Returns 0 if successful and -1 if fails.
Optional parameters:
lapl_id - Link access property list.
Related Fortran2003 Derived Type: h5o_info_t
TYPE, BIND(C) :: space_t
INTEGER(hsize_t) :: total ! Total space for storing object header in file
INTEGER(hsize_t) :: meta ! Space within header for object header metadata
! information
INTEGER(hsize_t) :: mesg ! Space within header for actual message
! information
INTEGER(hsize_t) :: free ! Free space within object header
END TYPE space_t
TYPE, BIND(C) :: mesg_t
INTEGER(c_int64_t) :: present ! Flags to indicate presence of message type
! in header
INTEGER(c_int64_t) :: shared ! Flags to indicate message type is shared
! in header
END TYPE mesg_t
TYPE, BIND(C) :: hdr_t
INTEGER :: version ! Version number of header format in file
INTEGER :: nmesgs ! Number of object header messages
INTEGER :: nchunks ! Number of object header chunks
INTEGER :: flags ! Object header status flags
TYPE(space_t) :: space
TYPE(mesg_t) :: mesg
END TYPE hdr_t
! Extra metadata storage for obj & attributes
TYPE, BIND(C) :: H5_ih_info_t
INTEGER(hsize_t) :: index_size ! btree and/or list
INTEGER(hsize_t) :: heap_size
END TYPE H5_ih_info_t
TYPE, BIND(C) :: meta_size_t
TYPE(H5_ih_info_t) :: obj ! v1/v2 B-tree & local/fractal heap for
! groups, B-tree for chunked datasets
TYPE(H5_ih_info_t) :: attr ! v2 B-tree & heap for attributes
ENDTYPE meta_size_t
TYPE, BIND(C) :: h5o_info_t
INTEGER(C_LONG) :: fileno ! File number that object is located in
INTEGER(haddr_t) :: addr ! Object address in file
INTEGER(C_INT) :: type ! Basic object type (group, dataset, etc.)
INTEGER :: rc ! Reference count of object
INTEGER, DIMENSION(8) :: atime ! Access time ! -- NOTE --
INTEGER, DIMENSION(8) :: mtime ! Modification time ! Returns an integer
INTEGER, DIMENSION(8) :: ctime ! Change time ! array as specified
INTEGER, DIMENSION(8) :: btime ! Birth time ! in Fortran intrinsic
! DATE_AND_TIME(VALUES)
INTEGER(hsize_t) :: num_attrs ! # of attributes attached to object
TYPE(hdr_t) :: hdr
TYPE(meta_size_t) :: meta_size
END TYPE h5o_info_t
| Release | Change |
| 1.8.0 | C function introduced in this release. |
| 1.8.8 |
Fortran 2003 subroutine and h5o_info_t derived type
introduced in this release. |
H5Oincr_refcount(
hid_t object_id
)
H5Oincr_refcount increments the hard link reference count
for an object. It should be used any time a user-defined link
that references an object by address is added. When the
link is deleted, H5Odecr_refcount should be used.
An object’s reference count is the number of hard links in the file that point to that object. See the “Programming Model” section of the “HDF5 Groups” chapter in the HDF5 User’s Guide for a more complete discussion of reference counts.
If a user application needs to determine an object’s
reference count, an
H5Oget_info
call is required; the reference count is returned in the
rc field of the H5O_info_t struct.
|
Warning: This function must be used with care!
Improper use can lead to inaccessible data, wasted space in the file, or file corruption. |
hid_t object_id
|
IN: Object identifier |
SUBROUTINE h5oincr_refcount_f(obj_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: obj_id
INTEGER , INTENT(OUT) :: hdferr
Inputs:
obj_id - Object identifier.
Outputs:
hdferr - Returns 0 if successful and -1 if fails.
| Release | Change |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
H5Olink(
hid_t object_id,
hid_t new_loc_id,
const char *new_link_name,
hid_t lcpl,
hid_t lapl
)
H5Olink creates a new hard link to an object in
an HDF5 file.
new_loc_id and new_name specify the
location and name of the new link while object_id
identifies the object that the link points to.
H5Olink is designed for two purposes:
H5Dcreate_anon,
H5Gcreate_anon,
or
H5Tcommit_anon.
| |
|
|
lcpl and lapl are the
link creation and access property lists associated with the
new link.
hid_t object_id |
IN: Object to be linked. |
hid_t new_loc_id |
IN: File or group identifier specifying location at which object is to be linked. |
const char *new_link_name |
IN: Name of link to be created, relative to
new_loc_id. |
hid_t lcpl_id |
IN: Link creation property list identifier. |
hid_t lapl_id |
IN: Link access property list identifier. |
C
with the path /A/B01/C but may not know at run time
whether the groups A and B01 exist.
The following code ensures that those groups are created
if they are missing:
hid_t lcpl_id = H5Pcreate(H5P_LINK_CREATE);
/* Creates a link creation property
* list (LCPL). */
int status = H5Pset_create_intermediate_group(lcpl_id, TRUE);
/* Sets "create missing intermediate
* groups" property in that LCPL. */
hid_t gid = H5Gcreate_anon(file_id, H5P_DEFAULT, H5P_DEFAULT);
/* Creates a group without linking
* it into the file structure. */
status = H5Olink(obj_id, file_id, "/A/B01/C", lcpl_id, H5P_DEFAULT);
/* Links group into file structure.*/
Note that unless the object is intended to be temporary,
the H5Olink call is mandatory if an object created
with one of the H5*create_anon functions
(or with H5Tcommit_anon)
is to be retained in the file;
without an H5Olink call, the object will not be linked into
the HDF5 file structure and will be deleted when the file is closed.
SUBROUTINE h5olink_f(object_id, new_loc_id, new_link_name, &
hdferr, lcpl_id, lapl_id)
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: object_id
INTEGER(HID_T) , INTENT(IN) :: new_loc_id
CHARACTER(LEN=*), INTENT(IN) :: new_link_name
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lcpl_id
INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lapl_id
Inputs:
object_id - Object to be linked.
new_loc_id - File or group identifier specifying location at
which object is to be linked.
new_link_name - Name of link to be created, relative to new_loc_id.
Outputs:
hdferr - Returns 0 if successful and -1 if fails.
Optional parameters:
lcpl_id - Link creation property list identifier. lapl_id - Link access property list identifier.
H5Dcreate_anon
H5Gcreate_anon
H5Tcommit_anon
| Release | C |
| 1.8.1 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
H5Oopen(
hid_t loc_id,
const char *name,
hid_t lapl_id
)
H5Oopen opens a group, dataset, or
committed (named) datatype
specified by a location, loc_id, and a path name,
name, in an HDF5 file.
This function opens the object in the same manner as
H5Gopen, H5Topen, and H5Dopen.
However, H5Oopen does not require the type of object
to be known beforehand. This can be useful with user-defined links,
for instance, when only a path may be known.
H5Oopen cannot be used to open a
dataspace, attribute, property list, or file.
Once an object of unknown type has been opened with
H5Oopen, the type of that object can be determined
by means of an
H5Iget_type
call.
loc_id can be either a file or group identifier.
name must be the path to that object relative to
loc_id.
lapl_id is the link access property list associated
with the link pointing to the object. If default link access
properties are appropriate, this can be passed in as
H5P_DEFAULT.
When it is no longer needed, the opened object should be closed
with H5Oclose, H5Gclose,
H5Tclose, or H5Dclose.
hid_t loc_id
|
IN: File or group identifier |
const char *name
|
IN: Path to the object,
relative to loc_id.
|
hid_t lapl_id
|
IN: Access property list identifier for the link pointing to the object |
SUBROUTINE h5oopen_f(loc_id, name, obj_id, hdferr, lapl_id)
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*), INTENT(IN) :: name
INTEGER(HID_T) , INTENT(OUT) :: obj_id
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lapl_id
Inputs:
loc_id - File or group identifier. name - Path to the object, relative to loc_id.
Outputs:
obj_id - Object identifier for the opened object. hdferr - Returns 0 if successful and -1 if fails.
Optional parameters:
lapl_id - Access property list identifier for the
link pointing to the object.
| Release | C |
| 1.8.1 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
H5Oopen_by_addr(
hid_t loc_id,
haddr_t addr
)
H5Oopen_by_addr opens a group, dataset, or
committed (named) datatype
using its address within an HDF5 file, addr.
The resulting opened object is identical to an object opened with
H5Oopen and should be closed with H5Oclose
or an object-type-specific closing function
(such as H5Gclose) when no longer needed.
loc_id can be either the file identifier or a
group identifier in the file. In either case, the HDF5 Library
uses the identifier only to identify the file.
The object’s address within the file, addr, is the
byte offset of the first byte of the object header from the beginning
of the HDF5 file space, i.e., from the beginning of the super block
(see the “HDF5 Storage Model” section of the
“The
HDF5 Data Model and File Structure” chapter
of the HDF5 User’ Guide).
addr can be obtained via either of two function calls.
H5Gget_objinfo
returns the object’s address in the
objno field of the H5G_stat_t struct;
H5Lget_info
returns the address in the address field of the
H5L_linkinfo_t struct.
|
Warning: This function must be used with care!
Improper use can lead to inaccessible data, wasted space in the file, or file corruption.
This function is dangerous if called on an invalid address.
The risk can be safely overcome by retrieving the object address
with |
The address of the HDF5 file on a physical device has no effect on
H5Oopen_by_addr, nor does the use of any file driver.
As stated above, the object address is its offset within the HDF5 file;
HDF5’s file drivers will transparently map this to an address
on a storage device.
hid_t loc_id
|
IN: File or group identifier |
haddr_t addr
|
IN: Object’s address in the file |
SUBROUTINE h5oopen_by_addr_f(loc_id, addr, obj_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: loc_id
INTEGER(HADDR_T), INTENT(IN) :: addr
INTEGER(HID_T) , INTENT(OUT) :: obj_id
INTEGER , INTENT(OUT) :: hdferr
Inputs:
loc_id - File or group identifier. addr - Object's address in the file.
Outputs:
obj_id - Object identifier for the opened object. hdferr - Returns 0 if successful and -1 if fails.
| Release | Change |
| 1.8.0 | Function introduced in this release. |
| 1.8.4 | Fortran subroutine added in this release. |
H5Oopen_by_idx(
hid_t loc_id,
const char *group_name,
H5_index_t index_type,
H5_iter_order_t order,
hsize_t n,
hid_t lapl_id
)
H5Oopen_by_idx opens the nth object in
the group specified by loc_id and group_name.
loc_id specifies a file or group.
group_name specifies the group relative to
loc_id in which the object can be found.
If loc_id fully specifies the group in which the object
resides, group_name can be a dot (.).
The specific object to be opened within the group is specified
by index_type, order, and n
as follows:
index_type specifies the type of index
by which objects are ordered.
Valid index types include
H5_INDEX_NAME, indexed by name, and
H5_INDEX_CRT_ORDER, indexed by creation order.
order specifies the order in which the links
are to be referenced for the purposes of this function.
Valid orders include
H5_ITER_INC for increasing order,
H5_ITER_DEC for decreasing order, and
H5_ITER_NATIVE.
Rather than implying a particular order,
H5_ITER_NATIVE instructs the HDF5 Library
to iterate through the objects in the fastest available order,
i.e., in a natural order.
n specifies the position of the object within
the index. Note that this count is zero-based;
0 (zero) indicates that the function will return
the value of the first object;
if n is 5, the function will return
the value of the sixth object; etc.
If lapl_id specifies the link access property list
to be used in accessing the object.
An object opened with this function should be closed when
it is no longer needed so that resource leaks will not develop.
H5Oclose can be used to close groups, datasets,
or committed datatypes.
hid_t loc_id |
IN: A file or group identifier. |
const char *group_name |
IN: Name of group, relative to loc_id,
in which object is located |
H5_index_t index_type |
IN: Type of index by which objects are ordered |
H5_iter_order_t order |
IN: Order of iteration within index |
hsize_t n |
IN: Object to open |
hid_t lapl_id |
IN: Link access property list |
SUBROUTINE h5oopen_by_idx_f(loc_id, group_name, index_type, order, n, &
obj_id, hdferr, lapl_id)
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*), INTENT(IN) :: group_name
INTEGER , INTENT(IN) :: index_type
INTEGER , INTENT(IN) :: order
INTEGER(HSIZE_T), INTENT(IN) :: n
INTEGER(HID_T) , INTENT(OUT) :: obj_id
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: lapl_id
Inputs:
loc_id - A file or group identifier. group_name - Name of group, relative to loc_id, in which object is located. index_type - Type of index by which objects are ordered. order - Order of iteration within index, NOTE: zero-based. n - Object to open.
Outputs:
obj_id - An object identifier for the opened object. hdferr - Returns 0 if successful and -1 if fails.
Optional parameters:
lapl_id - Link access property list.
| Release | C |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
herr_t H5Orefresh(hid_t object_id)
H5Orefresh causes all buffers associated with an
object to be cleared and immediately re-loaded with updated
contents from disk.
object_id can be any named object associated
with an HDF5 file including a dataset, a group, or a committed
datatype.
hid_t object_id
|
IN: Identifier of the object to be refreshed. |
| Release | Change |
| 1.10.0 | C function introduced with this release. |
H5Oset_comment(
hid_t object_id,
const char *comment
)
H5Oset_comment sets the comment for
the specified object to the contents of comment.
Any previously existing comment is overwritten.
The target object is specified by an identifier, object_id.
If comment is the empty string or a
null pointer, any existing comment message is removed from the object.
Comments should be relatively short, null-terminated, ASCII strings.
Comments can be attached to any object that has an object header. Datasets, groups, and committed (named) datatypes have object headers. Symbolic links do not have object headers.
If a comment is being added to an object attribute, this comment will be attached to the object to which the attribute belongs and not to the attribute itself.
hid_t object_id |
IN: Identifier of the target object |
const char *comment |
IN: The new comment. |
SUBROUTINE h5oset_comment_f(obj_id, comment, hdferr)
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: obj_id
CHARACTER(LEN=*), INTENT(IN) :: comment
INTEGER , INTENT(OUT) :: hdferr
Inputs:
obj_id - Identifier of the target object. comment - The new comment.
Outputs:
hdferr - Returns 0 if successful and -1 if fails.
| Release | C |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
H5Oset_comment_by_name(
hid_t loc_id,
const char *name,
const char *comment,
hid_t lapl_id
)
H5Oset_comment_by_name sets the comment for the
specified object to the contents of comment.
Any previously existing comment is overwritten.
The target object is specified by loc_id and
name.
loc_id can specify any object in the file.
name can be one of the following:
— The name of the object relative to
loc_id
— An absolute name of the object,
starting from /, the file’s root group
— A dot (.),
if loc_id fully specifies the object
If comment is the empty string or a
null pointer, any existing comment message is removed from the object.
Comments should be relatively short, null-terminated, ASCII strings.
Comments can be attached to any object that has an object header. Datasets, groups, and committed (named) datatypes have object headers. Symbolic links do not have object headers.
If a comment is being added to an object attribute, this comment will be attached to the object to which the attribute belongs and not to the attribute itself.
lapl_id contains a link access property list identifier.
A link access property list can come into play when traversing links
to access an object.
hid_t loc_id |
IN: Identifier of a file, group, dataset, or named datatype. |
const char *name |
IN: Name of the object whose comment is to be
set or reset, specified as a path relative to loc_id.
name can be '.' (a dot) if loc_id
fully specifies the object for which the comment is to be set.
|
const char *comment |
IN: The new comment. |
hid_t lapl_id |
IN: Link access property list identifier. |
SUBROUTINE h5oset_comment_by_name_f(loc_id, name, comment, hdferr, &
lapl_id)
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*), INTENT(IN) :: name
CHARACTER(LEN=*), INTENT(IN) :: comment
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lapl_id
Inputs:
loc_id - Identifier of a file, group, dataset, or named datatype.
name - Name of the object whose comment is to be set or reset,
specified as a path relative to loc_id.
comment - The new comment.
Outputs:
hdferr - Returns 0 if successful and -1 if fails.
Optional parameters:
lapl_id - Link access property list identifier.
| Release | C |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
H5Ovisit(
hid_t object_id,
H5_index_t index_type,
H5_iter_order_t order,
H5O_iterate_t op,
void *op_data
)
H5Ovisit is a recursive iteration function
to visit the object object_id and,
if object_id is a group,
all objects in and below it in an HDF5 file,
thus providing a mechanism for an application to perform
a common set of operations across all of those objects
or a dynamically selected subset.
For non-recursive iteration across the members of a group,
see H5Literate.
If object_id is a group identifier,
that group serves as the root of a recursive iteration.
If object_id is a file identifier, that file’s
root group serves as the root of the recursive iteration.
If object_id is any other type of object,
such as a dataset or named datatype, there is no iteration.
Two parameters are used to establish the iteration:
index_type and order.
index_type specifies the index to be used.
If the links in a group have not been indexed by the index type,
they will first be sorted by that index then the iteration will begin;
if the links have been so indexed, the sorting step will be
unnecesary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
Note that the index type passed in index_type is a
best effort setting.
If the application passes in a value indicating iteration in
creation order and a group is encountered that was not tracked
in creation order, that group will be iterated over in
alpha-numeric order by name, or name order.
(Name order is the native order used by the HDF5 Library
and is always available.)
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
The protoype of the callback function op is as follows
(as defined in the source code file H5Opublic.h):
(*H5O_iterate_t)(
hid_t o_id,
const char *name,
const H5O_info_t *object_info,
void *op_data)
The parameters of this callback function have the following values or meanings:
|
o_id
|
Object that serves as root of the iteration; same value
as the H5Ovisit object_id parameter
|
|
name
|
Name of object, relative to o_id,
being examined at current step of the iteration
|
|
object_info
| H5O_info_t struct containing information regarding that object |
|
op_data
|
User-defined pointer to data required by the application
in processing the object;
a pass-through of the op_data pointer provided
with the H5Ovisit_by_name function call
|
The H5O_info_t struct is defined in H5Opublic.h
and described in the
H5Oget_info function entry.
The return values from an operator are:
The H5Ovisit op_data parameter is a
user-defined pointer to the data required to process objects
in the course of the iteration.
This pointer is passed back to each step of the iteration in
the callback function’s op_data parameter.
H5Lvisit and
H5Ovisit are companion functions:
one for examining and operating on links;
the other for examining and operating on the objects that
those links point to.
Both functions ensure that by the time the function completes
successfully, every link or object below the specified point in the
file has been presented to the application for whatever
processing the application requires.
These functions assume that the membership of the group being iterated
over remains unchanged through the iteration; if any of the links in the
group change during the iteration, the resulting behavior is undefined.
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 object_id
|
IN: Identifier of the object at which the recursive iteration begins. |
H5_index_t index_type
|
IN: Type of index; valid values include:
H5_INDEX_NAME
H5_INDEX_CRT_ORDER
|
H5_iter_order_t order
|
IN: Order in which index is traversed;
valid values include:
H5_ITER_DEC
H5_ITER_INC
H5_ITER_NATIVE
|
H5O_iterate_t op
|
IN: Callback function passing data regarding the object to the calling application |
void *op_data
|
IN: User-defined pointer to data required by the application for its processing of the object |
On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.
SUBROUTINE h5ovisit_f(object_id, index_type, order, op, op_data, &
return_value, hdferr)
INTEGER(HID_T), INTENT(IN) :: object_id
INTEGER, INTENT(IN) :: index_type
INTEGER, INTENT(IN) :: order
TYPE(C_FUNPTR):: op
TYPE(C_PTR) :: op_data
INTEGER, INTENT(OUT) :: return_value
INTEGER, INTENT(OUT) :: hdferr
Inputs:
object_id - Identifier of the object at which the recursive iteration
begins.
index_type - Type of index; valid values include:
H5_INDEX_NAME_F
H5_INDEX_CRT_ORDER_F
order - Order in which index is traversed; valid values include:
H5_ITER_DEC_F
H5_ITER_INC_F
H5_ITER_NATIVE_F
op - Callback function passing data regarding the group to the
calling application
op_data - User-defined pointer to data required by the application
for its processing of the group
Outputs:
return_value - Returns the return value of the first operator that
returns a positive value, or zero if all members were
processed with no operator returning non-zero.
hdferr - Returns 0 if successful and -1 if fails.
| Release | Change |
| 1.8.8 | Fortran subroutine and data structure added. |
| 1.8.0 | C function introduced. |
H5Ovisit_by_name(
hid_t loc_id,
const char *object_name,
H5_index_t index_type,
H5_iter_order_t order,
H5O_iterate_t op,
void *op_data,
hid_t lapl_id
)
H5Ovisit_by_name is a recursive iteration function
to visit the object specified by the loc_id /
object_name parameter pair and, if that object is a group,
all objects in and below it in an HDF5 file,
thus providing a mechanism for an application to perform
a common set of operations across all of those objects
or a dynamically selected subset.
For non-recursive iteration across the members of a group,
see H5Literate.
The object serving as the root of the iteration is specified by
the loc_id / object_name parameter pair.
loc_id specifies a file or an object in a file;
object_name specifies either
an object in the file (with an absolute name based in the
file’s root group) or
an object name relative to loc_id.
If loc_id fully specifies the object that is to
serve as the root of the iteration, object_name should
be '.' (a dot).
(Note that when loc_id fully specifies the the
object that is to serve as the root of the iteration,
the user may wish to consider using
H5Ovisit
instead of H5Ovisit_by_name.)
Two parameters are used to establish the iteration:
index_type and order.
index_type specifies the index to be used.
If the links in a group have not been indexed by the index type,
they will first be sorted by that index then the iteration will begin;
if the links have been so indexed, the sorting step will be
unnecesary, so the iteration may begin more quickly.
Valid values include the following:
H5_INDEX_NAME
| Alpha-numeric index on name | |
H5_INDEX_CRT_ORDER
| Index on creation order |
Note that the index type passed in index_type is a
best effort setting.
If the application passes in a value indicating iteration in
creation order and a group is encountered that was not tracked
in creation order, that group will be iterated over in
alpha-numeric order by name, or name order.
(Name order is the native order used by the HDF5 Library
and is always available.)
order specifies the order in which objects are to be
inspected along the index specified in index_type.
Valid values include the following:
H5_ITER_INC
| Increasing order | |
H5_ITER_DEC
| Decreasing order | |
H5_ITER_NATIVE
| Fastest available order |
The op callback funtion
and the effect of the callback function’s return value
on the application are described in
H5Ovisit.
The H5O_info_t struct is defined in H5Opublic.h
and described in the
H5Oget_info function entry.
The H5Ovisit_by_name op_data parameter is a
user-defined pointer to the data required to process objects
in the course of the iteration.
This pointer is passed back to each step of the iteration in
the callback function’s op_data parameter.
lapl_id is a link access property list.
In the general case, when default link access properties are
acceptable, this can be passed in as H5P_DEFAULT.
An example of a situation that requires a non-default link access
property list is when the link is an external link; an external link
may require that a link prefix be set in a link access property list
(see
H5Pset_elink_prefix).
H5Lvisit_by_name
and H5Ovisit_by_name are companion functions:
one for examining and operating on links;
the other for examining and operating on the objects that
those links point to.
Both functions ensure that by the time the function completes
successfully, every link or object below the specified point in the
file has been presented to the application for whatever
processing the application requires.
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 loc_id
|
IN: Identifier of a file or group |
const char *object_name
|
IN: Name of the object,
generally relative to loc_id,
that will serve as root of the iteration
|
H5_index_t index_type
|
IN: Type of index; valid values include:
H5_INDEX_NAME
H5_INDEX_CRT_ORDER
|
H5_iter_order_t order
|
IN: Order in which index is traversed;
valid values include:
H5_ITER_DEC
H5_ITER_INC
H5_ITER_NATIVE
|
H5O_iterate_t op
|
IN: Callback function passing data regarding the object to the calling application |
void *op_data
|
IN: User-defined pointer to data required by the application for its processing of the object |
hid_t lapl_id
|
IN: Link access property list identifier |
On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.
SUBROUTINE h5ovisit_by_name_f(loc_id, object_name, index_type, order, &
op, op_data, return_value, hdferr, lapl_id)
USE, INTRINSIC :: ISO_C_BINDING
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*), INTENT(IN) :: object_name
INTEGER , INTENT(IN) :: index_type
INTEGER , INTENT(IN) :: order
TYPE(C_FUNPTR) :: op
TYPE(C_PTR) :: op_data
INTEGER , INTENT(OUT) :: return_value
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: lapl_id
Inputs:
loc_id - Identifier of a file or group.
object_name - Name of the object, generally relative to loc_id, that will
serve as root of the iteration
index_type - Type of index; valid values include:
H5_INDEX_NAME_F
H5_INDEX_CRT_ORDER_F
order - Order in which index is traversed; valid values include:
H5_ITER_DEC_F
H5_ITER_INC_F
H5_ITER_NATIVE_F
op - Callback function passing data regarding the group to the
calling application
op_data - User-defined pointer to data required by the application for
its processing of the group
Outputs:
return_value - Returns the return value of the first operator that returns
a positive value, or zero if all members were processed with
no operator returning non-zero.
hdferr - Returns 0 if successful and -1 if fails
Optional parameters:
lapl_id - Link access property list identifier.
| Release | C |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
typedef H5O_mcdt_search_ret_t (
*H5O_mcdt_search_cb_t
)(
void *op_data
)
H5Ocopy
to take after checking all suggested paths for a matching committed datatype
but before starting the global search of the destination file.
H5O_mcdt_search_cb_t
is the callback function that
H5Ocopy
will invoke if the callback is set and
when the merge committed datatype feature is enabled
in the object copy property list (see
H5Pset_copy_object).
After searching the list of suggested committed datatype paths,
H5Ocopy
will invoke this callback before searching all committed datatypes
in the destination file. This allows a user application
to add a customized step to the search process.
The callback function is set with
H5Pset_mcdt_search_cb
and the search process is described in
H5Padd_merge_committed_dtype_path.
Valid return values from this callback function are as follows
(defined in the enumerated datatype
H5O_mcdt_search_ret_t in H5Opublic.h):
H5O_MCDT_SEARCH_ERROR
|
Aborts H5Ocopy.
|
|
H5O_MCDT_SEARCH_CONT
| Continues the global search of all committed datatypes in the destination file. | |
H5O_MCDT_SEARCH_STOP | Stops the search, but continues copying. |
H5O_MCDT_SEARCH_ERROR, H5Ocopy
will abort and the destination file may be left in an
inconsistent or corrupted state.
void *op_data
| IN/OUT: Pointer to user-defined input data. This is a pass-through
of the data that was passed to
H5Pset_mcdt_search_cb.
|
H5O_MCDT_SEARCH_* values described above.
H5O_mcdt_search_cb_t failure modes are dependent on the
implementation of the callback function.
/* The user-defined callback function */
static H5O_mcdt_search_ret_t
mcdt_search_cb(void *_udata)
{
H5O_mcdt_search_ret_t action = *((H5O_mcdt_search_ret_t *)_udata);
return(action);
}
int main(void) {
hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);
/* Enable the merging committed datatype feature. */
H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);
/* Add the path to search for a matching committed datatype. */
H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");
/*
* Set the callback function to discontinue the global search
* if H5Ocopy cannot find a matching committed datatype from the
* above suggested path.
*/
action = H5O_MCDT_SEARCH_STOP;
H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action);
/* Do the copy. */
H5Ocopy(...ocpypl_id...);
...
...
}
H5Ocopy
H5Pset_copy_object
|
H5Pset_mcdt_search_cb
H5Pget_mcdt_search_cb
|
|
Copying Committed Datatypes with H5Ocopy
|
A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5 |
| Release | Change |
| 1.8.9 | C function type introduced in this release. |
The HDF Group Help Desk: 
Describes HDF5 Release 1.10. |
Copyright by
The HDF Group
and the Board of Trustees of the University of Illinois |