diff options
Diffstat (limited to 'doxygen/dox/high_level/extension.dox')
-rw-r--r-- | doxygen/dox/high_level/extension.dox | 654 |
1 files changed, 654 insertions, 0 deletions
diff --git a/doxygen/dox/high_level/extension.dox b/doxygen/dox/high_level/extension.dox new file mode 100644 index 0000000..c81ac6e --- /dev/null +++ b/doxygen/dox/high_level/extension.dox @@ -0,0 +1,654 @@ +/** \defgroup H5LR Extensions + * + * <em>Working with region references, hyperslab selections, + * and bit-fields (H5LR, H5LT)</em> + * + * 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 ( + * <a href="https://support.hdfgroup.org/projects/jpss/documentation"> + * project </a>, + * <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> + * software </a>). + * 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 + * <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> + * software </a> + * must be separately downloaded and installed. + * + * A comprehensive guide to this library, + * <a href="https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf"> + * <em>User Guide to the HDF5 High-level Library for Handling Region References and Hyperslab Selections</em></a> + * is available at + * https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf. + * + * - \ref H5LRcopy_reference + * \n Copies data from the specified dataset to a new location and + * creates a reference to it. + * - \ref H5LRcopy_region + * \n Copies data from a referenced region to a region in a + * destination dataset. + * - \ref H5LRcreate_ref_to_all + * \n 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. + * - \ref H5LRcreate_region_references + * \n Creates an array of region references using an array of paths to + * datasets and an array of corresponding hyperslab descriptions. + * - \ref H5LRget_region_info + * \n Retrieves information about the data a region reference points to. + * - \ref H5LRmake_dataset + * \n Creates and writes a dataset containing a list of + * region references. + * - \ref H5LRread_region + * \n Retrieves raw data pointed to by a region reference to + * an application buffer. + * - \ref H5LTcopy_region + * \n Copies data from a specified region in a source dataset + * to a specified region in a destination dataset. + * - \ref H5LTread_bitfield_value + * \n Retrieves the values of quality flags for each element + * to the application provided buffer. + * - \ref H5LTread_region + * \n Reads selected data to an application buffer. + * + */ + +/*------------------------------------------------------------------------- + * + * Make dataset functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Creates and writes a dataset containing a list of region references. + * + * \fgdta_loc_id + * \param[in] path Path to the dataset being created + * \param[in] type_id Datatype of the dataset + * \param[in] buf_size Size of the \p loc_id_ref and \p buf arrays + * \param[in] loc_id_ref Array of object identifiers; each identifier + * describes to which HDF5 file the corresponding + * region reference belongs to + * \param[in] buf Array of region references + * + * \return \herr_t + * + * \details Given an array of size \p buf_size of region references \p buf, + * the function will create a dataset with path \p path, at location + * specified by \p loc_id and of a datatype specified by \p 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 \p buf array belongs to the file identified + * by the corresponding object identifiers in the array \p loc_id_ref. + * + * If \p path does not exist in \p loc_id then the function will + * create the path specified by \p path automatically. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +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); + +/*------------------------------------------------------------------------- + * + * Make and manipulate dataset region references functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Creates an array of region references using an array of paths to + * datasets and an array of corresponding hyperslab descriptions. + * + * \param[in] obj_id File identifier for the HDF5 file containing + * the referenced regions or an object identifier + * for any object in that file + * \param[in] num_elem Number of elements in the \p path and + * \p buf arrays + * \param[in] path Array of pointers to strings, which contain + * the paths to the target datasets for the + * region references + * \param[in] block_coord Array of hyperslab coordinate + * \param[out] buf Buffer for returning an array of region + * references + * + * \return \herr_t + * + * \note **Motivation:** + * \note H5LRcreate_region_references() is useful when creating + * large numbers of similar region references. + * + * \details 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. + * + * \p path parameter is an array of pointers to strings. + * + * \p num_elem specifies the number of region references to be created, + * thus specifying the size of the \p path and \p _buf arrays. + * + * Buffer \p 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 \p 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 \p 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 + * + */ +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); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Copies data from the specified dataset to a new location and + * creates a reference to it. + * + * \param[in] obj_id Identifier of any object in a file an + * HDF5 reference belongs to + * \param[in] ref Reference to the datasets region + * \param[in] file Name of the destination file + * \param[in] path Full path to the destination dataset + * \param[in] block_coord Hyperslab coordinates in the destination + * dataset + * \param[out] ref_new Region reference to the new location of + * data + * + * \return \herr_t + * + * \details 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 \p path in the file with the name \p file, and to location + * specified by the hyperslab coordinates \p block_coord. It will + * create the region reference \p 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 \p 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 \p block_coord would be {2, 2, 5, 4}. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +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); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Copies data from a referenced region to a region in a + * destination dataset. + * + * \param[in] obj_id Identifier of any object in a file + * dataset region reference belongs to + * \param[in] ref Dataset region reference + * \param[in] file Name of the destination file + * \param[in] path Full path to the destination dataset + * \param[in] block_coord Hyperslab coordinates in the destination + * dataset + * + * \return \herr_t + * + * \details Given a dataset region reference \p ref in a source file + * specified by an identifier of any object in that file + * \p obj_id, the function will write data to the existing + * dataset \p path in file \p file to the simple hyperslab + * specified by \p block_coord. + * + * Buffer \p 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 \p block_coord would be {2, 2, 5, 4}. + * + * If \p 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 \p path and \p block_coord will be + * disregarded. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +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); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief 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. + * + * \fg_loc_id + * \param[in] group_path Absolute or relative path to the group + * at which traversal starts + * \param[in] ds_path Absolute or relative path to the dataset + * with region references to be created + * \param[in] index_type Index_type; + * see valid values below in description + * \param[in] order Order in which index is traversed; + * see valid values below in description + * \param[in] ref_type Reference type; + * see valid values below in description + * + * \return \herr_t + * + * \details 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 \p ds_path in a file specified by the + * \p 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 \p ref_type parameter. When \p 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 \p loc_id + * and \p group_path parameters. In a like manner, when + * \p ref_type is #H5R_OBJECT, each object reference points to + * an object (a group or a dataset) encountered by H5Lvisit(). + * + * If \p ds_path does not exist in \p loc_id then the function + * will create the path specified by \p ds_path automatically. + * + * \p index_type specifies the index to be used. + * Valid values include the following: + * - #H5_INDEX_NAME Alphanumeric index on name + * - #H5_INDEX_CRT_ORDER Index on creation order + * + * \p order specifies the order in which objects are to be + * inspected along the index specified in \p 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(). + * + * \p ref_type specifies the type of the reference to be used. + * Valid values include the following: + * - #H5R_DATASET_REGION Dataset region reference + * - #H5R_OBJECT Object reference + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +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); + +/*------------------------------------------------------------------------- + * + * Read dataset functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Retrieves raw data pointed to by a region reference + * to an application buffer. + * + * \param[in] obj_id File identifier for the HDF5 file containing + * the dataset with the referenced region or an + * object identifier for any object in that file + * \param[in] ref Region reference specifying data to be read + * in + * \param[in] mem_type Memory datatype of data read from referenced + * region into the application buffer + * \param[in,out] numelem Number of elements to be read into buffer + * \p buf + * \param[out] buf Buffer in which data is returned to the + * application + * + * \return \herr_t + * + * \details H5LRread_region() reads data pointed to by the region + * reference \p ref into the buffer \p buf. + * + * \p numelem specifies the number of elements to be read + * into \p buf. When the size of the reference region is unknown, + * H5LRread_region() can be called with \p buf set to NULL; + * the number of elements in the referenced region will be returned + * in \p numelem. + * + * The buffer buf must be big enough to hold \p numelem elements + * of type \p mem_type. For example, if data is read from the referenced + * region into an integer buffer, \p mem_type should be #H5T_NATIVE_INT + * and the buffer must be at least \c sizeof(int) * \p numelem bytes + * in size. This buffer must be allocated by the application. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +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 ); + +/*------------------------------------------------------------------------- + * + * Query dataset functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Retrieves information about the data a region reference + * points to. + * + * \param[in] obj_id Identifier of any object in an HDF5 file + * the region reference belongs to. + * \param[in] ref Region reference to query + * \param[in,out] len Size of the buffer to store \p path in. + * NOTE: if \p *path is not NULL then \p *len + * must be the appropriate length + * \param[out] path Full path that a region reference points to + * \param[out] rank The number of dimensions of the dataset + * dimensions of the dataset pointed by + * region reference. + * \param[out] dtype Datatype of the dataset pointed by the + * region reference. + * \param[out] sel_type Type of the selection (point or hyperslab) + * \param[in,out] numelem Number of coordinate blocks or + * selected elements. + * \param[out] buf Buffer containing description of the region + * pointed by region reference + * + * \return \herr_t + * + * \details H5LRget_region_info() queries information about the data + * pointed by a region reference \p 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 \p 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 \p ref is a region reference to query. + * + * The parameter \p path is a pointer to application allocated + * buffer of size \p len+1 to return an absolute path to a dataset + * the region reference points to. + * + * The parameter \p 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 \p len. + * + * The parameter \p 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 \p numelem describes how many elements will be + * placed in the buffer \p buf. The number should be interpreted + * using the value of \p sel_type. + * + * If value of \p sel_type is #H5S_SEL_HYPERSLABS, the parameter + * \p buf contains \p numelem blocks of the coordinates for each + * simple hyperslab of the referenced region. Each block has + * length \c 2*\p 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 \c 2*\p rank*\p numelem. If region reference + * points to a contiguous sub-array, then the value of \p 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 \p sel_type is #H5S_SEL_POINTS, the parameter \p buf + * contains \p numelem blocks of the coordinates for each selected + * point of the referenced region. Each block has length \p rank + * and contains coordinates of the element. The total size of the + * buffer to hold the description of the region will be + * \p rank* \p numelem. + * + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +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 ); + + + +/*------------------------------------------------------------------------- + * + * Make dataset functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Copies data from a specified region in a source dataset + * to a specified region in a destination dataset + * + * \param[in] file_src Name of the source file + * \param[in] path_src Full path to the source dataset + * \param[in] block_coord_src Hyperslab coordinates in the + * source dataset + * \param[in] file_dest Name of the destination file + * \param[in] path_dest Full path to the destination dataset + * \param[in] block_coord_dset Hyperslab coordinates in the + * destination dataset + * + * \return \herr_t + * + * \details Given a path to a dataset \p path_src in a file with the + * name \p file_src, and description of a simple hyperslab of + * the source \p block_coord_src, the function will write data + * to the dataset \p path_dest in file \p file_dest to the + * simple hyperslab specified by \p block_coord_dset. + * The arrays \p block_coord_src and \p 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 \p block_coord_dset would be {2, 2, 5, 4}. + * + * If \p 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 \p path_dest and + * \p block_coord_dset will be disregarded. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +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); + +/*------------------------------------------------------------------------- + * + * Read dataset functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Reads selected data to an application buffer. + * + * \param[in] file Name of file + * \param[in] path Full path to a dataset + * \param[in] block_coord Hyperslab coordinates + * \param[in] mem_type Memory datatype, describing the buffer + * the referenced data will be read into + * \param[out] buf Buffer containing data from the + * referenced region + * + * \return \herr_t + * + * \details H5LTread_region() reads data from a region described by + * the hyperslab coordinates in \p block_coord, located in + * the dataset specified by its absolute path \p path in a + * file specified by its name \p file. Data is read into a + * buffer \p buf of the datatype that corresponds to the + * HDF5 datatype specified by \p mem_type. + * + * Buffer \p 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 \p block_coord would be {2, 2, 5, 4}. + * + * Buffer \p buf should be big enough to hold selected elements + * of the type that corresponds to the \p mem_type + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +H5_HLRDLL herr_t H5LTread_region(const char *file, + const char *path, + const hsize_t *block_coord, + hid_t mem_type, + void *buf ); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Retrieves the values of quality flags for each element + * to the application provided buffer. + * + * \param[in] dset_id Identifier of the dataset with bit-field values + * \param[in] num_values Number of the values to be extracted + * \param[in] offset Array of staring bits to be extracted from + * the element; valid values: 0 (zero) through 7 + * \param[in] lengths Array of the number of bits to be extracted + * for each value + * \param[in] space Dataspace identifier, describing the elements + * to be read from the dataset with bit-field + * values + * \param[out] buf Buffer to read the values in + * + * \return \herr_t + * + * \details H5LTread_bitfield_value() reads selected elements from a + * dataset specified by its identifier \p dset_id, and unpacks + * the bit-field values to a buffer \p buf. + * + * The parameter \p space is a space identifier that indicates + * which elements of the dataset should be read. + * + * The parameter \p offset is an array of length \p num_values; + * the i<sup>th</sup> element of the array holds the value of the + * starting bit of the i<sup>th</sup> bit-field value. + * Valid values are: 0 (zero) through 7. + * + * The parameter \p lengths is an array of length \p num_values; + * the i<sup>th</sup> element of the array holds the number of + * bits to be extracted for the i<sup>th</sup> 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 \p buf is allocated by the application and should be big + * enough to hold \c num_sel_elem * \p num_values elements of the + * specified type, where \c num_sel_elem is a number of the elements + * to be read from the dataset. Data in the buffer is organized + * as \p num_values values for the first element, followed by the + * \p num_values values for the second element, ... , followed by + * the \p num_values values for the + * \c num_selected_elem<sup>th</sup> element. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +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); + |