h5writeatt

Write attribute to HDF5 file

Syntax

h5writeatt(filename,loc,attr,val)

h5writeatt(filename,loc,attr,val,'TextEncoding',encoding)

Description

h5writeatt(filename,loc,attr,val) writes the attribute named attr with the value val to the specified location in the HDF5 file.

h5writeatt(filename,loc,attr,val,'TextEncoding',encoding) writes attr to the specified location in the HDF5 file using the specified encoding. 'UTF-8' is the default setting for 'TextEncoding', while 'system' uses the system encoding to represent characters. It is usually unnecessary to specify 'system' as the encoding.

Examples

Write Attribute to Root Group

Write an attribute to the root group of examplefile.h5 whose value is the current time.

date = datestr(now);
h5writeatt('examplefile.h5','/','creation_date', date);

Read the attribute from the root group of the HDF5 file.

val1 = h5readatt('examplefile.h5','/','creation_date')

val1 = 
'05-Sep-2024 15:14:24'

Write Attribute to Dataset

Create an array of doubles and write it to the dataset /g4/world.

attData = [0 1 2 3];
h5writeatt('examplefile.h5','/g4/world','val2',attData);

Display the dataset metadata. The attribute val2 is listed one of the attributes belonging to the dataset.

h5disp('examplefile.h5','/g4/world');

HDF5 examplefile.h5 
Dataset 'world' 
    Size:  36x19
    MaxSize:  36x19
    Datatype:   H5T_IEEE_F64LE (double)
    ChunkSize:  []
    Filters:  none
    FillValue:  0.000000
    Attributes:
        'val2':  0.000000 1.000000 2.000000 3.000000 

Input Arguments

filename — Filename

string scalar | character vector

Filename of an existing HDF5 file, specified as a string scalar or character vector.

Depending on the location of your file, filename can take one of these forms.

Location	Form
Current folder	Specify the name of the file in filename. Example: "myFile.h5"
Other folders	If the file is not in the current folder or in a folder on the MATLAB® path, then specify the full or relative path in filename. Example: "C:\myFolder\myFile.h5" Example: "myFolder\myFile.h5"
Remote location	If the file is stored at a remote location, then filename must contain the full path of the file specified as a uniform resource locator (URL) of the form: scheme_name://path_to_file/filename Based on your remote location, scheme_name can be one of the values in this table. Remote Location scheme_name Amazon S3™ s3 Windows Azure® Blob Storage wasb, wasbs For more information, see Work with Remote Data. Example: "s3://myBucket/myFolder/myFile.h5"

• If your file consists of several physical files using the Family driver, specify filename using a format specifier. For example, to use the Family driver with the two files family0.h5 and family1.h5, specify filename as "family%d.h5".

• If your file consists of several physical files using the Multi driver or the Split driver, specify filename as the leading prefix of the names of the physical files. For example, to use the Multi driver with the six files multi-b.h5, multi-g.h5, multi-l.h5, multi-o.h5, multi-r.h5, and multi-s.h5, specify filename as "multi".

loc — Location in file

character vector | string scalar

Location in file, specified as a character vector or string scalar containing the full path name of an existing group or dataset to which you want to associate the attribute.

attr — Name of attribute

character vector | string scalar

Name of attribute, specified as a character vector or string scalar containing the name of an attribute belonging to a group or dataset. If the attribute does not exist, h5writeatt creates the attribute with the name specified.

If the specified attribute already exists but does not have a datatype or dataspace consistent with val, h5writeatt deletes the attribute and recreates it. String attributes are created with a scalar dataspace, which is a single, zero-dimensional data point.

val — Value of attribute

character vector | string array | numeric value

Value of attribute to be written, specified as a character vector, string scalar, or numeric value.

encoding — Text Encoding

'UTF-8' (default) | 'system'

Text encoding, specified as the comma-separated pair consisting of 'TextEncoding' and one of these values:

• 'UTF-8' — Represents characters using UTF-8 encoding.

• 'system' — Represents characters as bytes using the system encoding (not recommended).

Limitations

• h5writeatt does not support writing to files stored remotely in HDFS™.

• The h5writeatt function issues an error for attributes and datasets that fail file integrity checks. To write attributes in such situations, use the H5P.set_relax_file_integrity_checks function and the low-level HDF5 interface. (since R2024b)

Version History

Introduced in R2011a

R2024b: Attributes and datasets that fail file integrity checks no longer supported (R2024b Update)

The h5writeatt function now issues an error for attributes and datasets that fail file integrity checks. Previously, this function did not issue an error for such attributes or datasets. To write attributes in such situations, use the H5P.set_relax_file_integrity_checks function and the low-level HDF5 interface. This table shows how to update your code to use the low-level HDF5 interface.

R2024a and Earlier

Starting in R2024b

h5writeatt("myFilename.h5","myDatasetName","myAttrName",myAttrValue);

fapl = H5P.create("H5P_FILE_ACCESS"); H5P.set_relax_file_integrity_checks(fapl,"H5F_RFIC_UNUSUAL_NUM_UNUSED_NUMERIC_BITS") fid = H5F.open("myFilename.h5","H5F_ACC_RDWR",fapl); dset_id = H5D.open(fid,"myDatasetName"); % Assumes myAttrName is an existing attribute. % If it does not already exist, use H5A.create. attrID = H5A.open(dset_id,"myAttrName"); H5A.write(attrID,"H5ML_DEFAULT",myAttrValue) H5A.close(attrID) H5D.close(dset_id) H5F.close(fid) H5P.close(fapl)

R2020b: Write attributes to HDF5 files at a remote location

You can write attributes to HDF5 files in remote locations, such as Amazon S3, Windows Azure Blob Storage, and HDFS.

R2020b: Write attributes to HDF5 files with Unicode names

You can write attributes to HDF5 files whose names are encoded as Unicode characters.

R2020a: UTF-8 character encoding is the default setting

UTF-8 is now the default character encoding for h5writeatt so that all Unicode code points can be represented in HDF5 files. Previously, the default encoding was ASCII.