Link (H5L)

Links in HDF5 file

Description

Use the MATLAB^® HDF5 link interface, H5L, to create and manipulate links in an HDF5 group. This interface includes functions that enable the creation and use of user-defined link classes.

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:

  • 'H5_INDEX_NAME' — Alpha-numeric index by attribute name.

  • 'H5_INDEX_CRT_ORDER' — Index by creation order.

• 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:

  • 'system' — Use the system default encoding to interpret the link name.

  • 'UTF-8' — Use UTF-8 encoding to interpret the link name.

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:

  • 'system' — Use the system default encoding to interpret the link name.

  • 'UTF-8' — Use UTF-8 encoding to interpret the link name.

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:

  • 'H5_INDEX_NAME' — Alpha-numeric index by attribute.

  • 'H5_INDEX_CRT_ORDER' — Index by creation order.

• 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:

  • 'H5_INDEX_NAME' — Alpha-numeric index by attribute.

  • 'H5_INDEX_CRT_ORDER' — Index by creation order.

• 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:

  • 'H5_INDEX_NAME' — Alpha-numeric index by attribute.

  • 'H5_INDEX_CRT_ORDER' — Index by creation order.

• 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:

  • 'H5_INDEX_NAME' — Alpha-numeric index by attribute.

  • 'H5_INDEX_CRT_ORDER' — Index by creation order.

• 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.)

Examples

Remove Only Link to Group

Remove the only link to the '/g3' group in example.h5.

srcFile = fullfile(matlabroot,'toolbox','matlab','demos','example.h5');
copyfile(srcFile,'myfile.h5');
fileattrib('myfile.h5','+w');
fid = H5F.open('myfile.h5','H5F_ACC_RDWR','H5P_DEFAULT');
H5L.delete(fid,'g3','H5P_DEFAULT');
H5F.close(fid);

Determine If Link Exists

fid = H5F.open('example.h5');
gid = H5G.open(fid,'/g1/g1.2/g1.2.1');
if H5L.exists(gid,'slink','H5P_DEFAULT')
    fprintf('link exists\n');
else
    fprintf('link does not exist\n');
end

Rename Group in HDF5 File

Rename the '/g2' group to '/g2/g3'.

srcFile = fullfile(matlabroot,'toolbox','matlab','demos','example.h5');
copyfile(srcFile,'myfile.h5');
fileattrib('myfile.h5','+w');
fid = H5F.open('myfile.h5','H5F_ACC_RDWR','H5P_DEFAULT');
g2id = H5G.open(fid,'g2');
H5L.move(fid,'g3',g2id,'g3','H5P_DEFAULT','H5P_DEFAULT');
H5G.close(g2id);
H5F.close(fid);

Version History

Introduced before R2006a