[ HDF5 Tutorial Top ]

# Creating Groups Using Absolute and Relative Names

## Contents:

- Absolute vs. Relative Names
- Programming Example
  - Description
  - Remarks
  - File Contents

## Absolute vs. Relative Names

Recall that to create an HDF5 object, we have to specify the location where the object is to be created. This location is determined by the identifier of an HDF5 object and the name of the object to be created. The name of the created object can be either an absolute name or a name relative to the specified identifier. In the previous example, we used the file identifier and the absolute name `/MyGroup` to create a group.

In this section, we discuss HDF5 names and show how to use absolute and relative names.

### Names

HDF5 object names are a slash-separated list of components. There are few restrictions on names: component names may be any length except zero and may contain any character except slash (`/`) and the null terminator. A full name may be composed of any number of component names separated by slashes, with any of the component names being the special name `.` (a dot or period). A name which begins with a slash is an absolute name which is accessed beginning with the root group of the file; all other names are relative names and and the named object is accessed beginning with the specified group. Multiple consecutive slashes in a full name are treated as single slashes and trailing slashes are not significant. A special case is the name `/` (or equivalent) which refers to the root group.

Functions which operate on names generally take a location identifier, which can be either a file identifier or a group identifier, and perform the lookup with respect to that location. Several possibilities are described in the following table:

Location Type | Object Name | Description
File identifier | `/foo/bar` | The object `bar` in group `foo` in the root group.
Group identifier | `/foo/bar` | The object `bar` in group `foo` in the root group of the file containing the specified group. In other words, the group identifier's only purpose is to specify a file.
File identifier | / | The root group of the specified file.
Group identifier | / | The root group of the file containing the specified group.
Group identifier | `foo/bar` | The object `bar` in group `foo` in the specified group.
File identifier | . | The root group of the file.
Group identifier | . | The specified group.
Other identifier | . | The specified object.

## Programming Example

### Description

The following example code shows how to create groups using absolute and relative names. It creates three groups: the first two groups are created using the file identifier and the group absolute names while the third group is created using a group identifier and a name relative to the specified group.

[ C Example ] - `h5_crtgrpar.c`
[ Fortran Example ] - `grpsexample.f90`
[ Java Example ] - `CreateGroupAR.java`

NOTE: To download a tar file of the examples, including a Makefile, please go to the References page.

### Remarks

- `H5Gcreate`/`h5gcreate_f` creates a group at the location specified by a location identifier and a name. The location identifier can be a file identifier or a group identifier and the name can be relative or absolute.

- The first `H5Gcreate`/`h5gcreate_f` creates the group `MyGroup` in the root group of the specified file.

- The second `H5Gcreate`/`h5gcreate_f` creates the group `Group_A` in the group `MyGroup` in the root group of the specified file. Note that the parent group (`MyGroup`) already exists.

- The third `H5Gcreate`/`h5gcreate_f` creates the group `Group_B` in the specified group.

### File Contents

The file contents are shown below:

Fig. 9.1 The Contents of `groups.h5` (`groupsf.h5` for FORTRAN)

Fig. 9.2 `groups.h5` in DDL (for FORTRAN, the name in the first line is `groupsf.h5`)

          HDF5 "groups.h5" {
          GROUP "/" {
             GROUP "MyGroup" {
                GROUP "Group_A" {
                }
                GROUP "Group_B" {
                }
             }
          }
          }

The National Center for Supercomputing Applications
University of Illinois at Urbana-Champaign
hdfhelp@ncsa.uiuc.edu

###### Last Modified: June 22, 2001