Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5  1.15.0.f39b228
API Reference
Extensions

Detailed Description

Working with region references, hyperslab selections, and bit-fields (H5LR, H5LT)

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.

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/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf.

Functions

H5_HLRDLL herr_t H5LRmake_dataset (hid_t loc_id, const char *path, hid_t type_id, const size_t buf_size, const hid_t *loc_id_ref, const hdset_reg_ref_t *buf)
 Creates and writes a dataset containing a list of region references. More...
 
H5_HLRDLL herr_t H5LRcreate_region_references (hid_t obj_id, size_t num_elem, const char **path, const hsize_t *block_coord, hdset_reg_ref_t *buf)
 Creates an array of region references using an array of paths to datasets and an array of corresponding hyperslab descriptions. More...
 
H5_HLRDLL 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)
 Copies data from the specified dataset to a new location and creates a reference to it. More...
 
H5_HLRDLL herr_t H5LRcopy_region (hid_t obj_id, hdset_reg_ref_t *ref, const char *file, const char *path, const hsize_t *block_coord)
 Copies data from a referenced region to a region in a destination dataset. More...
 
H5_HLRDLL herr_t 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)
 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. More...
 
H5_HLRDLL herr_t H5LRread_region (hid_t obj_id, const hdset_reg_ref_t *ref, hid_t mem_type, size_t *numelem, void *buf)
 Retrieves raw data pointed to by a region reference to an application buffer. More...
 
H5_HLRDLL 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)
 Retrieves information about the data a region reference points to. More...
 
H5_HLRDLL 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_dset)
 Copies data from a specified region in a source dataset to a specified region in a destination dataset. More...
 
H5_HLRDLL herr_t H5LTread_region (const char *file, const char *path, const hsize_t *block_coord, hid_t mem_type, void *buf)
 Reads selected data to an application buffer. More...
 
H5_HLRDLL herr_t H5LTread_bitfield_value (hid_t dset_id, int num_values, const unsigned *offset, const unsigned *lengths, hid_t space, int *buf)
 Retrieves the values of quality flags for each element to the application provided buffer. More...
 

Function Documentation

◆ H5LRcopy_reference()

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

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


Parameters
[in]obj_idIdentifier of any object in a file an HDF5 reference belongs to
[in]refReference to the datasets region
[in]fileName of the destination file
[in]pathFull path to the destination dataset
[in]block_coordHyperslab coordinates in the destination dataset
[out]ref_newRegion reference to the new location of data
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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

Version
1.1 Fortran wrapper introduced in this release.
Since
1.0

◆ H5LRcopy_region()

H5_HLRDLL herr_t H5LRcopy_region ( hid_t  obj_id,
hdset_reg_ref_t ref,
const char *  file,
const char *  path,
const hsize_t block_coord 
)

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


Parameters
[in]obj_idIdentifier of any object in a file dataset region reference belongs to
[in]refDataset region reference
[in]fileName of the destination file
[in]pathFull path to the destination dataset
[in]block_coordHyperslab coordinates in the destination dataset
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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 in file file to the simple hyperslab specified by block_coord.

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 specify a rectangular hyperslab destination region starting at element (2,2) to element (5,4) then block_coord 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.

Version
1.1 Fortran wrapper introduced in this release.
Since
1.0

◆ H5LRcreate_ref_to_all()

H5_HLRDLL herr_t 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 
)

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.


Parameters
[in]loc_idLocation identifier. The identifier may be that of a file or group.
[in]group_pathAbsolute or relative path to the group at which traversal starts
[in]ds_pathAbsolute or relative path to the dataset with region references to be created
[in]index_typeIndex_type; see valid values below in description
[in]orderOrder in which index is traversed; see valid values below in description
[in]ref_typeReference type; see valid values below in description
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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:

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

For more detailed information on these two parameters,

See also
H5Lvisit().

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

Version
1.1 Fortran wrapper introduced in this release.
Since
1.0

◆ H5LRcreate_region_references()

H5_HLRDLL herr_t H5LRcreate_region_references ( hid_t  obj_id,
size_t  num_elem,
const char **  path,
const hsize_t block_coord,
hdset_reg_ref_t buf 
)

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


Parameters
[in]obj_idFile identifier for the HDF5 file containing the referenced regions or an object identifier for any object in that file
[in]num_elemNumber of elements in the path and buf arrays
[in]pathArray of pointers to strings, which contain the paths to the target datasets for the region references
[in]block_coordArray of hyperslab coordinate
[out]bufBuffer for returning an array of region references
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Note
Motivation:
H5LRcreate_region_references() is useful when creating large numbers of similar region references.

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

Version
1.1 Fortran wrapper introduced in this release.
Since
1.0

◆ H5LRget_region_info()

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

Retrieves information about the data a region reference points to.


Parameters
[in]obj_idIdentifier of any object in an HDF5 file the region reference belongs to.
[in]refRegion reference to query
[in,out]lenSize of the buffer to store path in. NOTE: if *path is not NULL then *len must be the appropriate length
[out]pathFull path that a region reference points to
[out]rankThe number of dimensions of the dataset dimensions of the dataset pointed by region reference.
[out]dtypeDatatype of the dataset pointed by the region reference.
[out]sel_typeType of the selection (point or hyperslab)
[in,out]numelemNumber of coordinate blocks or selected elements.
[out]bufBuffer containing description of the region pointed by region reference
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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.

Version
1.1 Fortran wrapper introduced in this release.
Since
1.0

◆ H5LRmake_dataset()

H5_HLRDLL herr_t H5LRmake_dataset ( hid_t  loc_id,
const char *  path,
hid_t  type_id,
const size_t  buf_size,
const hid_t loc_id_ref,
const hdset_reg_ref_t buf 
)

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


Parameters
[in]loc_idLocation identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute.
[in]pathPath to the dataset being created
[in]type_idDatatype of the dataset
[in]buf_sizeSize of the loc_id_ref and buf arrays
[in]loc_id_refArray of object identifiers; each identifier describes to which HDF5 file the corresponding region reference belongs to
[in]bufArray of region references
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

Given an array of size buf_size 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 loc_id_ref.

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

Version
1.1 Fortran wrapper introduced in this release.
Since
1.0

◆ H5LRread_region()

H5_HLRDLL herr_t H5LRread_region ( hid_t  obj_id,
const hdset_reg_ref_t ref,
hid_t  mem_type,
size_t *  numelem,
void *  buf 
)

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


Parameters
[in]obj_idFile identifier for the HDF5 file containing the dataset with the referenced region or an object identifier for any object in that file
[in]refRegion reference specifying data to be read in
[in]mem_typeMemory datatype of data read from referenced region into the application buffer
[in,out]numelemNumber of elements to be read into buffer buf
[out]bufBuffer in which data is returned to the application
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5LRread_region() reads data pointed to by the region reference ref into the buffer buf.

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

The buffer buf must be big enough to hold numelem 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) * numelem bytes in size. This buffer must be allocated by the application.

Version
1.1 Fortran wrapper introduced in this release.
Since
1.0

◆ H5LTcopy_region()

H5_HLRDLL 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_dset 
)

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


Parameters
[in]file_srcName of the source file
[in]path_srcFull path to the source dataset
[in]block_coord_srcHyperslab coordinates in the source dataset
[in]file_destName of the destination file
[in]path_destFull path to the destination dataset
[in]block_coord_dsetHyperslab coordinates in the destination dataset
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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_dset. The arrays block_coord_src and block_coord_dset 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_dset 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_dset will be disregarded.

Version
1.1 Fortran wrapper introduced in this release.
Since
1.0

◆ H5LTread_bitfield_value()

H5_HLRDLL herr_t H5LTread_bitfield_value ( hid_t  dset_id,
int  num_values,
const unsigned *  offset,
const unsigned *  lengths,
hid_t  space,
int *  buf 
)

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


Parameters
[in]dset_idIdentifier of the dataset with bit-field values
[in]num_valuesNumber of the values to be extracted
[in]offsetArray of staring bits to be extracted from the element; valid values: 0 (zero) through 7
[in]lengthsArray of the number of bits to be extracted for each value
[in]spaceDataspace identifier, describing the elements to be read from the dataset with bit-field values
[out]bufBuffer to read the values in
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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 offset 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. Valid values are: 0 (zero) through 7.

The parameter lengths is an array of length num_values; 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.

Version
1.1 Fortran wrapper introduced in this release.
Since
1.0

◆ H5LTread_region()

H5_HLRDLL herr_t H5LTread_region ( const char *  file,
const char *  path,
const hsize_t block_coord,
hid_t  mem_type,
void *  buf 
)

Reads selected data to an application buffer.


Parameters
[in]fileName of file
[in]pathFull path to a dataset
[in]block_coordHyperslab coordinates
[in]mem_typeMemory datatype, describing the buffer the referenced data will be read into
[out]bufBuffer containing data from the referenced region
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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

Version
1.1 Fortran wrapper introduced in this release.
Since
1.0