Reference (H5R)

HDF5 references

Description

Use the MATLAB^® HDF5 reference interface, H5R, to create and access information about references to HDF5 objects.

Functions

H5R.create

Create reference

ref = H5R.create(locID,objname,reftype,spaceID) creates a reference ref of the type specified in reftype pointing to the object specified by objname and locID.

 Details

Input Arguments

• locID — Object identifier.

• objname — Object name.

• reftype — Type of reference, specified as either "H5R_OBJECT" or "H5R_DATASET_REGION".

• spaceID — Dataspace identifier. You must specify spaceID as -1 if reftype is set to "H5R_OBJECT".

Output Arguments

• ref — Created reference.

H5R.dereference

Open object specified by reference

output = H5R.dereference(dsID,reftype,ref) returns an identifier to the object specified by ref in the dataset specified by dsID. This syntax corresponds to the H5Rdereference interface in version 1.8 of the HDF5 C library.

output = H5R.dereference(dsID,plistID,reftype,ref) returns an identifier to the object specified by ref in the dataset specified by dsID and with additional property list plistID. This syntax corresponds to the H5Rdereference interface in version 1.10 of the HDF5 C library.

 Details

Input Arguments

• dsID — Dataset identifier.

• plistID — Object access property list identifier.

• ref — Object name.

• reftype — Type of reference.

Output Arguments

• output — Identifier of dereferenced object.

H5R.get_name

Name of referenced object

name = H5R.get_name(locID,reftype,ref) returns the name of the object identified by ref of type reftype located in a dataset or group locID.

name = H5R.get_name(locID,reftype,ref,"TextEncoding",encoding) specifies the text encoding to use to interpret the reference name.

 Details

Input Arguments

• locID — Dataset or group identifier.

• reftype — Type of reference, specified as either "H5R_OBJECT" or "H5R_DATASET_REGION".

• ref — Object name.

• encoding — Text encoding to use to interpret the reference name, specified as one of the following values:

  • "system" — Use the system default encoding to interpret the reference name.

  • "UTF-8" — Use UTF-8 encoding to interpret the reference name.

H5R.get_obj_type

Type of referenced object

objType = H5R.get_obj_type(locID,reftype,ref) returns the type of object that an object reference points to. This syntax corresponds to the H5Rget_obj_type interface in version 1.8 of the HDF5 C library.

 Details

Input Arguments

• locID — Object identifier.

• reftype — Type of reference, specified as either "H5R_OBJECT" or "H5R_DATASET_REGION".

• ref — Object name.

Output Arguments

• objType — Type of object, interpreted as one of these:

  • "H5O_TYPE_GROUP" — Group. The numeric equivalent is 0.

  • "H5O_TYPE_DATASET" — Dataset. The numeric equivalent is 1.

  • "H5O_TYPE_NAMED_DATATYPE" — Named datatype. The numeric equivalent is 2.

H5R.get_region

Copy of dataspace of specified region

spaceID = H5R.get_region(fileID,reftype,ref) returns a dataspace with the specified region selected. fileID is used to identify the file containing the referenced region and can be any identifier for any object in the file.

Examples

Create Double-Precision and Reference Datasets

Create a double-precision dataset and a reference dataset.

fid = H5F.create("myfile.h5");
type1ID = H5T.copy("H5T_NATIVE_DOUBLE");
dims = [10 5];
h5_dims = fliplr(dims);
h5_maxdims = h5_dims;
space1ID = H5S.create_simple(2,h5_dims,h5_maxdims);
dcpl = "H5P_DEFAULT";
dset1ID = H5D.create(fid,"my_double",type1ID,space1ID,dcpl);
type2ID = "H5T_STD_REF_OBJ";
space2ID = H5S.create("H5S_SCALAR");
dset2ID = H5D.create(fid,"my_ref",type2ID,space2ID,dcpl);
refData = H5R.create(fid,"my_double","H5R_OBJECT",-1);
dxpl = "H5P_DEFAULT";
H5D.write(dset2ID,"H5ML_DEFAULT","H5S_ALL","H5S_ALL",dxpl,refData);
H5D.close(dset2ID);
H5S.close(space2ID);
H5D.close(dset1ID);
H5S.close(space1ID);
H5F.close(fid);

Return Object Identifier

Use the H5R.dereference to return an object identifier using the object reference.

plist = "H5P_DEFAULT";
space = "H5S_ALL";
fid = H5F.open("example.h5");
dsetID = H5D.open(fid,"/g3/reference");
refData = H5D.read(dsetID,"H5T_STD_REF_OBJ",space,space,plist);
derefDsetID = H5R.dereference(dsetID,"H5R_OBJECT",refData(:,1));
H5D.close(derefDsetID);
H5D.close(dsetID);
H5F.close(fid);

Version History

Introduced before R2006a

R2021b: Use H5R.dereference with an object access property list

You can optionally specify an object access property list in H5R.dereference.