Accessing objects by location and name:

To work with an HDF5 object, an application needs the object's location identifier. An object's location identifier is returned to an application after the object is opened.

To open an object, an application uses a function with three parameters: the location identifier of an already opened object, a path from the already opened object to the object that will be opened, and a property list. The location identifier of an already opened object is its loc_id. An already opened object might be a file or a group. The path from the already opened object to the object that will be opened is kept in the name parameter. The path will be one or more links. For the rest of this discussion, we will assume that the default property list, H5P_DEFAULT, is used.

See the HDF5 Reference Manual entries for the H5Dopen, H5Gopen, H5Oopen, and H5Topen functions for more information on opening datasets, groups, objects, and datatypes.

*

??????? The process of identifying an object is to specify a path to the object from a known location.

Suppose we wanted to read the dataset that is the target of the dset3 link in the figure below. The H5Dread function call needs an identifier for the dataset. How does an application go about getting that identifier?

The identifier that is returned from this process can then be used when the object is operated on. The loc_id and name parameters are used in many HDF5 function calls to specify a known location

???????

Many HDF5 function calls use a combination of a location and name to identify an HDF5 object.

The location will be specified by a location identifier, loc_id, and will be an HDF5 file or object such as a group, dataset, or committed datatype*.

The name parameter, name, will be a character string and will specify the links to an object in an HDF5 file. The link or links to the object will be either an absolute path or a relative path. An absolute path will include all of the links from the root group to the object. A relative path will include all of the links from any other group to the object.

Figure 1: File structure for DATA_FILE1

Several loc_id and name combinations are possible. To illustrate, the following combinations all identify dset3 in the file structure in the figure.

• If loc_id is a file identifier, name must specify the object from the file’s root group.

  loc_id specifies the file DATA_FILE1.
  name = '/group2/group3/dset3'  

• If loc_id is a group identifier and the object of interest is a member of that group, name will simply be the name of the link to the object.

  loc_id specifies group3.
  name = 'dset3'  

• If loc_id is a group identifier but the object of interest is not a direct member of that group, name would specify the object by a path relative to that group.

  loc_id specifies group2.
  name = 'group3/dset3'

  Alternatively, name could specify the object with an absolute path in the file containing loc_id.

  loc_id specifies group2.
  name = '/group2/group3/dset3'  

• There is one special case: if loc_id is the identifier of the object itself, name should be a dot ( . ). For those familiar with a UNIX shell, this works in much the same manner as a dot ( . ) specifying the current working directory.

  loc_id specifies dset3, the dataset itself.
  name = '.'  

Many HDF5 functions accept loc_id and name in all of the above combinations. When accepted combinations are limited for a specific function, the limitations are mentioned in the function’s reference manual entry.

For a related discussion of the structure of HDF5 files and HDF5 path names, see “The Structure of an HDF5 File” (particularly the sub-section “HDF5 Path Names and Navigation”) in the “HDF5 Data Model and File Structure” chapter of the HDF5 User’s Guide.

* In the past, a committed datatype was known as a named datatype.