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

tf = H5O.are_mdc_flushes_disabled(objID) returns logical 1 (true) if the HDF5 object specified by objID has had flushes of metadata disabled, and logical 0 (false) if it has not.

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 metadata entries for an object from being flushed

H5O.disable_mdc_flushes(objID) prevents metadata entries for an HDF5 object identified by objID from being flushed from the metadata cache to storage 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 metadata entries for an object to be flushed

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

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.get_info2(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".

Output Arguments

• objID — Identifier of opened object.

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 string scalars or character vectors:

  • "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 string scalars or character vectors:

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

Output Arguments

• objID — Identifier of opened object.

H5O.refresh

Clear and reload all data buffers

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

Recursively iterate through objects in group or file specified by identifier

[status,opdataOut] = H5O.visit(objID,idxtype,order,fnc,opdataIn) recursively iterates through all objects in and below the group or file specified by objID to perform a common function whose function handle is fnc.

 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 have not been indexed by the index type, they will be sorted by that index before the iteration begins. 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 values or their numeric equivalents:

  • "H5_INDEX_NAME" — Alpha-numeric index by link name.

  • "H5_INDEX_CRT_ORDER" — Index by creation order.

• order — Index traversal order, specified as one of these values or their numeric equivalents:

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

• fnc — Callback function with this signature: [f_status,f_opdataOut] = fnc(f_objID,name,f_opdataIn).

  Input Arguments for fnc

  • f_objID — Populated with objID input argument.

  • name — Name of current object.

  • f_opdataIn — Initially populated by opdataIn input argument; thereafter populated by f_opdataOut output argument of fnc from the previous iteration step.

  Output Arguments for fnc

  • f_status — Status indicator, interpreted as follows:

    • zero — Continues with the iteration, or populates status output argument if all members have been processed.

    • nonzero — Stops the iteration and populates the status output argument.

  • f_opdataOut — Value that populates the f_opdataIn input argument of fnc for the next iteration step. The final f_opdataOut at the end of the iteration populates the opdataOut output argument.

• opdataIn — User-defined value or structure that populates the f_opdataIn input argument of fnc in the first step of the iteration.

Output Arguments

• status — Populated by the final f_status output argument of fnc at the end of the iteration and interpreted as follows:

  • zero — Success. All objects were processed.

  • positive — Short-circuit success. The value is the index value of the last object that was processed.

  • negative — Failure.

• opdataOut — Populated by the final f_opdataOut output argument of fnc at the end of the iteration.

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

Recursively iterate through objects in group or file specified by identifier

[status,opdataOut] = H5O.visit2(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.

• idxtype — Type of index. If the links have not been indexed by the index type, they will be sorted by that index before the iteration begins. 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 values or their numeric equivalents:

  • "H5_INDEX_NAME" — Alpha-numeric index by link name.

  • "H5_INDEX_CRT_ORDER" — Index by creation order.

• order — Index traversal order, specified as one of these values or their numeric equivalents:

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

• fnc — Callback function with this signature: [f_status,f_opdataOut] = fnc(f_objID,name,f_opdataIn).

  Input Arguments for fnc

  • f_objID — Populated with objID input argument.

  • name — Name of current object.

  • f_opdataIn — Initially populated by opdataIn input argument; thereafter populated by f_opdataOut output argument of fnc from the previous iteration step.

  Output Arguments for fnc

  • f_status — Status indicator, interpreted as follows:

    • zero — Continues with the iteration, or populates status output argument if all members have been processed.

    • nonzero — Stops the iteration and populates the status output argument.

  • f_opdataOut — Value that populates the f_opdataIn input argument of fnc for the next iteration step. The final f_opdataOut at the end of the iteration populates the opdataOut output argument.

• opdataIn — User-defined value or structure that populates the f_opdataIn input argument of fnc in the first step of the iteration.

• fields — contains flags to determine which fields will be retrieved by fnc. 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.

Output Arguments

• status — Populated by the final f_status output argument of fnc at the end of the iteration and interpreted as follows:

  • zero — Success. All objects were processed.

  • positive — Short-circuit success. The value is the index value of the last object that was processed.

  • negative — Failure.

• opdataOut — Populated by the final f_opdataOut output argument of fnc at the end of the iteration.

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

Recursively iterate through objects in group or file specified by location and group name

[status,opdataOut] = H5O.visit_by_name(locID,objname,idxtype,order,fnc,opdataIn,laplID) recursively iterates though all objects in and below the group or file to perform a common function whose function handle is fnc. The starting point of the iteration is determined by a location identifier and a relative object name. A link access property list, laplID, may affect the outcome depending upon the type of link being traversed.

 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, there is no iteration.

• objname — Name (either absolute or relative to locID) of the object.

• idxtype — Type of index. If the links have not been indexed by the index type, they will be sorted by that index before the iteration begins. 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 values or their numeric equivalents:

  • "H5_INDEX_NAME" — Alpha-numeric index by link name.

  • "H5_INDEX_CRT_ORDER" — Index by creation order.

• order — Index traversal order, specified as one of these values or their numeric equivalents:

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

• fnc — Callback function with this signature: [f_status,f_opdataOut] = fnc(groupID,name,f_opdataIn).

  Input Arguments for fnc

  • groupID — Populated with locID input argument.

  • name — Name of current object.

  • f_opdataIn — Initially populated by opdataIn input argument; thereafter populated by f_opdataOut output argument of fnc from the previous iteration step.

  Output Arguments for fnc

  • f_status — Status indicator, interpreted as follows:

    • zero — Continues with the iteration, or populates status output argument if all members have been processed.

    • nonzero — Stops the iteration and populates the status output argument.

  • f_opdataOut — Value that populates the f_opdataIn input argument of fnc for the next iteration step. The final f_opdataOut at the end of the iteration populates the opdataOut output argument.

• opdataIn — User-defined value or structure that populates the f_opdataIn input argument of fnc in the first step of the iteration.

• laplID — Identifier of link access property list. 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 — Populated by the final f_status output argument of fnc at the end of the iteration and interpreted as follows:

  • zero — Success. All objects were processed.

  • positive — Short-circuit success. The value is the index value of the last object that was processed.

  • negative — Failure.

• opdataOut — Populated by the final f_opdataOut output argument of fnc at the end of the iteration.

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

Recursively iterate through objects in group or file specified by location and group name

[status,opdataOut] = H5O.visit_by_name2(locID,objname,idxtype,order,fnc,opdataIn,fields,laplID) recursively iterates though all objects in and below the group or file to perform a common function whose function handle is fnc. The starting point of the iteration is determined by a location identifier and a relative object name. A link access property list, laplID, may affect the outcome depending upon the type of link being traversed.

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, there is no iteration.

• objname — Name (either absolute or relative to locID) of the object.

• idxtype — Type of index. If the links have not been indexed by the index type, they will be sorted by that index before the iteration begins. 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 values or their numeric equivalents:

  • "H5_INDEX_NAME" — Alpha-numeric index by link name.

  • "H5_INDEX_CRT_ORDER" — Index by creation order.

• order — Index traversal order, specified as one of these values or their numeric equivalents:

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

• fnc — Callback function with this signature: [f_status,f_opdataOut] = fnc(groupID,name,f_opdataIn).

  Input Arguments for fnc

  • groupID — Populated with locID input argument.

  • name — Name of current object.

  • f_opdataIn — Initially populated by opdataIn input argument; thereafter populated by f_opdataOut output argument of fnc from the previous iteration step.

  Output Arguments for fnc

  • f_status — Status indicator, interpreted as follows:

    • zero — Continues with the iteration, or populates status output argument if all members have been processed.

    • nonzero — Stops the iteration and populates the status output argument.

  • f_opdataOut — Value that populates the f_opdataIn input argument of fnc for the next iteration step. The final f_opdataOut at the end of the iteration populates the opdataOut output argument.

• opdataIn — User-defined value or structure that populates the f_opdataIn input argument of fnc in the first step of the iteration.

• fields — contains flags to determine which fields will be retrieved by fnc. 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.

• laplID — Identifier of link access property list. 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 — Populated by the final f_status output argument of fnc at the end of the iteration and interpreted as follows:

  • zero — Success. All objects were processed.

  • positive — Short-circuit success. The value is the index value of the last object that was processed.

  • negative — Failure.

• opdataOut — Populated by the final f_opdataOut output argument of fnc at the end of the iteration.

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);
H5F.close(fid);
H5P.close(lcpl);
H5P.close(ocpl);

Open Object in An HDF5 File

fid = H5F.open("example.h5");
objID = H5O.open(fid,"g3","H5P_DEFAULT");
H5O.close(objID);
H5F.close(fid);

Version History

Introduced before R2006a

R2021b: Fine-tune the metadata cache by controlling flushes

You can use H5O.enable_mdc_flushes and H5O.disable_mdc_flushes to enable and disable flushing of metadata, respectively, and you can use H5O.are_mdc_flushes_disabled to determine whether flushes of metadata entries are disabled.

R2021b: Flush and refresh buffers associated with an object

You can use H5O.flush to flush the buffers associated with an object to disk and H5O.refresh to clear the buffer associated with an object and reload with updated contents from disk.

R2021b: Get object metadata with H5O.get_info2

You can use H5O.get_info2 for high-performance retrieval of object metadata from specified fields.

R2021b: Visit objects

You can use H5O.visit2 for high-performance visitation of objects specified by object identifier, and H5O.visit_by_name2 for high-performance visitation of objects specified by location and object name.