Attribute (H5A)

Metadata associated with datasets or groups

Description

Use the MATLAB^® HDF5 attribute interface, H5A, to create, read, and write dataset and group attributes, and access information about them.

An HDF5 attribute is a small metadata object that describes the nature and/or intended usage of a primary data object, which may be a dataset, group, or named datatype.

Functions

H5A.close

Close specified attribute

H5A.close(attrID) terminates access to the attribute specified by attrID, releasing the identifier.

H5A.create

Create attribute

attrID = H5A.create(locID,attName,typeID,spaceID,acplID) creates the attribute with name attName that is attached to the object specified by locID. This syntax corresponds to the H5Acreate in version 1.6 of the HDF5 C library.

attrID = H5A.create(locID,attName,typeID,spaceID,acplID,aaplID) creates an attribute with the additional attribute access property list identifier aaplID. This syntax corresponds to the H5Acreate in version 1.8 of the HDF5 C library.

Details

H5A.delete

Delete attribute

H5A.delete(locID,attName) removes the attribute specified by attName from the dataset, group, or named datatype specified by locID.

H5A.get_info

Information about attribute

info = H5A.get_info(attrID) returns information about an attribute specified by attrID.

H5A.get_name

Attribute name

attName = H5A.get_name(attrID) returns the name of the attribute specified by attrID.

attName = H5A.get_name(attrID,"TextEncoding",encoding) specifies the text encoding to use to interpret the attribute name.

Details

H5A.get_space

Copy of attribute dataspace

dspaceID = H5A.get_space(attrID) returns a copy of the dataspace for the attribute specified by attrID.

H5A.get_type

Copy of attribute datatype

typeID = H5A.get_type(attrID) returns a copy of the datatype for the attribute specified by attrID.

H5A.iterate

Execute function for attributes attached to object

status = H5A.iterate(locID,idx,fnc) executes the specified function fnc for each attribute of the group, dataset, or named datatype specified by locID. This interface corresponds to the H5Aiterate1 function in the HDF5 C library.

Details

[status,idxStop,cdataOut] = H5A.iterate(objID,idxType,order,idxStart,fnc,cdataIn) executes the specified function fnc for each attribute of the group, dataset, or named datatype specified by objID. This interface corresponds to the H5Aiterate2 function in the HDF5 C library.

Details

Input Arguments

objID — Identifier of the object to which the attributes are attached. The object can be a group, dataset, or named datatype.
idxType — Type of index, specified as one of these values or their numeric equivalents:
- "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 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.
idxStart — Attribute index at which iteration begins.
fnc — Callback function handle with this signature: [f_status,f_cdataOut] = fnc(locID,attName,info,f_cdataIn).
Input Arguments for fnc
- locID — Populated by objID input argument.
- attName — Name of current attribute.
- info — Information structure of attribute.
- f_cdataIn — Initially populated by cdataIn input argument; thereafter populated by f_cdataOut 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_cdataOut — Value that populates the f_cdataIn input argument of fnc for the next iteration step. The final f_cdataOut at the end of the iteration populates the cdataOut output argument.
cdataIn — User-defined value or structure that populates the f_cdataIn 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 attributes were processed.
- positive — Short-circuit success. The value is the index value of the last attribute that was processed.
- negative — Failure.
idxStop — Attribute index of the last attribute processed. This value can be used to resume an interrupted iteration.
cdataOut — Populated by the final f_cdataOut 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.)

H5A.open

Open attribute

attrID = H5A.open(objID,attName) opens an attribute for an object specified by a parent object identifier objID and attribute name attName.

attrID = H5A.open(objID,attName,aaplID) opens an attribute with an attribute access property list identifier aaplID.

Details

H5A.open_by_idx

Open attribute specified by index

attrID = H5A.open_by_idx(locID,objname,idxType,order,n) opens an existing attribute at index n attached to an object specified by its location, locID, and name, objname.

attrID = H5A.open_by_idx(locID,objname,idxType,order,n,aaplID,laplID) opens an attribute with an attribute access property list identifier aaplID and link access property list identifier laplID.

Details

H5A.open_by_name

Open attribute specified by name

attrID = H5A.open_by_name(locID,objname,attName) opens an existing attribute attached to an object specified by its location locID and name objname.

attrID = H5A.open_by_name(locID,objname,attName,aaplID,laplID) opens an existing attribute with the attribute access property list identifier aaplID and link access property list identifier laplID.

Details

H5A.read

Read attribute

attr = H5A.read(attrID) reads the attribute specified by attrID. MATLAB will determine the appropriate memory datatype.

attr = H5A.read(attrID,memtypeID) reads the attribute specified by attrID.

Details

H5A.write

Write attribute

H5A.write(attrID,typeID,buf) writes the data in the buffer buf into the attribute specified by attrID using memory datatype typeID.

Details

Examples

expand all

Read Attribute from HDF5 File and Delete It

Open Live Script

Read an attribute from the root group of an HDF5 file into the MATLAB workspace, delete it, then close the file.

Create a writeable copy of the file example.h5 in the current directory, and open the new file and its root group.

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");
gid = H5G.open(fid,"/");

Open the attribute attr1, read it into the workspace, then close it.

attrID = H5A.open(gid,"attr1");
data = H5A.read(attrID);
H5A.close(attrID);

Delete the attribute from the root group of the HDF5 file, then close the root group and file.

H5A.delete(gid,"attr1");
H5G.close(gid);
H5F.close(fid);

Create Attribute and Write Data Buffer to It

Open Live Script

Create an attribute in an HDF5 file and write a data buffer to it.

Create an HDF5 file named myfile.h5.

fid = H5F.create("myfile.h5");

Create an attribute create property list identifier, a datatype identifier of type "H5T_NATIVE_DOUBLE", and a data space identifier of type "H5S_SCALAR".

acpl = H5P.create("H5P_ATTRIBUTE_CREATE");
typeID = H5T.copy("H5T_NATIVE_DOUBLE");
spaceID = H5S.create("H5S_SCALAR");

Create an attribute with identifier attrID, and write a data buffer of 10.0 to it. Then, close the attribute and HDF5 file.

attrID = H5A.create(fid,"my_attr",typeID,spaceID,acpl);
H5A.write(attrID,"H5ML_DEFAULT",10.0)
H5A.close(attrID);
H5S.close(spaceID);
H5T.close(typeID);
H5F.close(fid);

Display Dataset Attribute Names

Open Live Script

Open each attribute in a dataset and print their names.

Open the dataset dset1.1.1 in the file example.h5.

fid = H5F.open("example.h5");
gid = H5G.open(fid,"/g1/g1.1");
dsID = H5D.open(fid,"/g1/g1.1/dset1.1.1");
info = H5O.get_info(dsID);

Open each attribute, print its name, then close it.

for idx = 0:info.num_attrs-1
    attrID = H5A.open_by_idx(gid,"dset1.1.1","H5_INDEX_NAME","H5_ITER_DEC",idx);
    fprintf("attribute name:  %s\n",H5A.get_name(attrID));
    H5A.close(attrID);
end

attribute name:  attr2
attribute name:  attr1

H5G.close(gid);
H5F.close(fid);

Version History

Introduced before R2006a

Attribute (H5A)

Description

Functions

H5A.close

H5A.create

H5A.delete

H5A.get_info

H5A.get_name

H5A.get_space

H5A.get_type

H5A.iterate

H5A.open

H5A.open_by_idx

H5A.open_by_name

H5A.read

H5A.write

Examples

Read Attribute from HDF5 File and Delete It

Create Attribute and Write Data Buffer to It

Display Dataset Attribute Names

Version History

See Also