[ HDF5 Tutorial Top ]

# Hyperslab Selections

## Contents:

- Selecting a Portion of a Dataspace
- Programming Example
  - Description
  - Remarks

## Selecting a Portion of a Dataspace

Hyperslabs are portions of datasets. A hyperslab selection can be a logically contiguous collection of points in a dataspace, or it can be a regular pattern of points or blocks in a dataspace. You can select a hyperslab to write to or read from with the function `H5Sselect_hyperslab` / `h5sselect_hyperslab_f`.

## Programming Example

### Description

This example creates a 5 x 6 integer array in a file called `sds.h5` (`sdsf.h5` in FORTRAN). It selects a 3 x 4 hyperslab from the dataset as follows (Dimension 0 is offset by 1 and Dimension 1 is offset by 2):

5 x 6 array:

|  | X | X | X | X
|  | X | X | X | X
|  | X | X | X | X

Then it reads the hyperslab from this file into a 2-dimensional plane (size 7 x 7) of a 3-dimensional array (size 7 x 7 x 3), as follows (with Dimension 0 offset by 3):

X | X | X | X |  |  |
X | X | X | X |  |  |
X | X | X | X |  |  |

To obtain the example, download:

[ C example ] - `h5_hyperslab.c`
[ FORTRAN example ] - `hyperslab.f90`
[ Java example ] - `HyperSlab.java`

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

### Remarks

- `H5Sselect_hyperslab` / `h5sselect_hyperslab_f` selects a hyperslab region to add to the current selected region for a specified dataspace.

  C:

          herr_t H5Sselect_hyperslab (hid_t space_id, H5S_seloper_t operator,
              const hssize_t *start, const hsize_t *stride,
              const hsize_t *count, const hsize_t *block )

  FORTRAN:

          h5sselect_hyperslab_f (space_id, operator, start, count, &
                                 hdferr, stride, block)

                  space_id    IN: INTEGER(HID_T)
                  operator    IN: INTEGER
                  start       IN: INTEGER(HSSIZE_T), DIMENSION(*)
                  count       IN: INTEGER(HSIZE_T), DIMENSION(*)
                  hdferr     OUT: INTEGER
                  stride      IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL
                  block       IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL

  - The parameter space_id is the dataspace identifier for the specified dataspace.

  - The parameter operator can be set to one of the following:
    `H5S_SELECT_SET` (`H5S_SELECT_SET_F` in FORTRAN)
      Replace the existing selection with the parameters from this call. Overlapping blocks are not supported with this operator.
    `H5S_SELECT_OR` (`H5S_SELECT_OR_F` in FORTRAN)
      Add the new selection to the existing selection.

  - The start array determines the starting coordinates of the hyperslab to select.

  - The stride array indicates which elements along a dimension are to be selected.

  - The count array determines how many positions to select from the dataspace in each dimension.

  - The block array determines the size of the element block selected by the dataspace.

  - In C, a non-negative value is returned if successful, and a negative value otherwise. In FORTRAN, the return value is returned in hdferr: 0 if successful and -1 otherwise.

  The start, stride, count, and block arrays must be the same size as the rank of the dataspace.

- The examples introduce the following call:
  `H5Dget_space / h5dget_space_f:`
    Returns an identifier for a copy of the dataspace of a dataset.

- The C example also introduces the following calls:
  `H5Sget_simple_extent_dims:`
    Returns the size and maximum size of each dimension of a dataspace.
  `H5Sget_simple_extent_ndims:`
    Determines the dimensionality (or rank) of a dataspace.

  The FORTRAN example does not use these calls, though they are available as `h5sget_simple_extent_dims_f` and `h5sget_simple_extent_ndims_f`.

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

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