[ HDF5 Tutorial Top ]

# Creating a Group

## Contents:

- What is a Group?
- Programming Example
  - Description
  - Remarks
  - File Contents

## What is a Group?

An HDF5 group is a structure containing zero or more HDF5 objects. The two primary HDF5 objects are groups and datasets. To create a group, the calling program must:

1. Obtain the location identifier where the group is to be created.
2. Create the group.
3. Close the group.

To create a group, the calling program must call `H5Gcreate`/`h5gcreate_f`. To close the group, `H5Gclose`/`h5gclose_f` must be called. For example:

C:

      group_id = H5Gcreate (loc_id, name, size_hint);
      status = H5Gclose (group_id);

FORTRAN:

      CALL h5gcreate_f (loc_id, name, group_id, error, size_hint=size)
           or
      CALL h5gcreate_f (loc_id, name, group_id, error)

      CALL h5gclose_f (group_id, error)

## Programming Example

### Description

The following example shows how to create and close a group. It creates a file called `group.h5` (`groupf.h5` for FORTRAN), creates a group called `MyGroup` in the root group, and then closes the group and file.

[ C Example ] - `h5_crtgrp.c`
[ FORTRAN Example ] - `groupexample.f90`
[ Java Example ] - `CreateGroup.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 new empty group, named `MyGroup` and located in the root group, and returns a group identifier.

  C:

        hid_t H5Gcreate (hid_t loc_id, const char *name, size_t size_hint)

  FORTRAN:

        h5gcreate_f (loc_id, name, group_id, hdferr, size_hint)

                 loc_id     INTEGER(HID_T)
                 name       CHARACTER(LEN=*)
                 group_id   INTEGER(HID_T)
                 hdferr     INTEGER
                            (Possible values: 0 on success and -1 on failure)
                 size_hint  INTEGER(SIZE_T), OPTIONAL
                            (Default value: OBJECT_NAMELEN_DEFAULT_F)

  - The loc_id parameter specifies the location at which to create the group.

  - The name parameter specifies the name of the group to be created.

  - The size_hint parameter specifies how much file space to reserve to store the names that will appear in the group. If a non-positive value is supplied, then a default size is used. Passing a value of zero is usually adequate since the library is able to dynamically resize the name heap.

  - In FORTRAN, the return value for the routine is passed in hdferr: 0 if successful, -1 otherwise. The group identifier is passed back in group_id. In C, the function returns a valid group identifier if successful and a negative value otherwise.

- `H5Gclose`/`h5gclose_f` closes the group. This call is mandatory.

  C:

        herr_t H5Gclose (hid_t group_id)

  FORTRAN:

        h5gclose_f (group_id, hdferr)

                 group_id  INTEGER(HID_T)
                 hdferr    INTEGER
                           (Possible values: 0 on success and -1 on failure)

### File Contents

The contents of `group.h5` and the definition of the group are shown below. (The FORTRAN program creates the HDF5 file `groupf.h5` and the resulting DDL shows `groupf.h5` in the first line.)

Fig. 8.1 The Contents of `group.h5`. |  | Fig. 8.2 `group.h5` in DDL

    HDF5 "group.h5" {
    GROUP "/" {
       GROUP "MyGroup" {
       }
    }
    }

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

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