-FORTRAN: Add "USE HDF5" and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface
+FORTRAN:
+USE HDF5
+and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface
+Java:
+
+import hdf.hdf5lib.H5;
+import hdf.hdf5lib.HDF5Constants;
+
@@ -609,6 +617,7 @@ on the HDF-EOS Tools and Information Center pag
\li \ref LBExamples
\li \ref ExAPI
\li Examples in the Source Code
+\li Other Examples
\section secHDF5ExamplesCompile How To Compile
For information on compiling in C, C++ and Fortran, see: \ref LBCompiling
diff --git a/doxygen/dox/LearnBasics.dox b/doxygen/dox/LearnBasics.dox
index 68700b8df83..ed83b367b6b 100644
--- a/doxygen/dox/LearnBasics.dox
+++ b/doxygen/dox/LearnBasics.dox
@@ -41,7 +41,7 @@ Navigate back: \ref index "Main" / \ref GettingStarted
Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics
-\section secLBExamples
+\section secLBExamples HDF5 Examples
These examples are used in the \ref LearnBasics topic. See \ref LBCompiling for details on compiling them.
PLEASE NOTE that the example programs are listed in the order they are expected to be run. Some example
programs use files created in earlier examples.
@@ -59,7 +59,7 @@ These examples (C, C++, Fortran, Java, Python) are provided in the HDF5 source c
Also see examples to Write by row (and column) below.
diff --git a/doxygen/dox/LearnBasics1.dox b/doxygen/dox/LearnBasics1.dox
index 64ba30ea9bf..f4b44d1cf89 100644
--- a/doxygen/dox/LearnBasics1.dox
+++ b/doxygen/dox/LearnBasics1.dox
@@ -53,86 +53,86 @@ The APIs are listed below:
-
H5
-
+
@ref H5_UG
+
Library Functions: general-purpose H5 functions
-
H5A
-
+
@ref H5A_UG
+
Annotation Interface: attribute access and manipulation routines
-
H5D
-
+
@ref H5D_UG
+
Dataset Interface: dataset access and manipulation routines
-
H5E
-
+
@ref H5E_UG
+
Error Interface: error handling routines
-
H5F
-
+
@ref H5F_UG
+
File Interface: file access routines
-
H5G
-
+
@ref H5G_UG
+
Group Interface: group creation and operation routines
-
H5I
-
+
@ref H5I_UG
+
Identifier Interface: identifier routines
-
H5L
-
+
@ref H5L_UG
+
Link Interface: link routines
-
H5O
-
+
@ref H5O_UG
+
Object Interface: object routines
-
H5P
-
+
@ref H5P_UG
+
Property List Interface: object property list manipulation routines
-
H5R
-
+
@ref H5R_UG
+
Reference Interface: reference routines
-
H5S
-
+
@ref H5S_UG
+
Dataspace Interface: dataspace definition and access routines
-
H5T
-
+
@ref H5T_UG
+
Datatype Interface: datatype creation and manipulation routines
-
H5Z
-
+
@ref H5Z_UG
+
Compression Interface: compression routine(s)
@@ -189,26 +189,38 @@ in the HDF5Constants class and are prefixed with "HDF5Constants.".:
\section LBProgTypes HDF5 library has its own defined types
\li #hid_t is used for object handles
-\li hsize_t is used for dimensions
+\li #hsize_t is used for dimensions
\li #herr_t is used for many return values
\section LBProgLang Language specific files must be included in applications
-FORTRAN: Add "USE HDF5" and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface
+FORTRAN:
+USE HDF5
+and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface
+@see @ref ExAPI for examples of using the HDF5 API.
+
Previous Chapter \ref LBAPI - Next Chapter \ref LBFileCreate
@@ -461,23 +473,23 @@ Some of the HDF5 predefined atomic datatypes are listed below.
One-byte, null-terminated string of eight-bit characters
@@ -492,42 +504,42 @@ Some of the HDF5 predefined atomic datatypes are listed below.
C
-
H5T_NATIVE_INT
+
#H5T_NATIVE_INT
int
-
H5T_NATIVE_FLOAT
+
#H5T_NATIVE_FLOAT
float
-
H5T_NATIVE_CHAR
+
#H5T_NATIVE_CHAR
char
-
H5T_NATIVE_DOUBLE
+
#H5T_NATIVE_DOUBLE
double
-
H5T_NATIVE_LDOUBLE
+
#H5T_NATIVE_LDOUBLE
long double
Fortran
-
H5T_NATIVE_INTEGER
+
H5T_NATIVE_INTEGER
integer
-
H5T_NATIVE_REAL
+
H5T_NATIVE_REAL
real
-
H5T_NATIVE_DOUBLE
+
H5T_NATIVE_DOUBLE
double precision
-
H5T_NATIVE_CHARACTER
+
H5T_NATIVE_CHARACTER
character
@@ -556,17 +568,17 @@ Property lists are a mechanism for modifying the default behavior when creating
more information on property lists see the \ref LBPropsList tutorial topic.
The following property lists can be specified when creating a dataset:
-\li Dataset Creation Property List
+\li Dataset Creation Property List
When creating a dataset, HDF5 allows the user to specify how raw data is organized and/or compressed on
disk. This information is stored in a dataset creation property list and passed to the dataset interface.
The raw data on disk can be stored contiguously (in the same linear way that it is organized in memory),
partitioned into chunks, stored externally, etc. In this tutorial, we use the default dataset creation
property list (contiguous storage layout and no compression). For more information about dataset creation
property lists, see \ref sec_dataset in the \ref UG.
-\li Link Creation Property List
+\li Link Creation Property List
The link creation property list governs creation of the link(s) by which a new dataset is accessed and the
creation of any intermediate groups that may be missing.
-\li Dataset Access Property List
+\li Dataset Access Property List
Dataset access property lists are properties that can be specified when accessing a dataset.
\section secLBDsetCreateSteps Steps to Create a Dataset
@@ -766,7 +778,7 @@ To read from or write to a dataset, the #H5Dread and #H5Dwrite routines are used
C
\code
- status = H5Dread (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf );
+ status = H5Dread (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf);
status = H5Dwrite (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf);
\endcode
diff --git a/doxygen/dox/LearnBasics2.dox b/doxygen/dox/LearnBasics2.dox
index 0df7d9ab620..eccb865fb09 100644
--- a/doxygen/dox/LearnBasics2.dox
+++ b/doxygen/dox/LearnBasics2.dox
@@ -858,11 +858,45 @@ H5Tinsert (complex_id, "imaginary", HOFFSET(tmp,im), H5T_NATIVE_DOUBLE);
\endcode
\subsection subsecLBDtypeSpecRef Reference
-There are two types of Reference datatypes in HDF5:
+There are three types of Reference datatypes in HDF5:
+\li \ref subsubsecLBDtypeSpecRefStd
\li \ref subsubsecLBDtypeSpecRefObj
\li \ref subsubsecLBDtypeSpecRefDset
-\subsubsection subsubsecLBDtypeSpecRefObj Reference to objects
+\subsubsection subsubsecLBDtypeSpecRefStd Standard Reference
+HDF5 references allow users to reference existing HDF5 objects as well as selections within datasets. The
+original API, now deprecated, was extended in order to add the ability to reference attributes as well as objects in
+external files.
+
+The newer API introduced a single opaque reference type, which not only has the advantage of hiding the internal
+representation of references, but it also allows for future extensions to be added more seamlessly. The newer API
+introduces a single abstract #H5R_ref_t type as well as attribute references and external references
+(i.e., references to objects in an external file).
+
+A file, group, dataset, named datatype, or attribute may be the target of an object reference.
+The object reference is created by
+#H5Rcreate_object with the name of an object which may be a file, group, dataset, named datatype, or attribute
+and the reference type #H5R_OBJECT. The object does not have to be open to create a reference to it.
+
+An object reference may also refer to a region (selection) of a dataset. The reference is created
+with #H5Rcreate_region. The dataspace for the region can be retrieved with a call to #H5Ropen_region.
+
+An object reference may also refer to a attribute. The reference is created
+with #H5Rcreate_attr. #H5Ropen_attr can be used to open the attribute by returning an identifier
+to the attribute just as if #H5Aopen has been called.
+
+An object reference can be accessed by a call to #H5Ropen_object.
+
+When the reference is to a dataset or dataset region, the #H5Ropen_object call returns an
+identifier to the dataset just as if #H5Dopen has been called.
+When the reference is to an attribute, the #H5Ropen_object call returns an
+identifier to the attribute just as if #H5Aopen has been called.
+
+The reference buffer from the #H5Rcreate_object call must be released by
+using #H5Rdestroy to avoid resource leaks and possible HDF5 library shutdown issues. And any identifiers
+returned by #H5Ropen_object must be closed with the appropriate close call.
+
+\subsubsection subsubsecLBDtypeSpecRefObj Reference to objects - Deprecated
In HDF5, objects (i.e. groups, datasets, and named datatypes) are usually accessed by name.
There is another way to access stored objects -- by reference.
@@ -890,7 +924,7 @@ The following steps are involved:
Close all objects when the task is complete.
-\subsubsection subsubsecLBDtypeSpecRefDset Reference to a dataset region
+\subsubsection subsubsecLBDtypeSpecRefDset Reference to a dataset region - Deprecated
A dataset region reference points to a dataset selection in another dataset.
A reference to the dataset selection (region) is constant for the life of the dataset.
diff --git a/doxygen/dox/ViewTools.dox b/doxygen/dox/ViewTools.dox
index 828a8e9cc1a..9ae42fe9f40 100644
--- a/doxygen/dox/ViewTools.dox
+++ b/doxygen/dox/ViewTools.dox
@@ -984,7 +984,164 @@ This dataset is much more complex. Also note that subsetting cannot be done on A
See this section for more information on the Array datatype.
+\subsubsection subsubsecViewToolsViewDtypes_newref New References
+References were reworked in HDF5 1.12.0. The new reference datatype is #H5T_STD_REF. The old reference datatypes are deprecated.
+@see sec_reference.
+
\subsubsection subsubsecViewToolsViewDtypes_objref Object Reference
+An Object Reference is a reference to an entire object (attribute, dataset, group, or named datatype).
+A dataset with an Object Reference datatype consists of one or more Object References.
+An Object Reference dataset can be used as an index to an HDF5 file.
+
+The /DS1 dataset in the following file (h5ex_t_objref.h5) is an Object Reference dataset.
+It contains two references, one to group /G1 and the other to dataset /DS2:
+\code
+$ h5dump h5ex_t_objref.h5
+HDF5 "h5ex_t_objref.h5" {
+GROUP "/" {
+ DATASET "DS1" {
+ DATATYPE H5T_REFERENCE { H5T_STD_REF }
+ DATASPACE SIMPLE { ( 2 ) / ( 2 ) }
+ DATA {
+ GROUP "h5ex_t_objref.h5/G1"
+ DATASET "h5ex_t_objref.h5/DS2"
+ DATA {
+ }
+ }
+ }
+ DATASET "DS2" {
+ DATATYPE H5T_STD_I32LE
+ DATASPACE NULL
+ DATA {
+ }
+ }
+ GROUP "G1" {
+ }
+}
+}
+\endcode
+
+\subsubsection subsubsecViewToolsViewDtypes_regref Region Reference
+A Region Reference is a reference to a selection within a dataset. A selection can be either
+individual elements or a hyperslab. In h5dump you will see the name of the dataset along with
+the elements or slab that is selected. A dataset with a Region Reference datatype consists of
+one or more Region References.
+
+An example of a Region Reference dataset (h5ex_t_regref.h5) can be found on the
+\ref ExAPI page,
+under Datatypes. If you examine this dataset with h5dump you will see that /DS1 is a
+Region Reference dataset as indicated by its datatype, highlighted in bold below:
+\code
+$ h5dump h5ex_t_regref.h5
+HDF5 "h5ex_t_regref.h5" {
+GROUP "/" {
+ DATASET "DS1" {
+ DATATYPE H5T_REFERENCE { H5T_STD_REF }
+ DATASPACE SIMPLE { ( 2 ) / ( 2 ) }
+ DATA {
+ DATASET "h5ex_t_regref.h5/DS2"{
+ REGION_TYPE POINT (0,1), (2,11), (1,0), (2,4)
+ DATATYPE H5T_STD_I8LE
+ DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) }
+ }
+ DATASET "h5ex_t_regref.h5/DS2" {
+ REGION_TYPE BLOCK (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2),
+ (2,11)-(2,13)
+ DATATYPE H5T_STD_I8LE
+ DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) }
+ }
+ }
+ }
+ DATASET "DS2" {
+ DATATYPE H5T_STD_I8LE
+ DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) }
+ DATA {
+ (0,0): 84, 104, 101, 32, 113, 117, 105, 99, 107, 32, 98, 114, 111, 119,
+ (0,14): 110, 0,
+ (1,0): 102, 111, 120, 32, 106, 117, 109, 112, 115, 32, 111, 118, 101,
+ (1,13): 114, 32, 0,
+ (2,0): 116, 104, 101, 32, 53, 32, 108, 97, 122, 121, 32, 100, 111, 103,
+ (2,14): 115, 0
+ }
+ }
+}
+}
+\endcode
+
+It contains two Region References:
+\li A selection of four individual elements in dataset /DS2 : (0,1), (2,11), (1,0), (2,4)
+See the #H5Sselect_elements API in the \ref UG for information on selecting individual elements.
+\li A selection of these blocks in dataset /DS2 : (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)
+See the #H5Sselect_hyperslab API in the \ref UG for how to do hyperslab selection.
+
+If you look at the code that creates the dataset (h5ex_t_regref.c) you will see that the
+first reference is created with these calls:
+\code
+ status = H5Sselect_elements (space, H5S_SELECT_SET, 4, coords[0]);
+ status = H5Rcreate_region(file, DATASET2, space, H5P_DEFAULT, &wdata[0]);
+\endcode
+
+where the buffer containing the coordinates to select is:
+\code
+ coords[4][2] = { {0, 1},
+ {2, 11},
+ {1, 0},
+ {2, 4} },
+\endcode
+
+The second reference is created by calling,
+\code
+ status = H5Sselect_hyperslab (space, H5S_SELECT_SET, start, stride, count, block);
+ status = H5Rcreate_region(file, DATASET2, space, H5P_DEFAULT, &wdata[1]);
+\endcode
+where start, stride, count, and block have these values:
+\code
+ start[2] = {0, 0},
+ stride[2] = {2, 11},
+ count[2] = {2, 2},
+ block[2] = {1, 3};
+\endcode
+
+These start, stride, count, and block values will select the elements shown in bold in the dataset:
+\code
+84 104 101 32 113 117 105 99 107 32 98 114 111 119 110 0
+102 111 120 32 106 117 109 112 115 32 111 118 101 114 32 0
+116 104 101 32 53 32 108 97 122 121 32 100 111 103 115 0
+\endcode
+
+If you use h5dump to select a subset of dataset
+/DS2 with these start, stride, count, and block values, you will see that the same elements are selected:
+\code
+$ h5dump -d "/DS2" -s "0,0" -S "2,11" -c "2,2" -k "1,3" h5ex_t_regref.h5
+HDF5 "h5ex_t_regref.h5" {
+DATASET "/DS2" {
+ DATATYPE H5T_STD_I8LE
+ DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) }
+ SUBSET {
+ START ( 0, 0 );
+ STRIDE ( 2, 11 );
+ COUNT ( 2, 2 );
+ BLOCK ( 1, 3 );
+ DATA {
+ (0,0): 84, 104, 101, 114, 111, 119,
+ (2,0): 116, 104, 101, 100, 111, 103
+ }
+ }
+}
+}
+\endcode
+
+NOTE that you must release the references created in the code with the #H5Rdestroy API.
+\code
+ status = H5Rdestroy(&wdata[0]);
+ status = H5Rdestroy(&wdata[1]);
+\endcode
+
+For more information on selections, see the tutorial topic on
+@ref LBDsetSubRW. Also see the
+\ref secViewToolsViewSub tutorial topic on using h5dump to view a subset.
+
+\subsubsection subsubsecViewToolsViewDtypes_depr_objref Deprecated Object Reference
An Object Reference is a reference to an entire object (dataset, group, or named datatype).
A dataset with an Object Reference datatype consists of one or more Object References.
An Object Reference dataset can be used as an index to an HDF5 file.
@@ -1014,7 +1171,7 @@ GROUP "/" {
}
\endcode
-\subsubsection subsubsecViewToolsViewDtypes_regref Region Reference
+\subsubsection subsubsecViewToolsViewDtypes_depr_regref Deprecated Region Reference
A Region Reference is a reference to a selection within a dataset. A selection can be either
individual elements or a hyperslab. In h5dump you will see the name of the dataset along with
the elements or slab that is selected. A dataset with a Region Reference datatype consists of
@@ -1057,7 +1214,6 @@ It contains two Region References:
See the #H5Sselect_elements API in the \ref UG for information on selecting individual elements.
\li A selection of these blocks in dataset /DS2 : (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)
See the #H5Sselect_hyperslab API in the \ref UG for how to do hyperslab selection.
-
If you look at the code that creates the dataset (h5ex_t_regref.c) you will see that the
first reference is created with these calls:
diff --git a/fortran/src/H5Fff.F90 b/fortran/src/H5Fff.F90
index 0c8b1d84099..dbd1c809bd5 100644
--- a/fortran/src/H5Fff.F90
+++ b/fortran/src/H5Fff.F90
@@ -427,7 +427,7 @@ END SUBROUTINE h5funmount_f
!!
!! \brief Opens HDF5 file.
!!
-!! \param name Name of the file to acecss.
+!! \param name Name of the file to access.
!! \param access_flags File access flags. Allowable values are:
!! \li H5F_ACC_RDWR_F
!! \li H5F_ACC_RDONLY_F
diff --git a/hl/src/H5DOpublic.h b/hl/src/H5DOpublic.h
index 5054178846b..661ca7a2abe 100644
--- a/hl/src/H5DOpublic.h
+++ b/hl/src/H5DOpublic.h
@@ -17,7 +17,7 @@
extern "C" {
#endif
-/** \page H5DO_UG The HDF5 High Level Optimizations
+/** \page H5DO_UG HDF5 High Level Optimizations
* @todo Under Construction
*/
diff --git a/hl/src/H5DSpublic.h b/hl/src/H5DSpublic.h
index edbebdbaf28..4afe51180f9 100644
--- a/hl/src/H5DSpublic.h
+++ b/hl/src/H5DSpublic.h
@@ -30,7 +30,7 @@ typedef herr_t (*H5DS_iterate_t)(hid_t dset, unsigned dim, hid_t scale, void *vi
extern "C" {
#endif
-/** \page H5DS_UG The HDF5 High Level Dimension Scales
+/** \page H5DS_UG HDF5 High Level Dimension Scales
* @todo Under Construction
*/
diff --git a/hl/src/H5IMpublic.h b/hl/src/H5IMpublic.h
index 0ba9d648cff..bf219b73e46 100644
--- a/hl/src/H5IMpublic.h
+++ b/hl/src/H5IMpublic.h
@@ -17,7 +17,7 @@
extern "C" {
#endif
-/** \page H5IM_UG The HDF5 High Level Images
+/** \page H5IM_UG HDF5 High Level Images
* @todo Under Construction
*/
diff --git a/hl/src/H5LTpublic.h b/hl/src/H5LTpublic.h
index 343f5272453..18f7502209f 100644
--- a/hl/src/H5LTpublic.h
+++ b/hl/src/H5LTpublic.h
@@ -34,7 +34,7 @@ typedef enum H5LT_lang_t {
extern "C" {
#endif
-/** \page H5LT_UG The HDF5 High Level Lite
+/** \page H5LT_UG HDF5 High Level Lite
* @todo Under Construction
*/
diff --git a/hl/src/H5PTpublic.h b/hl/src/H5PTpublic.h
index 3016e77ba60..607e385c5c7 100644
--- a/hl/src/H5PTpublic.h
+++ b/hl/src/H5PTpublic.h
@@ -17,7 +17,7 @@
extern "C" {
#endif
-/** \page H5PT_UG The HDF5 High Level Packet Table
+/** \page H5PT_UG HDF5 High Level Packet Table
* @todo Under Construction
*/
diff --git a/hl/src/H5TBpublic.h b/hl/src/H5TBpublic.h
index 42585cf012f..dbeb330a1db 100644
--- a/hl/src/H5TBpublic.h
+++ b/hl/src/H5TBpublic.h
@@ -17,7 +17,7 @@
extern "C" {
#endif
-/** \page H5TB_UG The HDF5 High Level Table
+/** \page H5TB_UG HDF5 High Level Table
* @todo Under Construction
*/
diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h
index e791f7cf00e..26e748ce1a0 100644
--- a/src/H5Dmodule.h
+++ b/src/H5Dmodule.h
@@ -67,17 +67,21 @@
* The dataset does not have to open to be linked or unlinked.
*
* \subsubsection subsubsec_dataset_intro_obj Object Reference
- * A dataset may be the target of an object reference. The object reference is created by
- * #H5Rcreate with the name of an object which may be a dataset and the reference type
+ * A file, group, dataset, named datatype, or attribute may be the target of an object reference.
+ * The object reference is created by
+ * #H5Rcreate_object with the name of an object which may be a dataset and the reference type
* #H5R_OBJECT. The dataset does not have to be open to create a reference to it.
*
* An object reference may also refer to a region (selection) of a dataset. The reference is created
- * with #H5Rcreate and a reference type of #H5R_DATASET_REGION.
+ * with #H5Rcreate_region.
*
- * An object reference can be accessed by a call to #H5Rdereference. When the reference is to a
- * dataset or dataset region, the #H5Rdereference call returns an identifier to the dataset just as if
+ * An object reference can be accessed by a call to #H5Ropen_object. When the reference is to a
+ * dataset or dataset region, the #H5Ropen_object call returns an identifier to the dataset just as if
* #H5Dopen has been called.
*
+ * The reference buffer from the #H5Rcreate_object call must be released by
+ * using #H5Rdestroy to avoid resource leaks and possible HDF5 library shutdown issues.
+ *
* \subsubsection subsubsec_dataset_intro_attr Adding Attributes
* A dataset may have user-defined attributes which are created with #H5Acreate and accessed
* through the @ref H5A API. To create an attribute for a dataset, the dataset must be open, and the
diff --git a/src/H5ESmodule.h b/src/H5ESmodule.h
index f128feeab0e..f63852db384 100644
--- a/src/H5ESmodule.h
+++ b/src/H5ESmodule.h
@@ -25,7 +25,7 @@
#define H5_MY_PKG H5ES
#define H5_MY_PKG_ERR H5E_EVENTSET
-/** \page H5ES_UG The HDF5 Event Set
+/** \page H5ES_UG HDF5 Event Set
* @todo Under Construction
*
* \section sec_async The HDF5 Event Set Interface
diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h
index 2e7918669b6..c76839e8e28 100644
--- a/src/H5Fmodule.h
+++ b/src/H5Fmodule.h
@@ -25,7 +25,7 @@
#define H5_MY_PKG H5F
#define H5_MY_PKG_ERR H5E_FILE
-/** \page H5F_UG The HDF5 File
+/** \page H5F_UG HDF5 File
*
* \section sec_file The HDF5 File
* \subsection subsec_file_intro Introduction
diff --git a/src/H5Imodule.h b/src/H5Imodule.h
index e6828506d1e..f8924d3df62 100644
--- a/src/H5Imodule.h
+++ b/src/H5Imodule.h
@@ -25,7 +25,7 @@
#define H5_MY_PKG H5I
#define H5_MY_PKG_ERR H5E_ID
-/** \page H5I_UG The HDF5 Identifiers
+/** \page H5I_UG HDF5 Identifiers
* @todo Under Construction
*/
diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h
index 7ab67da8138..f29aa5c50c0 100644
--- a/src/H5Lmodule.h
+++ b/src/H5Lmodule.h
@@ -25,7 +25,7 @@
#define H5_MY_PKG H5L
#define H5_MY_PKG_ERR H5E_LINK
-/** \page H5L_UG The HDF5 Links
+/** \page H5L_UG HDF5 Links
* @todo Under Construction
*/
diff --git a/src/H5Mmodule.h b/src/H5Mmodule.h
index 920ec3d1585..375399751b5 100644
--- a/src/H5Mmodule.h
+++ b/src/H5Mmodule.h
@@ -26,11 +26,11 @@
#define H5_MY_PKG_ERR H5E_MAP
/**
- * \page H5M_UG The HDF5 VOL Data Mapping
+ * \page H5M_UG HDF5 VOL Data Mapping
* \Bold{The HDF5 Data Mapping can only be used with the HDF5 VOL connectors that
* implement map objects.} The native HDF5 library does not support this feature.
*
- * \section sec_map The HDF5 Map Object
+ * \section sec_map HDF5 Map Object
*
* \todo Describe the map life cycle.
*
diff --git a/src/H5Omodule.h b/src/H5Omodule.h
index c3c3496bf32..1c1278a0e8a 100644
--- a/src/H5Omodule.h
+++ b/src/H5Omodule.h
@@ -25,7 +25,7 @@
#define H5_MY_PKG H5O
#define H5_MY_PKG_ERR H5E_OHDR
-/** \page H5O_UG The HDF5 Objects
+/** \page H5O_UG HDF5 Objects
* @todo Under Construction
*/
diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h
index cccdf6ef506..f034e7c6631 100644
--- a/src/H5PLmodule.h
+++ b/src/H5PLmodule.h
@@ -26,7 +26,7 @@
#define H5_MY_PKG H5PL
#define H5_MY_PKG_ERR H5E_PLUGIN
-/** \page H5PL_UG The HDF5 Plugins
+/** \page H5PL_UG HDF5 Plugins
*
* \section sec_filter_plugins HDF5 Filter Plugins
*
diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h
index 5e3affbfabc..443c4746d71 100644
--- a/src/H5Rmodule.h
+++ b/src/H5Rmodule.h
@@ -24,8 +24,372 @@
#define H5_MY_PKG H5R
#define H5_MY_PKG_ERR H5E_REFERENCE
-/** \page H5R_UG The HDF5 References
- * @todo Under Construction
+/** \page H5R_UG HDF5 References
+ *
+ * \section sec_reference HDF5 References
+ * HDF5 references allow users to reference existing HDF5 objects (file, group, dataset, named datatype, or
+ * attribute) as well as selections within datasets.
+ *
+ * The original API, now deprecated, was extended in order to add the ability to reference attributes as well
+ * as objects in external files. Additionally, there were some inherent limitations within the older API that
+ * restricted its use with virtual object layer (VOL) connectors, which do not necessarily follow HDF5’s
+ * native file format.
+ *
+ * The newer API introduced a single opaque reference type, which not only has the advantage of hiding the
+ * internal representation of references, but it also allows for future extensions to be added more
+ * seamlessly.
+ *
+ * \subsection subsec_reference_intro Introduction
+ * The deprecated HDF5 reference API only allowed users to create references to HDF5 objects (groups,
+ * datasets) and regions within a dataset. There were some limitations: it defined two separate reference
+ * types #hobj_ref_t and #hdset_reg_ref_t; the former directly mapped to an #haddr_t type that did not allow
+ * for external references, while the latter mapped to an HDF5 global heap entry, which was specific to native
+ * HDF5 and was created and written to the file when the reference was created. This prevented users from
+ * creating region references when the file is opened read-only, it was also not suitable for use outside of
+ * native HDF5 files. The newer API addressed these limitations by introducing a single abstract #H5R_ref_t
+ * type as well as missing reference types such as attribute references and external references (i.e.,
+ * references to objects in an external file).
+ *
+ * \subsection subsec_reference_dep Deprecated API
+ * There is no support for attribute references; references are only valid within the
+ * container that they reference; the size of the reference types are tied to the definition of an haddr_t or
+ * an entry in the file’s global heap, which only exists in native HDF5.
+ *
+ * \subsubsection subsubsec_reference_limit Limitations
+ * \li The #H5Rcreate signature forces users to constantly pass (#H5I_INVALID_HID) as a space_id, in the case
+ * where the reference type is not a region reference.
+ * \li The size of region
+ * references was defined as the size required to encode a global heap ID, this definition forces
+ * references to be written to the file at the time of their creation, hence preventing them to be created
+ * from a file that is opened read-only (e.g, when creating references to a file that one does not want
+ * to/cannot modify).
+ *
+ * \subsubsection subsubsec_reference_old_API Deprecated Methods
+ * The original API before hdf5 1.12.0 is defined below:
+ * \code
+ * // Deprecated reference buffer sizes that are kept for backward compatibility
+ * #define H5R_OBJ_REF_BUF_SIZE sizeof(haddr_t)
+ * #define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4)
+ *
+ * // Reference types
+ * typedef enum H5R_type_t {
+ * H5R_BADTYPE = (-1), // Invalid Reference Type
+ * H5R_OBJECT, // Object reference
+ * H5R_DATASET_REGION, // Dataset Region Reference
+ * H5R_MAXTYPE // Highest type (Invalid as true type)
+ * } H5R_type_t;
+ *
+ * // Object reference structure for user's code
+ * // This needs to be large enough to store largest haddr_t on a worst case
+ * // machine (8 bytes currently).
+ * typedef haddr_t hobj_ref_t;
+ *
+ * // Dataset Region reference structure for user's code
+ * // (Buffer to store heap ID and index)
+ * // This needs to be large enough to store largest haddr_t in a worst case
+ * // machine (8 bytes currently) plus an int
+ * typedef unsigned char hdset_reg_ref_t[H5R_DSET_REG_REF_BUF_SIZE];
+ *
+ * // Prototypes
+ * herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id);
+ * hid_t H5Rdereference2(hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref);
+ * hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref);
+ * herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *_ref, H5O_type_t *obj_type);
+ * ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, const void *ref, char *name , size_t size);
+ * \endcode
+ *
+ * \subsection subsec_reference_new New API
+ * The current API is defined below:
+ * \code
+ * // Deprecated reference buffer sizes that are kept for backward compatibility
+ * #define H5R_OBJ_REF_BUF_SIZE sizeof(haddr_t)
+ * #define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4)
+ *
+ * // Default reference buffer size.
+ * #define H5R_REF_BUF_SIZE (64)
+ *
+ * // Reference types allowed.
+ * typedef enum {
+ * H5R_BADTYPE = (-1), // Invalid reference type
+ * H5R_OBJECT1 = 0, // Backward compatibility (object)
+ * H5R_DATASET_REGION1 = 1, // Backward compatibility (region)
+ * H5R_OBJECT2 = 2, // Object reference
+ * H5R_DATASET_REGION2 = 3, // Region reference
+ * H5R_ATTR = 4, // Attribute Reference
+ * H5R_MAXTYPE = 5 // Highest type (invalid)
+ * } H5R_type_t;
+ *
+ * // Deprecated object reference type that is used with deprecated reference APIs.
+ * // This type can only be used with the "native" HDF5 VOL connector.
+ * typedef haddr_t hobj_ref_t;
+ *
+ * // Deprecated dataset region reference type that is used with deprecated reference APIs.
+ * // This type can only be used with the "native" HDF5 VOL connector.
+ * typedef struct {
+ * uint8_t __data[H5R_DSET_REG_REF_BUF_SIZE];
+ * } hdset_reg_ref_t;
+ *
+ * // Opaque reference type. The same reference type is used for object,
+ * // dataset region and attribute references. This is the type that
+ * // should always be used with the current reference API.
+ * typedef struct {
+ * union {
+ * uint8_t __data[H5R_REF_BUF_SIZE]; // opaque data
+ * int64_t align; // ensures alignment
+ * } u;
+ * } H5R_ref_t;
+ *
+ * // Constructors
+ * herr_t H5Rcreate_object(hid_t loc_id, const char *name, H5R_ref_t *ref_ptr);
+ * herr_t H5Rcreate_region(hid_t loc_id, const char *name, hid_t space_id, H5R_ref_t *ref_ptr);
+ * herr_t H5Rcreate_attr(hid_t loc_id, const char *name, const char *attr_name, H5R_ref_t *ref_ptr);
+ * herr_t H5Rdestroy(H5R_ref_t *ref_ptr);
+ *
+ * // Info
+ * H5R_type_t H5Rget_type(const H5R_ref_t *ref_ptr);
+ * htri_t H5Requal(const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr);
+ * herr_t H5Rcopy(const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr);
+ *
+ * // Dereference
+ * hid_t H5Ropen_object(const H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id);
+ * hid_t H5Ropen_region(const H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id);
+ * hid_t H5Ropen_attr(const H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id);
+ *
+ * // Get type
+ * herr_t H5Rget_obj_type3(const H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type);
+ *
+ * // Get name
+ * ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *name, size_t size);
+ * ssize_t H5Rget_obj_name(const H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, size_t size);
+ * ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t size);
+ * \endcode
+ *
+ * References can be stored and retrieved from a file by invoking the #H5Dwrite and #H5Dread functions
+ * with this single predefined type: #H5T_STD_REF.
+ *
+ * The advantage of a single type is that it becomes easier for users to mix references of different types. It
+ * is also more in line with the opaque type now defined for references. Note that when reading references
+ * back from a file, the library may, in consequence of this new design, allocate memory for each of these
+ * references. To release the memory, one must either call #H5Rdestroy on each of the references or, for
+ * convenience, call the new #H5Treclaim function on the buffer that contains the array of references (type
+ * can be compound type, array).
+ *
+ * As mentioned, instead of having separate routines for both vlen and reference types, we unify the existing:
+ * \code
+ * herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf);
+ * \endcode
+ * to
+ * \code
+ * herr_t H5Treclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf);
+ * \endcode
+ *
+ * \subsection subsec_reference_compat API Compatibility
+ * To preserve compatibility with applications and middleware libraries that have been using the existing
+ * reference API, we keep the existing #H5Rcreate, #H5Rdereference2, #H5Rget_region,
+ * #H5Rget_obj_type2 and #H5Rget_name routines, but moved to the deprecated
+ * API list of functions.
+ *
+ * It is important to note though that these routines only support the original reference types, noted as
+ * #H5R_OBJECT1 and #H5R_DATASET_REGION1 respectively. Any other reference type passed to these routines
+ * will return an error. For convenience and compatibility with previous versions of the library we define
+ * both #H5R_OBJECT and #H5R_DATASET_REGION to map to the original reference types \code
+ * // Versions for compatibility
+ * #define H5R_OBJECT H5R_OBJECT1
+ * #define H5R_DATASET_REGION H5R_DATASET_REGION1
+ * \endcode
+ *
+ * When creating and accessing references through these deprecated routines, users are still expected to use
+ * the datatypes which describe the #hobj_ref_t and #hdset_reg_ref_t types, #H5T_STD_REF_OBJ and
+ * #H5T_STD_REF_DSETREG.
+ *
+ * One important aspect of these changes is to ensure that previously written data can still be readable after
+ * those revisions and that new files produced will not create any undefined behavior when used with previous
+ * versions of the library. Backward as well as forward compatibility is summarized in the table:
+ *
+ *
+ *
+ *
Version
Old File Format/Old API
Old File Format/New API
New File Format/Old
+ * API
New File Format/New API
+ *
+ *
+ *
< 1.12.0
No change
N/A
Datatype version bump prevents from reading unknown
+ * reference types
N/A
+ *
+ *
+ *
≥ 1.12.0
+ *
Read and write references through old datatypes and use #hobj_ref_t and #hdset_reg_ref_t types
+ *
Read and write using #H5T_STD_REF to convert to new #H5R_ref_t type
+ *
Cannot use old API with new reference types
+ *
Can use opaque #H5R_ref_t type for all reference types
+ *
+ *
+ *
+ * Because previous library versions do not have a way of detecting when new unknown references types are
+ * read, we have to increment the global version of the datatypes, so that early detection can be done and the
+ * appropriate error is returned to the user. For versions prior to this change, the library will return an
+ * error when the datatype encountered has a version number greater than the currently supported version.
+ * Also, to prevent datatype version changes in the future, all library branches are now patched to check for
+ * unknown reference types.
+ *
+ * When reading old data with the new library version, one can either keep using the #H5T_STD_REF_OBJ
+ * and #H5T_STD_REF_DSETREG datatypes, which can be queried when opening a dataset, for example using
+ * #H5Dget_type, or use the #H5T_STD_REF datatype, which will trigger automatic type conversion. The
+ * #H5T_STD_REF_OBJ and #H5T_STD_REF_DSETREG datatypes require the use of the respective #hobj_ref_t
+ * and #hdset_reg_ref_t types, which can only be used with the old API functions. These types do not embed
+ * all the required information to be simply cast to an #H5R_ref_t type. When an #H5R_ref_t type is desired,
+ * the #H5T_STD_REF datatype must be used, allowing old reference data to be used with the new API.
+ *
+ * \subsection subsec_reference_example Usage Examples
+ *
+ * \subsubsection subsubsec_reference_example_new External References
+ * The example below illustrates the use of the new API with files that are opened read-only. Created
+ * references to the objects in that file are stored into a separate file, and accessed from that file,
+ * without the user explicitly opening the original file that was referenced. \code #include
+ *
+ * #include "hdf5.h"
+ * #include
+ *
+ * #define H5FILE_NAME1 "refer_extern1.h5"
+ * #define H5FILE_NAME2 "refer_extern2.h5"
+ *
+ * #define NDIMS 1 // Number of dimensions
+ * #define BUF_SIZE 4 // Size of example buffer
+ * #define NREFS 1 // Number of references
+ *
+ * int main(void) {
+ * hid_t file1, dset1, space1;
+ * hsize_t dset1_dims[NDIMS] = { BUF_SIZE };
+ * int dset_buf[BUF_SIZE];
+ *
+ * hid_t file2, dset2, space2;
+ * hsize_t dset2_dims[NDIMS] = { NREFS };
+ * H5R_ref_t ref_buf[NREFS] = { 0 };
+ * H5O_type_t obj_type;
+ * int i;
+ *
+ * for (i = 0; i < BUF_SIZE; i++)
+ * dset_buf[i] = i;
+ *
+ * // Create file with one dataset and close it
+ * file1 = H5Fcreate(H5FILE_NAME1, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+ * space1 = H5Screate_simple(NDIMS, dset1_dims, NULL);
+ * dset1 = H5Dcreate2(file1, "dataset1", H5T_NATIVE_INT, space1, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * H5Dwrite(dset1, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_buf);
+ * H5Dclose(dset1);
+ * H5Sclose(space1);
+ * H5Fclose(file1);
+ *
+ * // Create reference to dataset1 in "refer_extern1.h5"
+ * file1 = H5Fopen(H5FILE_NAME1, H5F_ACC_RDONLY, H5P_DEFAULT);
+ * H5Rcreate_object(file1, "dataset1", &ref_buf[0]);
+ * H5Fclose(file1);
+ *
+ * // Store reference in dataset in separate file "refer_extern2.h5"
+ * file2 = H5Fcreate(H5FILE_NAME2, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+ * space2 = H5Screate_simple(NDIMS, dset2_dims, NULL);
+ * dset2 = H5Dcreate2(file2, "references", H5T_STD_REF, space2, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * H5Dwrite(dset2, H5T_STD_REF, H5S_ALL, H5S_ALL, H5P_DEFAULT, ref_buf);
+ * H5Dclose(dset2);
+ * H5Sclose(space2);
+ * H5Fclose(file2);
+ * H5Rdestroy(&ref_buf[0]);
+ *
+ * // Read reference back from "refer_extern2.h5"
+ * file2 = H5Fopen(H5FILE_NAME2, H5F_ACC_RDONLY, H5P_DEFAULT);
+ * dset2 = H5Dopen2(file2, "references", H5P_DEFAULT);
+ * H5Dread(dset2, H5T_STD_REF, H5S_ALL, H5S_ALL, H5P_DEFAULT, ref_buf);
+ * H5Dclose(dset2);
+ * H5Fclose(file2);
+ *
+ * // Access reference and read dataset data without opening original file
+ * assert(H5Rget_type((const H5R_ref_t *)&ref_buf[0]) == H5R_OBJECT2);
+ * H5Rget_obj_type3((const H5R_ref_t *)&ref_buf[0], H5P_DEFAULT, &obj_type);
+ * assert(obj_type == H5O_TYPE_DATASET);
+ * dset1 = H5Ropen_object((const H5R_ref_t *)&ref_buf[0], H5P_DEFAULT, H5P_DEFAULT);
+ * H5Dread(dset1, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_buf);
+ * H5Dclose(dset1);
+ * H5Rdestroy(&ref_buf[0]);
+ *
+ * for (i = 0; i < BUF_SIZE; i++)
+ * assert(dset_buf[i] == i);
+ *
+ * return 0;
+ * }
+ * \endcode
+ *
+ * \subsubsection subsubsec_reference_example_old Backward Compatibility and New API
+ * The example below illustrates the use of the new API with a file that was written using the old-style
+ * reference API, showing how one can take advantage of the automatic type conversion from old reference type
+ * to new reference type.
+ * \code #include
+ *
+ * #include "hdf5.h"
+ * #include
+ *
+ * #define H5FILE_NAME "refer_deprec.h5"
+ *
+ * #define NDIMS 1 // Number of dimensions
+ * #define BUF_SIZE 4 // Size of example buffer
+ * #define NREFS 1 // Number of references
+ *
+ * int main(void) {
+ * hid_t file1, dset1, space1;
+ * hsize_t dset1_dims[NDIMS] = { BUF_SIZE };
+ * int dset_buf[BUF_SIZE];
+ *
+ * hid_t dset2, space2;
+ * hsize_t dset2_dims[NDIMS] = { NREFS };
+ * hobj_ref_t ref_buf[NREFS] = { 0 };
+ * H5R_ref_t new_ref_buf[NREFS] = { 0 };
+ * H5O_type_t obj_type;
+ * int i;
+ *
+ * for (i = 0; i < BUF_SIZE; i++)
+ * dset_buf[i] = i;
+ *
+ * // Create file with one dataset and close it
+ * file1 = H5Fcreate(H5FILE_NAME, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+ *
+ * space1 = H5Screate_simple(NDIMS, dset1_dims, NULL);
+ * dset1 = H5Dcreate2(file1, "dataset1", H5T_NATIVE_INT, space1, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * H5Dwrite(dset1, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_buf);
+ * H5Dclose(dset1);
+ * H5Sclose(space1);
+ *
+ * // Create reference to dataset1 with deprecated API
+ * // (reminder: there is no destroy call for those references)
+ * H5Rcreate(&ref_buf[0], file1, "dataset1", H5R_OBJECT, H5I_INVALID_HID);
+ *
+ * // Store reference in separate dataset using deprecated reference type
+ * space2 = H5Screate_simple(NDIMS, dset2_dims, NULL);
+ * dset2 = H5Dcreate2(file1, "references", H5T_STD_REF_OBJ, space2, H5P_DEFAULT, H5P_DEFAULT,
+ * H5P_DEFAULT);
+ * H5Dwrite(dset2, H5T_STD_REF_OBJ, H5S_ALL, H5S_ALL, H5P_DEFAULT, ref_buf); H5Dclose(dset2);
+ * H5Sclose(space2);
+ * H5Fclose(file1);
+ *
+ * // Read reference from file using new reference type
+ * file1 = H5Fopen(H5FILE_NAME, H5F_ACC_RDONLY, H5P_DEFAULT);
+ * dset2 = H5Dopen2(file1, "references", H5P_DEFAULT);
+ * H5Dread(dset2, H5T_STD_REF, H5S_ALL, H5S_ALL, H5P_DEFAULT, new_ref_buf);
+ * H5Dclose(dset2);
+ *
+ * // Access reference and read dataset data through new API
+ * assert(H5Rget_type((const H5R_ref_t *)&new_ref_buf[0]) == H5R_OBJECT2);
+ * H5Rget_obj_type3((const H5R_ref_t *)&new_ref_buf[0], H5P_DEFAULT, &obj_type);
+ * assert(obj_type == H5O_TYPE_DATASET);
+ * dset1 = H5Ropen_object((const H5R_ref_t *)&new_ref_buf[0], H5P_DEFAULT, H5P_DEFAULT);
+ * H5Dread(dset1, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_buf);
+ * H5Dclose(dset1);
+ * H5Rdestroy(&new_ref_buf[0]);
+ *
+ * for (i = 0; i < BUF_SIZE; i++)
+ * assert(dset_buf[i] == i);
+ * return 0;
+ * }
+ * \endcode
+ *
+ *
*/
/**
diff --git a/src/H5Smodule.h b/src/H5Smodule.h
index d212d5dbf2c..2dc8fe127d6 100644
--- a/src/H5Smodule.h
+++ b/src/H5Smodule.h
@@ -974,7 +974,33 @@
*
* This section is under construction.
*
- * \subsection subsec_dataspace_refer References to Dataset Regions
+ * \subsection subsec_dataspace_refer References
+ *
+ * Another use of selections is to store a reference to a region of a dataset in the file or an external file.
+ An HDF5 object reference
+ * object is a pointer to an object (attribute, dataset, group, or committed datatype) in the file or an
+ external file. A selection can
+ * be used to create a pointer to a set of selected elements of a dataset, called a region reference. The
+ * selection can be either a point selection or a hyperslab selection.
+ *
+ * A region reference is an object maintained by the HDF5 Library. The region reference can be stored in a
+ * dataset or attribute, and then read. The dataset or attribute is defined to have the special datatype,
+ * #H5T_STD_REF.
+ *
+ * To discover the elements and/or read the data, the region reference can be dereferenced to obtain the
+ * identifiers for the dataset and dataspace.
+ *
+ * For more information, \see subsubsec_datatype_other_refs.
+ *
+ * \subsubsection subsubsec_dataspace_refer_use Example Uses for Region References
+ *
+ * \subsubsection subsubsec_dataspace_refer_create Creating References to Regions
+ *
+ * \subsubsection subsubsec_dataspace_refer_read Reading References to Regions
+ *
+ * \subsection subsec_dataspace_deprecated_refer Deprecated References to Dataset Regions
+ * The API described in this section was deprecated since HDF5 1.12.0. Shown are
+ * examples and usage in use by applications written before 1.12.0.
*
* Another use of selections is to store a reference to a region of a dataset. An HDF5 object reference
* object is a pointer to an object (dataset, group, or committed datatype) in the file. A selection can
@@ -992,7 +1018,7 @@
*
* For more information, \see subsubsec_datatype_other_refs.
*
- * \subsubsection subsubsec_dataspace_refer_use Example Uses for Region References
+ * \subsubsection subsubsec_dataspace_deprecated_refer_use Deprecated Example Uses for Region References
*
* Region references are used to implement stored pointers to data within a dataset. For example, features
* in a large dataset might be indexed by a table. See the figure below. This table could be stored as an
@@ -1016,7 +1042,7 @@
*
*
*
- * \subsubsection subsubsec_dataspace_refer_create Creating References to Regions
+ * \subsubsection subsubsec_dataspace_deprecated_refer_create Deprecated Creating References to Regions
*
* To create a region reference:
* \li 1. Create or open the dataset that contains the region
@@ -1043,7 +1069,7 @@
* and a reference is created using \ref H5Rcreate(). The call to \ref H5Rcreate() specifies the file,
* dataset, and the dataspace with selection.
*
- * Create an array of region references
+ * Deprecated Create an array of region references
* \code
* // create an array of 4 region references
* hdset_reg_ref_t ref[4];
@@ -1085,7 +1111,7 @@
* When all the references are created, the array of references is written to the dataset R1. The
* dataset is declared to have datatype #H5T_STD_REF_DSETREG. See the example below.
*
- * Write the array of references to a dataset
+ * Deprecated Write the array of references to a dataset
* \code
* Hsize_t dimsr[1];
* dimsr[0] = 4;
@@ -1105,7 +1131,7 @@
* \li The dataset must exist in the file when the reference is created; #H5Rcreate
* \li The target dataset must be in the same file as the stored reference
*
- * \subsubsection subsubsec_dataspace_refer_read Reading References to Regions
+ * \subsubsection subsubsec_dataspace_refer_deprecated_read Deprecated Reading References to Regions
*
* To retrieve data from a region reference, the reference must be read from the file, and then the data can
* be retrieved. The steps are:
@@ -1127,7 +1153,7 @@
* \li The target dataset must be present and accessible in the file
* \li The selection must be a valid selection for the dataset
*
- * Read an array of region references; read from the first selection
+ * Deprecated Read an array of region references; read from the first selection
* \code
* dsetr_id = H5Dopen (file_id, "R1", H5P_DEFAULT);
* status = H5Dread(dsetr_id, H5T_STD_REF_DSETREG, H5S_ALL, H5S_ALL, H5P_DEFAULT, ref_out);
diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h
index 35e748bac3f..fd2a278fd22 100644
--- a/src/H5Tmodule.h
+++ b/src/H5Tmodule.h
@@ -598,10 +598,10 @@
*
*
*
- * #H5T_STD_REF_OBJ
+ * #H5T_STD_REF
*
*
- * Reference to an entire object in a file
+ * Reference to an object in a file
*
*
*
@@ -2943,8 +2943,63 @@ filled according to the value of this property. The padding can be:
* \endcode
*
* \subsubsection subsubsec_datatype_other_refs Reference
+ * In HDF5, objects (groups, datasets, attributes, and committed datatypes) are usually accessed by name.
+ * There is another way to access stored objects - by reference. Before HDF5 1.12.0, there were only two
+ * reference datatypes: object reference and region reference. Since 1.12.0, attribute references and
+ * external references were added. And all references can be stored and retrieved from a file by invoking
+ * the #H5Dwrite and #H5Dread functions with a single predefined type: #H5T_STD_REF.
+ *
+ * The first example below shows an example of code that creates
+ * references to four objects, and then writes the array of object references to a dataset. The second
+ * example below shows a dataset of datatype reference being read and one of the reference objects
+ * being dereferenced to obtain an object pointer.
+ *
+ * Create object references and write to a dataset
+ * \code
+ * dataset = H5Dcreate (fid1, “Dataset3”, H5T_STD_REF, sid1, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ *
+ * // Create reference to dataset
+ * ret = H5Rcreate_object(fid1,“/Group1/Dataset1”, H5R_OBJECT, &wbuf[0]);
+ *
+ * // Create reference to dataset
+ * ret = H5Rcreate_object(fid1, “/Group1/Dataset2”, H5R_OBJECT, &wbuf[1]);
+ *
+ * // Create reference to group
+ * ret = H5Rcreate_object(fid1, “/Group1”, H5R_OBJECT, &wbuf[2]);
+ *
+ * // Create reference to committed datatype
+ * ret = H5Rcreate_object(fid1, “/Group1/Datatype1”, H5R_OBJECT, &wbuf[3]);
+ *
+ * // Write selection to disk
+ * ret = H5Dwrite(dataset, H5T_STD_REF, H5S_ALL, H5S_ALL, H5P_DEFAULT, wbuf);
+ *
+ * // Release buffers
+ * status = H5Rdestroy(&wdata[0]);
+ * status = H5Rdestroy(&wdata[1]);
+ * status = H5Rdestroy(&wdata[2]);
+ * status = H5Rdestroy(&wdata[3]);
+ * \endcode
+ *
+ * Read a dataset with a reference datatype
+ * \code
+ * rbuf = (H5R_ref_t *)malloc(dims[0] * sizeof(H5R_ref_t));
+ *
+ * // Read selection from disk
+ * ret = H5Dread(dataset, H5T_STD_REF, H5S_ALL, H5S_ALL, H5P_DEFAULT, rbuf);
+ *
+ * // Open dataset object
+ * dset2 = H5Ropen_object(&rbuf[0], H5P_DEFAULT, H5P_DEFAULT);
+ *
+ * // Release buffers
+ * status = H5Rdestroy(&rbuf[0]);
+ * status = H5Rdestroy(&rbuf[1]);
+ * status = H5Rdestroy(&rbuf[2]);
+ * status = H5Rdestroy(&rbuf[3]);
+ * \endcode
+ *
+ * \subsubsection subsubsec_datatype_other_drefs Deprecated Reference
* In HDF5, objects (groups, datasets, and committed datatypes) are usually accessed by name.
- * There is another way to access stored objects - by reference. There are two reference datatypes:
+ * There is another way to access stored objects - by reference. There are two deprecated reference datatypes:
* object reference and region reference. Object reference objects are created with #H5Rcreate and
* other calls (cross reference). These objects can be stored and retrieved in a dataset as elements
* with reference datatype. The first example below shows an example of code that creates
@@ -3748,6 +3803,7 @@ filled according to the value of this property. The padding can be:
*
* ::= | |