Object (H5O)

Objects in file

Description

Use the MATLAB^® HDF5 object interface, H5O, to handle and access information about HDF5 objects.

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

  • 'H5_INDEX_NAME' — An alpha-numeric index by attribute name.

  • 'H5_INDEX_CRT_ORDER' — An 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— 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:

  • 'H5_INDEX_NAME' — An alpha-numeric index by attribute.

  • 'H5_INDEX_CRT_ORDER' — An 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,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:

  • 'H5_INDEX_NAME' — An alpha-numeric index by attribute.

  • 'H5_INDEX_CRT_ORDER' — An 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,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:

  • 'H5_INDEX_NAME' — An alpha-numeric index by attribute.

  • 'H5_INDEX_CRT_ORDER' — An 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: 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:

  • 'H5_INDEX_NAME' — An alpha-numeric index by attribute.

  • 'H5_INDEX_CRT_ORDER' — An 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.

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

Examples

Copy Group and Its Datasets to New Group

Copy the group '/g3' and all its datasets to a new group '/g3.5'.

srcFile = [matlabroot '/toolbox/matlab/demos/example.h5'];
copyfile(srcFile,'myfile.h5');
fileattrib('myfile.h5','+w');
ocpl = H5P.create('H5P_OBJECT_COPY');
lcpl = H5P.create('H5P_LINK_CREATE');
H5P.set_create_intermediate_group(lcpl,true);
fid = H5F.open('myfile.h5','H5F_ACC_RDWR','H5P_DEFAULT');
gid = H5G.open(fid,'/');
H5O.copy(gid,'g3',gid,'g3.5',ocpl,lcpl);
H5G.close(gid);
H5P.close(ocpl);
H5P.close(lcpl);
H5F.close(fid);

Open Object in An HDF5 File

fid = H5F.open('example.h5');
obj_id = H5O.open(fid,'g3','H5P_DEFAULT');
H5O.close(obj_id);
H5F.close(fid);