Last modified: 7 July 2010
Name: H5LRcreate_region_references
Signature:
herr_t H5LRcreate_region_references( hid_t loc_id, size_t num_elem, const char **path, const hsize_t *block_coord, hdset_reg_ref_t *ref_buf )

Purpose:
Creates an array of region references using an array of paths to datasets and an array of corresponding hyperslab descriptions.

Motivation:
H5LRcreate_region_references is useful when creating large numbers of similar region references.

Description:
H5LRcreate_region_references creates a list of region references given an array of paths to datasets and another array listing the corner coordinates of the corresponding hyperslabs.

path parameter is an array of pointers to strings.

num_elem specifies the number of region references to be created, thus specifying the size of the path and ref_buf arrays.

Buffer block_coord has size 2*rank and is the coordinates of the starting point following by the coordinates of the ending point of the hyperslab, repeated num_elem times for each hyperslab. For example, creating two region references to two hyperslabs, one with a rectangular hyperslab region starting at element (2,2) to element (5,4) and the second rectangular region starting at element (7,7) to element (9,10), results in block_coord being {2,2,5,4, 7,7,9,10}.

The rank of the hyperslab will be the same as the rank of the target dataset. H5LRcreate_region_references will retrieve the rank for each dataset and will use those values to interpret the values in the buffer. Please note that rank may vary from one dataset to another.

Parameters:
hid_t loc_id      IN: File identifier for the HDF5 file containing the referenced regions or an object identifier for any object in that file
size_t num_elem   IN: Number of elements in the path and ref_buf arrays
const char **path   IN: Array of pointers to strings, which contain the paths to the target datasets for the region references
const hsize_t *block_coord   IN: Array of hyperslab coordinates
hdset_reg_ref_t *ref_buf   OUT: Buffer for returning an array of region references

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: H5LRcreate_region_references_f: USE H5HL_REGION
SUBROUTINE H5LRcreate_region_references_f(loc_id, num_elem, path, block_coord, buf, error)
    
  IMPLICIT NONE
    
  INTEGER(hid_t), INTENT(IN)  :: loc_id                                       ! File identifier for the HDF5 file containing the 
                                                                              !  referenced regions or 
                                                                              !  an object identifier for any object in that file
  INTEGER(size_t), INTENT(IN) :: num_elem                                     ! Number of elements in the path and ref_buf arrays
  CHARACTER(LEN=*), DIMENSION(1:num_elem), INTENT(IN) :: path                 ! Array of strings, which contain the paths to the 
                                                                              !  target datasets for the region references
  INTEGER(hsize_t), DIMENSION(:), INTENT(IN) :: block_coord                   ! Array of hyperslab coordinates  
  TYPE(hdset_reg_ref_t_f), DIMENSION(1:num_elem), INTENT(OUT) :: buff         ! Buffer for returning an array of region references 
  INTEGER, INTENT(OUT) :: error                                               ! Error code:
                                                                              !  0 on success and -1 on failure
END SUBROUTINE H5LRcreate_region_references_f
    

History:
Release     Change
1.0 C function introduced in this release.
1.1 Fortran wrapper introduced in this release.