HDF5 High-level Functions for Region References, Hyperslabs, and Bit-fields

The following reference manual entries describe high-level HDF5 C and Fortran APIs for working with region references, hyperslab selections, and bit-fields. These functions were created as part of a project supporting NPP/NPOESS Data Production and Exploitation (project, software). While they were written to facilitate access to NPP, NPOESS, and JPSS data in the HDF5 format, these functions may be useful to anyone working with region references, hyperslab selections, or bit-fields.

Note that these functions are not part of the standard HDF5 distribution; the software must be separately downloaded and installed. For documentation of the underlying HDF5 Library, see  https://support.hdfgroup.org/HDF5/doc.

A comprehensive guide to this library, User Guide to the HDF5 High-level Library for Handling Region References and Hyperslab Selections is available at https://support.hdfgroup.org/projects/npoess/HL_NPOESS/doc/UG/NPOESS_HL-UG.pdf.

Reference Manual

Region Reference APIs    Hyperslab APIs

Bit-field API

C Code Examples

Example    Description    Illustrated function(s)
ex_lite_read_region.c    Read a dataset region, given a set of corner coordinates    H5LTread_region
ex_regref_read.c    Create, store and read data associated with region references    H5LRget_region_info
H5LRread_region
ex_lite_copy_region.c    Copy a dataset region    H5LTcopy_region
ex_regref_copy_references.c    Copy a referenced region and create a new region reference to the copy    H5LRcopy_references
ex_regref_create.c    Create region references and create a new dataset composed of data from the referenced regions    H5LRcreate_region_references
ex_ref_to_all.c    Create and write a dataset of region references    H5LRcreate_ref_to_all
ex_bitfield.c    Read and write quality flag bit-fields    H5LTread_bitfield_value

FORTRAN Code Examples

Example    Description    Illustrated function(s)
ex_lite_read_region.f90    Read a dataset region, given a set of corner coordinates    H5LTread_region_f
ex_regref_read.f90    Create, store and read data associated with region references    H5LRget_region_info_f
H5LRread_region_f
ex_lite_copy_region.f90    Copy a dataset region    H5LTcopy_region_f
ex_regref_copy_reference.f90    Copy a referenced region and create a new region reference to the copy    H5LRcopy_references_f
ex_regref_create.f90    Create region references and create a new dataset composed of data from the referenced regions    H5LRcreate_region_references_f
ex_ref_to_all.f90    Create and write a dataset of region references    H5LRcreate_ref_to_all_f
ex_bitfield.f90    Read and write quality flag bit-fields    H5LTread_bitfield_value_f

RFCs


Region Reference APIs

Last modified: 7 July 2010
Name: H5LRget_region_info
Signature:
herr_t H5LRget_region_info( hid_t obj_id, const hdset_reg_ref_t *ref, size_t *len, char *path, int*rank, hid_t *dtype, H5S_sel_type *sel_type, size_t *numelem, hsize_t *buf )

Purpose:
Retrieves information about the data a region reference points to.

Description:
H5LRget_region_info queries information about the data pointed by a region reference ref. It returns one of the absolute paths to a dataset, length of the path, dataset’s rank and datatype, description of the referenced region and type of the referenced region. Any output argument can be NULL if that argument does not need to be returned.

The parameter obj_id is an identifier for any object in the HDF5 file containing the referenced object. For example, it can be an identifier of a dataset the region reference belongs to or an identifier of an HDF5 file the dataset with region references is stored in.

The parameter ref is a region reference to query.

The parameter path is a pointer to application allocated buffer of size len+1 to return an absolute path to a dataset the region reference points to.

The parameter len is a length of absolute path string plus the \0 string terminator. If path parameter is NULL, actual length of the path (+1 for \0 string terminator) is returned to application and can be used to allocate buffer path of an appropriate length len.

The parameter sel_type describes the type of the selected region. Possible values can be H5S_SEL_POINTS for point selection and H5S_SEL_HYPERSLABS for hyperslab selection.

The parameter numelem describes how many elements will be placed in the buffer buf. The number should be interpreted using the value of sel_type.

If value of sel_type is H5S_SEL_HYPERSLABS, the parameter buf contains numelem blocks of the coordinates for each simple hyperslab of the referenced region. Each block has length 2*rank and is organized as follows: <"start" coordinate>, immediately followed by <"opposite" corner coordinate>. The total size of the buffer to hold the description of the region will be 2*rank*numelem. If region reference points to a contiguous sub-array, then the value of numelem is 1 and the block contains coordinates of the upper left and lower right corners of the sub-array (or simple hyperslab).

If value of sel_type is H5S_SEL_POINTS, the parameter buf contains numelem blocks of the coordinates for each selected point of the referenced region. Each block has length rank and contains coordinates of the element. The total size of the buffer to hold the description of the region will be rank*numelem.

Parameters:
hid_t obj_id      IN: Identifier of any object in an HDF5 file the region reference belongs to.
const hdset_reg_ref_t *ref   IN: Region reference to query.
size_t *len   IN/OUT: Size of the buffer to store path in. NOTE: if *path is not NULL then *len must be the appropriate length
char *path   OUT: Full path that a region reference points to.
int *rank   OUT: The number of dimensions of the dataset dimensions of the dataset pointed by region reference.
hid_t *dtype   OUT: Datatype of the dataset pointed by the region reference.
H5S_sel_type *sel_type   OUT: Type of the selection (point or hyperslab).
size_t *numelem   IN/OUT: Number of coordinate blocks or selected elements.
hsize_t *buf   OUT: Buffer containing description of the region pointed by region reference.

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

Fortran90 Interface: H5LRget_region_info_f: USE H5HL_REGION 
SUBROUTINE H5LRget_region_info_f(obj_id, ref, error, &               
     length, path, rank, dtype, sel_type, numelem, buf)
   IMPLICIT NONE

  INTEGER(hid_t), INTENT(IN) :: obj_id                              ! Identifier of any object in an HDF5 file the region 
                                                                    !  reference belongs to.
  TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref                        ! Region reference to query
  INTEGER, INTENT(OUT) :: error                                     ! Error code:
                                                                    !  0 on success and -1 on failure
  INTEGER(size_t), INTENT(INOUT), OPTIONAL :: length                ! Size of the buffer to store path in
                                                                    ! NOTE: If path is present then length
                                                                    !       is required and must be large enough to hold path.
                                                                    !       Returns the trimmed length of path
  CHARACTER(LEN=*), INTENT(INOUT), DIMENSION(1:1), OPTIONAL :: path ! Full path that a region reference points to
  INTEGER, INTENT(OUT), OPTIONAL :: rank                            ! The number of dimensions of the dataset dimensions 
                                                                    !  of the dataset pointed by region reference
  INTEGER(hid_t), INTENT(OUT), OPTIONAL :: dtype                    ! Datatype of the dataset pointed by the region reference
  INTEGER, INTENT(OUT), OPTIONAL :: sel_type                        ! Type of the selection (point or hyperslab)
  INTEGER(size_t), INTENT(INOUT), OPTIONAL :: numelem               ! Number of coordinate blocks or selected elements
  INTEGER(hsize_t), DIMENSION(*), OPTIONAL :: buf                   ! Buffer containing description of the region pointed 
                                                                    !  by region reference
END SUBROUTINE H5LRget_region_info_f

History:
Release     Change
1.0 C function introduced in this release.
1.1 Fortran wrapper introduced in this release.
(Top)
Last modified: 7 July 2010
Name: H5LRread_region
Signature:
herr_t H5LRread_region( hid_t loc_id, const hdset_reg_ref_t *ref, hid_t mem_type, size_t *num_elem, void *buf )

Purpose:
Retrieves raw data pointed to by a region reference to an application buffer.

Description:
H5LRread_region reads data pointed to by the region reference ref into the buffer buf.

num_elem specifies the number of elements to be read into buf. When the size of the reference region is unknown, H5LRread_region can be called with buf set to NULL; the number of elements in the referenced region will be returned in num_elem.

The buffer buf must be big enough to hold num_elem elements of type mem_type. For example, if data is read from the referenced region into an integer buffer, mem_type should be H5T_NATIVE_INT and the buffer must be at least  sizeof(int) * num_elem  bytes in size. This buffer must be allocated by the application.

Parameters:
hid_t loc_id      IN: File identifier for the HDF5 file containing the dataset with the referenced region or an object identifier for any object in that file
const hdset_reg_ref_t *ref   IN: Region reference specifying data to be read in
hid_t mem_type   IN: Memory datatype of data read from referenced region into the application buffer
size_t *num_elem   IN/OUT: Number of elements to be read into buffer buf
void *buf   OUT: Buffer in which data is returned to the application

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

Fortran90 Interface: H5LRread_region_f: USE H5HL_REGION 
SUBROUTINE H5LRread_region_f(loc_id, ref, dtype, numelem, buf, error)

  IMPLICIT NONE
    
  INTEGER(hid_t), INTENT(IN) :: loc_id       ! File identifier for the HDF5 file containing the dataset with 
                                             !  the referenced region or an object identifier for any object 
                                             !  in that file 
  TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref ! Region reference specifying data to be read in 
  INTEGER(hid_t), INTENT(IN) :: dtype        ! Memory datatype of data read from referenced region into the 
                                             !  application buffer
  INTEGER(size_t), INTENT(INOUT) :: numelem  ! Number of elements to be read into buffer buf
  TYPE(C_PTR), INTENT(OUT) :: buf            ! Buffer in which data is returned to the application 
  INTEGER, INTENT(OUT) :: error              ! Error code:
                                             !  0 on success and -1 on failure
END SUBROUTINE H5LRread_region_f

History:
Release     Change
1.0 C function introduced in this release.
1.1 Fortran wrapper introduced in this release.
(Top)
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.
(Top)
Last modified: 7 July 2010
Name: H5LRmake_dataset
Signature:
herr_t H5LRmake_dataset( hid_t loc_id, const char *path, hid_t type_id, const size_t num_elem, const hid_t *obj_id, const hdset_reg_ref_t *buf )

Purpose:
Creates and writes a dataset containing a list of region references.

Description:
Given an array of size num_elem of region references buf, the function will create a dataset with path path, at location specified by loc_id and of a datatype specified by type_id, and will write data associated with each region reference in the order corresponding to the order of the region references in the buffer. It is assumed that all referenced hyperslabs have the same dimensionality, and only the size of the slowest changing dimension may differ. Each reference in the buf array belongs to the file identified by the corresponding object identifiers in the array obj_id.

If path does not exist in loc_id then the function will create the path specified by path automatically.

Parameters:
hid_t loc_id      IN: Location identifier of the dataset to be created
const char *path   IN: Path to the dataset being created
hid_t type_id   IN: Datatype of the dataset
const size_t num_elem      IN: Size of the obj_id and buf arrays
const hid_t *obj_id   IN: Array of object identifiers; each identifier describes to which HDF5 file the corresponding region reference belongs to
const hdset_reg_ref_t *buf   IN: Array of region references

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

Fortran90 Interface: H5LRmake_dataset_f: USE H5HL_REGION 
SUBROUTINE H5LRmake_dataset_f(loc_id, path, type_id, &
     buf_size,loc_id_ref, ref, error)

  IMPLICIT NONE

  INTEGER(hid_t), INTENT(IN) :: loc_id                              ! Location identifier of the dataset to be created 
  CHARACTER(LEN=*), INTENT(IN) :: path                              ! Path to the dataset being created 
  INTEGER(hid_t), INTENT(IN) :: type_id                             ! Datatype of the dataset 
  INTEGER(size_t) :: buf_size                                       ! Size of the obj_id and buf arrays 
  INTEGER(hid_t), DIMENSION(1:buf_size), INTENT(IN) :: loc_id_ref   ! Array of object identifiers; each identifier describes 
                                                                    !  to which HDF5 file the corresponding region 
                                                                    !  reference belongs to 
  TYPE(hdset_reg_ref_t_f), DIMENSION(1:buf_size), INTENT(IN) :: ref ! Array of region references  
  INTEGER, INTENT(OUT) :: error                                     ! Error code:
                                                                    !  0 on success and -1 on failure

END SUBROUTINE H5LRmake_dataset_f

History:
Release     Change
1.0 C function introduced in this release.
1.1 Fortran wrapper introduced in this release.
(Top)
Last modified: 7 July 2010
Name: H5LRcopy_region
Signature:
herr_t H5LRcopy_region( hid_t obj_id, hdset_reg_ref_t *ref, const char *file_dest, const char *path_dest, const hsize_t *block_coord_dest )

Purpose:
Copies data from a referenced region to a region in a destination dataset.

Description:
Given a dataset region reference ref in a source file specified by an identifier of any object in that file obj_id, the function will write data to the existing dataset path_dest in file file_dest to the simple hyperslab specified by block_coord_dest.

Buffer block_coord_dest has size 2*rank and is the coordinates of the starting point following by the coordinates of the ending point of the hyperslab. For example, to specify a rectangular hyperslab destination region starting at element (2,2) to element (5,4) then block_coord_dest would be {2, 2, 5, 4}.

If path does not exist in the destination file (as may be the case when writing to a new file) then the dataset will be copied directly to the path and block_coord will be disregarded.

Parameters:
hid_t obj_id      IN: Identifier of any object in a file dataset region reference belongs to
hdset_reg_ref_t *ref   IN: Dataset region reference
const char *file_dest   IN: Name of the destination file
const char *path_dest   IN: Full path to the destination dataset
const hsize_t *block_coord_dest   IN: Hyperslab coordinates in the destination dataset

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

Fortran90 Interface: H5LRcopy_region_f: USE H5HL_REGION 
SUBROUTINE H5LRcopy_region_f(obj_id, ref, file_dest, path_dest, block_coord_dest, error)

  IMPLICIT NONE

  INTEGER(hid_t), INTENT(IN) :: obj_id                           ! Identifier of any object in a file 
                                                                 ! dataset region reference belongs to 
  TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref                     ! Dataset region reference 
  CHARACTER(LEN=*), INTENT(IN) :: file_dest                      ! Name of the destination file 
  CHARACTER(LEN=*), INTENT(IN) :: path_dest                      ! Full path to the destination dataset
  INTEGER(hsize_t), DIMENSION(:), INTENT(IN) :: block_coord_dest ! Hyperslab coordinates in the destination dataset
  INTEGER, INTENT(OUT) :: error                                  ! Error code:
                                                                 !  0 on success and -1 on failure
END SUBROUTINE H5LRcopy_region_f

History:
Release     Change
1.0 C function introduced in this release.
1.1 Fortran wrapper introduced in this release.
(Top)
Last modified: 7 July 2010
Name: H5LRcopy_reference
Signature:
herr_t H5LRcopy_reference( hid_t obj_id, hdset_reg_ref_t *ref, const char *file, const char *path, const hsize_t *block_coord, hdset_reg_ref_t *ref_new )

Purpose:
Copies data from the specified dataset to a new location and creates a reference to it.

Description:
Given a data set pointed to by a region reference, the function H5LRcopy_reference will copy the hyperslab data referenced by a datasets region reference into existing dataset specified by its path path in the file with the name file, and to location specified by the hyperslab coordinates block_coord. It will create the region reference ref_new to point to the new location. The number of elements in the old and newly specified regions has to be the same.

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. For example, to extract a rectangular hyperslab region starting at element (2,2) to element (5,4) then block_coord would be {2, 2, 5, 4}.

Parameters:
hid_t obj_id      IN: Identifier of any object in a file an HDF5 reference belongs to
hdset_reg_ref_t ref   IN: Reference to the datasets region
const char *file   IN: Name of the destination file
const char *path   IN: Full path to the destination dataset
const hsize_t *block_coord   IN: Hyperslab coordinates in the destination dataset
hdset_reg_ref_t *ref_new   OUT: Region reference to the new location of data

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

Fortran90 Interface: H5LRcopy_reference_f: USE H5HL_REGION 
SUBROUTINE H5LRcopy_reference_f( obj_id, ref, file, path, block_coord, ref_new, error )

  IMPLICIT NONE

  INTEGER(hid_t), INTENT(in) :: obj_id                       ! Identifier of any object in a file an 
                                                             !  HDF5 reference belongs to 
  TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref                 ! Reference to the datasets region 
  CHARACTER(LEN=*), INTENT(IN) :: file                       ! Name of the destination file
  CHARACTER(LEN=*), INTENT(IN) :: path                       ! Full path to the destination dataset 
  INTEGER(hsize_t), DIMENSION(:), INTENT(IN) :: block_coord  ! Hyperslab coordinates in the destination dataset 
  TYPE(hdset_reg_ref_t_f), INTENT(OUT) :: ref_new            ! Region reference to the new location of data 
  INTEGER, INTENT(OUT) :: error                              ! Error code:
                                                             !  0 on success and -1 on failure
END SUBROUTINE H5LRcopy_reference_f

History:
Release     Change
1.0 C function introduced in this release.
1.1 Fortran wrapper introduced in this release.
(Top)
Last modified: 7 July 2010
Name: H5LRcreate_ref_to_all
Signature:
return_type H5LRcreate_ref_to_all( hid_t loc_id, const char *group_path, const char *ds_path, H5_index_t index_type, H5_iter_order_t order,
 H5R_type_t ref_type )

Purpose:
Creates a dataset with the region references to the data in all datasets located under a specified group in a file or creates a dataset with object references to all objects (groups or datasets) located under a specified group in a file.

Description:
H5LRcreate_ref_to_all creates a dataset with the region references to the data in all datasets located under a specified group in a file or creates a dataset with object references to all objects (groups or datasets) located under a specified group in a file.

Given a dataset path ds_path in a file specified by the loc_id identifier, the function H5LRcreate_ref_to_all will create a contiguous one-dimensional dataset with the region references or object references depending on the value of the ref_type parameter. When ref_type is H5R_DATASET_REGION, each region reference points to all data in a dataset encountered by an internally called H5Lvisit routine, which starts at the group specified by the loc_id and group_path parameters. In a like manner, when ref_type is H5R_OBJECT, each object reference points to an object (a group or a dataset) encountered by H5Lvisit.

If ds_path does not exist in loc_id then the function will create the path specified by ds_path automatically.

index_type specifies the index to be used. Valid values include the following:

H5_INDEX_NAME         Alpha-numeric index on name
H5_INDEX_CRT_ORDER    Index on creation order

order specifies the order in which objects are to be inspected along the index specified in index_type. Valid values include the following:

H5_ITER_INC       Increasing order
H5_ITER_DEC       Decreasing order
H5_ITER_NATIVE    Fastest available order

For more detailed information on these two parameters, see H5Lvisit.

ref_type specifies the type of the reference to be used. Valid values include the following:

H5R_DATASEY_REGION    Dataset region reference
H5R_OBJECT            Object reference

Parameters:
hid_t loc_id      IN: File or group identifier
const char *group_path      IN: Absolute or relative path to the group at which traversal starts
const char *ds_path      IN: Absolute or relative path to the dataset with region references to be created
H5_index_t index_type      IN: Index type; valid values include:
     H5_INDEX_NAME
     H5_INDEX_CRT_ORDER
H5_iter_order_t order      IN: Order in which index is traversed; valid values include:
     H5_ITER_DEC
     H5_ITER_INC
     H5_ITER_NATIVE
H5R_type_t ref_type      IN: Reference type; valid values include:
     H5R_DATASET_REGION
     H5R_OBJECT

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

Fortran90 Interface: H5LRcreate_ref_to_all_f: USE H5HL_REGION 
SUBROUTINE H5LRcreate_ref_to_all_f(loc_id, group_path, ds_path, index_type, order, ref_type, error)
    
  IMPLICIT NONE

  INTEGER(hid_t), INTENT(IN) :: loc_id       ! File or group identifier 
  CHARACTER(LEN=*), INTENT(IN) :: group_path ! Absolute or relative path to the group at 
                                             !  which traversal starts 
  CHARACTER(LEN=*), INTENT(IN) :: ds_path    ! Absolute or relative path to the dataset 
                                             !  with region references to be created  
  INTEGER, INTENT(IN) :: index_type          ! Index type; valid values include:
                                             !     H5_INDEX_NAME_F
                                             !     H5_INDEX_CRT_ORDER_F
  INTEGER, INTENT(IN) :: order               ! Order in which index is traversed; valid values include:
                                             !     H5_ITER_DEC_F
                                             !     H5_ITER_INC_F
                                             !     H5_ITER_NATIVE_F
  INTEGER, INTENT(IN) :: ref_type            ! Reference type; valid values include:  
                                             !     H5R_DATASET_REGION_F
                                             !     H5R_OBJECT_F 
  INTEGER, INTENT(OUT) :: error              ! Error code:
                                             !  0 on success and -1 on failure
END SUBROUTINE H5LRcreate_ref_to_all_f

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

Hyperslab APIs

Last modified: 7 July 2010
Name: H5LTread_region
Signature:
herr_t H5LTread_region( const char *file, const char *path, const hsize_t *block_coord, hid_t mem_type, void *buf )

Purpose:
Reads selected data to an application buffer.

Description:
H5LTread_region reads data from a region described by the hyperslab coordinates in block_coord, located in the dataset specified by its absolute path path in a file specified by its name file. Data is read into a buffer buf of the datatype that corresponds to the HDF5 datatype specified by mem_type.

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. For example, to extract a rectangular hyperslab region starting at element (2,2) to element (5,4) then block_coord would be {2, 2, 5, 4}.

Buffer buf should be big enough to hold selected elements of the type that corresponds to the mem_type datatype.

Parameters:
const char *file      IN: Name of file
const char *path   IN: Full path to a dataset
const hsize_t *block_coord   IN: Hyperslab coordinates
hid_t mem_type   IN: Memory datatype, describing the buffer the referenced data will be read into
void *buf   OUT: Buffer containing data from the referenced region

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

Fortran90 Interface: H5LTread_region_f: USE H5HL_REGION 
SUBROUTINE H5LTread_region_f(file, path, block_coord, mem_type, buf, error)
    
  IMPLICIT NONE
  CHARACTER(LEN=*), INTENT(IN) :: file                      ! Name of file
  CHARACTER(LEN=*), INTENT(IN) :: path                      ! Full path to a dataset 
  INTEGER(hsize_t), DIMENSION(:), INTENT(IN) :: block_coord ! Hyperslab coordinates 
  INTEGER(hid_t), INTENT(IN) :: mem_type                    ! Memory datatype, describing the buffer
                                                            ! the referenced data will be read into 
  TYPE(C_PTR), INTENT(OUT) :: buf                           ! Buffer containing data from 
                                                            ! the referenced region
  INTEGER, INTENT(OUT) :: error                             ! Error code:
                                                            ! 0 on success and -1 on failure
END SUBROUTINE H5LTread_region_f

History:
Release     Change
1.0 C function introduced in this release.
1.1 Fortran wrapper introduced in this release.
(Top)
Last modified: 7 July 2010
Name: H5LTcopy_region
Signature:
herr_t H5LTcopy_region( const char *file_src, const char *path_src, const hsize_t *block_coord_src, const char *file_dest, const char *path_dest, const hsize_t *block_coord_dest )

Purpose:
Copies data from a specified region in a source dataset to a specified region in a destination dataset.

Description:
Given a path to a dataset path_src in a file with the name file_src, and description of a simple hyperslab of the source block_coord_src, the function will write data to the dataset path_dest in file file_dest to the simple hyperslab specified by block_coord_dest. The arrays block_coord_src and block_coord_dest have a length of 2*rank and are the coordinates of the starting point following by the coordinates of the ending point of the hyperslab. For example, to specify a rectangular hyperslab destination region starting at element (2,2) to element (5,4) then block_coord_dest would be {2, 2, 5, 4}.

If path_dest does not exist in the destination file (as may be the case when writing to a new file) then the dataset will be copied directly to the path_dest and block_coord_dest will be disregarded.

Parameters:
const char *file_src,      IN: Name of the source file
const char *path_src,      IN: Full path to the source dataset
const hsize_t *block_coord_src,      IN: Hyperslab coordinates in the source dataset
const char *file_dest,      IN: Name of the destination file
const char *path_dest,      IN: Full path to the destination dataset
const hsize_t *block_coord_dest      IN: Hyperslab coordinates in the destination dataset

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

Fortran90 Interface: H5LTcopy_region_f: USE H5HL_REGION 
SUBROUTINE H5LTcopy_region_f(file_src, path_src, block_coord_src, &
     file_dest, path_dest, block_coord_dest, error)
    
  IMPLICIT NONE
  CHARACTER(LEN=*),INTENT(IN) :: file_src                       ! Name of the source file
  CHARACTER(LEN=*),INTENT(IN) :: path_src                       ! Full path to the source dataset 
  INTEGER(hsize_t), DIMENSION(:),INTENT(IN) :: block_coord_src  ! Hyperslab coordinates in the source dataset
  CHARACTER(LEN=*),INTENT(IN) :: file_dest                      ! Name of the destination file 
  CHARACTER(LEN=*),INTENT(IN) :: path_dest                      ! Full path to the destination dataset 
  INTEGER(hsize_t), DIMENSION(:),INTENT(IN) :: block_coord_dest ! Hyperslab coordinates in the destination dataset 
  INTEGER,INTENT(OUT) :: error                                  ! Error code:
                                                                ! 0 on success and -1 on failure
END SUBROUTINE H5LTcopy_region_f

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

Bit-field API

Last modified: 7 July 2010
Name: H5LTread_bitfield_value
Signature:
herr_t H5LTread_bitfield_value( hid_t dset_id, int num_values, const unsigned *offsets, const unsigned *lengths, hid_t space, int *buf )

Purpose:
Retrieves the values of quality flags for each element to the application provided buffer.

Description:
H5LTread_bitfield_value reads selected elements from a dataset specified by its identifier dset_id, and unpacks the bit-field values to a buffer buf.

The parameter space is a space identifier that indicates which elements of the dataset should be read.

The parameter offsets is an array of length num_values; the ith element of the array holds the value of the starting bit of the ith bit-field value. The parameter lengths is an array of length num_flags; the ith element of the array holds the number of bits to be extracted for the ith bit-field value. Extracted bits will be interpreted as a base-2 integer value. Each value will be converted to the base-10 integer value and stored in the application buffer. Buffer buf is allocated by the application and should be big enough to hold num_sel_elem * num_values elements of the specified type, where num_sel_elem is a number of the elements to be read from the dataset. Data in the buffer is organized as num_values values for the first element, followed by the num_values values for the second element, ... , followed by the num_values values for the num_selected_elemth element.

Parameters:
hid_t dset_id      IN: Identifier of the dataset with bit-field values
int num_values   IN: Number of the values to be extracted
const unsigned *offsets   IN: Array of staring bits to be extracted from the element
Valid values: 0 (zero) through 7
const unsigned *lengths   IN: Array of the number of bits to be extracted for each value
hid_t space   IN: Dataspace identifier, describing the elements to be read from the dataset with bit-field values
int *buf   OUT: Buffer to read the values in

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

Fortran90 Interface: H5LTread_bitfield_value_f: USE H5HL_REGION 
SUBROUTINE H5LTread_bitfield_value_f(dset_id, num_values, offset, &
     lengths, space, buf, dims, error)

  IMPLICIT NONE
  INTEGER(hid_t), INTENT(IN) :: dset_id        ! Identifier of the dataset with bit-field values 
  INTEGER, INTENT(IN) :: num_values            ! Number of the values to be extracted 
  INTEGER, DIMENSION(*), INTENT(IN) :: offset  ! Array of staring bits to be extracted from the element
                                               !  valid values: 1 through 8
  INTEGER, DIMENSION(*), INTENT(IN) :: lengths ! Array of the number of bits to be extracted for each value 
  INTEGER, DIMENSION(:), INTENT(IN) :: dims    ! Dimension of the reading buffer, buf
  INTEGER(hid_t), INTENT(IN) :: space          ! Dataspace identifier, describing the elements to be read from the dataset 
                                               !  with bit-field values 
  INTEGER, DIMENSION(*), INTENT(OUT) :: buf    ! Buffer to read the values in, buf has dimensions dims
  INTEGER, INTENT(OUT) :: error                ! Error code:
                                               !  0 on success and -1 on failure
END SUBROUTINE H5LTread_bitfield_value_f

History:
Release     Change
1.0 C function introduced in this release.
1.1 Fortran wrapper introduced in this release.
(Top)
The HDF Group Help Desk:
Describes HDF5 High-Level Region and Hyperslab Functions Release 1.1, September 2010.
Last modified: 30 December 2010 		Copyright by The HDF Group