Functions
H5O.are_mdc_flushes_disabled
Determine whether flushes of metadata entries are disabled (since
R2021b)
tf = H5O.are_mdc_flushes_disabled(objID)
returns true if an HDF5
object has had flushes of metadata entries disabled. The object identifier specified in
objID
must be the identifier for a dataset, group, or committed
datatype.
H5O.close
Close object
H5O.close(objID)
closes the object objID
. The
input objID
cannot be a dataspace, attribute, property list, or
file.
H5O.copy
Copy object from source location to destination location
H5O.copy(srcID,srcname,destID,destname,ocplID,lcplID)
copies the
dataset, group, or committed datatype specified by srcname
from the file
or group specified by srcID
to the destination location
destID
.
Details
Input Arguments
srcID
— Source group or file identifier.
srcname
— Name of the source file or group.
destID
— Identifier of a group in the current file, or
identifier of a different file. If destID
is a file identifier, the
copy is placed in the root group of destID
.
destname
— Name of the new copy of the group or file, and must
not pre-exist in the destination location. If destname
already
exists at the location destID
, the operation will fail.
ocplID
— Object creation property list identifier.
lcplID
— Link creation property list identifier.
H5O.disable_mdc_flushes
Prevent object or metadata entries from being flushed (since
R2021b)
H5O.disable_mdc_flushes(objID)
prevents metadata entries for an
object or cache objID
from the metadata cache to storage. 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, you must manually flush the cache or entries for individual objects using the
appropriate function:
H5F.flush
H5D.flush
H5G.flush
H5O.flush
H5T.flush
H5O.enable_mdc_flushes
Allow object or metadata entries to be flushed (since
R2021b)
H5O.enable_mdc_flushes(objID)
allows the dirty metadata entries of an
object or cache objID
to be flushed from the cache by the usual cache
eviction/flush policy. The input object identifier must be the identifier of a dataset,
group, or committed datatype.
H5O.flush
Flush all data buffers to disk (since R2021b)
H5O.flush(objID)
causes all buffers associated with the object
objID
to be immediately flushed to disk without removing the data from
the cache. The objID
can be any named object associated with a file
including a dataset, a group, or a committed datatype.
H5O.get_comment
Get comment for object specified by object identifier
comment = H5O.get_comment(objID)
retrieves the comment for the object
specified by objID
.
H5O.get_comment_by_name
Get comment for object location and object name
comment = H5O.get_comment_by_name(locID,objname,laplID)
retrieves a
comment where a location id and name together specify the object. A link access property
list can affect the outcome if a link is traversed to access the object.
H5O.get_info
Object metadata
info = H5O.get_info(objID)
retrieves the metadata for an object
specified by objID
. For details about the object metadata, please refer
to the HDF5 documentation.
H5O.get_info2
Object metadata from specified fields
info = H5O.flush(objID,fields)
retrieves the metadata for an object
specified by objID
using the parameter fields
.
If you are encountering performance issues using H5O.get_info
, using
H5O.get_info2
can help improve performance.
Details
Input Arguments
objID
— Object identifier.
fields
— Parameter that contains flags to determine which
fields will be filled in info
. For details about the object
metadata, please refer to the HDF5 documentation.
H5O.link
Create hard link to specified object
H5O.link(objID,locID,linkname,lcplID,laplID)
creates a hard link to
an object specified by objID
where locID
and
linkname
specify the location. H5O.link
is designed
to add additional structure to an existing file so that, for example, an object can be
shared among multiple groups.
Details
Input Arguments
objID
— Object identifier.
locID
— File or group identifier where link is located.
linkname
— Link name.
lcplID
— Link creation property list identifier.
laplID
— Link access property list identifier.
H5O.open
Open specified object
objID = H5O.open(objID,relname,laplID)
opens an object specified by
objID
and relative path name relname
.
Details
Input Arguments
objID
— Object identifier.
relname
— Relative path name.
laplID
— Link access property list identifier. If default link
access properties are appropriate, this can be passed in as
'H5P_DEFAULT'
.
H5O.open_by_idx
Open object specified by index
objID = H5O.open_by_idx(locID,groupName,idxtype,order,n,laplID)
opens
the object at index n
in the group specified by locID
and groupName
.
Details
Input Arguments
locID
— File or group identifier.
groupName
— Name of group relative to locID
in which the object can be found.
idxtype
— Type of index, specified as one of these character
vectors or string scalars:
order
— Index traversal order, specified as one of these character
vectors or string scalars:
'H5_ITER_INC'
— Iteration from beginning to end.
'H5_ITER_DEC'
— Iteration from end to beginning.
'H5_ITER_NATIVE'
— Iteration in the fastest available
order.
n
— Zero-based position of the object within the index.
laplID
— Link access property list identifier.
H5O.refresh
Clear and reload all data buffers (since R2021b)
H5O.refresh(objID)
causes all buffers associated with the object
objID
to be cleared and immediately reloaded with updated contents from
disk. This function essentially closes the object, evicts all metadata associated with it
from the cache, and then reopens the object. The reopened object is automatically
re-registered with the same identifier. The objID
can be any named object
associated with a file including a dataset, a group, or a committed datatype.
H5O.set_comment
Set comment for object specified by object identifier
H5O.set_comment(objID,comment)
sets a comment for the object
specified by objID
.
H5O.set_comment_by_name
Set comment for object specified by location and object name
H5O.set_comment_by_name(objID,relname,comment,laplID)
sets a comment
for an object specified by objID
and relative name
relname
. The link access property list identifier,
laplID
, can affect the outcome if links are traversed.
H5O.visit
Visit objects specified by object identifier
[status,opdataOut] = H5O.visit(objID,idxtype,order,fnc,opdataIn)
is a
recursive iteration function to visit the object objID
and, if
objID
is a group, all objects in and below it in an HDF5 file. This
provides a mechanism for an application to perform a common set of operations across all of
those objects or a dynamically selected subset.
Details
Input Arguments
objID
— Object identifier. If objID
is a
group identifier, it serves as the root group of a recursive iteration. If
objID
is a file identifier, the root group of the specified file
serves as the root of the recursive iteration. If objID
is any
other type of object, such as a dataset or named datatype, there is no
iteration.
idxtype
— Type of index. 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 unnecessary,
so the iteration may begin more quickly. Specify idxtype
as one of
these character vectors or string scalars:
order
— Index traversal order, specified as one of these
character vectors or string scalars:
'H5_ITER_INC'
— Iteration from beginning to end.
'H5_ITER_DEC'
— Iteration from end to beginning.
'H5_ITER_NATIVE'
— Iteration in the fastest available
order.
opdataIn
— User-defined value or structure passed to the first
step of the iteration of the opdataIn
parameter of
fnc
.
fnc
— Callback function with this signature:
[status,opdataOut] = fnc(groupID,name,opdataIn)
.
groupID
— Group identifier.
name
— Object name.
Output Arguments
status
— Value returned by the callback function
fnc
and interpreted as one of the following:
zero
— Continues with the iteration or returns zero status
value to the caller if all members have been processed.
positive
— Stops the iteration and returns the positive
status value to the caller.
negative
— Stops the iteration and throws an error
indicating failure.
opdataOut
— Value that forms the opdataIn
for the next iteration step. The final opdataOut
at the end of the
iteration is then returned to the caller as opdataOut
.
Note
The index type passed in idxtype
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.)
H5O.visit2
Visit objects specified by object identifier
[status,opdataOut] =
H5O.visit(objID,idxtype,order,fnc,opdataIn,fields)
recursively visits all
objects accessible from object objID
using the flags specified in
fields
, and executes the function fnc
on each object
in objID
.
If you are encountering performance issues using H5O.visit
, using
H5O.visit2
can help improve performance.
Details
Input Arguments
objID
— Object identifier. If objID
is a
group identifier, it serves as the root group of a recursive iteration. If
objID
is a file identifier, the root group of the specified file
serves as the root of the recursive iteration. If objID
is any
other type of object, such as a dataset or named datatype, there is no
iteration.
fields
— contains flags to determine which fields will be
retrieved by the fnc
callback function. Valid values are:
'H5O_INFO_BASIC'
— Fill in fileno
,
addr
, type
, and rc
fields.
'H5O_INFO_TIME'
— Fill in atime
,
mtime
, ctime
, and btime
fields.
'H5O_INFO_NUM_ATTRS'
— Fill in num_attrs
field.
'H5O_INFO_HDR'
— Fill in hdr
field.
'H5O_INFO_META_SIZE'
— Fill in meta_size
field.
'H5O_INFO_ALL'
— Fill in all fields.
idxtype
— Type of index. 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 unnecessary,
so the iteration may begin more quickly. Specify idxtype
as one of
these character vectors or string scalars:
order
— Index traversal order, specified as one of these
character vectors or string scalars:
'H5_ITER_INC'
— Iteration from beginning to end.
'H5_ITER_DEC'
— Iteration from end to beginning.
'H5_ITER_NATIVE'
— Iteration in the fastest available
order.
opdataIn
— User-defined value or structure passed to the first
step of the iteration of the opdataIn
parameter of
fnc
.
fnc
— Callback function with this signature:
[status,opdataOut] = fnc(groupID,name,opdataIn)
.
groupID
— Group identifier.
name
— Object name.
Output Arguments
status
— Value returned by the callback function
fnc
and interpreted as one of the following:
zero
— Continues with the iteration or returns zero status
value to the caller if all members have been processed.
positive
— Stops the iteration and returns the positive
status value to the caller.
negative
— Stops the iteration and throws an error
indicating failure.
opdataOut
— Value that forms the opdataIn
for the next iteration step. The final opdataOut
at the end of the
iteration is then returned to the caller as opdataOut
.
Note
The index type passed in idxtype
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.)
H5O.visit_by_name
Visit objects specified by location and object name
[status,opdata_out] =
H5O.visit_by_name(locID,objname,idxtype,order,fnc,opdataIn,laplID)
specifies the
object by the pairing of the location identifier and object name.
Details
Input Arguments
locID
— Object identifier. If locID
is a
group identifier, it serves as the root group of a recursive iteration. If
locID
is a file identifier, the root group of the specified file
serves as the root of the recursive iteration. If locID
is any
other type of object, such as a dataset or named datatype,
H5O.visit_by_name
does not iterate.
objname
— Object in a file with either an absolute name or
relative to locID
.
idxtype
— Type of index. 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 unnecessary,
so the iteration may begin more quickly. Specify idxtype
as one of
these character vectors or string scalars:
order
— Index traversal order, specified as one of these
character vectors or string scalars:
'H5_ITER_INC'
— Iteration from beginning to end.
'H5_ITER_DEC'
— Iteration from end to beginning.
'H5_ITER_NATIVE'
— Iteration in the fastest available
order.
opdataIn
— User-defined value or structure passed to the first
step of the iteration of the opdataIn
parameter of
fnc
.
fnc
— Callback function with this signature: function
[status,opdataOut] = fnc(groupID,name,opdataIn)
.
name
— Object name.
groupID
— Group identifier.
laplID
— Link access property list identifier. A link access
property list can affect the outcome if links are involved. When default link access
properties are acceptable, 'H5P_DEFAULT'
can be used.
Output Arguments
status
— Value returned by the callback function
fnc
and interpreted as one of the following:
zero
— Continues with the iteration or returns zero status
value to the caller if all members have been processed.
positive
— Stops the iteration and returns the positive
status value to the caller.
negative
— Stops the iteration and throws an error
indicating failure.
opdataOut
— Value that forms the opdataIn
for the next iteration step. The final opdataOut
at the end of the
iteration is then returned to the caller as opdataOut
.
Note
The index type passed in idxtype
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.)
H5O.visit_by_name2
Visit objects specified by location and object name
[status,opdata_out] =
H5O.visit_by_name(locID,objname,idxtype,order,fnc,opdataIn,fields,laplID)
specifies the object by the pairing of the location identifier and object name with the
additional parameter fields
.
If you are encountering performance issues using H5O.visit_by_name
,
using H5O.visit_by_name2
can help improve performance.
Details
Input Arguments
locID
— Object identifier. If locID
is a
group identifier, it serves as the root group of a recursive iteration. If
locID
is a file identifier, the root group of the specified file
serves as the root of the recursive iteration. If locID
is any
other type of object, such as a dataset or named datatype,
H5O.visit_by_name
does not iterate.
objname
— Object in a file with either an absolute name or
relative to locID
.
idxtype
— Type of index. 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 unnecessary,
so the iteration may begin more quickly. Specify idxtype
as one of
these character vectors or string scalars:
order
— Index traversal order, specified as one of these
character vectors or string scalars:
'H5_ITER_INC'
— Iteration from beginning to end.
'H5_ITER_DEC'
— Iteration from end to beginning.
'H5_ITER_NATIVE'
— Iteration in the fastest available
order.
fields
— contains flags to determine which fields will be
retrieved by the fnc
callback function. Valid values are:
'H5O_INFO_BASIC'
— Fill in fileno
,
addr
, type
, and rc
fields.
'H5O_INFO_TIME'
— Fill in atime
,
mtime
, ctime
, and btime
fields.
'H5O_INFO_NUM_ATTRS'
— Fill in num_attrs
field.
'H5O_INFO_HDR'
— Fill in hdr
field.
'H5O_INFO_META_SIZE'
— Fill in meta_size
field.
'H5O_INFO_ALL'
— Fill in all fields.
opdataIn
— User-defined value or structure passed to the first
step of the iteration of the opdataIn
parameter of
fnc
.
fnc
— Callback function with this signature: function
[status,opdataOut] = fnc(groupID,name,opdataIn)
.
name
— Object name.
groupID
— Group identifier.
laplID
— Link access property list identifier. A link access
property list can affect the outcome if links are involved. When default link access
properties are acceptable, 'H5P_DEFAULT'
can be used.
Output Arguments
status
— Value returned by the callback function
fnc
and interpreted as one of the following:
zero
— Continues with the iteration or returns zero status
value to the caller if all members have been processed.
positive
— Stops the iteration and returns the positive
status value to the caller.
negative
— Stops the iteration and throws an error
indicating failure.
opdataOut
— Value that forms the opdataIn
for the next iteration step. The final opdataOut
at the end of the
iteration is then returned to the caller as opdataOut
.
Note
The index type passed in idxtype
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.)