Development Environment

Including Metadata in an HDF File

You can optionally include information in an HDF file that describes your data. HDF defines an separate annotation API; however, the HDF SD API includes an annotation capability. This section only describes the annotation capabilities of the HDF SD API. For information about the Annotation API, see the official NCSA documentation.

Types of Attributes

Using the HDF SD API, you can associate attributes with three types of HDF objects:

• An entire HDF file -- File attributes, also called global attributes, generally contain information pertinent to all the data sets in the file.
• A data set in an HDF file -- Data set attributes, also called local attributes, describe individual data sets.
• A dimension of a data set -- Dimension attributes provide information about one particular dimension of a data set.

Multiple Attributes

You can associate multiple attributes with a single HDF object. HDF maintains an attribute index for each object. The attribute index is zero-based. The first attribute has index value 0, the second has index value 1, and so on. You access an attribute by its index value.

Each attribute has the format name=value, where name (called label in HDF terminology) is a text string up to 256 characters in length and value contains one or more entries of the same data type. A single attribute can have multiple values.

Associating Attributes with HDF SD Objects

In the HDF SD API, you use the SDsetattr routine to associate an attribute with a file, data set, or dimension. In MATLAB, use the hdfsd function, specifying setattr as the first argument. As other arguments, specify

• A valid HDF SD identifier associated with the object. This value can be a file identifier (sd_id), a data set identifier (sds_id), or a dimension identifier (dim_id).
• A text string that defines the name of the attribute. The SD interface supports predefined attributes that have reserved names and, in some cases, data types. For information about these attributes, see Creating Predefined Attributes.
• The attribute value.

For example, this code creates a global attribute, named my_global_attr, and associates it with the HDF file identified by sd_id.

• status = hdfsd('setattr',sd_id,'my_global_attr','my_attr_val');
  

Note    In the NCSA documentation, the SDsetattr routine has two additional arguments: data type and the number of values in the attribute. When calling this routine from MATLAB, you do not have to include these arguments. The MATLAB HDF function can determine the data type and size of the attribute from the value you specify.

Creating Predefined Attributes

Predefined attributes are identical to user-defined attributes except that the HDF SD API has already defined their names and data types. For example, the HDF SD API defines an attribute, named cordsys, in which you can specify the coordinate system used by the data set. Possible values of this attribute include the text strings 'cartesian', 'polar', and 'spherical'.

Predefined attributes can be useful because they establish conventions that applications can depend on. The HDF SD API supports predefined attributes for data sets and dimensions only; there are no predefined attributes for files. For a complete list of the predefined attributes, see the NCSA documentation.

In the HDF SD API, you create predefined attributes the same way you create user-defined attributes, using the SDsetattr routine. In MATLAB, use the hdfsd function, specifying setattr as the first argument:

• attr_name = 'cordsys';
  attr_value = 'polar';
  
  status = hdfsd('setattr',sds_id,attr_name,attr_value);
  

The HDF SD API also includes specialized functions for writing and reading the predefined attributes. These specialized functions, such as SDsetdatastrs, are sometimes easier to use, especially when you are reading or writing multiple related predefined attributes. You must use specialized functions to read or write the predefined dimension attributes.

The HDF SD Export Programming Model

Using the MATLAB HDF Utility API