Selecting Individual Points and Copying a Dataspace

Description

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

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).

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
         }
      }
   }
   }

   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
         }
      }
   }
   }

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
         }
      }
   }
   }

   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
         }
      }
   }
   }