[ HDF5 Tutorial Top ]

# Selecting Individual Points and Copying a Dataspace

## Contents:

- Description
- Programming Example
  - Description
  - Remarks
  - File Contents

## Description

You can select independent points to read from or write to in a dataspace by use of the `H5Sselect_elements` / `h5sselect_elements_f` function.

The `H5Scopy` / `h5scopy_f` function allows you to make an exact copy of a dataspace. This can reduce the number of function calls needed when selecting a dataspace.

## Programming Example

### Description

This example shows how to use `H5Sselect_elements` / `h5sselect_elements_f` to select individual points in a dataset and how to use `H5Scopy` / `h5scopy_f` to make a copy of a dataspace.

[ C example ] - `h5_copy.c`
[ FORTRAN example ] - `selectele.f90`
[ Java example ] - `Copy.java`

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

### Remarks

- `H5Sselect_elements` / `h5sselect_elements_f` selects array elements to be included in the selection for a dataspace:

  C:

         herr_t H5Sselect_elements (hid_t space_id, H5S_seloper_t operator,
                                    size_t num_elements,
                                    const hssize_t **coord )

  FORTRAN:

         h5sselect_elements_f (space_id, operator, num_elements, coord, hdferr)

            space_id       IN: INTEGER(HID_T)
            operator       IN: INTEGER
            num_elements   IN: INTEGER
            coord          IN: INTEGER(HSSIZE_T), DIMENSION(*,*)
            hdferr        OUT: INTEGER

  - The space_id parameter is the dataspace identifier.

  - The operator parameter can be set to one of the following values:
    `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 coord array is a two-dimensional array of size `NUMP x RANK` in C (`RANK x NUMP` in FORTRAN) where `NUMP` is the number of selected points and `RANK` is the rank of the dataset. Note that these coordinates are 0-based in C and 1-based in FORTRAN.

    Consider the non-zero elements of the following array:

                    0  59   0  53
                    0   0   0   0
                    0   0   1   0

    In C, the coord array selecting these points would be as follows:

                    0   1
                    0   3
                    2   2

    While in FORTRAN, the coord array would be as follows:

                    1   1   3
                    2   4   3

  - In C, this function returns a non-negative value if successful and a negative value otherwise. In FORTRAN, the value returned in hdferr indicates whether it was successful (0) or not (-1).

- `H5Scopy` / `h5scopy_f` creates an exact copy of a dataspace:

  C:

         hid_t H5Scopy (hid_t space_id)

  FORTRAN:

         h5scopy_f (space_id, new_space_id, hdferr)

            space_id       IN: INTEGER(HID_T)
            new_space_id  OUT: INTEGER(HID_T)
            hdferr        OUT: INTEGER

  - The space_id parameter is the dataspace identifier to copy.

  - In C, the identifier to the dataspace's copy is returned if the function is successful and a negative value is returned if not. In FORTRAN, the new dataspace identifier is returned in new_space_id and the return value is returned in hdferr ( 0 if successful and -1 if not).

### File Contents

Following is the DDL for copy1.h5 and copy2.h5, as viewed with the following commands:
`h5dump copy1.h5`
`h5dump copy2.h5`

C:

Fig. S.1a `copy1.h5` in DDL

       HDF5 "copy1.h5" {
       GROUP "/" {
          DATASET "Copy1" {
             DATATYPE { H5T_STD_I32BE }
             DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) }
             DATA {
                0, 59, 0, 53,
                0, 0, 0, 0,
                0, 0, 0, 0
             }
          }
       }
       }

Fig. S.1b `copy2.h5` in DDL

       HDF5 "copy2.h5" {
       GROUP "/" {
          DATASET "Copy2" {
             DATATYPE { H5T_STD_I32BE }
             DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) }
             DATA {
                1, 59, 1, 53,
                1, 1, 1, 1,
                1, 1, 1, 1
             }
          }
       }
       }

FORTRAN:

Fig. S.2a `copy1.h5` in DDL

       HDF5 "copy1.h5" {
       GROUP "/" {
          DATASET "Copy1" {
             DATATYPE { H5T_STD_I32BE }
             DATASPACE { SIMPLE ( 4, 3 ) / ( 4, 3 ) }
             DATA {
                0, 0, 0,
                53, 0, 0,
                0, 0, 0,
                59, 0, 0
             }
          }
       }
       }

Fig. S.2b `copy2.h5` in DDL

       HDF5 "copy2.h5" {
       GROUP "/" {
          DATASET "Copy2" {
             DATATYPE { H5T_STD_I32BE }
             DATASPACE { SIMPLE ( 4, 3 ) / ( 4, 3 ) }
             DATA {
                1, 1, 1,
                53, 1, 1,
                1, 1, 1,
                59, 1, 1
             }
          }
       }
       }

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

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