Functions
H5L.copy
Copy link from source location to destination location
H5L.copy(srcID,srcname,destID,destname,lcplID,laplID)
copies the link
specified by srcname
from the file or group specified by
srcID
to the destination destID
. The new copy of the
link is created with the name destname
.
Details
Input Arguments
srcID
— Group or file identifier of source link.
srcname
— Name of the source link in the file or group.
destID
— Identifier of the current file or a group in the
current file. If destID
is the file identifier,
H5L.copy
the copy is placed in the root group of the file.
destname
— Name of the copy of the link.
lcplID
— Link creation property list identifier.
laplID
— Link access property list identifier.
H5L.create_external
Create soft link to external object
H5L.create_external(filename,objname,linkID,linkname,lcplID,laplID)
creates a soft link to an object in a different file.
Details
Input Arguments
filename
— Target file containing the target object.
objname
— Path to the target object within that file. The
objname
argument must start at the root group of the file, but is
not interpreted until lookup time.
linkID
— File or group identifier of new link.
linkname
— Name of new link, and is interpreted relative to
linkID
.
lcplID
— Link creation property list identifier associated with
new link.
laplID
— Link access property list identifier associated with
new link.
H5L.create_hard
Create hard link
H5L.create_hard(objID,objname,linkID,linkname,lcplID,laplID)
creates
a new hard link to a preexisting object in an HDF5 file. The new link may be one of many
that point to that object.
Details
Input Arguments
objID
— Identifier of target object, the object to which the
new hard link points.
objname
— Name of target object, the object to which the new
hard link points.
linkID
— File or group identifier of new link.
linkname
— Name of new link, and is interpreted relative to
linkID
.
lcplID
— Link creation property list identifier associated with
new link.
laplID
— Link access property list identifier associated with
new link.
H5L.create_soft
Create soft link
H5L.create_soft(targetPath,linkID,linkname,lcplID,laplID)
creates a
new soft link to an object in an HDF5 file. The new link may be one of many that point to
that object i.e., the object that the new soft link points to.
Details
Input Arguments
targetPath
— Path to the target object, the object that the new
soft link points to. The targetPath
can be anything and is
interpreted at lookup time. This targetPath
may be absolute in the
file or relative to linkID
.
linkID
— File or group identifier of new link.
linkname
— Name of new link, and is interpreted relative to
linkID
.
lcplID
— Link creation property list identifier associated with
new link.
laplID
— Link access property list identifier associated with
new link.
H5L.delete
Remove link
H5L.delete(locID,name,laplID)
removes the link specified by
name
from the location locID
based on the link
access property list identifier specified by laplID
.
H5L.exists
Determine if link exists
tf = H5L.exists(locID,linkname,laplID)
checks if a link specified by
the pairing of an object identifier and name exists within a group, based on the link access
property list identifier specified by laplID
.
H5L.get_info
Information about link
linkStruct = H5L.get_info(locID,linkname,laplID)
returns information
about a link. A file or group identifier, locID
, specifies the location
of the link. The linkname
argument, interpreted relative to
linkID
, specifies the link being queried.
H5L.get_name_by_idx
Information about link specified by index
name = H5L.get_name_by_idx(locID,groupname,idxtype,order,n,laplID)
retrieves information about a link at index n
present in group
groupname
at location locID
.
name =
H5L.get_name_by_idx(locID,groupname,idxtype,order,n,laplID,'TextEncoding',encoding)
additionally specifies the text encoding to use to interpret the link name.
Details
Input Arguments
locID
— Group identifier.
groupname
— Name of group.
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
— Link for which to retrieve information.
laplID
— Link access property list identifier for querying the
group.
encoding
— Text encoding, specified as one of these
values:
H5L.get_val
Value of symbolic link
linkval = H5L.get_val(linklocID,linkname,laplID)
returns the value of
a symbolic link. This function corresponds to the H5L.get_val
and
H5Lunpack_elink_val
functions in the HDF5 1.8 C API.
linkval =
H5L.get_val(linklocID,linkname,laplID,'TextEncoding',encoding)
additionally
specifies the text encoding to use to interpret the link value.
Details
Input Arguments
linklocID
— File or group identifier.
linkname
— Name of symbolic link and is defined relative to
linklocID
. Symbolic links can be soft links, external links, or
certain user-defined links. In the case of soft links, linkval
is a
cell array containing the path to which the link points. In the case of external
links, linkval
is a cell array consisting of the name of the target
file and the object name.
laplID
— Link access property list identifier.
encoding
— Text encoding, specified as one of these
values:
Output Arguments
linkval
— Value of symbolic link. In the case of soft links,
linkval
is a cell array containing the path to which the link
points. In the case of external links, linkval
is a cell array
consisting of the name of the target file and the object name.
H5L.iterate
Iterate over links
[status,idxOut,opdataOut] =
H5L.iterate(groupID,idxtype,order,idxIn,fnc,opdataIn)
iterates through the links
in a group, specified by groupID
, to perform a common function whose
function handle is fnc
. H5L.iterate
does not
recursively follow links into subgroups of the specified group.
Details
Input Arguments
groupID
— Group identifier.
idxtype
— Type of index. If the links 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.
idxIn
— Starting point of the iteration.
fnc
— Callback function with this signature:
[status,opdataOut] = fnc(groupID,linkname,opdataIn)
.
opdataIn
— User-defined value or structure and is passed to the
first step of the iteration in the opdataIn
parameter of
fnc
.
linkname
— Input link name.
Output Arguments
status
— Value returned by the callback function
fnc
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.
idxOut
— Point at which iteration was stopped. This allows an
interrupted iteration to be resumed.
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
.
H5L.iterate_by_name
Iterate through links in group specified by name
[status,idx_out,opdataOut] =
H5L.iterate_by_name(locID,groupname,idxtype,order,idxIn,fnc,opdataIn,laplID)
iterates through the links in a group to perform a common function whose function handle is
fnc
. The starting point of the iteration is pairing of a specified by
the location identifier and a relative group name. H5L.iterate_by_name
does not recursively follow links into subgroups of the specified group. A link access
property list, laplID
, may affect the outcome depending upon the type of
link being traversed.
Details
Input Arguments
locID
— Group or file identifier.
groupname
— Group name.
idxtype
— Type of index. If the links 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.
idxIn
— Starting point of the iteration.
opdataIn
— User-defined value or structure and is passed to the
first step of the iteration in the opdataIn
parameter of
fnc
.
fnc
— Callback function with this signature:
[status,opdataOut] = fnc(groupID,linkname,opdataIn)
.
linkname
— Input link name.
laplID
— Link access property list identifier.
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.
idxOut
— Point at which iteration was stopped. This allows an
interrupted iteration to be resumed.
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
.
H5L.move
Rename link
H5L.move(srcID,srcname,destID,destname,lcplID,laplID)
renames a link
within an HDF5 file. The original link, srcname
, is removed from the
group graph and the new link, destname
, is inserted. This change is
accomplished as an atomic operation.
Details
Input Arguments
srcID
— File or group identifier associated with existing
link.
srcname
— Path to existing link and is interpreted relative to
srcID
.
destID
— File or group identifier associated with link to use
to replace srcname
in the group graph.
destname
— Name of new link.
lcplID
— Link creation property list identifier.
laplID
— Link access property list identifier.
H5L.visit
Recursively iterate through links in group specified by group
identifier
[status,opdataOut] = H5L.visit(groupID,idxtype,order,fnc,opdataIn)
recursively iterates through all links in and below a group, specified by
groupID
, to perform a common function whose function handle is
fnc
.
Details
Input Arguments
groupID
— Group identifier.
idxtype
— Type of index. If the links 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,linkname,opdataIn)
.
linkname
— Input link 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.)
H5L.visit_by_name
Recursively iterate through links in group specified by location and group
name
[status,opdataOut] =
H5L.visit_by_name(locID,groupname,idxtype,order,fnc,opdataIn,laplID)
recursively
iterates though all links in and below a group to perform a common function whose function
handle is fnc
. The starting point of the iteration is specified by the
pairing of a location id and a relative group name. A link access property list,
laplID
, may affect the outcome depending upon the type of link being
traversed.
Details
Input Arguments
locID
— Group or file identifier.
groupname
— Group name.
idxtype
— Type of index. If the links 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,linkname,opdataIn)
.
linkname
— Input link name.
laplID
— Link access property list identifier.
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.)