diff options
| author | Barbara Jones <bljones@hdfgroup.org> | 2001-03-08 16:47:44 (GMT) |
|---|---|---|
| committer | Barbara Jones <bljones@hdfgroup.org> | 2001-03-08 16:47:44 (GMT) |
| commit | 345e07fc11458901632c697ae794d91962eed817 (patch) | |
| tree | bb30b14de021bd2c70480b9126008002d6bdb36e /doc | |
| parent | d8c843156a3879a51f7e3062f51beba4e84b1ca2 (diff) | |
| download | hdf5-345e07fc11458901632c697ae794d91962eed817.zip hdf5-345e07fc11458901632c697ae794d91962eed817.tar.gz hdf5-345e07fc11458901632c697ae794d91962eed817.tar.bz2 | |
[svn-r3563] Add changes to tutorial for Fortran
Purpose:
[is this a bug fix? feature? ...]
Description:
[describe the bug, or describe the new feature, etc]
Solution:
[details about the changes, algorithm, etc...]
[Please as detail as you can since your own explanation is
better than others guessing it from the code.]
Platforms tested:
[machines you have tested the changed version. This is absolute
important. Test it out on at least two or three different platforms
such as Big-endian-32bit (SUN/IRIX), little-endian-32(LINUX) and
64-bit (IRIX64/UNICOS/DEC-ALPHA) would be good.]
Diffstat (limited to 'doc')
32 files changed, 3266 insertions, 3009 deletions
diff --git a/doc/html/Tutor/Contents.html b/doc/html/Tutor/Contents.html index 49c4a32..d2584e5 100644 --- a/doc/html/Tutor/Contents.html +++ b/doc/html/Tutor/Contents.html @@ -2,6 +2,7 @@ <body bgcolor="#BBFFFF"> + <!-- The following tag is for use only in the distributed doc set. Remove (or comment out) when served from HDF web server. @@ -9,6 +10,7 @@ Remove (or comment out) when served from HDF web server. <center> <font size=-1><a href="../index.html" target=_top>Return to HDF5 Doc Set</a></font> </center> +<br> <hr> @@ -16,7 +18,6 @@ Remove (or comment out) when served from HDF web server. <A HREF="READ1ST.HTML" Target="RdFirstWin" onClick="window.open("READ1ST.HTML","RdFirstWin","toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=yes,resizable=1,width=500,height=250,titlebar=yes")"><IMG SRC="GRAPHICS/READ1ST.GIF" BORDER=0 ALT="Read this first!"></A> --> - <a href="title.html" TARGET="CONTENT"><IMG SRC="Graphics/TitlePg.gif" BORDER=0 ALT="Tutorial Title Page"></a> <br> @@ -56,11 +57,11 @@ Remove (or comment out) when served from HDF web server. <a href="ContentsAdv.html" TARGET="BUTTONS"><IMG SRC="Graphics/AdvTopics.gif" BORDER=0 ALT="Advanced Topics"></a> <!-- <br> -<a href="compound.html" TARGET="CONTENT"><IMG SRC="Graphics/CompDTypes.gif" BORDER=0 ALT="Compound Data Types"></a> +<a href="compound.html" TARGET="CONTENT"><IMG SRC="Graphics/CompDTypes.gif" BORDER=0 ALT="Compound Datatypes"></a> <br> -<a href="select.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectHyp.gif" BORDER=0 ALT="Selections Using H5Sselect_hyperslab"></a> +<a href="select.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectHyp.gif" BORDER=0 ALT="Dataspace Selection - Hyperslab"></a> <br> -<a href="selectc.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectElemCp.gif" BORDER=0 ALT="Selections Using H5Sselect_elements and H5Scopy"></a> +<a href="selectc.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectElemCp.gif" BORDER=0 ALT="Dataspace Selection - Individual Points"></a> <br> <a href="reftoobj.html" TARGET="CONTENT"><IMG SRC="Graphics/RefObject.gif" BORDER=0 ALT="References to Objects"></a> <br> diff --git a/doc/html/Tutor/ContentsAdd.html b/doc/html/Tutor/ContentsAdd.html index 78a1386..cd5d2e1 100644 --- a/doc/html/Tutor/ContentsAdd.html +++ b/doc/html/Tutor/ContentsAdd.html @@ -10,6 +10,7 @@ Remove (or comment out) when served from HDF web server. <center> <font size=-1><a href="../index.html" target=_top>Return to HDF5 Doc Set</a></font> </center> +<br> <hr> @@ -19,85 +20,32 @@ Remove (or comment out) when served from HDF web server. <a href="Contents.html" TARGET="BUTTONS"><IMG SRC="Graphics/TOCShort.gif" BORDER=0 ALT="(Short TOC)"></a> -<br> <hr> <a href="title.html" TARGET="CONTENT"><IMG SRC="Graphics/TitlePg.gif" BORDER=0 ALT="Tutorial Title Page"></a> -<br> - <hr> -<a href="ContentsIntro.html" TARGET="BUTTONS"><IMG SRC="Graphics/IntroTopics.gif" BORDER=0 ALT="Introductory Topics"></a> -<!-- -<a href="intro.html" TARGET="CONTENT"><IMG SRC="Graphics/Intro.gif" BORDER=0 ALT="Introduction"></a> -<br> -<br> -<a href="fileorg.html" TARGET="CONTENT"><img src="Graphics/FileOrg.gif" BORDER=0 ALT="HDF5 File Organization"></a> -<br> -<a href="api.html" TARGET="CONTENT"><IMG SRC="Graphics/H5API.gif" BORDER=0 ALT="The HDF5 API"></a> -<br> -<a href="crtfile.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateFile.gif" BORDER=0 ALT="Creating an HDF5 File"></a> -<br> -<a href="crtdat.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateDset1.gif" BORDER=0 ALT="Creating a Dataset"></a> -<br> -<a href="rdwt.html" TARGET="CONTENT"><IMG SRC="Graphics/RdWrDataset.gif" BORDER=0 ALT="Reading from and Writing to a Dataset"></a> -<br> -<a href="crtatt.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateAttr.gif" BORDER=0 ALT="Creating an Attribute"></a> -<br> -<a href="crtgrp.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateGrp1.gif" BORDER=0 ALT="Creating a Group"></a> -<br> -<a href="crtgrpar.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateGrp2.gif" BORDER=0 ALT="Creating Groups Using Absolute and Relative Names"></a> -<br> -<a href="crtgrpd.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateDset2.gif" BORDER=0 ALT="Creating Datasets in a Group"></a> - -<br> -<br> -<a href="questions.html" TARGET="CONTENT"><IMG SRC="Graphics/Quiz.gif" BORDER=0 ALT="Quiz Questions"></a> -<br> -<a href="answers.html" TARGET="CONTENT"><IMG SRC="Graphics/QuizAns.gif" BORDER=0 ALT="Quiz Answers"></a> ---> +<a href="ContentsIntro.html" TARGET="BUTTONS"><IMG SRC="Graphics/IntroTopics.gif" BORDER=0 ALT="Introductory Topics"></a> <hr> -<a href="ContentsAdv.html" TARGET="BUTTONS"><IMG SRC="Graphics/AdvTopics.gif" BORDER=0 ALT="Advanced Topics"></a> -<!-- -<br> -<a href="compound.html" TARGET="CONTENT"><IMG SRC="Graphics/CompDTypes.gif" BORDER=0 ALT="Compound Data Types"></a> -<br> -<a href="select.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectHyp.gif" BORDER=0 ALT="Selections Using H5Sselect_hyperslab"></a> -<br> -<a href="selectc.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectElemCp.gif" BORDER=0 ALT="Selections Using H5Sselect_elements and H5Scopy"></a> -<br> -<a href="reftoobj.html" TARGET="CONTENT"><IMG SRC="Graphics/RefObject.gif" BORDER=0 ALT="References to Objects"></a> -<br> -<a href="reftoreg.html" TARGET="CONTENT"><IMG SRC="Graphics/RefRegion.gif" BORDER=0 ALT="References to Dataset Regions"></a> -<br> -<a href="extend.html" TARGET="CONTENT"><IMG SRC="Graphics/ChunkExt.gif" BORDER=0 ALT="Chunking and Extendible Datasets"></a> -<br> -<a href="mount.html" TARGET="CONTENT"><IMG SRC="Graphics/MountFile.gif" BORDER=0 ALT="Mounting Files"></a> -<br> -<a href="iterate.html" TARGET="CONTENT"><IMG SRC="Graphics/Iterate.gif" BORDER=0 ALT="Group Iteration"></a> ---> +<a href="ContentsAdv.html" TARGET="BUTTONS"><IMG SRC="Graphics/AdvTopics.gif" BORDER=0 ALT="Advanced Topics"></a> <hr> + + <IMG SRC="Graphics/AddInfo.gif" BORDER=0 ALT="Additional Information"> -<br> <a href="util.html" TARGET="CONTENT"><IMG SRC="Graphics/Utilities.gif" BORDER=0 ALT="HDF5 Utilities -- h5ls and h5dump"></a> -<br> <a href="glossary.html" TARGET="CONTENT"><IMG SRC="Graphics/Glossary.gif" BORDER=0 ALT="Glossary"></a> -<br> <a href="references.html" TARGET="CONTENT"><IMG SRC="Graphics/References.gif" BORDER=0 ALT="References"></a> -<br> <a href="examples/" TARGET="CONTENT"><IMG SRC="Graphics/Examples.gif" BORDER=0 ALT="Example Programs"></a> +<hr> -<hr> <a href="ContentsFull.html" TARGET="BUTTONS"><IMG SRC="Graphics/TOCFull.gif" BORDER=0 ALT="Full TOC"></a> -<br> <hr> -<br> <a href="Copyright.html" TARGET="CONTENT"><IMG SRC="Graphics/Copy.gif" BORDER=0 ALT="Copyright, Etc."></a><br> diff --git a/doc/html/Tutor/ContentsAdv.html b/doc/html/Tutor/ContentsAdv.html index b2ac014..ac27c0e 100644 --- a/doc/html/Tutor/ContentsAdv.html +++ b/doc/html/Tutor/ContentsAdv.html @@ -10,6 +10,7 @@ Remove (or comment out) when served from HDF web server. <center> <font size=-1><a href="../index.html" target=_top>Return to HDF5 Doc Set</a></font> </center> +<br> <hr> @@ -18,85 +19,36 @@ Remove (or comment out) when served from HDF web server. --> <a href="Contents.html" TARGET="BUTTONS"><IMG SRC="Graphics/TOCShort.gif" BORDER=0 ALT="(Short TOC)"></a> -<br> <hr> <a href="title.html" TARGET="CONTENT"><IMG SRC="Graphics/TitlePg.gif" BORDER=0 ALT="Tutorial Title Page"></a> -<br> - <hr> -<a href="ContentsIntro.html" TARGET="BUTTONS"><IMG SRC="Graphics/IntroTopics.gif" BORDER=0 ALT="Introductory Topics"></a> -<!-- -<br> -<a href="intro.html" TARGET="CONTENT"><IMG SRC="Graphics/Intro.gif" BORDER=0 ALT="Introduction"></a> -<br> -<a href="fileorg.html" TARGET="CONTENT"><img src="Graphics/FileOrg.gif" BORDER=0 ALT="HDF5 File Organization"></a> -<br> -<a href="api.html" TARGET="CONTENT"><IMG SRC="Graphics/H5API.gif" BORDER=0 ALT="The HDF5 API"></a> -<br> -<a href="crtfile.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateFile.gif" BORDER=0 ALT="Creating an HDF5 File"></a> -<br> -<a href="crtdat.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateDset1.gif" BORDER=0 ALT="Creating a Dataset"></a> -<br> -<a href="rdwt.html" TARGET="CONTENT"><IMG SRC="Graphics/RdWrDataset.gif" BORDER=0 ALT="Reading from and Writing to a Dataset"></a> -<br> -<a href="crtatt.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateAttr.gif" BORDER=0 ALT="Creating an Attribute"></a> -<br> -<a href="crtgrp.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateGrp1.gif" BORDER=0 ALT="Creating a Group"></a> -<br> -<a href="crtgrpar.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateGrp2.gif" BORDER=0 ALT="Creating Groups Using Absolute and Relative Names"></a> -<br> -<a href="crtgrpd.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateDset2.gif" BORDER=0 ALT="Creating Datasets in a Group"></a> -<br> -<br> -<a href="questions.html" TARGET="CONTENT"><IMG SRC="Graphics/Quiz.gif" BORDER=0 ALT="Quiz Questions"></a> -<br> -<a href="answers.html" TARGET="CONTENT"><IMG SRC="Graphics/QuizAns.gif" BORDER=0 ALT="Quiz Answers"></a> ---> - +<a href="ContentsIntro.html" TARGET="BUTTONS"><IMG SRC="Graphics/IntroTopics.gif" BORDER=0 ALT="Introductory Topics"></a> <hr> + + <IMG SRC="Graphics/AdvTopics.gif" BORDER=0 ALT="Advanced Topics"> -<br> -<a href="compound.html" TARGET="CONTENT"><IMG SRC="Graphics/CompDTypes.gif" BORDER=0 ALT="Compound Data Types"></a> -<br> -<a href="select.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectHyp.gif" BORDER=0 ALT="Selections Using H5Sselect_hyperslab"></a> -<br> -<a href="selectc.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectElemCp.gif" BORDER=0 ALT="Selections Using H5Sselect_elements and H5Scopy"></a> -<br> +<a href="compound.html" TARGET="CONTENT"><IMG SRC="Graphics/CompDTypes.gif" BORDER=0 ALT="Compound Datatypes"></a> +<a href="select.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectHyp.gif" BORDER=0 ALT="Dataspace Selection - hyperslab"></a> +<a href="selectc.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectElemCp.gif" BORDER=0 ALT="Dataspace Selection - Individual Points"></a> <a href="reftoobj.html" TARGET="CONTENT"><IMG SRC="Graphics/RefObject.gif" BORDER=0 ALT="References to Objects"></a> -<br> <a href="reftoreg.html" TARGET="CONTENT"><IMG SRC="Graphics/RefRegion.gif" BORDER=0 ALT="References to Dataset Regions"></a> -<br> <a href="extend.html" TARGET="CONTENT"><IMG SRC="Graphics/ChunkExt.gif" BORDER=0 ALT="Chunking and Extendible Datasets"></a> -<br> <a href="mount.html" TARGET="CONTENT"><IMG SRC="Graphics/MountFile.gif" BORDER=0 ALT="Mounting Files"></a> -<br> <a href="iterate.html" TARGET="CONTENT"><IMG SRC="Graphics/Iterate.gif" BORDER=0 ALT="Group Iteration"></a> +<hr> -<hr> <a href="ContentsAdd.html" TARGET="BUTTONS"><IMG SRC="Graphics/AddInfo.gif" BORDER=0 ALT="Additional Information"></a> -<!-- -<br> -<a href="util.html" TARGET="CONTENT"><IMG SRC="Graphics/Utilities.gif" BORDER=0 ALT="HDF5 Utilities -- h5ls and h5dump"></a> -<br> -<a href="glossary.html" TARGET="CONTENT"><IMG SRC="Graphics/Glossary.gif" BORDER=0 ALT="Glossary"></a> -<br> -<a href="references.html" TARGET="CONTENT"><IMG SRC="Graphics/References.gif" BORDER=0 ALT="References"></a> -<br> -<a href="examples/" TARGET="CONTENT"><IMG SRC="Graphics/Examples.gif" BORDER=0 ALT="Example Programs"></a> ---> +<hr> -<hr> <a href="ContentsFull.html" TARGET="BUTTONS"><IMG SRC="Graphics/TOCFull.gif" BORDER=0 ALT="Full TOC"></a> -<br> +<hr> -<hr> -<br> <a href="Copyright.html" TARGET="CONTENT"><IMG SRC="Graphics/Copy.gif" BORDER=0 ALT="Copyright, Etc."></a><br> diff --git a/doc/html/Tutor/ContentsFull.html b/doc/html/Tutor/ContentsFull.html index 09cd5b9..d873f82 100644 --- a/doc/html/Tutor/ContentsFull.html +++ b/doc/html/Tutor/ContentsFull.html @@ -10,6 +10,7 @@ Remove (or comment out) when served from HDF web server. <center> <font size=-1><a href="../index.html" target=_top>Return to HDF5 Doc Set</a></font> </center> +<br> <hr> @@ -19,79 +20,49 @@ Remove (or comment out) when served from HDF web server. <a href="Contents.html" TARGET="BUTTONS"><IMG SRC="Graphics/TOCShort.gif" BORDER=0 ALT="(Short TOC)"></a> -<br> <hr> <a href="title.html" TARGET="CONTENT"><IMG SRC="Graphics/TitlePg.gif" BORDER=0 ALT="Tutorial Title Page"></a> -<br> <hr> <IMG SRC="Graphics/IntroTopics.gif" BORDER=0 ALT="Introductory Topics"> -<br> <a href="intro.html" TARGET="CONTENT"><IMG SRC="Graphics/Intro.gif" BORDER=0 ALT="Introduction"></a> -<br> <a href="fileorg.html" TARGET="CONTENT"><img src="Graphics/FileOrg.gif" BORDER=0 ALT="HDF5 File Organization"></a> -<br> <a href="api.html" TARGET="CONTENT"><IMG SRC="Graphics/H5API.gif" BORDER=0 ALT="The HDF5 API"></a> -<br> <a href="crtfile.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateFile.gif" BORDER=0 ALT="Creating an HDF5 File"></a> -<br> <a href="crtdat.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateDset1.gif" BORDER=0 ALT="Creating a Dataset"></a> -<br> <a href="rdwt.html" TARGET="CONTENT"><IMG SRC="Graphics/RdWrDataset.gif" BORDER=0 ALT="Reading from and Writing to a Dataset"></a> -<br> <a href="crtatt.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateAttr.gif" BORDER=0 ALT="Creating an Attribute"></a> -<br> <a href="crtgrp.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateGrp1.gif" BORDER=0 ALT="Creating a Group"></a> -<br> <a href="crtgrpar.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateGrp2.gif" BORDER=0 ALT="Creating Groups Using Absolute and Relative Names"></a> -<br> <a href="crtgrpd.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateDset2.gif" BORDER=0 ALT="Creating Datasets in a Group"></a> <br> -<br> <a href="questions.html" TARGET="CONTENT"><IMG SRC="Graphics/Quiz.gif" BORDER=0 ALT="Quiz Questions"></a> -<br> <a href="answers.html" TARGET="CONTENT"><IMG SRC="Graphics/QuizAns.gif" BORDER=0 ALT="Quiz Answers"></a> <hr> <IMG SRC="Graphics/AdvTopics.gif" BORDER=0 ALT="Advanced Topics"> -<br> -<a href="compound.html" TARGET="CONTENT"><IMG SRC="Graphics/CompDTypes.gif" BORDER=0 ALT="Compound Data Types"></a> -<br> -<a href="select.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectHyp.gif" BORDER=0 ALT="Selections Using H5Sselect_hyperslab"></a> -<br> -<a href="selectc.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectElemCp.gif" BORDER=0 ALT="Selections Using H5Sselect_elements and H5Scopy"></a> -<br> +<a href="compound.html" TARGET="CONTENT"><IMG SRC="Graphics/CompDTypes.gif" BORDER=0 ALT="Compound Datatypes"></a> +<a href="select.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectHyp.gif" BORDER=0 ALT="Dataspace Selection - Hyperslab"></a> +<a href="selectc.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectElemCp.gif" BORDER=0 ALT="Dataspace Selection - Individual Points"></a> <a href="reftoobj.html" TARGET="CONTENT"><IMG SRC="Graphics/RefObject.gif" BORDER=0 ALT="References to Objects"></a> -<br> <a href="reftoreg.html" TARGET="CONTENT"><IMG SRC="Graphics/RefRegion.gif" BORDER=0 ALT="References to Dataset Regions"></a> -<br> <a href="extend.html" TARGET="CONTENT"><IMG SRC="Graphics/ChunkExt.gif" BORDER=0 ALT="Chunking and Extendible Datasets"></a> -<br> <a href="mount.html" TARGET="CONTENT"><IMG SRC="Graphics/MountFile.gif" BORDER=0 ALT="Mounting Files"></a> -<br> <a href="iterate.html" TARGET="CONTENT"><IMG SRC="Graphics/Iterate.gif" BORDER=0 ALT="Group Iteration"></a> <hr> <IMG SRC="Graphics/AddInfo.gif" BORDER=0 ALT="Additional Information"> -<br> <a href="util.html" TARGET="CONTENT"><IMG SRC="Graphics/Utilities.gif" BORDER=0 ALT="HDF5 Utilities -- h5ls and h5dump"></a> -<br> <a href="glossary.html" TARGET="CONTENT"><IMG SRC="Graphics/Glossary.gif" BORDER=0 ALT="Glossary"></a> -<br> <a href="references.html" TARGET="CONTENT"><IMG SRC="Graphics/References.gif" BORDER=0 ALT="References"></a> -<br> <a href="examples/" TARGET="CONTENT"><IMG SRC="Graphics/Examples.gif" BORDER=0 ALT="Example Programs"></a> -<hr> -<a href="Contents.html" TARGET="BUTTONS"><IMG SRC="Graphics/TOCShort.gif" BORDER=0 ALT="(Short TOC)"></a> - <hr> -<br> <a href="Copyright.html" TARGET="CONTENT"><IMG SRC="Graphics/Copy.gif" BORDER=0 ALT="Copyright, Etc."></a><br> diff --git a/doc/html/Tutor/ContentsIntro.html b/doc/html/Tutor/ContentsIntro.html index 5b974d1..96bd716 100644 --- a/doc/html/Tutor/ContentsIntro.html +++ b/doc/html/Tutor/ContentsIntro.html @@ -10,6 +10,7 @@ Remove (or comment out) when served from HDF web server. <center> <font size=-1><a href="../index.html" target=_top>Return to HDF5 Doc Set</a></font> </center> +<br> <hr> @@ -19,85 +20,41 @@ Remove (or comment out) when served from HDF web server. <a href="Contents.html" TARGET="BUTTONS"><IMG SRC="Graphics/TOCShort.gif" BORDER=0 ALT="(Short TOC)"></a> -<br> <hr> <a href="title.html" TARGET="CONTENT"><IMG SRC="Graphics/TitlePg.gif" BORDER=0 ALT="Tutorial Title Page"></a> -<br> - <hr> + <IMG SRC="Graphics/IntroTopics.gif" BORDER=0 ALT="Introductory Topics"> -<br> <a href="intro.html" TARGET="CONTENT"><IMG SRC="Graphics/Intro.gif" BORDER=0 ALT="Introduction"></a> -<br> <a href="fileorg.html" TARGET="CONTENT"><img src="Graphics/FileOrg.gif" BORDER=0 ALT="HDF5 File Organization"></a> -<br> <a href="api.html" TARGET="CONTENT"><IMG SRC="Graphics/H5API.gif" BORDER=0 ALT="The HDF5 API"></a> -<br> <a href="crtfile.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateFile.gif" BORDER=0 ALT="Creating an HDF5 File"></a> -<br> <a href="crtdat.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateDset1.gif" BORDER=0 ALT="Creating a Dataset"></a> -<br> <a href="rdwt.html" TARGET="CONTENT"><IMG SRC="Graphics/RdWrDataset.gif" BORDER=0 ALT="Reading from and Writing to a Dataset"></a> -<br> <a href="crtatt.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateAttr.gif" BORDER=0 ALT="Creating an Attribute"></a> -<br> <a href="crtgrp.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateGrp1.gif" BORDER=0 ALT="Creating a Group"></a> -<br> <a href="crtgrpar.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateGrp2.gif" BORDER=0 ALT="Creating Groups Using Absolute and Relative Names"></a> -<br> <a href="crtgrpd.html" TARGET="CONTENT"><IMG SRC="Graphics/CreateDset2.gif" BORDER=0 ALT="Creating Datasets in a Group"></a> <br> -<br> <a href="questions.html" TARGET="CONTENT"><IMG SRC="Graphics/Quiz.gif" BORDER=0 ALT="Quiz Questions"></a> -<br> <a href="answers.html" TARGET="CONTENT"><IMG SRC="Graphics/QuizAns.gif" BORDER=0 ALT="Quiz Answers"></a> +<hr> -<hr> <a href="ContentsAdv.html" TARGET="BUTTONS"><IMG SRC="Graphics/AdvTopics.gif" BORDER=0 ALT="Advanced Topics"></a> -<!-- -<br> -<a href="compound.html" TARGET="CONTENT"><IMG SRC="Graphics/CompDTypes.gif" BORDER=0 ALT="Compound Data Types"></a> -<br> -<a href="select.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectHyp.gif" BORDER=0 ALT="Selections Using H5Sselect_hyperslab"></a> -<br> -<a href="selectc.html" TARGET="CONTENT"><IMG SRC="Graphics/SelectElemCp.gif" BORDER=0 ALT="Selections Using H5Sselect_elements and H5Scopy"></a> -<br> -<a href="reftoobj.html" TARGET="CONTENT"><IMG SRC="Graphics/RefObject.gif" BORDER=0 ALT="References to Objects"></a> -<br> -<a href="reftoreg.html" TARGET="CONTENT"><IMG SRC="Graphics/RefRegion.gif" BORDER=0 ALT="References to Dataset Regions"></a> -<br> -<a href="extend.html" TARGET="CONTENT"><IMG SRC="Graphics/ChunkExt.gif" BORDER=0 ALT="Chunking and Extendible Datasets"></a> -<br> -<a href="mount.html" TARGET="CONTENT"><IMG SRC="Graphics/MountFile.gif" BORDER=0 ALT="Mounting Files"></a> -<br> -<a href="iterate.html" TARGET="CONTENT"><IMG SRC="Graphics/Iterate.gif" BORDER=0 ALT="Group Iteration"></a> ---> +<hr> -<hr> <a href="ContentsAdd.html" TARGET="BUTTONS"><IMG SRC="Graphics/AddInfo.gif" BORDER=0 ALT="Additional Information"></a> -<!-- -<br> -<a href="util.html" TARGET="CONTENT"><IMG SRC="Graphics/Utilities.gif" BORDER=0 ALT="HDF5 Utilities -- h5ls and h5dump"></a> -<br> -<a href="glossary.html" TARGET="CONTENT"><IMG SRC="Graphics/Glossary.gif" BORDER=0 ALT="Glossary"></a> -<br> -<a href="references.html" TARGET="CONTENT"><IMG SRC="Graphics/References.gif" BORDER=0 ALT="References"></a> -<br> -<a href="examples/" TARGET="CONTENT"><IMG SRC="Graphics/Examples.gif" BORDER=0 ALT="Example Programs"></a> ---> +<hr> -<hr> <a href="ContentsFull.html" TARGET="BUTTONS"><IMG SRC="Graphics/TOCFull.gif" BORDER=0 ALT="Full TOC"></a> -<br> +<hr> -<hr> -<br> <a href="Copyright.html" TARGET="CONTENT"><IMG SRC="Graphics/Copy.gif" BORDER=0 ALT="Copyright, Etc."></a><br> diff --git a/doc/html/Tutor/Copyright.html b/doc/html/Tutor/Copyright.html index b22c16c..358ae02 100644 --- a/doc/html/Tutor/Copyright.html +++ b/doc/html/Tutor/Copyright.html @@ -21,7 +21,7 @@ NCSA HDF5 (Hierarchical Data Format 5) Software Library and Utilities</h3> NCSA HDF5 (Hierarchical Data Format 5) Software Library and Utilities <br> -Copyright 1998, 1999 by the Board of Trustees of the University of Illinois +Copyright 1998, 1999, 2000 by the Board of Trustees of the University of Illinois <br> <strong>All rights reserved.</strong> <p> @@ -67,13 +67,51 @@ the possibility of such damage. </ol> + + +<hr> +Portions of HDF5 were developed with support from the University of +California, Lawrence Livermore National Laboratory (UC LLNL). +The following statment applies to those portions of the product +and must be retained in any redistribution of source code, binaries, +documentation, and/or accompanying materials: + +<dir> +This work was partially produced at the University of California, +Lawrence Livermore National Laboratory (UC LLNL) under contract no. +W-7405-ENG-48 (Contract 48) between the U.S. Department of Energy (DOE) +and The Regents of the University of California (University) for the +operation of UC LLNL. +<p> +<b>DISCLAIMER:</b> +This work was prepared as an account of work sponsored by an agency of the +United States Government. Neither the United States Government nor the +University of California nor any of their employees, makes any warranty, +express or implied, or assumes any liability or responsibility for the +accuracy, completeness, or usefulness of any information, apparatus, +product, or process disclosed, or represents that its use would not +infringe privately-owned rights. Reference herein to any specific +commercial products, process, or service by trade name, trademark, +manufacturer, or otherwise, does not necessarily constitute or imply its +endorsement, recommendation, or favoring by the United States Government +or the University of California. The views and opinions of authors +expressed herein do not necessarily state or reflect those of the United +States Government or the University of California, and shall not be used +for advertising or product endorsement purposes. +</dir> + + + + <hr> <address> <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> +</address> +Last modified: 7 June 2000 <br> -Last modified: 13 October 1999 +Describes HDF5 Release 1.2.2, June 2000 </body> </html> diff --git a/doc/html/Tutor/answers.html b/doc/html/Tutor/answers.html index 6bc239b..986b2f5 100644 --- a/doc/html/Tutor/answers.html +++ b/doc/html/Tutor/answers.html @@ -1,5 +1,5 @@ <HTML><HEAD> -<TITLE>HDF5 Tutorial - Introductory Topics Questions with Answers +<TITLE>HDF5 Tutorial - Introductory Topics Quiz with Answers </TITLE> </HEAD> @@ -13,182 +13,290 @@ width=78 height=27 alt="NCSA"><P></A> [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] <H1> -<BIG><BIG><BIG><FONT COLOR="#c101cd">Introductory Topics Questions with -Answers</FONT> +<BIG><BIG><BIG><FONT COLOR="#c101cd">Introductory Topics Quiz + with Answers</FONT> </BIG></BIG></BIG></H1> <hr noshade size=1> -<PRE> -Section 2: HDF File Organization -================================ - -1. Name and describe the two primary objects that can be stored in an HDF5 - file: - -Answer: -Group: A grouping structure containing zero or more HDF5 objects, together - with supporting metadata. - -Dataset: A multidimensional array of data elements, together with - supporting metadata. - -2. What is an attribute? - -Answer: An HDF attribute is a user-defined HDF5 structure that provides extra - information about an HDF5 object. - -3. Give the path name for an object called "harry" that is a member of a - group called "dick," which in turn is a member of the root group. - -Answer: /dick/harry - -Section 3: The HDF5 API -======================= - -Describe the purpose of each of the following HDF5 APIs: - -H5A, H5D, H5E, F5F, H5G, H5T, H5Z - -H5A: Attribute access and manipulation routines. -H5D: Dataset access and manipulation routines. -H5E: Error handling routines. -F5F: File access routines. -H5G: Routines for creating and operating on groups. -H5T: Routines for creating and manipulating the datatypes of dataset elements. -H5Z: Data compression routines. - - -Section 4: Creating an HDF File -=============================== - -1. What two HDF5 routines must be called in order to create an HDF5 file? - -Answer: H5Fcreate and H5Fclose. - -2. What include file must be included in any file that uses the HDF5 library. - -Answer: hdf5.h must be included because it contains definitions and - declarations used by the library. - -3. An HDF5 file is never completely empty because as soon as an HDF5 file - is created, it automatically contains a certain primary object. What is - that object? - -Answer: The root group. - - -Section 5: Creating a Dataset -============================= - -1. Name and describe two major datatype categories. - -Answer: atomic datatype - An atomic datatype cannot be decomposed into - smaller units at the API level. - compound datatype - A compound datatype is a collection of atomic/ - compound datatypes, or small arrays of such types. - -2. List the HDF5 atomic datatypes. Give an example of a predefined datatype. - -Answer: There are six HDF5 atomic datatypes: integer, floating point, - date and time, character string, bit field, opaque. - H5T_IEEE_F32LE - 4-byte little-endian, IEEE floating point, - H5T_NATIVE_INT - native integer - -3. What does the dataspace describe? What are the major characteristics of the - simple dataspace? - -Answer: The dataspace describes the dimensionality of the dataset. It is - characterized by its rank and dimension sizes. +<h3>Section 2: HDF File Organization</h3> +<ol> + +<li>Name and describe the two primary objects that can be stored in an HDF5 + file. + + <dl> + <dt><b>Answers:</b> + <dd><em>Group:</em> A grouping structure containing zero or more + HDF5 objects, together with supporting metadata. + <dd><em>Dataset:</em> A multidimensional array of data elements, + together with supporting metadata. + </dl> + +<p> +<li>What is an attribute? + + <dl> + <dt><b>Answer:</b> + <dd>An HDF5 attribute is a user-defined HDF5 structure that provides extra + information about an HDF5 object. + </dl> + +<p> +<li>Give the path name for an object called <code>harry</code> that is + a member of a group called <code>dick</code>, which, in turn, is a + member of the root group. + + <dl> + <dt><b>Answer:</b> + <dd><code>/dick/harry</code> + </dl> + + +</ol> +<h3>Section 3: The HDF5 API</h3> +<ol> + +<li>Describe the purpose of each of the following HDF5 APIs: + + <dir> + H5A, H5D, H5E, H5F, H5G, H5T, H5Z + </dir> + + <dl> + <dt><b>Answers:</b> + <dir> + H5A: Attribute access and manipulation routines <br> + H5D: Dataset access and manipulation routines <br> + H5E: Error handling routines <br> + H5F: File access routines <br> + H5G: Routines for creating and operating on groups <br> + H5T: Routines for creating and manipulating the + datatypes of dataset elements <br> + H5Z: Data compression routines + </dir> + </dl> + + +</ol> +<h3>Section 4: Creating an HDF5 File</h3> +<ol> + +<li>What two HDF5 routines must be called to create an HDF5 file? + + <dl> + <dt><b>Answer:</b> + <dd><code>H5Fcreate</code> and <code>H5Fclose</code>. + </dl> + +<p> +<li>What include file must be included in any file that uses the HDF5 library? + + <dl> + <dt><b>Answer:</b> + <dd><code>hdf5.h</code> must be included because it contains definitions + and declarations used by the library. + </dl> + +<p> +<li>An HDF5 file is never completely empty because as soon as it is created, + it automatically contains a certain primary object. What is that object? + + <dl> + <dt><b>Answer:</b> + <dd>The root group. + </dl> + + +</ol> +<h3>Section 5: Creating a Dataset</h3> +<ol> + +<li>Name and describe two major datatype categories. + + <dl> + <dt><b>Answers:</b> + <dd><em>Atomic datatype:</em> + An atomic datatype cannot be decomposed into smaller units at the + API level. + <br> + <em>Compound datatype:</em> + A compound datatype is a collection of atomic and compound datatypes, + or small arrays of such types. + </dl> + +<p> +<li>List the HDF5 atomic datatypes. Give an example of a predefined datatype. + + <dl> + <dt><b>Answers:</b> + <dd>There are six HDF5 atomic datatypes: integer, floating point, + date and time, character string, bit field, and opaque. + Examples of predefined datatypes include the following: + <dir> + <code>H5T_IEEE_F32LE</code> + - 4-byte little-endian, IEEE floating point <br> + <code>H5T_NATIVE_INT</code> + - native integer + </dir> + </dl> + +<p> +<li>What does the dataspace describe? What are the major characteristics of + the simple dataspace? + + <dl> + <dt><b>Answers:</b> + <dd>The dataspace describes the dimensionality of the dataset. + A simple dataspace is characterized by its rank and dimension sizes. + </dl> -4. What information needs to be passed to the H5Dcreate function, i.e. +<p> +<li>What information needs to be passed to the H5Dcreate function, i.e., what information is needed to describe a dataset at creation time? -Answer: dataset location, name, dataspace, datatype, and creation properties. + <dl> + <dt><b>Answer:</b> + <dd>The dataset location, name, dataspace, datatype, and dataset + creation property list. + </dl> -Section 6: Reading from/Writing to a Dataset -============================================ +</ol> +<h3>Section 6: Reading from and Writing to a Dataset</h3> +<ol> -1. What are six pieces of information which need to be specified for +<li>What are six pieces of information which need to be specified for reading and writing a dataset? -Answer: A dataset, a dataset's datatype and dataspace in memory, the - dataspace in the file, the transfer properties and data buffer. - -2. Why are both the memory dataspace and file dataspace needed for - read/write operations, but only the memory datatype is specified for the - datatype? - -Answer: A dataset's file datatype is specified at creation time and cannot be - changed. Both file and memory dataspaces are needed for performing - subsetting and partial I/O operations. - -3. What does the line DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } in Fig 6.1 - means? - -Answer: It means that the dataset "dset" has a simple dataspace with the - current dimensions (4,6) and the maximum size of the dimensions (4,6). - - -Section 7: Creating an Attribute -================================ - -1. What is an attribute? - -Answer: An attribute is a dataset attached to an object. It describes the - nature and/or the intended usage of the object. - -2. Can partial I/O operations be performed on attributes? - -Answer: No - - -Section 8: Creating a Group -=========================== - -What are the two primary objects that can be included in -a group? - -Answer: A group and a dataset - - -Section 9: Creating Groups using Absolute/Relative Names -======================================================== - -1. Group names can be specified in two "ways". What are these - two types of group names that you can specify? - -Answer: relative and absolute - -2. You have a dataset named "moo" in the group "boo", which is - in the group "foo", which in turn, is in the root group. How would - you specify an absolute name to access this dataset? - -Answer: /foo/boo/moo - -Section 10: Creating Datasets in Groups -======================================= - -Describe a way to access the dataset "moo" described in the previous section -(Section 9, question 2), using a relative and absolute pathname. - -Answers: 1. Access the group, "/foo", and get the group ID. - Access the group "boo" using the group ID obtained in Step 1. - Access the dataset "moo" using the group ID in Step 2. - gid = H5Gopen (file_id, "/foo", 0); /* absolute path */ - gid1 = H5Gopen (gid, "boo", 0); /* relative path */ - did = H5Dopen (gid1, "moo"); /* relative path */ + <dl> + <dt><b>Answer:</b> + <dd>The dataset identifier, the dataset's datatype and dataspace in + memory, the dataspace in the file, the dataset transfer property + list, and a data buffer. + </dl> + +<p> +<li>Why are both the memory dataspace and file dataspace needed for + read/write operations, while only the memory datatype is required? + + <dl> + <dt><b>Answer:</b> + <dd>A dataset's file datatype is not required for a read/write operation + because the file datatype is specified when the dataset is created + and cannot be changed. Both file and memory dataspaces are required + for dataset subsetting and for performing partial I/O operations. + </dl> + +<p> +<li>What does the line + <br> + <code>DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } </code> + <br>in Figure 6.1 mean? + + <dl> + <dt><b>Answer:</b> + <dd>It means that the dataset <code>dset</code> has a simple dataspace + with the current dimensions (4,6) and the maximum size of the + dimensions (4,6). + </dl> + + +</ol> +<h3>Section 7: Creating an Attribute</h3> +<ol> + +<li>What is an attribute? + + <dl> + <dt><b>Answer:</b> + <dd>An attribute is a dataset attached to an object. It describes the + nature and/or the intended usage of the object. + </dl> + +<p> +<li>Can partial I/O operations be performed on attributes? + + <dl> + <dt><b>Answer:</b> + <dd>No. + </dl> + + +</ol> +<h3>Section 8: Creating a Group</h3> +<ol> + +<li>What are the two primary objects that can be included in a group? + + <dl> + <dt><b>Answer:</b> + <dd>A group and a dataset. + </dl> + + +</ol> +<h3>Section 9: Creating Groups Using Absolute and Relative Names</h3> +<ol> + +<li>Group names can be specified in two ways. What are these two types + of group names? + + <dl> + <dt><b>Answer:</b> + <dd>Relative and absolute. + </dl> + +<p> +<li>You have a dataset named <code>moo</code> in the group + <code>boo</code>, which is in the group <code>foo</code>, + which, in turn, is in the root group. + How would you specify an absolute name to access this dataset? + + <dl> + <dt><b>Answer:</b> + <dd><code>/foo/boo/moo</code> + </dl> + + +</ol> +<h3>Section 10: Creating Datasets in Groups</h3> +<ol> + +<li>Describe a way to access the dataset <code>moo</code> described in + the previous section (Section 9, question 2) using a + relative name. + Describe a way to access the same dataset using an absolute name. + + <dl> + <dt><b>Answers:</b> + <ol> + <li>Access the group <code>/foo</code> and get the group ID. + Access the group <code>boo</code> using the group ID obtained + in Step 1. + Access the dataset <code>moo</code> using the group ID obtained + in Step 2. + <pre> +gid = H5Gopen (file_id, "/foo", 0); /* absolute path */ +gid1 = H5Gopen (gid, "boo", 0); /* relative path */ +did = H5Dopen (gid1, "moo"); /* relative path */ </pre> - 2. Access the group, "/foo", and get the group ID. - Access the dataset "boo/moo", with the group ID just obtained. - gid = H5Gopen (file_id, "/foo", 0); /* absolute path */ - did = H5Dopen (gid, "boo/moo"); /* relative path */ + <li>Access the group <code>/foo</code> and get the group ID. + Access the dataset <code>boo/moo</code> with the group ID + just obtained. + <pre> +gid = H5Gopen (file_id, "/foo", 0); /* absolute path */ +did = H5Dopen (gid, "boo/moo"); /* relative path */ </pre> - 3. Access the dataset with an absolute path. - did = H5Dopen (file_id, "/foo/boo/moo"); /* absolute path */ -</PRE> + <li>Access the dataset with an absolute path. + <pre> +did = H5Dopen (file_id, "/foo/boo/moo"); /* absolute path */ </pre> + </ol> + </dl> + +</ol> + <!-- BEGIN FOOTER INFO --> <P><hr noshade size=1> @@ -203,7 +311,9 @@ Answers: 1. Access the group, "/foo", and get the group ID. <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 2, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: January 13, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> diff --git a/doc/html/Tutor/api.html b/doc/html/Tutor/api.html index 3ed0a84..ba186a7 100644 --- a/doc/html/Tutor/api.html +++ b/doc/html/Tutor/api.html @@ -21,11 +21,21 @@ width=78 height=27 alt="NCSA"><P></A> <BODY> <P> -The HDF5 library provides several interfaces, and is currently implemented in -C. The APIs provide routines for accessing HDF5 files and creating and -manipulating HDF5 objects. All C routines in the HDF5 library begin with -a prefix of the form H5*, where * is a single letter indicating the object on -which the operation is to be performed. The APIs are listed below: +The HDF5 library provides several interfaces, or APIs. +These APIs provide routines for creating, accessing, and manipulating +HDF5 files and objects. +<P> +The library itself is implemented in C. To facilitate the work of +FORTRAN90 and Java programmers, HDF5 function wrappers have been developed +in each of these languages. +At the time of this writing, a set of C++ wrappers is in development. +This tutorial discusses the use of the C functions and the FORTRAN wrappers. +<P> +All C routines in the HDF5 library begin with a prefix of the form <I>H5</I>*, +where * is one or two uppercase letters indicating the type of object on which the +function operates. +The FORTRAN wrappers come in the form of subroutines that begin with +<I>h5</I> and end with <I>_f</I>. The APIs are listed below: <P> <table width="65%" border="2" cellpadding="4"> <tr bgcolor="#FFCC99" bordercolor="#FFFFFF"> @@ -40,76 +50,78 @@ which the operation is to be performed. The APIs are listed below: <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5</b></div> </td> - <td width="89%">Library Functions: the general-purpose H5 functions.</td> + <td width="89%">Library Functions: general-purpose H5 functions</td> </tr> <tr bordercolor="#FFFFFF"> <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5A</b></div> </td> - <td width="89%">Annotation Interface: attribute access and manipulating routines.</td> + <td width="89%">Annotation Interface: attribute access and manipulation + routines</td> </tr> <tr bordercolor="#FFFFFF"> <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5D</b></div> </td> - <td width="89%">Dataset Interface: dataset access and manipulating routines. - </td> + <td width="89%">Dataset Interface: dataset access and manipulation + routines</td> </tr> <tr bordercolor="#FFFFFF"> <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5E</b></div> </td> - <td width="89%">Error Interface: error handling routines.</td> + <td width="89%">Error Interface: error handling routines</td> </tr> <tr bordercolor="#FFFFFF"> <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5F</b></div> </td> - <td width="89%">File Interface: file access routines.</td> + <td width="89%">File Interface: file access routines</td> </tr> <tr bordercolor="#FFFFFF"> <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5G</b></div> </td> - <td width="89%">Group Interface: group creating and operating routines.</td> + <td width="89%">Group Interface: group creation and operation routines</td> </tr> <tr bordercolor="#FFFFFF"> <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5I</b></div> </td> - <td width="89%">Identifier Interface: identifier routines.</td> + <td width="89%">Identifier Interface: identifier routines</td> </tr> <tr bordercolor="#FFFFFF"> <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5P</b></div> </td> - <td width="89%">Property List Interface: object property list manipulating - routines.</td> + <td width="89%">Property List Interface: object property list manipulation + routines</td> </tr> <tr bordercolor="#FFFFFF"> <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5R</b></div> </td> - <td width="89%">Reference Interface: reference routines.</td> + <td width="89%">Reference Interface: reference routines</td> </tr> <tr bordercolor="#FFFFFF"> <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5S</b></div> </td> - <td width="89%">Dataspace Interface: routines for defining dataspaces.</td> + <td width="89%">Dataspace Interface: dataspace definition and access + routines</td> </tr> <tr bordercolor="#FFFFFF"> <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5T</b></div> </td> - <td width="89%">Data type Interface: routines for creating and manipulating - the data type of dataset elements.</td> + <td width="89%">Datatype Interface: datatype creation and manipulation + routines</td> </tr> <tr bordercolor="#FFFFFF"> <td width="11%" bgcolor="#99CCCC"> <div align="center"><b>H5Z</b></div> </td> - <td width="89%">Compression Interface: compression routine(s).</td> + <td width="89%">Compression Interface: compression routine(s)</td> </tr> </table> @@ -127,8 +139,11 @@ which the operation is to be performed. The APIs are listed below: <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: July 30, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: December 10, 1999</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/compound.html b/doc/html/Tutor/compound.html index 7983bf4..d68d5a3 100644 --- a/doc/html/Tutor/compound.html +++ b/doc/html/Tutor/compound.html @@ -1,5 +1,5 @@ <HTML><HEAD> -<TITLE>HDF5 Tutorial - Compound Data Types +<TITLE>HDF5 Tutorial - Compound Datatypes </TITLE> </HEAD> @@ -13,7 +13,7 @@ width=78 height=27 alt="NCSA"><P></A> [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] <H1> -<BIG><BIG><BIG><FONT COLOR="#c101cd">Compound Data Types</FONT> +<BIG><BIG><BIG><FONT COLOR="#c101cd">Compound Datatypes</FONT> </BIG></BIG></BIG></H1> <hr noshade size=1> @@ -21,7 +21,7 @@ width=78 height=27 alt="NCSA"><P></A> <BODY> <H2>Contents:</H2> <UL> - <LI><A HREF="#def">Creating Compound Data Types</A> + <LI><A HREF="#def">Creating Compound Datatypes</A> <LI>Programming Example <UL> <LI> <A HREF="#desc">Description</A> @@ -29,43 +29,48 @@ width=78 height=27 alt="NCSA"><P></A> <LI> <A HREF="#fc">File Contents</A> </UL> </UL> +<em><b>Note:</b> The FORTRAN API does not yet support compound datatypes.</em> <HR> <A NAME="def"> -<H2>Creating Compound Data Types</H2> -A compound data type is similar to a struct in C or a common block in -Fortran. It is a collection of one or more atomic types or small arrays of -such types. To create and use a compound data type you need to refer to -various properties of the data compound data type: +<H2>Creating Compound Datatypes</H2> +A compound datatype is similar to a struct in C or a common block in +FORTRAN. It is a collection of one or more atomic types or small arrays of +such types. To create and use a compound datatype you need to be familiar +with various properties of the compound datatype: <UL> - <LI>It is of class compound. + <LI>It is of class <strong>compound</strong>. <LI>It has a fixed total size, in bytes. <LI>It consists of zero or more members (defined in any order) with - unique names and which occupy non-overlapping regions within the datum. - <LI>Each member has its own data type. - <LI>Each member is referenced by an index number between zero and N-1, - where N is the number of members in the compound data type. + unique names and occupying non-overlapping regions within the datum. + <LI>Each member has its own datatype. + <LI>Each member is referenced by an index number between zero and <em>N</em>-1, + where <em>N</em> is the number of members in the compound datatype. <LI>Each member has a name which is unique among its siblings in a - compound data type. - <LI>Each member has a fixed byte offset, which is the first byte - (smallest byte address) of that member in a compound data type. + compound datatype. + <LI>Each member has a fixed byte offset, which locates the first byte + (smallest byte address) of that member in the compound datatype. <LI>Each member can be a small array of up to four dimensions. </UL> -Properties of members of a compound data type are defined when the -member is added to the compound type and cannot be subsequently modified. +Properties of members of a compound datatype are defined when the +member is added to the compound datatype and cannot be subsequently modified. <P> -Compound data types must be built out of other data types. First, one -creates an empty compound data type and specifies its total size. Then -members are added to the compound data type in any order. +Compound datatypes must be built out of other datatypes. First, one +creates an empty compound datatype and specifies its total size. Then +members are added to the compound datatype in any order. <H2> Programming Example</H2> <A NAME="desc"> <H3><U>Description</U></H3> -This example shows how to create a compound data type, write an array -to the file which uses the compound data type, and read back subsets of -the members.<BR> - -[<A HREF="examples/h5_compound.c">Download h5_compound.c</A>] +This example shows how to create a compound datatype, write an array +to the file which uses the compound datatype, and read back subsets of +the members. +<p> +<UL> +[ <A HREF="examples/h5_compound.c">C Example</A> ] - <code>h5_compound.c</code> +<BR> +[ <A HREF="examples/java/Compound.java">Java Example</A> ] - <code>Compound.java</code> +</UL> <PRE> +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ #include "hdf5.h" @@ -126,7 +131,7 @@ main(void) file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); /* - * Create the memory data type. + * Create the memory datatype. */ s1_tid = H5Tcreate (H5T_COMPOUND, sizeof(s1_t)); H5Tinsert(s1_tid, "a_name", HOFFSET(s1_t, a), H5T_NATIVE_INT); @@ -159,7 +164,7 @@ main(void) dataset = H5Dopen(file, DATASETNAME); /* - * Create a data type for s2 + * Create a datatype for s2 */ s2_tid = H5Tcreate(H5T_COMPOUND, sizeof(s2_t)); @@ -186,7 +191,7 @@ main(void) printf("\n"); /* - * Create a data type for s3. + * Create a datatype for s3. */ s3_tid = H5Tcreate(H5T_COMPOUND, sizeof(float)); @@ -235,33 +240,34 @@ Field b : <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI>H5Tcreate creates a new data type of the specified class with +<LI><CODE>H5Tcreate</CODE> creates a new datatype of the specified class with the specified number of bytes. <PRE> hid_t H5Tcreate ( H5T_class_t class, size_t size ) </PRE> <UL> -<LI>The <I>class</I> parameter specifies the data type to create. -Currently only the H5T_COMPOUND data type class is supported with this +<LI>The <I>class</I> parameter specifies the datatype to create. +Currently only the <CODE>H5T_COMPOUND</CODE> datatype class is supported with this function. <LI>The <I>size</I> parameter specifies the number of bytes in the -data type to create. +datatype to create. </UL> <P> -<LI>H5Tinsert adds a member to the compound data type specified by +<LI><CODE>H5Tinsert</CODE> adds a member to the compound datatype specified by <I>type_id</I>. <PRE> - herr_t H5Tinsert ( hid_t type_id, const char * name, off_t offset, hid_t field_id ) + herr_t H5Tinsert ( hid_t type_id, const char * name, off_t offset, + hid_t field_id ) </PRE> <UL> -<LI>The <I>type_id</I> parameter is the identifier of the compound data type +<LI>The <I>type_id</I> parameter is the identifier of the compound datatype to modify. <LI>The <I>name</I> parameter is the name of the field to insert. The new -member name must be unique within a compound data type. +member name must be unique within a compound datatype. <LI>The <I>offset</I> parameter is the offset in the memory structure of the field to insert. -The library defines the HOFFSET macro to compute the offset of a member within +The library defines the <CODE>HOFFSET</CODE> macro to compute the offset of a member within a struct: <PRE> HOFFSET ( s, m ) @@ -269,15 +275,15 @@ a struct: This macro computes the offset of member <I>m</I> within a struct variable <I>s</I>. -<LI>The <I>field_id</I> parameter is the data type identifier of the +<LI>The <I>field_id</I> parameter is the datatype identifier of the field to insert. </UL> <P> -<LI>H5Tclose releases a data type. +<LI><CODE>H5Tclose</CODE> releases a datatype. <PRE> herr_t H5Tclose ( hid_t type_id ) </PRE> -The <I>type_id</I> parameter is the identifier of the data type to release. +The <I>type_id</I> parameter is the identifier of the datatype to release. </UL> <A NAME="fc"> <H3><U>File Contents</U></H3> @@ -365,8 +371,11 @@ GROUP "/" { <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/crtatt.html b/doc/html/Tutor/crtatt.html index 82de873..bc9498a 100644 --- a/doc/html/Tutor/crtatt.html +++ b/doc/html/Tutor/crtatt.html @@ -36,160 +36,212 @@ width=78 height=27 alt="NCSA"><P></A> <P> Attributes are small datasets that can be used to describe the nature and/or the intended usage of the object they are attached to. In this section, we -show how to create and read/write an attribute. +show how to create, read, and write an attribute. <P> <P> <H3>Creating an attribute</H3> <P> - Creating an attribute is similar to the creation of a dataset. To create an - attribute the application must specify the object which the attribute is - attached to, the data type and space of the attribute data and the creation - properties. + Creating an attribute is similar to creating a dataset. To create an + attribute, the application must specify the object which the attribute is + attached to, the datatype and dataspace of the attribute data, + and the attribute creation property list. <P> The steps to create an attribute are as follows: <OL> <LI> Obtain the object identifier that the attribute is to be attached to. - <LI> Define the characteristics of the attribute and specify creation - properties. + <LI> Define the characteristics of the attribute and specify the + attribute creation property list. <UL> - <LI> Define the data type. + <LI> Define the datatype. <LI> Define the dataspace. - <LI> Specify the creation properties. + <LI> Specify the attribute creation property list. </UL> <LI> Create the attribute. - <LI> Close the attribute and data type, dataspace, and creation property - list if necessary. + <LI> Close the attribute and datatype, dataspace, and + attribute creation property list, if necessary. </OL> <P> - To create an attribute, the calling program must contain the following calls: + To create and close an attribute, the calling program must use +<code>H5Acreate</code>/<code>h5acreate_f</code> and +<code>H5Aclose</code>/<code>h5aclose_f</code>. For example: +<P> +<I>C</I>: <PRE> - attr_id = H5Acreate(loc_id, attr_name, type_id, space_id, create_plist); - H5Aclose(attr_id); + attr_id = H5Acreate (dset_id, attr_name, type_id, space_id, creation_prp); + status = H5Aclose (attr_id); </PRE> +<I>FORTRAN</I>: +<PRE> + CALL h5acreate_f (dset_id, attr_nam, type_id, space_id, attr_id, & + hdferr, creation_prp=creat_plist_id) + <i>or</i> + CALL h5acreate_f (dset_id, attr_nam, type_id, space_id, attr_id, hdferr) + + CALL h5aclose_f (attr_id, hdferr) +</PRE> <H3>Reading/Writing an attribute</H3> <P> - Attributes may only be read/written as an entire object. No partial I/O is - currently supported. Therefore, to perform I/O operations on an attribute, the + Attributes may only be read or written as an entire object; no partial I/O is + supported. Therefore, to perform I/O operations on an attribute, the application needs only to specify the attribute and the attribute's memory - data type. + datatype. <P> - The steps to read/write an attribute are as follows. + The steps to read or write an attribute are as follows. <OL> <LI> Obtain the attribute identifier. - <LI> Specify the attribute's memory data type. + <LI> Specify the attribute's memory datatype. <LI> Perform the desired operation. - <LI> Close the memory data type if necessary. + <LI> Close the memory datatype if necessary. </OL> <P> -To read/write an attribute, the calling program must contain the following - calls: +To read and/or write an attribute, the calling program must contain the +<code>H5Aread</code>/<code>h5aread_f</code> and/or +<code>H5Awrite</code>/<code>h5awrite_f</code> routines. For example: +<P> +<I>C</I>: <PRE> - status = H5Aread(attr_id, mem_type_id, buf); + status = H5Aread (attr_id, mem_type_id, buf); + status = H5Awrite (attr_id, mem_type_id, buf); </PRE> - or +<I>FORTRAN</I>: <PRE> - status = H5Awrite(attr_id, mem_type_id, buf); + CALL h5awrite_f (attr_id, mem_type_id, buf, hdferr) + CALL h5aread_f (attr_id, mem_type_id, buf, hdferr) </PRE> <P> <H2> Programming Example</H2> <A NAME="desc"> <H3><U>Description</U></H3> This example shows how to create and write a dataset attribute. -It opens an existing file 'dset.h5', obtains the id of the dataset "/dset1", +It opens an existing file <code>dset.h5</code> in C +(<code>dsetf.h5</code> in FORTRAN), +obtains the identifier of the dataset <code>/dset</code>, defines the attribute's dataspace, creates the dataset attribute, writes the attribute, and then closes the attribute's dataspace, attribute, dataset, and file. <BR> -[ <A HREF="examples/h5_crtatt.c">Download h5_crtatt.c</A> ] -<PRE> -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <hdf5.h> -#define FILE "dset.h5" - -main() { - - hid_t file_id, dataset_id, attribute_id, dataspace_id; /* identifiers -*/ - hsize_t dims; - int attr_data[2]; - herr_t status; - - /* Initialize the attribute data. */ - attr_data[0] = 100; - attr_data[1] = 200; - - /* Open an existing file. */ - file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT); - - /* Open an existing dataset. */ - dataset_id = H5Dopen(file_id, "/dset"); - - /* Create the data space for the attribute. */ - dims = 2; - dataspace_id = H5Screate_simple(1, &dims, NULL); - - /* Create a dataset attribute. */ - attribute_id = H5Acreate(dataset_id, "attr", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT); - - /* Write the attribute data. */ - status = H5Awrite(attribute_id, H5T_NATIVE_INT, attr_data); - - /* Close the attribute. */ - status = H5Aclose(attribute_id); +<UL> +[ <A HREF="examples/h5_crtatt.c">C Example </A> ] - <code>h5_crtatt.c</code><BR> +[ <A HREF="examples/attrexample.f90">FORTRAN Example</A> ] - <code>attrexample.f90</code><BR> +[ <A HREF="examples/java/CreateAttribute.java">Java Example </A> ] +- <code>CreateAttribute.java</code><BR> +</UL> - /* Close the dataspace. */ - status = H5Sclose(dataspace_id); +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. - /* Close to the dataset. */ - status = H5Dclose(dataset_id); - - /* Close the file. */ - status = H5Fclose(file_id); -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -</PRE> <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI> H5Acreate creates an attribute which is attached to the object specified by - the first parameter, and returns an identifier. +<LI><code>H5Acreate</code>/<code>h5acreate_f</code> creates an attribute + which is attached to the object specified by the first parameter, + and returns an identifier. +<P> +<I>C</I>: <PRE> - hid_t H5Acreate (hid_t loc_id, const char *name, hid_t type_id, - hid_t space_id, hid_t create_plist) + hid_t H5Acreate (hid_t obj_id, const char *name, hid_t type_id, + hid_t space_id, hid_t creation_prp) </PRE> -<UL> - <LI> The first parameter is the identifier of the object which the attribute is - attached to. - - <LI> The second parameter is the name of the attribute to create. - - <LI> The third parameter is the identifier of the attribute's datatype. - - <LI> The fourth parameter is the identifier of the attribute's dataspace. +<I>FORTRAN</I>: +<PRE> + h5acreate_f (obj_id, name, type_id, space_id, attr_id, & + hdferr, creation_prp) + + obj_id INTEGER(HID_T) + name CHARACTER(LEN=*) + type_id INTEGER(HID_T) + space_id INTEGER(HID_T) + attr_id INTEGER(HID_T) + hdferr INTEGER + (Possible values: 0 on success and -1 on failure) + creation_prp INTEGER(HID_T), OPTIONAL - <LI> The last parameter is the identifier of the creation property list. - H5P_DEFAULT specifies the default creation property list. +</PRE> +<UL> + <LI> The <I>obj_id</I> parameter is the identifier of the object that + the attribute is attached to. + <P> + <LI> The <I>name</I> parameter is the name of the attribute to create. +<P> + <LI> The <I>type_id</I> parameter is the identifier of the + attribute's datatype. +<P> + <LI> The <I>space_id</I> parameter is the identifier of the attribute's + dataspace. +<P> + <LI> The <I>creation_prp</I> parameter is the creation property list + identifier. + <code>H5P_DEFAULT</code> in C (<code>H5P_DEFAULT_F</code> in FORTRAN) + specifies the default creation property list. + This parameter is optional in FORTRAN; when it is omitted, + the default creation property list is used. +<P> + <LI> In FORTRAN, the return code for this call is returned in <I>hdferr</I>: + 0 if successful, -1 if not. The attribute identifier is returned + in <I>attr_id</I>. In C, the function returns the + attribute identifier if successful and a negative value if not. + + </UL> <P> -<LI> H5Awrite writes the entire attribute, and returns the status of the write. +<LI><code>H5Awrite</code>/<code>h5awrite_f</code> writes the entire attribute, + and returns the status of the write. +<P> +<I>C</I>: <PRE> herr_t H5Awrite (hid_t attr_id, hid_t mem_type_id, void *buf) </PRE> -<UL> - <LI> The first parameter is the identifier of the attribute to write. +<I>FORTRAN</I>: +<PRE> + h5awrite_f (attr_id, mem_type_id, buf, hdferr) - <LI> The second parameter is the identifier of the attribute's memory datatype. + attr_id INTEGER(HID_T) + memtype_id INTEGER(HID_T) + buf TYPE(VOID) + hdferr INTEGER + (Possible values: 0 on success and -1 on failure) - <LI> The last parameter is the data buffer. +</PRE> +<UL> + <LI> The <I>attr_id</I> parameter is the identifier of the attribute + to write. +<P> + <LI> The <I>mem_type_id</I> parameter is the identifier of the + attribute's memory datatype. +<P> + <LI> The <I>buf</I> parameter is the data buffer to write out. +<P> + <LI>In C, this function returns a non-negative value if successful and + a negative value, otherwise. In FORTRAN, the return value is in the + <I>hdferr</I> parameter: 0 if successful, -1 otherwise. </UL> <P> -<LI> When an attribute is no longer accessed by a program, H5Aclose must be called - to release the attribute from use. This call is mandatory. -<PRE> +<LI> When an attribute is no longer accessed by a program, + <code>H5Aclose</code>/<code>h5aclose_f</code> must be called + to release the attribute from use. + The C routine returns a non-negative value if successful; + otherwise it returns a negative value. + In FORTRAN, the return value is in the <I>hdferr</I> parameter: + 0 if successful, -1 otherwise. +<P> +<I>C</I>: +<pre> herr_t H5Aclose (hid_t attr_id) -</PRE> +</pre> + +<I>FORTRAN</I>: +<pre> + h5aclose_f (attr_id, hdferr) + + attr_id INTEGER(HID_T) + hdferr INTEGER + (Possible values: 0 on success and -1 on failure) + +</pre> + <ul> + <li> An <code>H5Aclose</code>/<code>h5aclose_f</code> call is mandatory. + </ul> </UL> @@ -197,37 +249,63 @@ main() { <A NAME="fc"> <H3><U>File Contents</U></H3> <P> -The contents of 'dset.h5' and the attribute definition are given in the -following: +The contents of <code>dset.h5</code> (<code>dsetf.h5</code> for FORTRAN) and the +attribute definition are shown below: <P> -<B>Fig. 7.1</B> <I>'dset.h5' in DDL</I> +<B>Fig. 7.1a</B> <I><code>dset.h5</code> in DDL</I> <PRE> - - HDF5 "dset.h5" { - GROUP "/" { - DATASET "dset" { - DATATYPE { H5T_STD_I32BE } - DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) } - DATA { - 1, 2, 3, 4, 5, 6, - 7, 8, 9, 10, 11, 12, - 13, 14, 15, 16, 17, 18, - 19, 20, 21, 22, 23, 24 - } - ATTRIBUTE "attr" { - DATATYPE { H5T_STD_I32BE } - DATASPACE { SIMPLE ( 2 ) / ( 2 ) } - DATA { - 100, 200 - } - } +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) } + DATA { + 1, 2, 3, 4, 5, 6, + 7, 8, 9, 10, 11, 12, + 13, 14, 15, 16, 17, 18, + 19, 20, 21, 22, 23, 24 + } + ATTRIBUTE "attr" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 2 ) / ( 2 ) } + DATA { + 100, 200 } } + } +} +} +</PRE> +<B>Fig. 7.1b</B> <I><code>dsetf.h5</code> in DDL</I> +<PRE> +HDF5 "dsetf.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 6, 4 ) / ( 6, 4 ) } + DATA { + 1, 7, 13, 19, + 2, 8, 14, 20, + 3, 9, 15, 21, + 4, 10, 16, 22, + 5, 11, 17, 23, + 6, 12, 18, 24 + } + ATTRIBUTE "attr" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 2 ) / ( 2 ) } + DATA { + 100, 200 + } } + } +} +} </PRE> + <A NAME="ddl"> <h3><U>Attribute Definition in DDL</U></H3> <B>Fig. 7.2</B> <I>HDF5 Attribute Definition</I> @@ -254,7 +332,9 @@ following: <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> diff --git a/doc/html/Tutor/crtdat.html b/doc/html/Tutor/crtdat.html index cb07ccd..867a089 100644 --- a/doc/html/Tutor/crtdat.html +++ b/doc/html/Tutor/crtdat.html @@ -36,68 +36,132 @@ width=78 height=27 alt="NCSA"><P></A> <P> A dataset is a multidimensional array of data elements, together with supporting metadata. To create a dataset, the application program must specify -the location to create the dataset, the dataset name, the data type and space -of the data array, and the dataset creation properties. +the location at which to create the dataset, the dataset name, the datatype +and dataspace of the data array, and the dataset creation property list. <P> - <H3> Data Types</H3> - A data type is a collection of data type properties, all of which can + <H3> Datatypes</H3> + A datatype is a collection of datatype properties, all of which can be stored on disk, and which when taken as a whole, provide complete - information for data conversion to or from that data type. + information for data conversion to or from that datatype. <P> - There are two categories of data types in HDF5: atomic and compound data - types. An atomic type is a type which cannot be decomposed into smaller - units at the API level. A compound data type is a collection of one or more - atomic types or small arrays of such types. + There are two categories of datatypes in HDF5: atomic and compound + datatypes. An <i>atomic datatype</i> is a datatype which cannot be + decomposed into smaller datatype units at the API level. + These include the integer, float, date and time, string, bitfield, and + opaque datatypes. + A <i>compound datatype</i> is a collection of one or more + atomic datatypes and/or small arrays of such datatypes. <P> - Atomic types include integer, float, date and time, string, bit field, and - opaque. Figure 5.1 shows the HDF5 data types. Some of the HDF5 predefined - atomic data types are listed in Figure 5.2. In this tutorial, we consider - only - HDF5 predefined integers. For information on data types, see the HDF5 - User's Guide. + Figure 5.1 shows the HDF5 datatypes. Some of the HDF5 predefined + atomic datatypes are listed in Figures 5.2a and 5.2b. + In this tutorial, we consider only HDF5 predefined integers. + For further information on datatypes, see + <a href="../Datatypes.html">The Datatype Interface (H5T)</a> in the + <cite>HDF5 User's Guide</cite>. <P> - <B>Fig 5.1</B> <I>HDF5 data types</I> + <B>Fig 5.1</B> <I>HDF5 datatypes</I> <PRE> +-- integer +-- floating point +---- atomic ----+-- date and time | +-- character string - HDF5 datatypes --| +-- bit field + HDF5 datatypes --| +-- bitfield | +-- opaque | +---- compound </PRE> - <B>Fig. 5.2</B> <I>Examples of HDF5 predefined data types</I> -<table width="52%" border="1" cellpadding="4"> + +<table width="100%" border="0" cellpadding="4"> +<tr><td valign=top> + + <B>Fig. 5.2a</B> <I>Examples of HDF5 predefined datatypes</I> + +<table width="95%" border="1" cellpadding="0"> <tr bgcolor="#ffcc99" bordercolor="#FFFFFF"> - <td width="20%"><b>Data Type</b></td> + <td width="20%"><b>Datatype</b></td> <td width="80%"><b>Description</b></td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc" width="20%">H5T_STD_I32LE</td> - <td width="80%">Four-byte, little-endian, signed two's complement integer</td> + <td bgcolor="#99cccc" width="20%"><code>H5T_STD_I32LE</code></td> + <td width="80%">Four-byte, little-endian, signed, two's complement integer</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc" width="20%">H5T_STD_U16BE</td> + <td bgcolor="#99cccc" width="20%"><code>H5T_STD_U16BE</code></td> <td width="80%">Two-byte, big-endian, unsigned integer</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc" width="20%">H5T_IEEE_F32BE</td> + <td bgcolor="#99cccc" width="20%"><code>H5T_IEEE_F32BE</code></td> <td width="80%">Four-byte, big-endian, IEEE floating point</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc" width="20%">H5T_IEEE_F64LE</td> + <td bgcolor="#99cccc" width="20%"><code>H5T_IEEE_F64LE</code></td> <td width="80%">Eight-byte, little-endian, IEEE floating point</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc" width="20%">H5T_C_S1</td> + <td bgcolor="#99cccc" width="20%"><code>H5T_C_S1</code></td> <td width="80%">One-byte, null-terminated string of eight-bit characters</td> </tr> </table> - <H3>Dataspaces</H3> +</td><td valign=top> + + <B>Fig. 5.2b</B> <I>Examples of HDF5 predefined native datatypes</I> +<table width="95%" border="1" cellpadding="4"> + <tr bgcolor="#ffcc99" bordercolor="#FFFFFF"> + <td width="20%"><b>Native Datatype</b></td> + <td width="80%"><b>Corresponding C or FORTRAN Type</b></td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><B>C:</B></td> + <td width="80%"> </td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_INT</code></td> + <td width="80%">int</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_FLOAT</code></td> + <td width="80%">float</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_CHAR</code></td> + <td width="80%">char</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_DOUBLE</code></td> + <td width="80%">double</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_LDOUBLE</code></td> + <td width="80%">long double</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><B>FORTRAN:</B></td> + <td width="80%"> </td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_INT</code></td> + <td width="80%">integer</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_REAL</code></td> + <td width="80%">real</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_DOUBLE</code></td> + <td width="80%">double precision</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_CHAR</code></td> + <td width="80%">character</td> + </tr> +</table> + +</table> + + <H3> Datasets and Dataspaces</H3> A dataspace describes the dimensionality of the data array. A dataspace is either a regular N-dimensional array of data points, called a simple @@ -114,27 +178,29 @@ of the data array, and the dataset creation properties. </PRE> The dimensions of a dataset can be fixed (unchanging), or they may be - unlimited, which means that they are extendible. A dataspace can also - describe portions of a dataset, making it possible to do partial I/O + unlimited, which means that they are extensible. A dataspace can also + describe a portion of a dataset, making it possible to do partial I/O operations on selections. - <h3>Dataset creation properties</H3> + <h3>Dataset Creation Property Lists</H3> - When creating a dataset, HDF5 allows users to specify how raw data is - organized on disk and how the raw data is compressed. This information is + 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 and - stored externally, etc. In this tutorial, we use the default creation - property list; that is, no compression and - contiguous storage layout is used. For more information about the creation - properties, see the HDF5 User's Guide. + 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; that is, contiguous storage layout + and no compression are used. For more information about + dataset creation property lists, + see <a href="../Datasets.html">The Dataset Interface (H5D)</a> + in the <cite>HDF5 User's Guide</cite>. <P> -In HDF5, data types and spaces are independent objects, which are created -separately from any dataset that they might be attached to. Because of this the -creation of a dataset requires definitions of data type and dataspace. -In this tutorial, we use HDF5 predefined data types (integer) and consider +In HDF5, datatypes and dataspaces are independent objects which are created +separately from any dataset that they might be attached to. Because of this, +the creation of a dataset requires definition of the datatype and dataspace. +In this tutorial, we use HDF5 predefined datatypes (integer) and consider only simple dataspaces. Hence, only the creation of dataspace objects is needed. <P> @@ -142,158 +208,250 @@ needed. To create an empty dataset (no data written) the following steps need to be taken: <OL> -<LI> Obtain the location id where the dataset is to be created. -<LI> Define the dataset characteristics and creation properties. +<LI> Obtain the location identifier where the dataset is to be created. +<LI> Define the dataset characteristics and the dataset creation property list. <UL> - <LI> define a data type - <LI> define a dataspace - <LI> specify dataset creation properties + <LI> Define a datatype. + <LI> Define a dataspace. + <LI> Specify the dataset creation property list. </UL> <LI> Create the dataset. -<LI> Close the data type, dataspace, and the property list if necessary. +<LI> Close the datatype, the dataspace, and the property list if necessary. <LI> Close the dataset. </OL> -To create a simple dataspace, the calling program must contain the following -calls: +To create a simple dataspace, the calling program must contain a +call to create and close the dataspace. For example: +<P> +<I>C</I>: +<PRE> + space_id = H5Screate_simple (rank, dims, maxdims); + status = H5Sclose (space_id ); +</PRE> +<I>FORTRAN</I>: <PRE> - dataspace_id = H5Screate_simple(rank, dims, maxdims); - H5Sclose(dataspace_id ); + CALL h5screate_simple_f (rank, dims, space_id, hdferr, maxdims=max_dims) + <i>or</i> + CALL h5screate_simple_f (rank, dims, space_id, hdferr) + + CALL h5sclose_f (space_id, hdferr) </PRE> -To create a dataset, the calling program must contain the following calls: +To create a dataset, the calling program must contain calls to create +and close the dataset. For example: +<P> +<I>C</I>: <PRE> - dataset_id = H5Dcreate(hid_t loc_id, const char *name, hid_t type_id, - hid_t space_id, hid_t create_plist_id); - H5Dclose (dataset_id); + dset_id = H5Dcreate (hid_t loc_id, const char *name, hid_t type_id, + hid_t space_id, hid_t creation_prp); + status = H5Dclose (dset_id); </PRE> +<I>FORTRAN</I>: +<PRE> + CALL h5dcreate_f (loc_id, name, type_id, space_id, dset_id, & + hdferr, creation_prp=creat_plist_id) + <i>or</i> + CALL h5dcreate_f (loc_id, name, type_id, space_id, dset_id, hdferr) + CALL h5dclose_f (dset_id, hdferr) +</PRE> +If using the pre-defined datatypes in FORTRAN, then a call must +be made to initialize and terminate access to the pre-defined datatypes: +<PRE> + CALL h5init_types_f (hdferr) + CALL h5close_types_f (hdferr) +</PRE> +<code>h5init_types_f</code> must be called before any HDF5 library +subroutine calls are made; +<code>h5close_types_f</code> must be called after the final HDF5 library +subroutine call. +See the programming example below for an illustration of the use of +these calls. <P> <H2> Programming Example</H2> <A NAME="desc"> <H3><U>Description</U></H3> The following example shows how to create an empty dataset. -It creates a file called 'dset.h5', defines the dataset dataspace, creates a +It creates a file called <code>dset.h5</code> in the C version +(<code>dsetf.h5</code> in Fortran), defines the dataset dataspace, creates a dataset which is a 4x6 integer array, and then closes the dataspace, the dataset, and the file. <BR> -[ <A HREF="examples/h5_crtdat.c">Download h5_crtdat.c</A> ] -<PRE> -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <hdf5.h> -#define FILE "dset.h5" - -main() { - - hid_t file_id, dataset_id, dataspace_id; /* identifiers */ - hsize_t dims[2]; - herr_t status; - - /* Create a new file using default properties. */ - file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - - /* Create the data - space for the dataset. */ - dims[0] = 4; - dims[1] = 6; - dataspace_id = H5Screate_simple(2, dims, NULL); - - /* Create the dataset. */ - dataset_id = H5Dcreate(file_id, "/dset", H5T_STD_I32BE, dataspace_id, - H5P_DEFAULT); - - /* End access to the dataset and release resources used by it. */ - status = H5Dclose(dataset_id); - - /* Terminate access to the data space. */ - status = H5Sclose(dataspace_id); +<UL> +[ <A HREF="examples/h5_crtdat.c">C Example</A> ] + -- <code>h5_crtdat.c</code><BR> +[ <A HREF="examples/dsetexample.f90">Fortran Example</A> ] + -- <code>dsetexample.f90</code><BR> +[ <A HREF="examples/java/CreateDataset.java">Java Example</A> ] + -- <code>CreateDataset.java</code> +</UL> - /* Close the file. */ - status = H5Fclose(file_id); -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -</PRE> +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page of this tutorial. <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI> H5Screate_simple creates a new simple data space and returns a data space - identifier. +<LI><code>H5Screate_simple</code>/<code>h5screate_simple_f</code> +creates a new simple dataspace and returns a dataspace identifier. <PRE> +<I>C</I>: hid_t H5Screate_simple (int rank, const hsize_t * dims, const hsize_t * maxdims) +<I>FORTRAN</I>: + h5screate_simple_f (rank, dims, space_id, hdferr, maxdims) + + rank INTEGER + dims(*) INTEGER(HSIZE_T) + space_id INTEGER(HID_T) + hdferr INTEGER + (Valid values: 0 on success and -1 on failure) + maxdims(*) INTEGER(HSIZE_T), OPTIONAL </PRE> <UL> - <LI> The first parameter specifies the rank of the dataset. - - <LI> The second parameter specifies the size of the dataset. - - <LI> The third parameter is for the upper limit on the size of the dataset. - If it is NULL, the upper limit is the same as the dimension - sizes specified by the second parameter. + <LI> The <I>rank</I> parameter specifies the rank, i.e., the number of + dimensions, of the dataset. + + <LI> The <I>dims</I> parameter specifies the size of the dataset. + + <LI>The <I>maxdims</I> parameter specifies the upper limit on the + size of the dataset. + If this parameter is NULL in C (or not specified in FORTRAN), + then the upper limit is the same as the dimension + sizes specified by the <I>dims</I> parameter. + <LI>The function returns the dataspace identifier in C if successful; + otherwise it returns a negative value. + In FORTRAN, the dataspace identifier + is returned in the <I>space_id</I> parameter. If the call is successul + then a 0 is returned in <I>hdferr</I>; otherwise a -1 is returned. </UL> <P> -<LI> H5Dcreate creates a dataset at the specified location and returns a - dataset identifier. +<LI><code>H5Dcreate</code>/<code>h5dcreate_f</code> creates a dataset +at the specified location and returns a dataset identifier. <PRE> +<I>C</I>: hid_t H5Dcreate (hid_t loc_id, const char *name, hid_t type_id, - hid_t space_id, hid_t create_plist_id) + hid_t space_id, hid_t creation_prp) +<I>FORTRAN</I>: + h5dcreate_f (loc_id, name, type_id, space_id, dset_id, & + hdferr, creation_prp) + + loc_id INTEGER(HID_T) + name CHARACTER(LEN=*) + type_id INTEGER(HID_T) + space_id INTEGER(HID_T) + dset_id INTEGER(HID_T) + hdferr INTEGER + (Valid values: 0 on success and -1 on failure) + creation_prp INTEGER(HID_T), OPTIONAL </PRE> <UL> - <LI> The first parameter is the location identifier. + <LI> The <I>loc_id</I> parameter is the location identifier. +<P> + <LI> The <I>name</I> parameter is the name of the dataset to create. - <LI> The second parameter is the name of the dataset to create. +<P> + <LI> The <I>type_id</I> parameter specifies the datatype identifier. - <LI> The third parameter is the data type identifier. H5T_STD_I32BE, a - 32-bit Big Endian integer, is an HDF atomic data type. +<P> + <LI> The <I>space_id</I> parameter is the dataspace identifier. - <LI> The fourth parameter is the data space identifier. +<P> + <LI> The <I>creation_prp</I> parameter specifies the + dataset creation property list. + <code>H5P_DEFAULT</code> in C and <code>H5P_DEFAULT_F</code> in FORTRAN + specify the default dataset creation property list. + This parameter is optional in FORTRAN; if it is omitted, + the default dataset creation property list will be used. +<P> + <LI> The C function returns the dataset identifier if successful and + a negative value otherwise. The FORTRAN call returns the + dataset identifier in <I>dset_id</I>. If it is successful, then 0 is + returned in <I>hdferr</I>; otherwise a -1 is returned. - <LI> The last parameter specifies the dataset creation property list. - H5P_DEFAULT specifies the default dataset creation property list. </UL> <P> -<LI>H5Dcreate creates an empty array and initializes the data to 0. +<LI><code>H5Dcreate</code>/<code>h5dcreate_f</code> creates an empty array +and initializes the data to 0. <P> -<LI> When a dataset is no longer accessed by a program, H5Dclose must be -called to release the resource used by the dataset. This call is mandatory. +<LI> When a dataset is no longer accessed by a program, +<code>H5Dclose</code>/<code>h5dclose_f</code> must be called to release +the resource used by the dataset. This call is mandatory. <PRE> - hid_t H5Dclose (hid_t dataset_id) +<I>C</I>: + hid_t H5Dclose (hid_t dset_id) +<I>FORTRAN</I>: + h5dclose_f (dset_id, hdferr) + + dset_id INTEGER(HID_T) + hdferr INTEGER + (Valid values: 0 on success and -1 on failure) </PRE> </UL> <A NAME="fc"> <H3><U>File Contents</U></H3> -The file contents of 'dset.h5' are shown is <B>Figure 5.4</B> and <B>Figure 5.5</B>. -<table width="73%" border="1" cellspacing="4" bordercolor="#FFFFFF"> +The contents of the file <code>dset.h5</code> (<code>dsetf.h5</code> +for FORTRAN) are shown in <B>Figure 5.4</B> and <B>Figures 5.5a </B> +and <B>5.5b</B>. +<P> +<table border="0"> +<tr align=left><td> +<B>Figure 5.4</B> <I>Contents of <code>dset.h5</code> ( <code>dsetf.h5</code>)</i> +</td></tr><tr align=center><td> +<IMG src="img002.gif"> </PRE> +</td></tr></table> + +<table width="100%" border="1" cellspacing="4" bordercolor="#FFFFFF"> <tr bordercolor="#FFFFFF"> - <td width="37%"><b>Figure 5.4</b> <i>The Contents of 'dset.h5'</i> - </td> - <td width="63%"><b>Figure 5.5</b> <i>'dset.h5' in DDL</i> </td> + <td width="50%"><b>Figure 5.5a</b> <i><code>dset.h5</code> in DDL</i> </td> + <td width="50%"><b>Figure 5.5b</b> <i><code>dsetf.h5</code> in DDL</i> </td> </tr> <tr bordercolor="#000000"> -<!-- <td width="37%"><IMG src="dseth5.jpg" width="206" height="333"></td> --> - <td width="37%"><IMG src="img002.gif"></td> - <td width="63%"> - <pre> HDF5 "dset.h5" { - GROUP "/" { - DATASET "dset" { - DATATYPE { H5T_STD_I32BE } - DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) } - DATA { - 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0 - } - } + <td width="35%"> + <PRE> +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) } + DATA { + 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0 } + } +} +} +</PRE> + </td> + <td width="35%"> + <pre> +HDF5 "dsetf.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 6, 4 ) / ( 6, 4 ) } + DATA { + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0 } + } +} +} </pre> </td> </tr> </table> +<p> +Note in Figures 5.5a and 5.5b that +<code>H5T_STD_I32BE</code>, a 32-bit Big Endian integer, +is an HDF atomic datatype. <A NAME="ddl"> @@ -302,12 +460,12 @@ The following is the simplified DDL dataset definition: <P> <B>Fig. 5.6</B> <I>HDF5 Dataset Definition</I> <PRE> - <dataset> ::= DATASET "<dataset_name>" { <data type> + <dataset> ::= DATASET "<dataset_name>" { <datatype> <dataspace> <data> <dataset_attribute>* } - <data type> ::= DATATYPE { <atomic_type> } + <datatype> ::= DATATYPE { <atomic_type> } <dataspace> ::= DATASPACE { SIMPLE <current_dims> / <max_dims> } @@ -329,8 +487,11 @@ The following is the simplified DDL dataset definition: <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@@ncsa.uiuc.edu"> hdfhelp@@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/crtfile.html b/doc/html/Tutor/crtfile.html index 8786aab..a5db890 100644 --- a/doc/html/Tutor/crtfile.html +++ b/doc/html/Tutor/crtfile.html @@ -13,7 +13,7 @@ width=78 height=27 alt="NCSA"><P></A> [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] <H1> -<BIG><BIG><BIG><FONT COLOR="#c101cd">Creating an HDF5 file</FONT> +<BIG><BIG><BIG><FONT COLOR="#c101cd">Creating an HDF5 File</FONT> </BIG></BIG></BIG></H1> <hr noshade size=1> @@ -34,134 +34,228 @@ width=78 height=27 alt="NCSA"><P></A> <A NAME="def"> <H2>What is an HDF5 file?</h2> <P> -An HDF5 file is a binary file which contains scientific data and supporting -metadata. The two primary objects stored in an HDF5 file are groups and -datasets. Groups and datasets will be discussed in the other sessions. +An HDF5 file is a binary file containing scientific data and supporting +metadata. The primary types of objects stored in an HDF5 file, groups and +datasets, will be discussed in other sections of this tutorial. <P> -To create a file, the program application must specify a file name, file +To create a file, an application must specify a filename, file access mode, file creation property list, and file access property list. <P> <UL> - <LI><B> File Creation Property List:</B><BR> + <LI><B> File access mode:</B><BR> + When creating a file, the file access mode specifies the action to + take if the file already exists: + <UL> + <LI><code>H5F_ACC_TRUNC</code> specifies that if the file already exists, + the current contents will be deleted so that the application can rewrite + the file with new data. + <LI><code>H5F_ACC_EXCL</code> specifies that the open is to fail if + the file already exists. + <LI>If the file does not already exist, the file access parameter is + ignored. + <LI>In all cases, the application has both read and write access to + a successfully created file. + </UL> +<P> + Note that there are two different access modes for opening exisitng files: + <UL> + <LI><code>H5F_ACC_RDONLY</code> specifies that the application has + read access but will not be allowed to write any data. + <LI><code>H5F_ACC_RDWR</code> specifies that the application has + read and write access. + </UL> +<P> + For further information, see + <a href="../Files.html">The File Interface (H5F)</a> section of the + <cite>HDF5 User's Guide</cite> and + the <a href="../RM_H5F.html#File-Create">H5F: File Interface</a> + section of the <cite>HDF5 Reference Manual</cite>. +<P> + <LI><B> File creation property list:</B><BR> The file creation property list is used to control the file metadata. File metadata contains information about the size of the user-block, the size of various file data structures used by the HDF5 library, etc. + In this tutorial, the default file creation property list, + <code>H5P_DEFAULT</code>, is used. <P> - The user-block is a fixed length block of data located at the beginning - of the file which is ignored by the HDF5 library and may be used to store - any data information found to be useful to applications. + The user-block is a fixed-length block of data located at the beginning + of the file which is ignored by the HDF5 library. + The user-block may be used to store + any data or information found to be useful to applications. <P> - For more details, see the HDF5 documentation. In this tutorial, - the default file metadata is used. + For further information, see + <a href="../Files.html">The File Interface (H5F)</a> section of the + <cite>HDF5 User's Guide</cite>. <P> - <LI><B> File Access Property List:</B><BR> + <LI><B> File access property list:</B><BR> The file access property list is used to control different methods of - performing I/O on files. See the HDF5 User's Guide for details. The default - file access property is used in this tutorial. + performing I/O on files. + The default file access property list, <code>H5P_DEFAULT</code>, + is used in this tutorial. +<P> + For further information, see + <a href="../Files.html">The File Interface (H5F)</a> section of the + <cite>HDF5 User's Guide</cite>. </UL> <P> The steps to create and close an HDF5 file are as follows: <OL> - <LI> Specify the file creation and access property lists if necessary. - <LI> Create a file. - <LI> Close the file and close the property lists if necessary. + <LI> Specify the file creation and access property lists, if necessary. + <LI> Create the file. + <LI> Close the file and close the property lists, if necessary. </OL> -To create an HDF5 file, the calling program must contain the following calls: - -<PRE> - file_id = H5Fcreate(filename, access_mode, create_id, access_id); +To create an HDF5 file, the calling program must contain calls to +create and close the file. For example: +<P> +<I>C</I>:<PRE> + file_id = H5Fcreate (filename, access_mode, create_id, access_id); + status = H5Fclose (file_id); +</PRE> +<I>FORTRAN</I>:<PRE> + CALL h5fcreate_f (filename, access_mode, file_id, hdferr, & + creation_prp=create_id, access_prp=access_id) + <i>or</i> + CALL h5fcreate_f (filename, access_mode, file_id, hdferr) - H5Fclose(file_id); + CALL h5fclose_f (file_id, hdferr) </PRE> +In FORTRAN, the file creation property list, <code>creation_prp</code>, +and file access property list, <code>access_prp</code>, +are optional parameters; +they can be omitted if the default values are to be used. <P> <H2>Programming Example</H2> <A NAME="desc"> <H3><U>Description</U></H3> The following example demonstrates how to create and close an HDF5 file. -It creates a file called 'file.h5', and then closes the file.<BR> -[ <A HREF="examples/h5_crtfile.c">Download h5_crtfile.c</A> ] -<PRE> -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - - -#include <hdf5.h> -#define FILE "file.h5" - -main() { - - hid_t file_id; /* file identifier */ - herr_t status; - - /* Create a new file using default properties. */ - file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); +It creates a file called <code>file.h5</code> in the C version, +<code>filef.h5</code> in FORTRAN, and then closes the file.<P> - /* Terminate access to the file. */ - status = H5Fclose(file_id); -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +<UL> +[ <A HREF="examples/h5_crtfile.c" target="ExternalWin">C Example</A> ] + -- <code>h5_crtfile.c</code> <BR> +[ <A HREF="examples/fileexample.f90" target="ExternalWin">FORTRAN Example</A> ] + -- <code>fileexample.f90</code><BR> +[ <A HREF="examples/java/CreateFile.java" target="ExternalWin">Java Example</A> ] -- <code>CreateFile.java</code> +</UL> +<P> +<B>NOTE:</B> To download a tar file of all of the examples, including +a Makefile, please go to the <A HREF="references.html">References</A> page. -</PRE> <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI>The include file 'hdf5.h' contains definitions and declarations, and it must - be included in any file that uses the HDF5 library. +<LI><B>In C:</B> + The include file <code>hdf5.h</code> contains definitions and declarations + and must be included in any program that uses the HDF5 library. + <BR><B>In FORTRAN:</B> + The module <code>HDF5</code> contains definitions and declarations + and must be used in any program that uses the HDF5 library. <P> -<LI>H5Fcreate creates an HDF5 file and returns the file identifier. +<LI><code>H5Fcreate</code>/<code>h5fcreate_f</code> creates + an HDF5 file and returns the file identifier. <PRE> - hid_t H5Fcreate (const char *name, unsigned flags, hid_t create_id, - hid_t access_id) +<I>C</I>: + hid_t H5Fcreate (const char *name, unsigned access_mode, hid_t creation_prp, + hid_t access_prp) +<I>FORTRAN</I>: + h5fcreate_f (name, access_mode, file_id, hdferr, creation_prp, access_prp) + + name CHARACTER(LEN=*) + access_flag INTEGER + (Valid values: H5F_ACC_RDWR_F, H5F_ACC_RDONLY_F, + H5F_ACC_TRUNC_F, H5F_ACC_EXCL_F, H5F_ACC_DEBUG_F) + file_id INTEGER(HID_T) + hdferr INTEGER + (Valid values: 0 on success and -1 on failure) + creation_prp INTEGER(HID_T), OPTIONAL + (Default value: H5P_DEFAULT_F) + access_prp INTEGER(HID_T), OPTIONAL + (Default value: H5P_DEFAULT_F) + </PRE> <UL> - <LI> The first parameter specifies the name of the file to be created. + <LI> The <I>name</I> parameter specifies the name of the file to be created. <P> - <LI> The second parameter specifies the file access mode. H5F_ACC_TRUNC will - truncate a file if it already exists. + <LI> The <I>access_mode</I> parameter specifies the file access mode. + <code>H5F_ACC_TRUNC</code> (<code>H5F_ACC_TRUNC_F</code> in FORTRAN) + will truncate a file if it already exists. <P> - <LI> The third parameter specifies the file creation property list. - H5P_DEFAULT indicates that the default file creation property list is - used. - + <LI> The <I>creation_prp</I> parameter + specifies the file creation property list. + For C, using <code>H5P_DEFAULT</code> indicates that the + default file creation property list is to be used. + This option is optional in FORTRAN; if it is omitted, the default file + creation property list, <code>H5P_DEFAULT_F</code>, is used. <P> - <LI> The last parameter of H5Fcreate specifies the file access property list. - H5P_DEFAULT indicates that the default file access property list is used. + <LI> The <I>access_prp</I> parameter + specifies the file access property list. + For C, using <code>H5P_DEFAULT</code> indicates that the + default file creation property list is to be used. + This option is optional in FORTRAN; if it is omitted, the default file + creation property list, <code>H5P_DEFAULT_F</code>, is used. +<P> + <LI> In C, this function returns the file identifier if successful and + a negative value otherwise. + In FORTRAN, the file identifier is returned in the + <I>file_id</I> parameter. If the call is successful, 0 (zero) is + passed back in the <I>hdferr</I> parameter. Otherwise, <I>hdferr</I> + will have a value of -1. </UL> <P> -<LI> When a file is no longer accessed by a program, H5Fclose must be called to - release the resource used by the file. This call is mandatory. +<LI> When a file is no longer accessed by a program, + <code>H5Fclose</code>/<code>h5fclose_f</code> + must be called to release the resources used by the file. This call + is mandatory. <PRE> +<I>C</I>: herr_t H5Fclose (hid_t file_id) + +<I>FORTRAN</I>: + h5fclose_f(file_id, hdferr) </PRE> <P> <LI>The root group is automatically created when a file is created. - Every file has a root group and the path name of the root group is '/'. + Every file has a root group and the path name of the root group is + always <code>/</code>. </UL> <A NAME="fc"> <H3><U>File Contents</U></H3> -HDF has developed tools to examine the contents of HDF5 files. The tool used -in this tutorial is the HDF5 dumper, h5dump. h5dump is a tool that displays -the file contents in human readable form to an ASCII file in DDL. DDL (Data -Description Language) is a language that describes HDF5 objects in Backus-Naur -Form. To view the file contents, type: +The HDF team has developed tools for examining the contents of HDF5 files. +The tool used in this tutorial is the HDF5 dumper, <code>h5dump</code>, +which displays the file contents in human-readable form. +The output of <code>h5dump</code> is an ASCII display formatted according +to the HDF5 DDL grammar. +This grammar is defined, using Backus-Naur Form, in the +<a href="../ddl.html">DDL in BNF for HDF5</a>. +<p> +To view the file contents, type: <PRE> <B>h5dump <filename></B> </PRE> -Figure 4.1 describes the file contents of 'file.h5' using a directed graph. -Each HDF5 object is represented by a rectangle and the arrows indicate -the structure of the contents. In Fig. 4.2, 'file.h5' contains -a group object named '/' (the root group). + +Figure 4.1 describes the file contents of <code>file.h5</code> (<code>filef.h5</code>) +using a directed graph. +The directed graphs in this tutorial use an oval to represent an HDF5 group +and a rectangle to represent an HDF5 dataset (none in this example). +Arrows indicate the inclusion direction of the contents (none in this example). <P> -<B>Fig. 4.1</B> <I>Contents of 'file.h5'</I> +<B>Fig. 4.1</B> <I>Contents of <code>file.h5</code> (<code>filef.h5</code>)</I> <PRE> <!-- <IMG src="fileh5.jpg" width="205" height="208"></PRE> --> <IMG src="img001.gif"></PRE> -Figure 4.2 is the text-description of 'file.h5' generated by h5dump. The HDF5 -file called 'file.h5' contains a group called '/'. + +Figure 4.2 is the text description of <code>file.h5</code>, as generated by +<code>h5dump</code>. The HDF5 file called <code>file.h5</code> contains +a group called <code>/</code>, or the <I>root group</I>. +(The file called <code>filef.h5</code>, +created by the FORTRAN version of the example, has the same output except +that the filename shown is <code>filef.h5</code>.) <P> -<B> Fig. 4.2</B> <I>'file.h5' in DDL</I> +<B> Fig. 4.2</B> <I><code>file.h5</code> in DDL</I> <PRE> HDF5 "file.h5" { @@ -171,15 +265,18 @@ file called 'file.h5' contains a group called '/'. </PRE> <A NAME="ddl"> + <h3><U>File Definition in DDL</U></H3> + Figure 4.3 is the simplified DDL file definition for creating an HDF5 file. For simplicity, a simplified DDL is used in this tutorial. A complete and -more rigorous DDL can be found in the HDF5 User's Guide. See the -<A HREF="references.html">References</A> section of this tutorial. +more rigorous DDL can be found in the +<a href="../ddl.html">DDL in BNF for HDF5</a>, a section of the +<cite>HDF5 User's Guide</cite>. <P> <B> Fig. 4.3</B> <I>HDF5 File Definition</I> <P> - The explanation of the symbols used in the DDL: + The following symbol definitions are used in the DDL: <PRE> ::= defined as @@ -187,7 +284,7 @@ more rigorous DDL can be found in the HDF5 User's Guide. See the <a> | <b> one of <a> or <b> <a>* zero or more occurrences of <a> </PRE> - The simplified DDL file definition: + The simplified DDL for file definition is as follows: <PRE> <file> ::= HDF5 "<file_name>" { <root_group> } @@ -211,14 +308,14 @@ more rigorous DDL can be found in the HDF5 User's Guide. See the <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> -<BR> + <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> </BODY> </HTML> - - - diff --git a/doc/html/Tutor/crtgrp.html b/doc/html/Tutor/crtgrp.html index 566fd2c..678f805 100644 --- a/doc/html/Tutor/crtgrp.html +++ b/doc/html/Tutor/crtgrp.html @@ -42,13 +42,25 @@ program must: <LI> Create the group. <LI> Close the group. </OL> -To create a group, the calling program must contain the following calls: +To create a group, the calling program must call +<code>H5Gcreate</code>/<code>h5gcreate_f</code>. +To close the group, <code>H5Gclose</code>/<code>h5gclose_f</code> +must be called. For example: +<P> +<I>C:</I> <PRE> group_id = H5Gcreate (loc_id, name, size_hint); - H5Gclose (group_id); + status = H5Gclose (group_id); </PRE> +<I>FORTRAN:</I> +<PRE> + CALL h5gcreate_f (loc_id, name, group_id, error, size_hint=size) + <i>or</i> + CALL h5gcreate_f (loc_id, name, group_id, error) + CALL h5gclose_f (group_id, error) +</PRE> <P> @@ -56,77 +68,102 @@ To create a group, the calling program must contain the following calls: <A NAME="desc"> <H3><U>Description</U></H3> The following example shows how to create and close a group. It creates a file -called 'group.h5', creates a group called <I>MyGroup</I> in the root group, +called <code>group.h5</code> (<code>groupf.h5</code> for FORTRAN), +creates a group called <code>MyGroup</code> in the root group, and then closes the group and file. <BR> -[ <A HREF="examples/h5_crtgrp.c">Download h5_crtgrp.c</A> ] -<PRE> - -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <hdf5.h> -#define FILE "group.h5" - -main() { - - hid_t file_id, group_id; /* identifiers */ - herr_t status; - - /* Create a new file using default properties. */ - file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - - /* Create a group named "/MyGroup" in the file. */ - group_id = H5Gcreate(file_id, "/MyGroup", 0); - - /* Close the group. */ - status = H5Gclose(group_id); +<UL> +[ <A HREF="examples/h5_crtgrp.c">C Example</A> ] + - <code>h5_crtgrp.c</code><BR> +[ <A HREF="examples/groupexample.f90">FORTRAN Example</A> ] + - <code>groupexample.f90</code><BR> +[ <A HREF="examples/java/CreateGroup.java">Java Example</A> ] + - <code>CreateGroup.java</code> +</UL> +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. - /* Terminate access to the file. */ - status = H5Fclose(file_id); -} -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ </PRE> <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI> H5Gcreate creates a new empty group and returns a group identifier. +<LI><code>H5Gcreate</code>/<code>h5gcreate_f</code> creates + a new empty group, named <code>MyGroup</code> and located in the + root group, and returns a group identifier. +<P> +<I>C:</I> <PRE> hid_t H5Gcreate (hid_t loc_id, const char *name, size_t size_hint) </PRE> +<I>FORTRAN:</I> +<PRE> + h5gcreate_f (loc_id, name, group_id, hdferr, size_hint) + + loc_id INTEGER(HID_T) + name CHARACTER(LEN=*) + group_id INTEGER(HID_T) + hdferr INTEGER + (Possible values: 0 on success and -1 on failure) + size_hint INTEGER(SIZE_T), OPTIONAL + (Default value: OBJECT_NAMELEN_DEFAULT_F) + +</PRE> <UL> - <LI> The first parameter specifies the location to create the group. - - <LI> The second parameter specifies the name of the group to be created. - - <LI> The third parameter specifies how much file space to reserve to store the + <LI>The <I>loc_id</I> parameter specifies the location at which + to create the group. +<P> + <LI> The <I>name</I> parameter specifies the name of the group to be created. +<P> + <LI> The <I>size_hint</I> parameter specifies how much file space to + reserve to store the names that will appear in the group. If a non-positive value is supplied, then a default size is used. Passing a value of zero is usually adequate since the library is able to dynamically resize the name heap. +<P> + <LI>In FORTRAN, the return value for the routine is passed in + <I>hdferr</I>: 0 if successful, -1 otherwise. The group identifier + is passed back in <I>group_id</I>. In C, the function returns a valid + group identifier if successful and a negative value otherwise. + </UL> <P> -<LI> H5Gcreate creates a group named <I>MyGroup</I> in the root group of the specified - file. +<LI><code>H5Gclose</code>/<code>h5gclose_f</code> closes the group. + This call is mandatory. <P> -<LI> H5Gclose closes the group. This call is mandatory. +<I>C:</I> <PRE> herr_t H5Gclose (hid_t group_id) </PRE> +<I>FORTRAN:</I> +<PRE> + h5gclose_f (group_id, hdferr) + + group_id INTEGER(HID_T) + hdferr INTEGER + (Possible values: 0 on success and -1 on failure) + +</PRE> </UL> <A NAME="fc"> <H3><U>File Contents</U></H3> -The contents of 'group.h5' and the definition of the group are given in the -following: +The contents of <code>group.h5</code> and the +definition of the group are shown below. (The FORTRAN program +creates the HDF5 file <code>groupf.h5</code> and the resulting DDL shows +<code>groupf.h5</code> in the first line.) <P> -<table width="56%" border="1" bordercolor="#FFFFFF" cellpadding="6" cellspacing="6"> - <tr> - <td width="47%"><b>Fig. 8.1</b> <i>The Contents of 'group.h5'.</i> +<table width="80%" border="1" bordercolor="#FFFFFF" cellpadding="6" cellspacing="6"> + <tr valign=top> + <td width="43%"><b>Fig. 8.1</b> <i>The Contents of <code>group.h5</code>.</i> + </td> + <td width="10%"> </td> - <td width="53%"><b>Fig. 8.2</b> <i>'group.h5' in DDL</i> </td> + <td width="47%"><b>Fig. 8.2</b> <i><code>group.h5</code> in DDL</i> </td> </tr> <tr bordercolor="#000000"> <!-- <td width="47%"><IMG src="grouph5.jpg" width="205" height="333"></td> --> - <td width="47%"><IMG src="img003.gif"></td> - <td width="53%" valign="top"> + <td align=center><IMG src="img003.gif"></td> + <td bordercolor="#FFFFFF"> </td> + <td valign="top"> <pre> HDF5 "group.h5" { GROUP "/" { @@ -154,7 +191,9 @@ GROUP "/" { <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> diff --git a/doc/html/Tutor/crtgrpar.html b/doc/html/Tutor/crtgrpar.html index d5fbc66..2ad598a 100644 --- a/doc/html/Tutor/crtgrpar.html +++ b/doc/html/Tutor/crtgrpar.html @@ -1,5 +1,5 @@ <HTML><HEAD> -<TITLE>HDF5 Tutorial - Creating Groups using Absolute/Relative Names +<TITLE>HDF5 Tutorial - Creating Groups using Absolute and Relative Names </TITLE> </HEAD> @@ -13,8 +13,8 @@ width=78 height=27 alt="NCSA"><P></A> [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] <H1> -<BIG><BIG><BIG><FONT COLOR="#c101cd">Creating Groups using -Absolute/Relative Names</FONT> +<BIG><BIG><BIG><FONT COLOR="#c101cd">Creating Groups Using +Absolute and Relative Names</FONT> </BIG></BIG></BIG></H1> <hr noshade size=1> @@ -39,95 +39,103 @@ object is to be created. This location is determined by the identifier of an HDF object and the name of the object to be created. The name of the created object can be either an absolute name or a name relative to the specified identifier. -In Example 5, we used the file identifier and the absolute name "/MyGroup" to create a -group. The file identifier and the name "/" specifies the location where the group -"MyGroup" was created. +In the previous example, we used the file identifier and the absolute name +<code>/MyGroup</code> to create a group. <P> -In this section, we discuss HDF5 names and show how to use absolute/relative -names by giving an example of creating groups in a file. +In this section, we discuss HDF5 names and show how to use absolute and +relative names. <H3>Names</H3> HDF5 object names are a slash-separated list of components. There are few restrictions on names: component names may be any length except zero and may -contain any character except slash ("/") and the null terminator. A full name +contain any character except slash (<code>/</code>) and the null terminator. +A full name may be composed of any number of component names separated by slashes, with any -of the component names being the special name ".". A name which begins with a -slash is an absolute name which is accessed beginning with the root group of the -file while all other relative names are accessed beginning with the specified -group. Multiple consecutive slashes in a full name are treated as single slashes -and trailing slashes are not significant. A special case is the name "/" (or +of the component names being the special name <code>.</code> (a dot or period). +A name which begins with a slash is an absolute name which is accessed +beginning with the root group of the file; +all other names are relative names and and the named object is +accessed beginning with the specified group. +Multiple consecutive slashes in a full name are treated as single slashes +and trailing slashes are not significant. A special case is the name <code>/</code> (or equivalent) which refers to the root group. <P> -Functions which operate on names generally take a location identifier which -is either a file ID or a group ID and perform the lookup with respect to that -location. Some possibilities are: +Functions which operate on names generally take a location identifier, which +can be either a file identifier or a group identifier, and perform the lookup +with respect to that location. +Several possibilities are described in the following table: -<table width="67%" border="1" bordercolor="#000000" cellpadding="4"> +<center> +<table border="1" width=80% bordercolor="#000000" cellpadding="4"> <tr bgcolor="#ffcc99" bordercolor="#FFFFFF"> <td><b> Location Type </b></td> <td><b>Object Name</b></td> <td><b>Description</b></td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc" height="22">File ID</td> + <td bgcolor="#99cccc" height="22">File identifier</td> <td height="22" bgcolor="#CCCCCC"> - <div align="center">/foo/bar</div> + <div align="center"><code>/foo/bar</code></div> </td> - <td height="22">The object bar in group foo in the root group. </td> + <td height="22">The object <code>bar</code> in group <code>foo</code> + in the root group. </td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc">Group ID </td> + <td bgcolor="#99cccc">Group identifier </td> <td bgcolor="#CCCCCC"> - <div align="center">/foo/bar</div> + <div align="center"><code>/foo/bar</code></div> </td> - <td>The object bar in group foo in the root group of the file containing the - specified group. In other words, the group ID's only purpose is to supply - a file. </td> + <td>The object <code>bar</code> in group <code>foo</code> in the + root group of the file containing the specified group. + In other words, the group identifier's only purpose is to + specify a file. </td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc">File ID</td> + <td bgcolor="#99cccc">File identifier</td> <td bgcolor="#CCCCCC"> <div align="center">/</div> </td> <td>The root group of the specified file.</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc">Group ID</td> + <td bgcolor="#99cccc">Group identifier</td> <td bgcolor="#CCCCCC"> <div align="center">/</div> </td> <td>The root group of the file containing the specified group.</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc">Group ID</td> + <td bgcolor="#99cccc">Group identifier</td> <td bgcolor="#CCCCCC"> - <div align="center">foo/bar</div> + <div align="center"><code>foo/bar</code></div> </td> - <td>The object bar in group foo in the specified group.</td> + <td>The object <code>bar</code> in group <code>foo</code> in + the specified group.</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc">File ID</td> + <td bgcolor="#99cccc">File identifier</td> <td bgcolor="#CCCCCC"> - <div align="center">.</div> + <div align="center"><b>.</b></div> </td> <td>The root group of the file.</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc">Group ID</td> + <td bgcolor="#99cccc">Group identifier</td> <td bgcolor="#CCCCCC"> - <div align="center">.</div> + <div align="center"><b>.</b></div> </td> <td>The specified group.</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc">Other ID</td> + <td bgcolor="#99cccc">Other identifier</td> <td bgcolor="#CCCCCC"> - <div align="center">.</div> + <div align="center"><b>.</b></div> </td> <td>The specified object.</td> </tr> </table> +</center> <P> @@ -136,74 +144,51 @@ location. Some possibilities are: <H3><U>Description</U></H3> The following example code shows how to create groups using absolute and relative names. It creates three groups: the first two groups are -created using the file identifier and the group absolute names, and the -third group is created using a group identifier and the name relative +created using the file identifier and the group absolute names while the +third group is created using a group identifier and a name relative to the specified group. <BR> -[ <A HREF="examples/h5_crtgrpar.c">Download h5_crtgrpar.c</A> ] - -<PRE> - -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <hdf5.h> -#define FILE "groups.h5" - -main() { - - hid_t file_id, group1_id, group2_id, group3_id; /* identifiers */ - herr_t status; - - /* Create a new file using default properties. */ - file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - - /* Create group "MyGroup" in the root group using absolute name. */ - group1_id = H5Gcreate(file_id, "/MyGroup", 0); - - /* Create group "Group_A" in group "MyGroup" using absolute name. */ - group2_id = H5Gcreate(file_id, "/MyGroup/Group_A", 0); - - /* Create group "Group_B" in group "MyGroup" using relative name. */ - group3_id = H5Gcreate(group1_id, "Group_B", 0); +<UL> +[ <A HREF="examples/h5_crtgrpar.c">C Example</A> ] - <code>h5_crtgrpar.c</code><BR> +[ <A HREF="examples/grpsexample.f90">Fortran Example</A> ] - <code>grpsexample.f90</code><BR> +[ <A HREF="examples/java/CreateGroupAR.java">Java Example</A> ] - <code>CreateGroupAR.java</code> +</UL> - /* Close groups. */ - status = H5Gclose(group1_id); - status = H5Gclose(group2_id); - status = H5Gclose(group3_id); - - /* Close the file. */ - status = H5Fclose(file_id); -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -</PRE> +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI> H5Gcreate creates a group at the location specified by a location ID and a - name. The location ID can be a file ID or a group ID and the name can be - relative or absolute. - -<LI> The first H5Gcreate creates the group 'MyGroup' in the root group of the - specified file. - -<LI> The second H5Gcreate creates the group 'Group_A' in the group 'MyGroup' - in the root group of the specified file. Note that the parent group (MyGroup) - already exists. - -<LI> The third H5Gcreate creates the group 'Group_B' in the specified group. +<LI><code>H5Gcreate</code>/<code>h5gcreate_f</code> creates a group at the + location specified by a location identifier and a name. + The location identifier can be a file identifier or a group identifier + and the name can be relative or absolute. +<P> +<LI>The first <code>H5Gcreate</code>/<code>h5gcreate_f</code> creates the group + <code>MyGroup</code> in the root group of the specified file. +<P> +<LI>The second <code>H5Gcreate</code>/<code>h5gcreate_f</code> creates the group + <code>Group_A</code> in the group <code>MyGroup</code> in the root group + of the specified file. Note that the parent group (<code>MyGroup</code>) + already exists. +<P> +<LI>The third <code>H5Gcreate</code>/<code>h5gcreate_f</code> creates the group + <code>Group_B</code> in the specified group. </UL> <A NAME="fc"> <H3><U>File Contents</U></H3> The file contents are shown below: <P> -<B>Fig. 9.1</B> <I>The Contents of 'groups.h5'</I> +<B>Fig. 9.1</B> <I>The Contents of <code>groups.h5</code> + (<code>groupsf.h5</code> for FORTRAN)</I> <P> <!--<IMG src="groupsh5.jpg" width="285" height="383"></P> --> <IMG src="img004.gif"></P> - <B> Fig. 9.2</B> <I>'groups.h5' in DDL</I> + <B> Fig. 9.2</B> <I><code>groups.h5</code> in DDL + (for FORTRAN, the name in the first line is <code>groupsf.h5</code>)</I> <PRE> HDF5 "groups.h5" { @@ -233,7 +218,9 @@ The file contents are shown below: <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> diff --git a/doc/html/Tutor/crtgrpd.html b/doc/html/Tutor/crtgrpd.html index e92a101..c9c7129 100644 --- a/doc/html/Tutor/crtgrpd.html +++ b/doc/html/Tutor/crtgrpd.html @@ -32,13 +32,16 @@ width=78 height=27 alt="NCSA"><P></A> <HR> <A NAME="ds"> <H2><U>Creating datasets in groups</U></H2> -We have shown how to create groups, datasets and attributes. In this section, -we show how to create datasets in groups. Recall that H5Dcreate creates a -dataset at the location specified by a location identifier and a name. Similar to -H5Gcreate, the location identifier can be a file identifier or a group identifier and the name can be -relative or absolute. The location identifier and the name together determine the -location where the dataset is to be created. If the location identifier and name -refers to a group, then the dataset is created in that group. +We have shown how to create groups, datasets, and attributes. +In this section, we show how to create datasets in groups. +Recall that <code>H5Dcreate</code>/<code>h5dcreate_f</code> +creates a dataset at the location specified by a location identifier and +a name. Similar to <code>H5Gcreate</code>/<code>h5gcreate_f</code>, +the location identifier can be a +file identifier or a group identifier and the name can be +relative or absolute. The location identifier and the name together determine +the location where the dataset is to be created. If the location identifier +and name refer to a group, then the dataset is created in that group. <H2> Programming Example</H2> @@ -46,127 +49,98 @@ refers to a group, then the dataset is created in that group. <H3><U>Description</U></H3> This example shows how to create a dataset in a particular group. It opens the file created in the previous example and creates two datasets.<BR> -[ <A HREF="examples/h5_crtgrpd.c">Download h5_crtgrpd.c</A> ] -<PRE> - -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <hdf5.h> -#define FILE "groups.h5" - -main() { - - hid_t file_id, group_id, dataset_id, dataspace_id; /* identifiers */ - hsize_t dims[2]; - herr_t status; - int i, j, dset1_data[3][3], dset2_data[2][10]; - - /* Initialize the first dataset. */ - for (i = 0; i < 3; i++) - for (j = 0; j < 3; j++) - dset1_data[i][j] = j + 1; - - /* Initialize the second dataset. */ - for (i = 0; i < 2; i++) - for (j = 0; j < 10; j++) - dset2_data[i][j] = j + 1; - - /* Open an existing file. */ - file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT); - - /* Create the data space for the first dataset. */ - dims[0] = 3; - dims[1] = 3; - dataspace_id = H5Screate_simple(2, dims, NULL); - - /* Create a dataset in group "MyGroup". */ - dataset_id = H5Dcreate(file_id, "/MyGroup/dset1", H5T_STD_I32BE, dataspace_id -, - H5P_DEFAULT); - - /* Write the first dataset. */ - status = H5Dwrite(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, - dset1_data); - - /* Close the data space for the first dataset. */ - status = H5Sclose(dataspace_id); - - /* Close the first dataset. */ - status = H5Dclose(dataset_id); - - /* Open an existing group of the specified file. */ - group_id = H5Gopen(file_id, "/MyGroup/Group_A"); - - /* Create the data space for the second dataset. */ - dims[0] = 2; - dims[1] = 10; - dataspace_id = H5Screate_simple(2, dims, NULL); - - /* Create the second dataset in group "Group_A". */ - dataset_id = H5Dcreate(group_id, "dset2", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT); - - /* Write the second dataset. */ - status = H5Dwrite(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, - dset2_data); - - /* Close the data space for the second dataset. */ - status = H5Sclose(dataspace_id); - - /* Close the second dataset */ - status = H5Dclose(dataset_id); - - /* Close the group. */ - status = H5Gclose(group_id); - - /* Close the file. */ - status = H5Fclose(file_id); -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -</PRE> +<UL> +[ <A HREF="examples/h5_crtgrpd.c">C Example</A> ] - <code>h5_crtgrpd.c</code> +<BR> +[ <A HREF="examples/grpdsetexample.f90">FORTRAN Example</A> ] +- <code>grpdsetexample.f90</code><BR> +[ <A HREF="examples/java/CreateGroupDataset.java">Java Example</A> ] +- <code>CreateGroupDataset.java</code> +</UL> +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. <A NAME="fc"> <H3><U>File Contents</U></H3> <P> -<B>Fig. 10.1</B> <I>The Contents of 'groups.h5'</I> +<B>Fig. 10.1</B> <I>The Contents of <code>groups.h5</code> + (<code>groupsf.h5</code> for FORTRAN)</I> <PRE> <IMG src="img005.gif"></PRE> <!-- <IMG src="groups2.jpg" width="324" height="433"></PRE> --> </PRE> - <B>Fig. 10.2</B> <I>'groups.h5' in DDL</I> + <B>Fig. 10.2a</B> <I><code>groups.h5</code> in DDL</I> <PRE> - HDF5 "groups.h5" { - GROUP "/" { - GROUP "MyGroup" { - GROUP "Group_A" { - DATASET "dset2" { - DATATYPE { H5T_STD_I32BE } - DATASPACE { SIMPLE ( 2, 10 ) / ( 2, 10 ) } - DATA { - 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, - 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 - } - } - } - GROUP "Group_B" { - } - DATASET "dset1" { - DATATYPE { H5T_STD_I32BE } - DATASPACE { SIMPLE ( 3, 3 ) / ( 3, 3 ) } - DATA { - 1, 2, 3, - 1, 2, 3, - 1, 2, 3 - } +HDF5 "groups.h5" { +GROUP "/" { + GROUP "MyGroup" { + GROUP "Group_A" { + DATASET "dset2" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 2, 10 ) / ( 2, 10 ) } + DATA { + 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, + 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 } } } + GROUP "Group_B" { } + DATASET "dset1" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 3, 3 ) / ( 3, 3 ) } + DATA { + 1, 2, 3, + 1, 2, 3, + 1, 2, 3 + } + } + } +} +} </PRE> + <B>Fig. 10.2b</B> <I><code>groupsf.h5</code> in DDL</I> +<PRE> - +HDF5 "groupsf.h5" { +GROUP "/" { + GROUP "MyGroup" { + GROUP "Group_A" { + DATASET "dset2" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 10, 2 ) / ( 10, 2 ) } + DATA { + 1, 1, + 2, 2, + 3, 3, + 4, 4, + 5, 5, + 6, 6, + 7, 7, + 8, 8, + 9, 9, + 10, 10 + } + } + } + GROUP "Group_B" { + } + DATASET "dset1" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 3, 3 ) / ( 3, 3 ) } + DATA { + 1, 1, 1, + 2, 2, 2, + 3, 3, 3 + } + } + } +} +} +</PRE> <!-- BEGIN FOOTER INFO --> <P><hr noshade size=1> @@ -178,7 +152,9 @@ main() { <!-- <A HREF="helpdesk.mail.html"> --> <BR><A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> diff --git a/doc/html/Tutor/extend.html b/doc/html/Tutor/extend.html index 03b5972..2c7fb11 100644 --- a/doc/html/Tutor/extend.html +++ b/doc/html/Tutor/extend.html @@ -35,16 +35,19 @@ width=78 height=27 alt="NCSA"><P></A> <HR> <A NAME="def"> <H2>Creating an Extendible Dataset</H2> -An extendible dataset is one whose dimensions can grow. In HDF5, it is possible to define a dataset to have certain initial dimensions, then later -to increase the size of any of the initial dimensions. +An extendible dataset is one whose dimensions can grow. +HDF5 allows you to define a dataset to have certain initial dimensions, +then to later increase the size of any of the initial dimensions. <P> -HDF5 requires you to use chunking in order to define extendible datasets. Chunking makes it possible to extend datasets efficiently, without -having to reorganize storage excessively. +HDF5 requires you to use chunking to define extendible datasets. +This makes it possible to extend datasets efficiently without +having to excessively reorganize storage. <P> The following operations are required in order to write an extendible dataset: <OL> <LI>Declare the dataspace of the dataset to have unlimited dimensions for all dimensions that might eventually be extended. - <LI>Set dataset creation properties to enable chunking and create a dataset. + <LI>Set dataset creation properties to enable chunking. + <LI>Create the dataset. <LI>Extend the size of the dataset. </OL> <H2> Programming Example</H2> @@ -52,229 +55,197 @@ The following operations are required in order to write an extendible dataset: <H3><U>Description</U></H3> This example shows how to create a 3 x 3 extendible dataset, write to that dataset, extend the dataset to 10x3, and write to the dataset again. -[<A HREF="examples/h5_extend.c">Download h5_extend.c</A>] -<PRE> - -/************************************************************** - * - * This example shows how to work with extendible datasets. - * In the current version of the library a dataset MUST be - * chunked in order to be extendible. - * - * This example is derived from the h5_extend_write.c and - * h5_read_chunk.c examples that are in the "Introduction - * to HDF5". - * - *************************************************************/ - -#include "hdf5.h" - -#define FILE "ext.h5" -#define DATASETNAME "ExtendibleArray" -#define RANK 2 - -int -main (void) -{ - hid_t file; /* handles */ - hid_t dataspace, dataset; - hid_t filespace; - hid_t cparms; - hid_t memspace; - - hsize_t dims[2] = { 3, 3}; /* dataset dimensions - at creation time */ - hsize_t dims1[2] = { 3, 3}; /* data1 dimensions */ - hsize_t dims2[2] = { 7, 1}; /* data2 dimensions */ - - hsize_t maxdims[2] = {H5S_UNLIMITED, H5S_UNLIMITED}; - hsize_t size[2]; - hssize_t offset[2]; - hsize_t i,j; - herr_t status, status_n; - int data1[3][3] = { {1, 1, 1}, /* data to write */ - {1, 1, 1}, - {1, 1, 1} }; - - int data2[7] = { 2, 2, 2, 2, 2, 2, 2}; - - /* Variables used in reading data back */ - hsize_t chunk_dims[2] ={2, 5}; - hsize_t chunk_dimsr[2]; - hsize_t dimsr[2]; - int data_out[10][3]; - int rank, rank_chunk; - - /* Create the data space with unlimited dimensions. */ - dataspace = H5Screate_simple (RANK, dims, maxdims); - - /* Create a new file. If file exists its contents will be overwritten. */ - file = H5Fcreate (FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - - /* Modify dataset creation properties, i.e. enable chunking */ - cparms = H5Pcreate (H5P_DATASET_CREATE); - status = H5Pset_chunk ( cparms, RANK, chunk_dims); - - /* Create a new dataset within the file using cparms - creation properties. */ - dataset = H5Dcreate (file, DATASETNAME, H5T_NATIVE_INT, dataspace, - cparms); - - /* Extend the dataset. This call assures that dataset is 3 x 3.*/ - size[0] = 3; - size[1] = 3; - status = H5Dextend (dataset, size); - - /* Select a hyperslab */ - filespace = H5Dget_space (dataset); - offset[0] = 0; - offset[1] = 0; - status = H5Sselect_hyperslab (filespace, H5S_SELECT_SET, offset, NULL, - dims1, NULL); - - /* Write the data to the hyperslab */ - status = H5Dwrite (dataset, H5T_NATIVE_INT, dataspace, filespace, - H5P_DEFAULT, data1); - - /* Extend the dataset. Dataset becomes 10 x 3 */ - dims[0] = dims1[0] + dims2[0]; - size[0] = dims[0]; - size[1] = dims[1]; - status = H5Dextend (dataset, size); - - /* Select a hyperslab */ - filespace = H5Dget_space (dataset); - offset[0] = 3; - offset[1] = 0; - status = H5Sselect_hyperslab (filespace, H5S_SELECT_SET, offset, NULL, - dims2, NULL); - - /* Define memory space */ - dataspace = H5Screate_simple (RANK, dims2, NULL); - - /* Write the data to the hyperslab */ - status = H5Dwrite (dataset, H5T_NATIVE_INT, dataspace, filespace, - H5P_DEFAULT, data2); - - /* Close resources */ - status = H5Dclose (dataset); - status = H5Sclose (dataspace); - status = H5Sclose (filespace); - status = H5Fclose (file); - -/**************************************************************** - Read the data back - ***************************************************************/ - - file = H5Fopen (FILE, H5F_ACC_RDONLY, H5P_DEFAULT); - dataset = H5Dopen (file, DATASETNAME); - filespace = H5Dget_space (dataset); - rank = H5Sget_simple_extent_ndims (filespace); - status_n = H5Sget_simple_extent_dims (filespace, dimsr, NULL); - - cparms = H5Dget_create_plist (dataset); - if (H5D_CHUNKED == H5Pget_layout (cparms)) - { - rank_chunk = H5Pget_chunk (cparms, 2, chunk_dimsr); - } - - memspace = H5Screate_simple (rank,dimsr,NULL); - status = H5Dread (dataset, H5T_NATIVE_INT, memspace, filespace, - H5P_DEFAULT, data_out); - printf("\n"); - printf("Dataset: \n"); - for (j = 0; j < dimsr[0]; j++) - { - for (i = 0; i < dimsr[1]; i++) - printf("%d ", data_out[j][i]); - printf("\n"); - } +<UL> +[<A HREF="examples/h5_extend.c">C example</A> ] + - <code>h5_extend.c</code><BR> +[<A HREF="examples/chunk.f90">FORTRAN example</A> ] + - <code>chunk.f90</code> +</UL> +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. - status = H5Pclose (cparms); - status = H5Dclose (dataset); - status = H5Sclose (filespace); - status = H5Sclose (memspace); - status = H5Fclose (file); -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -</PRE> <A NAME="rem"> <H3><U>Remarks</U></H3> <P> <UL> -<LI>The function H5Pcreate creates a new property as an instance of - a property list. The signature of this function is as follows: -<PRE> - hid_t H5Pcreate ( H5P_class_t type ) -</PRE> +<LI>The routine <CODE>H5Pcreate</CODE> / <CODE>h5pcreate_f</CODE> +creates a new property as an instance of + a property list. The signature is as follows: +<P> +<I><B>C:</B></I> +<pre> + hid_t H5Pcreate (H5P_class_t classtype) +</pre> +<P> +<I><B>FORTRAN:</B></I> +<pre> + h5pcreate_f (classtype, prp_id, hdferr) + + classtype IN: INTEGER + prp_id OUT: INTEGER(HID_T) + hdferr OUT: INTEGER +</pre> +<P> <UL> -<LI>The parameter <I>type</I> is the type of property list to create.<BR> - The class types are: H5P_FILE_CREATE, H5P_FILE_ACCESS, H5P_DATASET_CREATE, - H5P_DATASET_XFER, and H5P_MOUNT +<LI>The parameter <I>classtype</I> is the type of property list to create. + Valid class types are as follows: +<center> +<table border=1> + <tr align=center> + <td><b>C</b></td> + <td><b>FORTRAN</b></td> + </tr><tr align=left> + <td><code> <BR> + H5P_FILE_CREATE <BR> + H5P_FILE_ACCESS <BR> + H5P_DATASET_CREATE<BR> + H5P_DATASET_XFER <BR> + H5P_MOUNT <BR><BR> + </code></td> + <td><code> <BR> + H5P_FILE_CREATE_F <BR> + H5P_FILE_ACCESS_F <BR> + H5P_DATASET_CREATE_F<BR> + H5P_DATASET_XFER_F <BR> + H5P_MOUNT_F <BR><BR> + </code></td> + </tr> +</table> +</center> +<LI>In C, the property list identifier is returned if successful; +otherwise a negative value is returned, if not. +In FORTRAN, the property list identifier is returned in <I>prp_id</I> +and the return value for the call is returned in <I>hdferr</I>. </UL> <P> -<LI>The function H5Pset_chunk sets the size of the chunks used +<LI>The routine <CODE>H5Pset_chunk</CODE> / <CODE>h5pset_chunk_f</CODE> +sets the size of the chunks used to store a chunked layout dataset. - The signature of this function is as follows: -<PRE> - herr_t H5Pset_chunk ( hid_t plist, int ndims, const hsize_t * dim ) -</PRE> + The signature of this routine is as follows: +<P> +<I><B>C:</B></I> +<pre> + herr_t H5Pset_chunk (hid_t prp_id, int ndims, + const hsize_t * dims) +</pre> +<P> +<I><B>FORTRAN:</B></I> +<pre> + h5pset_chunk_f (prp_id, ndims, dims, hdferr) + + prp_id IN: INTEGER(HID_T) + ndims IN: INTEGER + dims IN: INTEGER(HSIZE_T), DIMENSION(ndims) + hdferr OUT: INTEGER + +</pre> +<P> <UL> -<LI>The first parameter, <I>plist</I>, is the identifier for the property +<LI>The <em>prp_id</em> parameter is the identifier for the property list to query. -<LI>The second parameter, <I>ndims</I>, is the number of dimensions of +<LI>The <em>ndims</em> parameter is the number of dimensions of each chunk. -<LI>The third parameter, <I>dim</I>, is an array containing the size of +<LI>The <em>dims</em> parameter is an array containing the size of each chunk. +<LI>In C, a non-negative value is returned if successful; otherwise a + negative value is returned. + In FORTRAN, the return value is returned in <em>hdferr</em>: 0 if + successful and -1 otherwise. </UL> <P> -A non-negative value is returned if successful; otherwise a negative -value is returned. -<P> -<LI>The function H5Dextend extends a dataset that has an unlimited +<LI>The <CODE>H5Dextend</CODE> / <CODE>h5dextend_f</CODE> routine +extends a dataset that has an unlimited dimension. The signature is as follows: -<PRE> - herr_t H5Dextend ( hid_t dataset_id, const hsize_t * size ) -</PRE> +<P> +<I><B>C:</B></I> +<pre> + herr_t H5Dextend (hid_t dset_id, const hsize_t * size) +</pre> +<P> +<I><B>FORTRAN:</B></I> +<pre> + h5dextend_f (dset_id, size, hdferr) + + dset_id IN: INTEGER(HID_T) + size IN: INTEGER(HSIZE_T), DIMENSION(*) + hdferr OUT: INTEGER<BR> +</pre> +<P> <UL> -<LI>The first parameter, <I>dataset_id</I>, is the identifier of - the dataset. -<LI>The second parater, <I>size</I>, is an array containing the +<LI>The <em>dset_id</em> parameter is the dataset identifier. +<LI>The <em>size</em> parameter, is an array containing the new magnitude of each dimension. +<LI>In C, this function returns a non-negative value if successful and + a negative value otherwise. + In FORTRAN, the return value is returned in <em>hdferr</em>: + 0 if successful and -1 otherwise. </UL> <P> -This function returns a non-negative value if successful; otherwise -it returns a negative value. -<P> -<LI>The H5Dget_create_plist function returns an identifier for a +<LI>The <CODE>H5Dget_create_plist</CODE> / <CODE>h5dget_create_plist_f</CODE> +routine returns an identifier for a copy of the dataset creation property list for a dataset. <P> -<LI>The H5Pget_layout function returns the layout of the raw data for a -dataset. Valid types are H5D_COMPACT, H5D_CONTIGUOUS, and H5D_CHUNKED. +<LI>The C function, <CODE>H5Pget_layout</CODE>, returns the layout of the raw data for a +dataset. Valid types are <CODE>H5D_CONTIGUOUS</CODE> and +<CODE>H5D_CHUNKED</CODE>. +A FORTRAN routine for <CODE>H5Pget_layout</CODE> does not yet exist. +<P> +<LI>The <CODE>H5Pget_chunk</CODE> / <CODE>h5pget_chunk_f</CODE> +routine retrieves the size of chunks +for the raw data of a chunked layout dataset. +The signature is as follows: +<P> +<I><B>C:</B></I> +<pre> + int H5Pget_chunk (hid_t prp_id, int ndims, hsize_t * dims) +</pre> +<P> +<I><B>FORTRAN:</B></I> +<pre> + h5pget_chunk_f (prp_id, ndims, dims, hdferr) + + prp_id IN: INTEGER(HID_T) + ndims IN: INTEGER + dims OUT: INTEGER(HSIZE_T), DIMENSION(ndims) + hdferr OUT: INTEGER +</pre> <P> -<LI>The H5Pget_chunk function retrieves the size of chunks for the -raw data of a chunked layout dataset. -The signature of this function is: -<PRE> - int H5Pget_chunk ( hid_t plist, int max_ndims, hsize_t * dims ) -</PRE> <UL> -<LI>The first parameter, <I>plist</I>, is the identifier of the + +<LI>The <em>prp_id</em> parameter is the identifier of the property list to query. -<LI>The second parameter, <I>max_ndims</I>, is the size of the <I>dims</I> +<LI>The <em>ndims</em> parameter is the size of the <em>dims</em> array. -<LI>The third parameter, <I>dims</I>, is the array to store the chunk - dimensions +<LI>The <em>dims</em> parameter is the array in which to store the chunk + dimensions. +<LI>In C, this function returns the chunk dimensionality if successful + and a negative value otherwise. + In FORTRAN, the return value is returned in <em>hdferr</em>: + the chunked rank if successful and -1 otherwise. </UL> <P> -<LI>The H5Pclose function terminates access to a property list. - The signature of this function is: -<PRE> - herr_t H5Pclose ( hid_t plist ) -</PRE> -where <I>plist</I> is the identifier of the property list to terminate -access to. +<LI>The <CODE>H5Pclose</CODE> / <CODE>h5pclose_f</CODE> routine + terminates access to a property list. + The signature is as follows: +<P> +<I><B>C:</B></I> +<pre> + herr_t H5Pclose (hid_t prp_id) +</pre> +<P> +<I><B>FORTRAN:</B></I> +<pre> + h5pclose_f (prp_id, hdferr) + + prp_id IN: INTEGER(HID_T) + hdferr OUT: INTEGER +</pre> +<P> +<ul> +<li>The <em>prp_id</em> parameter is the identifier of the property list + to terminate access to. +</ul> </UL> @@ -301,8 +272,11 @@ access to. <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: January 19, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/fileorg.html b/doc/html/Tutor/fileorg.html index 03c2c29..afc0cba 100644 --- a/doc/html/Tutor/fileorg.html +++ b/doc/html/Tutor/fileorg.html @@ -21,28 +21,28 @@ width=78 height=27 alt="NCSA"><P></A> <BODY> <P> -An HDF5 file is a container for storing a variety of scientific data, and the -two primary HDF5 objects are groups and datasets. +An HDF5 file is a container for storing a variety of scientific data +is composed of two primary types of objects: groups and datasets. <UL> <LI><B>HDF5 group:</B> a grouping structure containing zero or more HDF5 - objects, together with supporting metadata. + objects, together with supporting metadata <LI><B>HDF5 dataset:</B> a multidimensional array of data elements, together - with supporting metadata. + with supporting metadata </UL> -Any HDF5 group or dataset may have an associated attribute list. An HDF5 -attribute is a user-defined HDF5 structure that provides extra information +Any HDF5 group or dataset may have an associated attribute list. An <B>HDF5 +attribute</B> is a user-defined HDF5 structure that provides extra information about an HDF5 object. <P> -Working with groups and group members (datasets for example) is similar in many +Working with groups and datasets is similar in many ways to working with directories and files in UNIX. As with UNIX directories -and files, objects in an HDF5 file are often described by giving their full (or -absolute) path names. +and files, an HDF5 object in an HDF5 file is often referred to by its +<B>full path name</B> (also called an <B>absolute path name</B>). <UL> <CODE>/</CODE> signifies the root group.<BR> - <CODE>/foo</CODE> signifies a member of the root group called <I>foo</I>. + <CODE>/foo</CODE> signifies a member of the root group called <code>foo</code>. <BR> - <CODE>/foo/zoo</CODE> signifies a member of the group <I>foo</I>, which in + <CODE>/foo/zoo</CODE> signifies a member of the group <code>foo</code>, which in turn is a member of the root group. </UL> <P> @@ -90,8 +90,11 @@ The tutorial ends with a glossary and references. <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: July 30, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: December 10, 1999</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/glossary.html b/doc/html/Tutor/glossary.html index 84a938d..82757b8 100644 --- a/doc/html/Tutor/glossary.html +++ b/doc/html/Tutor/glossary.html @@ -44,8 +44,8 @@ number of entries in symbol tables (used to store groups) and additional version manner, called a complex dataspace. <P> -<DT><B>DATA TYPE</B> -<DD>An HDF5 Data Type is an object that describes the type of the +<DT><B>DATATYPE</B> +<DD>An HDF5 Datatype is an object that describes the type of the element in an HDF5 multi-dimensional array. There are two categories of datatypes: atomic and compound data types. An atomic type is a type which cannot be decomposed into smaller @@ -181,6 +181,13 @@ A hyperslab is a portion of a dataset. A hyperslab selection can be a logically contiguous collection of points in a dataspace, or it can be a regular pattern of points or blocks in a dataspace. <P> +<DT><B>MOUNTING FILES</B> +<DD> +HDF5 allows you to combine two or more HDF5 files in a manner similar +to mounting files in UNIX. The group structure and metadata +from one file appear as though they exist in another file. +<P> + <DT><B>NAMES</B> <DD>HDF5 object names are a slash-separated list of components. A name which begins with a slash is an absolute name which is accessed @@ -192,6 +199,28 @@ can be a regular pattern of points or blocks in a dataspace. MPI (Message Passing Interface). <P> +<DT><B>REFERENCE</B> +<DD> +<B>OBJECT REFERENCE:</B><BR> + A reference to an entire object in the current HDF5 file. + <P> + An object + reference points to an entire object in the current HDF5 file by storing + the relative file address (OID) of the object header for the object + pointed to. The relative file address of an object header is constant + for the life of the object. An object reference is of a fixed size in + the file. +<P> +<B>DATASET REGION REFERENCE:</B><BR> + Reference to a specific dataset region. + <P> + A dataset region reference points to a region of a dataset in the + current HDF5 file by storing the OID of the dataset and the global + heap offset of the region referenced. The region referenced is + located by retrieving the coordinates of the areas in the region + from the global heap. A dataset region reference is of a variable + size in the file. +<P> <DT><B>THREADSAFE (HDF5)</B> <DD>A "thread-safe" version of HDF-5 (TSHDF5) is one that can be called from any thread of a multi-threaded program. Any calls to HDF can be made in any order, and each individual HDF call will perform correctly. A calling program does not have to explicitly lock the HDF @@ -221,7 +250,9 @@ library as regular HDF-5 library, with additional code to synchronize access to <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: September 1, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: January 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> diff --git a/doc/html/Tutor/intro.html b/doc/html/Tutor/intro.html index abf664c..0cca74a 100644 --- a/doc/html/Tutor/intro.html +++ b/doc/html/Tutor/intro.html @@ -22,27 +22,39 @@ width=78 height=27 alt="NCSA"><P></A> Welcome to the HDF5 Tutorial provided by the HDF User Support Group. <P> HDF5 is a file format and library for storing scientific data. -HDF5 was designed and implemented to address the deficiencies of HDF4.x. -It has a more powerful and flexible data model, supports files larger than 2 GB, -supports parallel I/O, and is thread-safe. For a short overview presentation -of the HDF5 data model, library and tools see: +It was designed and implemented + to meet growing and ever-changing scientific data-storage + and data-handling needs, + to take advantage of the power and features of today's + computing systems, and + to address the deficiencies of HDF4.x. +HDF5 has a powerful and flexible data model, + supports files larger than 2 GB (the limit of HDF4.x files), and + supports parallel I/O. +Thread-safety is designed and is to be implemented in the near future. +For a short overview of the HDF5 data model, library, and tools, see +the slide presentation at the following URL: <PRE> - <A HREF="http://hdf.ncsa.uiuc.edu/HDF5/HDF5_overview/index.htm">http://hdf.ncsa.uiuc.edu/HDF5/HDF5_overview/index.htm</A> + <A HREF="http://hdf.ncsa.uiuc.edu/HDF5/papers/HDF5_overview/index.htm">http://hdf.ncsa.uiuc.edu/HDF5/papers/HDF5_overview/index.htm</A> </PRE> This tutorial covers the basic HDF5 data objects and file structure, -the HDF5 programming model and the API functions necessary for creating and -modifying data objects. It also introduces the available HDF5 tools to access +the HDF5 programming model, and the API functions necessary for creating and +modifying data objects. It also introduces the available HDF5 tools for accessing HDF5 files. <P> -The examples used in this tutorial, along with a Makefile to compile them +The examples used in this tutorial, along with a Makefile to compile them, can be found in <A HREF="./examples/">./examples/</A>. You can also download a <A HREF="http://hdf.ncsa.uiuc.edu/training/other-ex5/examples.tar">tar -file</A> with the examples and Makefile. In -order to use the Makefile you may have to edit it and update the +file</A> with the examples and Makefile. +To use the Makefile, you may have to edit it and update the compiler and compiler options, as well as the path for the HDF5 binary distribution. +The Java examples can be found in +a subdirectory of the ./examples/ directory called java/. The java/ +directory contains a Makefile and shell scripts for running the java +programs. <P> -Please check the <A HREF="references.html">References</A> for where to find +Please check the <A HREF="references.html">References</A> for pointers to other examples of HDF5 Programs. <P> We hope that the step-by-step examples and instructions will give you a quick @@ -68,8 +80,11 @@ Please send your comments and suggestions to hdfhelp@ncsa.uiuc.edu. <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: October 8, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/iterate.html b/doc/html/Tutor/iterate.html index 4cb0475..e051764 100644 --- a/doc/html/Tutor/iterate.html +++ b/doc/html/Tutor/iterate.html @@ -21,11 +21,13 @@ width=78 height=27 alt="NCSA"><P></A> <BODY> <H2>Contents:</H2> <UL> - <LI><A HREF="#def">How to Iterate Over Group Members</A> + <LI><A HREF="#def">How to Iterate over Group Members Using C </A> + <LI><A HREF="#deff">How to Iterate over Group Members Using FORTRAN</A> <LI>Programming Example <UL> <LI> <A HREF="#desc">Description</A> - <LI> <A HREF="#rem">Remarks</A> + <LI> <A HREF="#remc">Remarks for C Example</A> + <LI> <A HREF="#remf">Remarks for FORTRAN Example</A> <!-- <LI> <A HREF="#fc">File Contents</A> <LI> <A HREF="#ddl">Dataset Definition in DDL</A> @@ -34,15 +36,15 @@ width=78 height=27 alt="NCSA"><P></A> </UL> <HR> <A NAME="def"> -<H2>How to Iterate Over Group Members</H2> +<H2>How to Iterate over Group Members Using C</H2> This section discusses how to find names and object types of HDF5 group -members. +members using C. <P> -The HDF5 Group interface has a function, H5Giterate, to iterate over the -group members. +The HDF5 Group interface includes the <CODE>H5Giterate</CODE> function, +which iterates over the group members. <P> -Operations on each group member can be performed during the iteration process. -The operator function and its data are passed to the iterator as parameters. +Operations on each group member can be performed during the iteration process +by passing the operator function and its data to the iterator as parameters. There are no restrictions on what kind of operations can be performed on group members during the iteration procedure. <P> @@ -52,168 +54,91 @@ The following steps are involved: <LI> Write an operator function which will be used during the iteration process. The HDF5 library defines the operator function signature and return values. <LI> Open the group to iterate through. -<LI> Use H5Giterate to iterate through the group or just a few members of - the group. +<LI> Iterate through the group or just a few members of the group. </OL> +<A NAME="deff"> +<H2>How to Iterate Over Group Members using FORTRAN</H2> +There is no FORTRAN call to iterate over group members. +Instead, this functionality is provided by two FORTRAN calls: +<ul> + <li><CODE>hgn_members_f</CODE> returns the number of group members. + <li><CODE>h5gget_obj_info_idx_f</CODE> returns the name and type of the + group member, which is identified by its index. +</ul> +<P> <H2> Programming Example</H2> <A NAME="desc"> <H3><U>Description</U></H3> -In this example we iterate through the members of the root group. The -operator function displays the members' names and their object types. -The object type can be a group, dataset, or named datatype. -[ <A HREF="examples/h5_iterate.c">Download h5_iterate.c</A> ] +In this example we iterate through the members of the root group. +<UL> +[ <A HREF="examples/h5_iterate.c">C example</A> ] + - <code>h5_iterate.c</code><BR> +[ <A HREF="examples/grpit.f90">FORTRAN example</A> ] + - <code>grpit.f90</code> +</UL> +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. +<P> +Following is the output from these examples: +<P> +<I><U>Output from C Example</U></I> <PRE> + Objects in the root group are: -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <hdf5.h> - -#define FILE "iterate.h5" -#define FALSE 0 - -/* 1-D dataset with fixed dimensions */ -#define SPACE1_NAME "Space1" -#define SPACE1_RANK 1 -#define SPACE1_DIM1 4 - -herr_t file_info(hid_t loc_id, const char *name, void *opdata); - /* Operator function */ -int -main(void) { - hid_t file; /* HDF5 File IDs */ - hid_t dataset; /* Dataset ID */ - hid_t group; /* Group ID */ - hid_t sid; /* Dataspace ID */ - hid_t tid; /* Datatype ID */ - hsize_t dims[] = {SPACE1_DIM1}; - herr_t ret; /* Generic return value */ - -/* Compound datatype */ -typedef struct s1_t { - unsigned int a; - unsigned int b; - float c; -} s1_t; - - /* Create file */ - file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - - /* Create dataspace for datasets */ - sid = H5Screate_simple(SPACE1_RANK, dims, NULL); - - /* Create a group */ - group=H5Gcreate(file,"Group1",-1); - - /* Close a group */ - ret = H5Gclose(group); - - /* Create a dataset */ - dataset=H5Dcreate(file,"Dataset1",H5T_STD_U32LE,sid,H5P_DEFAULT); - - /* Close Dataset */ - ret = H5Dclose(dataset); - - /* Create a datatype */ - tid = H5Tcreate (H5T_COMPOUND, sizeof(s1_t)); - - /* Insert fields */ - ret=H5Tinsert (tid, "a", HOFFSET(s1_t,a), H5T_NATIVE_INT); - - ret=H5Tinsert (tid, "b", HOFFSET(s1_t,b), H5T_NATIVE_INT); - - ret=H5Tinsert (tid, "c", HOFFSET(s1_t,c), H5T_NATIVE_FLOAT); - - /* Save datatype for later */ - ret=H5Tcommit (file, "Datatype1", tid); - - /* Close datatype */ - ret = H5Tclose(tid); - - /* Iterate through the file to see members of the root group */ - - printf(" Objects in the root group are:\n"); - printf("\n"); - - H5Giterate(file, "/", NULL, file_info, NULL); - - /* Close file */ - ret = H5Fclose(file); - - return 0; -} - -/* - * Operator function. - */ -herr_t file_info(hid_t loc_id, const char *name, void *opdata) -{ - H5G_stat_t statbuf; - - /* - * Get type of the object and display its name and type. - * The name of the object is passed to this function by - * the Library. Some magic :-) - */ - H5Gget_objinfo(loc_id, name, FALSE, &statbuf); - switch (statbuf.type) { - case H5G_GROUP: - printf(" Object with name %s is a group \n", name); - break; - case H5G_DATASET: - printf(" Object with name %s is a dataset \n", name); - break; - case H5G_TYPE: - printf(" Object with name %s is a named datatype \n", name); - break; - default: - printf(" Unable to identify an object "); - } - return 0; - } - -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + Object with name Dataset1 is a dataset + Object with name Datatype1 is a named datatype + Object with name Group1 is a group </PRE> -The output of this program is: +<I><U>Output from FORTRAN Example</U></I> <PRE> - Objects in the root group are: - - Object with name Dataset1 is a dataset - Object with name Datatype1 is a named datatype - Object with name Group1 is a group -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + Number of root group member is 1 + MyGroup 1 + Number of group MyGroup member is 2 + Group_A 1 + dset1 2 + Number of group MyGroup/Group_A member is 1 + dset2 2 </PRE> -<A NAME="rem"> -<H3><U>Remarks</U></H3> +<A NAME="remc"> +<H3><U>Remarks for C Example</U></H3> <P> <UL> <LI> The operator function in this example is called <I>file_info</I>. The signature of the operator function is as follows: <PRE> - herr_t *(H5G_operator_t) (hid_group_id, const char* name, void *operator_data) + herr_t *(H5G_operator_t) (hid group_id, const char* name, + void *operator_data) </PRE> <UL> - <LI>The first parameter is a group identifier for the group being iterated - over. It is passed to the operator by the iterator function, H5Giterate. - <LI> The second parameter is the name of the current object. The name is - passed to the operator function by the HDF5 library. - <LI> The third parameter is the operator data. It is passed to and from - the operator by the iterator, H5Giterate. - - The operator function in this example just prints the name and type + <LI>The <em>group_id</em> parameter is a group identifier for the + group being iterated over. + It is passed to the operator by the iterator function, + <CODE>H5Giterate</CODE>. +<P> + <LI>The <em>name</em> parameter is the name of the current object. + The name is passed to the operator function by the HDF5 library. +<P> + <LI> The <em>operator_data</em> parameter is the operator data. + It is passed to and from + the operator by the iterator, <CODE>H5Giterate</CODE>. +</UL> +<P> + The operator function in this example simply prints the name and type of the current object and then exits. - This information can also be used to open the object and perform different operations or queries. For example a named datatype object's name can be used to open the datatype and query its properties. -</UL> <P> The operator return value defines the behavior of the iterator. <UL> +<P> <LI>A zero return value causes the iterator to continue, returning zero when all group members have been processed. +<P> <LI>A positive value causes the iterator to immediately return that value, indicating a short-circuit success. The iterator can be restarted at the next group member. +<P> <LI>A negative value causes the iterator to immediately return that value, indicating failure. The iterator can be restarted at the next group member. @@ -222,56 +147,119 @@ The output of this program is: In this example the operator function returns 0, which causes the iterator to continue and go through all group members. <P> -<LI>The function H5Gget_objinfo is used to determine the type of the object. +<LI>The function <CODE>H5Gget_objinfo</CODE> is used to determine the type of the object. It also returns the modification time, number of hard links, and some other information. <P> The signature of this function is as follows: <PRE> - herr_t H5Gget_objinfo(hid_t loc_id, const char * name, hbool_t follow_link, + herr_t H5Gget_objinfo (hid_t loc_id, const char * name, + hbool_t follow_link, H5G_stat_t *statbuf) </PRE> <UL> - <LI> The first two arguments specify the object by its location and name. + <LI>The <em>loc_id</em> and <em>name</em> arguments + specify the object by its location and name. This example uses the group identifier and name relative to the group to specify the object. - <LI> The third argument is a flag which indicates whether a - symbolic link should be followed or not. A zero value indicates +<P> + <LI>The <em>follow_link</em> argument is a flag which indicates + whether a symbolic link should be followed. A zero value indicates that information should be returned for the link itself, but not about the object it points to. +<P> The root group in this example does not have objects that are links, so this flag is not important for our example. - <LI> The fourth argument is a buffer to return information in. - Type information is returned into the field "type" of the - H5G_stat_t data structure (statbuf.type). Possible values are: - H5G_GROUP, H5G_DATASET, H5G_TYPE, and H5G_LINK. +<P> + <LI>The <em>statbuf</em> argument is the buffer in which to return + information. + Type information is returned into the field <em>type</em> of the + <CODE>H5G_stat_t</CODE> data structure (<code>statbuf.type</code>). + Valid values are + <CODE>H5G_GROUP</CODE>, <CODE>H5G_DATASET</CODE>, + <CODE>H5G_TYPE</CODE>, and <CODE>H5G_LINK</CODE>. </UL> <P> -<LI> The H5Giterate function has the following signature: +<LI> The <CODE>H5Giterate</CODE> function has the following signature: <PRE> - int H5Giterate(hid_t loc_id, const char *name , idx, - H5G_operator_t operator, void * operator_data) + int H5Giterate (hid_t loc_id, const char *name , int *idx, + H5G_operator_t operator, void * operator_data) </PRE> <UL> - <LI> The first parameter is the group for the group being iterated over. - <LI> The second parameter is the group name. - <LI> The third parameter specifies that iteration begins with the - <I>idx</I> object in the group and the next element to be processed - is returned in the <I>idx</I> parameter. In our example NULL is + <LI> The <em>loc_id</em> parameter is the group identifier for the + group being iterated over. + <LI> The <em>name</em> parameter is the group name. + <LI> The <em>idx</em> parameter is an index specifying that iteration + begins with the <em>idx</em>-th object in the group. + Upon the function's return, the index of the next element + to be processed is returned in <I>idx</I>. In our example, NULL is used to start at the first group member. Since no stopping point is returned in this case, the iterator cannot be restarted if one of the calls to its operator returns a non-zero value. - <LI> The fourth parameter is an operator function. - <LI> The fifth argument is the operator data. We used NULL since no - data was passed to and from the operator. + <LI> The <em>operator</em> parameter is the operator function. + <LI> The <em>operator_data</em> argument is the operator data. + We used NULL since no data was passed to or from the operator. </UL> </UL> -<!-- -<A NAME="fc"> -<H3><U>File Contents</U></H3> ---> - +<A NAME="remf"> +<H3><U>Remarks for FORTRAN Example</U></H3> +<P> +<UL> +<LI>This program creates an HDF5 file with groups in it and + then uses <CODE>h5gn_members_f</CODE> to get the number of members in + each group and <CODE>h5gget_obj_idx_f</CODE> to obtain the group member's + name and type. +<P> +<LI>The number of members in a group are obtained with the +<CODE>h5gn_members_f</CODE> call: +<PRE> + h5gn_members_f (loc_id, name, nmembers, hdferr) + + loc_id IN: INTEGER (HID_T) + name IN: CHARACTER (LEN=*) + nmembers OUT: INTEGER + hdferr OUT: INTEGER +</PRE> +<UL> + <LI>The <I>loc_id</I> parameter is the file or group identifier. + <LI>The <I>name</I> parameter is the name of the group to obtain the number + of members in. + <LI>The number of members in the group is returned in <I>nmembers</I>. + <LI>The <I>hdferr</I> parameter contains the return code from the + call: 0 if successful and -1 otherwise. +</UL> +<P> +<LI>The name of each group and its type are obtained with the +<CODE>h5gget_obj_info_idx_f</CODE> call: +<PRE> + h5gget_obj_info_idx_f (loc_id, name, idx, & + obj_name, obj_type, hdferr) + + loc_id IN: INTEGER (HID_T) + name IN: CHARACTER (LEN=*) + idx IN: INTEGER + obj_name OUT: CHARACTER (LEN=*) + obj_type OUT: INTEGER + hdferr OUT: INTEGER + </PRE> +<UL> +<LI>The <I>loc_id</I> parameter is the file or group identifier. +<LI>The <I>name</I> parameter is the name of the group. +<LI>The <I>idx</I> parameter is the index of the member object. +<LI>The <I>obj_name</I> parameter is the name of the object that gets returned. +<LI>The <I>obj_type</I> parameter is the object type that gets returned. + Valid values are as follows: +<PRE> + H5G_LINK_F + H5G_GROUP_F + H5G_DATASET_F + H5G_TYPE_F +</PRE> +<LI>The <I>hdferr</I> parameter contains the return code from the + call: 0 if successful and -1 otherwise. +</UL> +</UL> @@ -290,8 +278,11 @@ The output of this program is: <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: January 19, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/mount.html b/doc/html/Tutor/mount.html index 9d0e494..fc37149 100644 --- a/doc/html/Tutor/mount.html +++ b/doc/html/Tutor/mount.html @@ -35,244 +35,196 @@ width=78 height=27 alt="NCSA"><P></A> <A NAME="def"> <H2>Mounting Files</H2> -HDF5 allows you to combine two or more HDF5 files in a manner similar to mounting -files in UNIX. The group structure and metadata from one file appear as though +HDF5 allows you to combine two or more HDF5 files in memory +in a manner similar to mounting files in UNIX. +The group structure and metadata from one file appear as though they exist in another file. The following steps are involved: <OL> <LI>Open the files. -<LI>Choose the "mount point" in the first file (parent). The "mount point" in - HDF5 is a group ( it can also be the root group ). +<LI>Choose the <strong>mount point</strong> in the first file + (the parent file). The mount point in + HDF5 is a group, which CANNOT be the root group. -<LI>Use the HDF5 API function H5Fmount to mount the second file (child) in - the first one. +<LI>Use the HDF5 routine <CODE>H5Fmount</CODE> / <CODE>h5fmount_f</CODE> + to mount the second file (the child file) in the first file. <LI>Work with the objects in the second file as if they were members of - the "mount point" group in the first file. The previous contents of - the "mount point" group are temporarily hidden. + the mount point group in the first file. The previous contents of + the mount point group are temporarily hidden. -<LI>Unmount the second file using the H5Funmount function when the work is done. +<LI>Unmount the second file using <CODE>H5Funmount</CODE> / + <CODE>h5funmount_f</CODE> when the work is done. </OL> <H2> Programming Example</H2> <A NAME="desc"> <H3><U>Description</U></H3> -In the following example we create one file with a group in it, and another -file with a dataset. Mounting is used to access the dataset from the second -file as a member of a group in the first file. The following picture -illustrates this concept. +In the following example, we create one file containing a group and +another file containing a dataset. +Mounting is used to access the dataset from the second +file as a member of a group in the first file. +The following figures illustrate this concept. <PRE> - 'FILE1' 'FILE2' + FILE1 FILE2 --------------------- -------------------- -! ! ! ! -! / ! ! / ! -! | ! ! | ! -! | ! ! | ! -! V ! ! V ! -! -------- ! ! ---------- ! -! ! Group ! ! ! ! Dataset! ! -! --------- ! ! ---------- ! -!------------------! !------------------! + -------------------- -------------------- + ! ! ! ! + ! / ! ! / ! + ! | ! ! | ! + ! | ! ! | ! + ! V ! ! V ! + ! -------- ! ! ---------- ! + ! ! Group ! ! ! ! Dataset! ! + ! --------- ! ! ---------- ! + !------------------! !------------------! </PRE> -After mounting the second file, 'FILE2', under the group in the file, 'FILE1', -the parent has the following structure: +After mounting <code>FILE2</code> under the group in <code>FILE1</code>, +the parent file has the following structure: <PRE> - 'FILE1' + FILE1 - -------------------- - ! ! - ! / ! - ! | ! - ! | ! - ! V ! - ! -------- ! - ! ! Group ! ! - ! --------- ! - ! | ! - ! | ! - ! V ! - ! ----------- ! - ! ! Dataset ! ! - ! !---------- ! - ! ! - !------------------! + -------------------- + ! ! + ! / ! + ! | ! + ! | ! + ! V ! + ! -------- ! + ! ! Group ! ! + ! --------- ! + ! | ! + ! | ! + ! V ! + ! ----------- ! + ! ! Dataset ! ! + ! !---------- ! + ! ! + !------------------! </PRE> -[ <A HREF="examples/h5_mount.c">Download h5_mount.c</A> ] -<PRE> -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include<hdf5.h> - -#define FILE1 "mount1.h5" -#define FILE2 "mount2.h5" - -#define RANK 2 -#define NX 4 -#define NY 5 - -int main(void) -{ - - hid_t fid1, fid2, gid; /* Files and group identifiers */ - hid_t did, tid, sid; /* Dataset and datatype identifiers */ - - herr_t status; - hsize_t dims[] = {NX,NY}; /* Dataset dimensions */ - - int i, j; - int bm[NX][NY], bm_out[NX][NY]; /* Data buffers */ - - /* - * Initialization of buffer matrix "bm" - */ - for(i =0; i < NX; i++) { - for(j = 0; j < NY; j++) - bm[i][j] = i + j; - } - - /* - * Create first file and a group in it. - */ - fid1 = H5Fcreate(FILE1, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - gid = H5Gcreate(fid1, "/G", 0); - - /* - * Close group and file - */ - H5Gclose(gid); - H5Fclose(fid1); - - /* - * Create second file and dataset "D" in it. - */ - fid2 = H5Fcreate(FILE2, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - dims[0] = NX; - dims[1] = NY; - sid = H5Screate_simple(RANK, dims, NULL); - did = H5Dcreate(fid2, "D", H5T_NATIVE_INT, sid, H5P_DEFAULT); - - /* - * Write data to the dataset. - */ - status = H5Dwrite(did, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, bm); - - /* - * Close all identifiers. - */ - H5Sclose(sid); - H5Dclose(did); - H5Fclose(fid2); - - /* - * Reopen both files - */ - fid1 = H5Fopen(FILE1, H5F_ACC_RDONLY, H5P_DEFAULT); - fid2 = H5Fopen(FILE2, H5F_ACC_RDONLY, H5P_DEFAULT); - - /* - * Mount second file under G in the first file. - */ - H5Fmount(fid1, "/G", fid2, H5P_DEFAULT); - - /* - * Access dataset D in the first file under /G/D name. - */ - did = H5Dopen(fid1,"/G/D"); - tid = H5Dget_type(did); - status = H5Dread(did, tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, bm_out); - - /* - * Print out the data. - */ - for(i=0; i < NX; i++){ - for(j=0; j < NY; j++) - printf(" %d", bm_out[i][j]); - printf("\n"); - } - - /* - * Close all identifers - */ - H5Tclose(tid); - H5Dclose(did); - - /* - * Unmounting second file - */ - H5Funmount(fid1, "/G"); +[ <A HREF="examples/h5_mount.c">C program</A> ] + - <code>h5_mount.c</code><BR> +[ <A HREF="examples/mount.f90">FORTRAN program</A> ] + - <code>mountexample.f90</code> +<P> - /* - * Close both files - */ - H5Fclose(fid1); - H5Fclose(fid2); +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. - return 0; -} -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -</PRE> <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> <LI> The first part of the program creates a group in one file and creates and writes a dataset to another file. <P> -<LI> Both files are reopened with the H5F_ACC_RDONLY access flag since no - objects will be modified. The child should be opened with H5F_ACC_RDWR if - the dataset is to be modified. +<LI> Both files are reopened and the second file is mounted in the first + using <CODE>H5Fmount</CODE> / <CODE>h5fmount_f</CODE>. + If no objects will be modified, the + files can be opened with <CODE>H5F_ACC_RDONLY</CODE> + (<CODE>H5F_ACC_RDONLY_F</CODE> in FORTRAN). + If the data is to be modified, the files should be opened with + <CODE>H5F_ACC_RDWR</CODE> (<CODE>H5F_ACC_RDWR_F</CODE> in FORTRAN). +<P> +<I><B>C:</B></I> +<pre> + herr_t H5Fmount (hid_t loc_id, const char *dsetname, + hid_t file_id, hid_t access_prp) +</pre> +<P> +<I><B>FORTRAN:</B></I> +<pre> + h5fmount_f (loc_id, dsetname, file_id, hdferr, access_prp) + + loc_id IN: INTEGER (HID_T) + dsetname IN: CHARACTER (LEN=*) + file_id IN: INTEGER (HID_T) + hdferr OUT: INTEGER + access_prp IN: INTEGER (HID_T), OPTIONAL + (Default value: H5P_DEFAULT_F) +</pre> <P> -<LI> The second file is mounted in the first using the H5Fmount function. -<PRE> - herr_t H5Fmount(hid_t loc_id, const char *name, hid_t file_id, hid_t plist_id) -</PRE> <UL> - <LI> The first two arguments specify the location of the "mount point" - ( a group ). In this example the "mount point" is a group "/G" in the - file specified by its handle <I>fid1</I>. Since group G is in the root - group of the first file, one can also use just "G" to identify it. + <LI> The <em>loc_id</em> and <em>dsetname</em> arguments + specify the location of the mount point. + In this example, the mount point is a group <code>/G</code> in the + specified file. Since the group <code>/G</code> is in the root + group of the first file, one can also use just <code>G</code> to + identify it. <P> - Below is a description of another scenario:<BR> - Suppose group G was a member of group D in the first file (<I>fid1</I>). - Then mounting point G can be specified in two different ways: + Below is a description of another scenario: + <p> + Suppose the group <code>G</code> were a member of + the group <code>H</code> in the first file. + Then the mount point <code>G</code> can be specified in + two different ways: <P> <UL> - <LI> <I>loc_id</I> is <I>fid1</I><BR> - <I>name</I> is "D/G" + <LI> <em>loc_id</em> is the file identifier for the first file.<BR> + <em>dsetname</em> is <code>H/G</code>. <P> - <LI> <I>loc_id</I> is an identifier of the group "D"<BR> - <I>name</I> is just "G" + <LI> <em>loc_id</em> is the identifier for the group <code>H</code>.<BR> + <em>dsetname</em> is <code>G</code>. </UL> <P> - <LI> The third argument is an identifier of the file which will be mounted. - Only one file can be mounted per "mount point". + <LI> The <em>file_id</em> argument is the identifier for the file + which will be mounted. + Only one file can be mounted per mount point. <P> - <LI> The fourth argument is an identifier of the property list to be used. - Currently, only the default property list, H5P_DEFAULT, can be used. + <LI> The <I>access_prp</I> argument is the identifier for the property list + to be used. Currently, only the default property list, + <CODE>H5P_DEFAULT</CODE>, can be used in C. + In FORTRAN, this argument can be omitted or + <CODE>H5P_DEFAULT_F</CODE> can be used. +<P> + <LI> The C function <CODE>H5Fmount</CODE> returns a non-negative + value if successful and a negative value otherwise. + With the FORTRAN routine, <CODE>h5fmount_f</CODE>, + the return value of the call is returned in <em>hdferr</em>: + 0 if successful and -1 otherwise. </UL> <P> -<LI> In this example we just read data from the dataset D. One can modify - data also. If the dataset is modified while the file is mounted, it becomes - modified in the original file too after the file is unmounted. +<LI>In this example, we only read data from the dataset <code>D</code>. + One can also modify data. + If the dataset is modified while the file is mounted, it is + modified in the original file after the file is unmounted. <P> -<LI> The file is unmounted with the H5Funmount function: -<PRE> - herr_t H5Funmount(hid_t loc_id, const char *name) -</PRE> - Arguments to this function specify the location of the "mount point". - In our example <I>loc_id</I> is an identifier of the first file, and - <I>name</I> is the name of group G, "/G". One could also use "G" - instead of "/G" since G is a member of the root group in the file - <I>fid1</I>. Notice that H5Funmount does not close files. They are closed - with the respective calls to the H5Fclose function. Closing the parent - automatically unmounts the child. +<LI> The file is unmounted with <CODE>H5Funmount</CODE> / +<CODE>h5funmount_f</CODE>: +<P> +<I><B>C:</B></I> +<pre> + herr_t H5Funmount (hid_t loc_id, const char *dsetname) +</pre> +<P> +<I><B>FORTRAN:</B></I> +<pre> + h5funmount_f (loc_id, dsetname, hdferr) + + loc_id IN: INTEGER (HID_T) + dsetname IN: CHARACTER (LEN=*) + hdferr OUT: INTEGER +</pre> +<P> +<ul> + <li>The <I>loc_id</I> and <I>dsetname</I> arguments specify the location + of the mount point. + In our example <I>loc_id</I> is the first file's file identifier + and <I>dsetname</I> is the name of group <code>/G</code>. +</ul> +<P> +<li>Note that <CODE>H5Funmount</CODE> / <CODE>h5funmount_f</CODE> + does not close files. Files are closed with the respective calls to + the <CODE>H5Fclose</CODE> / <CODE>h5fclose_f</CODE> function. +<P> +<li>Closing the parent file automatically unmounts the child file. <P> -<LI>The h5dump utility cannot display files in memory, therefore no output - of FILE1 after FILE2 was mounted is provided. +<LI>The <code>h5dump</code> utility cannot display files in memory. + Therefore, no output of <code>FILE1</code> after <code>FILE2</code> + was mounted is provided. </UL> </UL> @@ -291,8 +243,11 @@ int main(void) <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: January 19, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/property.html b/doc/html/Tutor/property.html new file mode 100644 index 0000000..9d40d44 --- /dev/null +++ b/doc/html/Tutor/property.html @@ -0,0 +1,169 @@ +<HTML><HEAD> +<TITLE>HDF5 Tutorial - Property Lists +</TITLE> +</HEAD> + +<body bgcolor="#ffffff"> + +<!-- BEGIN MAIN BODY --> + +<A HREF="http://www.ncsa.uiuc.edu/"><img border=0 +src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif" +width=78 height=27 alt="NCSA"><P></A> + + [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] +<H1> +<BIG><BIG><BIG><FONT COLOR="#c101cd">Property Lists</FONT> +</BIG></BIG></BIG></H1> + +<hr noshade size=1> + +<BODY> +<!-- +<H2>Contents:</H2> +<UL> + <LI> <A HREF="#def">Definition of Property Lists</A> +</UL> +<HR> +<A NAME="def"> +--> +<P> +The property list interface provides a mechanism for adding functionality +to HDF5 calls, without increasing the number of arguments used +for a given call. +<P> +A property list is a collection of values which can +be passed to various HDF5 functions to control features that +are typically unimportant or whose default values are usually used +(by specifying <code>H5P_DEFAULT</code> / <CODE>H5P_DEFAULT_F</CODE>). +<P> +It supports unusual cases when: + +<UL> +<LI><A HREF="#cf">Creating Files</A> +<LI><A HREF="#fa">Accessing Files</A> +<LI><A HREF="#cd">Creating Datasets</A> +<LI><A HREF="#rdwt">Reading or Writing Data</A> +</UL> + + +<A NAME="cf"> +<H3>Creating Files</H3> +The File Creation property list, H5P_FILE_CREATE, applies to H5Fcreate() +only and is used to control the file metadata which is maintained in the +super block of the file. The parameters that can be modified are: +user-block size, offset and length sizes, symbol table parameters, +and index storage parameters. +<P> +The following example shows how to create a file with 64-bit object +offsets and lengths: +<PRE> + hid_t create_plist; + hid_t file_id; + + create_plist = H5Pcreate(H5P_FILE_CREATE); + H5Pset_sizes(create_plist, 8, 8); + + file_id = H5Fcreate("test.h5", H5F_ACC_TRUNC, + create_plist, H5P_DEFAULT); + . + . + . + H5Fclose(file_id); +</PRE> + +<A NAME="fa"> +<H3>Accessing Files</H3> +The File Access property list, H5P_FILE_ACCESS, applies to H5Fcreate() and +H5Fopen() and is used to control different methods of +performing I/O on files. The different types of I/O are: unbuffered I/O, +buffered I/O, memory I/O, parallel files using MPI I/O, and data alignment. +<P> +Following is an example of using the H5P_FILE_ACCESS property list for creating +HDF5 files with the metadata and data split into different files: +<BR> +[ <A HREF="examples/h5split.c">C program</A> ] + - <code>h5split.c</code><BR> +<P> + +<A NAME="cd"> +<h3>Creating Datasets</H3> +The Dataset Creation property list, H5P_DATASET_CREATE, applies to +H5Dcreate() and controls information on how raw data +is organized on disk and how the raw data is compressed. The dataset API +partitions these terms by layout, compression, and external storage: +<P> +<UL> + <LI>Layout: +<UL> +<LI>H5D_COMPACT: Data is small and can be stored in object header (<I>not + implemented yet</I>). This eliminates disk seek/read requests. +<P> +<LI>H5D_CONTIGUOUS: (default) The data is large, non-extendible, +non-compressible, non-sparse, and can be stored externally. +<P> +<LI>H5D_CHUNKED: The data is large and can be extended in any dimension. +It is partitioned into chunks so each chunk is the same logical size. +Following is an example that uses the H5P_DATASET_CREATE property list to create +a chunked and extendible dataset: +<BR> +[ <A HREF="examples/h5_extend.c">C program</A> ] + - <code>h5_extend.c</code><BR> +<P> +</UL> +<LI>Compression: (gzip compression) +<LI>External Storage Properties: The data must be contiguous to be stored + externally. It allows you to store the data in one or more non-HDF5 files. +Following is an example of using the H5P_DATASET_CREATE property list to +create a dataset in an external file: +<BR> +[ <A HREF="examples/h5_crtextd.c">C program</A> ] + - <code>h5_crtextd.c</code><BR> +<P> +</UL> +</UL> +<A NAME="rdwt"> +<H3>Reading or Writing Data</H3> + +The Data Transfer property list, H5P_DATASET_XFER, is used to control +various aspects of I/O, such as caching hints or collective I/O information. +<P> +The following code sets the maximum size for the type conversion buffer +and background buffer: +<PRE> + plist_xfer = H5Pcreate (H5P_DATASET_XFER); + H5Pset_buffer(plist_xfer, (hsize_t)NX*NY*NZ, NULL, NULL); + status = H5Dread (dataset, H5T_NATIVE_UCHAR, memspace, dataspace, + plist_xfer); +</PRE> +See:<BR> + [ <A HREF="examples/h5_xfer.c">C program</A> ] + - <code> h5_xfer.c</code><BR> + + +<!-- BEGIN FOOTER INFO --> + +<P><hr noshade size=1> +<font face="arial,helvetica" size="-1"> + <a href="http://www.ncsa.uiuc.edu/"><img border=0 + src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif" + width=78 height=27 alt="NCSA"><br> + The National Center for Supercomputing Applications</A><br> + <a href="http://www.uiuc.edu/">University of Illinois + at Urbana-Champaign</a><br> + <br> +<!-- <A HREF="helpdesk.mail.html"> --> +<A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> +hdfhelp@ncsa.uiuc.edu</A> +<br> +<BR> <H6>Last Modified: February 12, 2001</H6><BR> +<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +</FONT> +<BR> +<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> + +</BODY> +</HTML> + + + diff --git a/doc/html/Tutor/questions.html b/doc/html/Tutor/questions.html index 26153f3..92d9d36 100644 --- a/doc/html/Tutor/questions.html +++ b/doc/html/Tutor/questions.html @@ -1,5 +1,5 @@ <HTML><HEAD> -<TITLE>HDF5 Tutorial - Introductory Topics Questions +<TITLE>HDF5 Tutorial - Introductory Topics Quiz </TITLE> </HEAD> @@ -13,106 +13,125 @@ width=78 height=27 alt="NCSA"><P></A> [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] <H1> -<BIG><BIG><BIG><FONT COLOR="#c101cd">Introductory Topics Questions</FONT> +<BIG><BIG><BIG><FONT COLOR="#c101cd">Introductory Topics Quiz</FONT> </BIG></BIG></BIG></H1> <hr noshade size=1> -<PRE> -Section 2: HDF File Organization -================================ +<h3>Section 2: HDF File Organization</h3> -1. Name and describe the two primary objects that can be stored in an HDF5 - file: +<ol> +<li>Name and describe the two primary objects that can be stored in an HDF5 + file. -2. What is an attribute? +<p> +<li>What is an attribute? -3. Give the path name for an object called "harry" that is a member of a - group called "dick," which in turn is a member of the root group. +<p> +<li>Give the path name for an object called <code>harry</code> that is a member of a + group called <code>dick</code>, which, in turn, is a member of the root group. +</ol> -Section 3: The HDF5 API -======================= +<h3>Section 3: The HDF5 API</h3> -Describe the purpose of each of the following HDF5 APIs: +<ol> +<li>Describe the purpose of each of the following HDF5 APIs: + <dir> + H5A, H5D, H5E, H5F, H5G, H5T, H5Z + </dir> +</ol> -H5A, H5D, H5E, F5F, H5G, H5T, H5Z +<h3>Section 4: Creating an HDF5 File</h3> +<ol> +<li>What two HDF5 routines must be called to create an HDF5 file? -Section 4: Creating an HDF File -=============================== +<p> +<li>What include file must be included in any file that uses the HDF5 library? -1. What two HDF5 routines must be called in order to create an HDF5 file? +<p> +<li>An HDF5 file is never completely empty because as soon as it is created, + it automatically contains a certain primary object. What is that object? +</ol> -2. What include file must be included in any file that uses the HDF5 library. -3. An HDF5 file is never completely empty because as soon as an HDF5 file - is created, it automatically contains a certain primary object. What is - that object? +<h3>Section 5: Creating a Dataset</h3> +<ol> +<li>Name and describe two major datatype categories. +<p> +<li>List the HDF5 atomic datatypes. Give an example of a predefined datatype. -Section 5: Creating a Dataset -============================= +<p> +<li>What does the dataspace describe? What are the major characteristics of + the simple dataspace? -1. Name and describe two major datatype categories. +<p> +<li>What information needs to be passed to the <code>H5Dcreate</code> + function, i.e., what information is needed to describe a dataset at + creation time? +</ol> -2. List the HDF5 atomic datatypes. Give an example of a predefined datatype. -3. What does the dataspace describe? What are the major characteristics of the - simple dataspace? +<h3>Section 6: Reading from and Writing to a Dataset</h3> -4. What information needs to be passed to the H5Dcreate function, i.e. - what information is needed to describe a dataset at creation time? - - -Section 6: Reading from/Writing to a Dataset -============================================ - -1. What are six pieces of information which need to be specified for +<ol> +<li>What are six pieces of information which need to be specified for reading and writing a dataset? -2. Why are both the memory dataspace and file dataspace needed for - read/write operations, but only the memory datatype is specified for the - datatype? +<p> +<li>Why are both the memory dataspace and file dataspace needed for + read/write operations, while only the memory datatype is required? -3. What does the line DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } in Fig 6.1 - means? +<p> +<li>What does the line + <br> + <code>DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } </code> + <br>in Figure 6.1 mean? +</ol> -Section 7: Creating an Attribute -================================ +<h3>Section 7: Creating an Attribute</h3> -1. What is an attribute? +<ol> +<li>What is an attribute? -2. Can partial I/O operations be performed on attributes? +<p> +<li>Can partial I/O operations be performed on attributes? +</ol> -Section 8: Creating a Group -=========================== +<h3>Section 8: Creating a Group</h3> -What are the two primary objects that can be included in -a group? +<ol> +<li>What are the two primary objects that can be included in a group? +</ol> -Section 9: Creating Groups using Absolute/Relative Names -======================================================== +<h3>Section 9: Creating Groups Using Absolute and Relative Names</h3> -1. Group names can be specified in two "ways". What are these - two types of group names that you can specify? +<ol> +<li>Group names can be specified in two ways. What are these two types + of group names? -2. You have a dataset named "moo" in the group "boo", which is - in the group "foo", which in turn, is in the root group. How would - you specify an absolute name to access this dataset? +<p> +<li>You have a dataset named <code>moo</code> in the group <code>boo</code>, which is + in the group <code>foo</code>, which, in turn, is in the root group. + How would you specify an absolute name to access this dataset? +</ol> -Section 10: Creating Datasets in Groups -======================================= +<h3>Section 10: Creating Datasets in Groups</h3> -Describe a way to access the dataset "moo" described in the previous section -(Section 9, question 2), using a relative and absolute pathname. +<ol> +<li>Describe a way to access the dataset <code>moo</code> described in the +previous section (Section 9, question 2) using a relative name. +Describe a way to access the same dataset using an absolute name. +</ol> </PRE> <!-- BEGIN FOOTER INFO --> @@ -129,7 +148,9 @@ Describe a way to access the dataset "moo" described in the previous section <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 2, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: January 13, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> diff --git a/doc/html/Tutor/rdwt.html b/doc/html/Tutor/rdwt.html index 1eb1a84..445bdf2 100644 --- a/doc/html/Tutor/rdwt.html +++ b/doc/html/Tutor/rdwt.html @@ -1,5 +1,5 @@ <HTML><HEAD> -<TITLE>HDF5 Tutorial - Reading to/Writing from a Dataset +<TITLE>HDF5 Tutorial - Reading from and Writing to a Dataset </TITLE> </HEAD> @@ -13,7 +13,7 @@ width=78 height=27 alt="NCSA"><P></A> [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] <H1> -<BIG><BIG><BIG><FONT COLOR="#c101cd">Reading to/Writing from a Dataset</FONT> +<BIG><BIG><BIG><FONT COLOR="#c101cd">Reading from and Writing to a Dataset</FONT> </BIG></BIG></BIG></H1> <hr noshade size=1> @@ -21,7 +21,7 @@ width=78 height=27 alt="NCSA"><P></A> <BODY> <H2>Contents:</H2> <UL> - <LI><A HREF="#rdwr">Reading to/Writing from a Dataset</A> + <LI><A HREF="#rdwr">Reading from and Writing to a Dataset</A> <LI> Programming Example <UL> <LI> <A HREF="#desc">Description </A> @@ -31,54 +31,74 @@ width=78 height=27 alt="NCSA"><P></A> </UL> <HR> <A NAME="rdwr"> -<H2>Reading to/Writing from a Dataset</h2> +<H2>Reading from and Writing to a Dataset</h2> <P> During a dataset I/O operation, the library transfers raw data between memory -and the file. The memory can have a data type different than the file data type -and can also be a different size (memory is a subset of the dataset elements, -or vice versa). Therefore, to perform read or write operations, the application +and the file. The data in memory can have a datatype different from that of +the file and can also be of a different size +(i.e., the data in memory is a subset of the dataset elements, or vice versa). +Therefore, to perform read or write operations, the application program must specify: <UL> <LI> The dataset - <LI> The dataset's data type in memory + <LI> The dataset's datatype in memory <LI> The dataset's dataspace in memory <LI> The dataset's dataspace in the file - <LI> The transfer properties (The data transfer properties control various - aspects of the I/O operations like the number of processes participating - in a collective I/O request or hints to the library to control caching of - raw data. In this tutorial, we use the default transfer properties.) + <LI>The dataset transfer property list + (The dataset transfer property list controls various aspects of the + I/O operations, such as the number of processes participating in a + collective I/O request or hints to the library to control caching of + raw data. In this tutorial, we use the default dataset transfer + property list.) <LI> The data buffer </UL> <P> -The steps to read to/write from a dataset are +The steps to read from or write to a dataset are as follows: <OL> <LI> Obtain the dataset identifier. - <LI> Specify the memory data type. + <LI> Specify the memory datatype. <LI> Specify the memory dataspace. <LI> Specify the file dataspace. <LI> Specify the transfer properties. <LI> Perform the desired operation on the dataset. <LI> Close the dataset. - <LI> Close the dataspace/data type, and property list if necessary. + <LI> Close the dataspace, datatype, and property list if necessary. </OL> -To read to/write from a dataset, the calling program must contain the following call: +To read from or write to a dataset, +the <code>H5Dread</code>/<code>h5dread_f</code> and +<code>H5Dwrite</code>/<code>h5dwrite_f</code> +routines are used. <P> +<I>C</I>: <PRE> - H5Dread(dataset_id, mem_type_id, mem_space_id, file_space_id, - xfer_plist_id, buf ); -</PRE> - or + 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); + +</PRE> +<I>FORTRAN</I>: <PRE> - H5Dwrite(dataset_id, mem_type_id, mem_space_id, file_space_id, - xfer_plist_id, buf); + CALL h5dread_f(dset_id, mem_type_id, buf, error, & + mem_space_id=mspace_id, file_space_id=fspace_id, & + xfer_prp=xfer_plist_id) + <font face=times><i>or</i></font> + CALL h5dread_f(dset_id, mem_type_id, buf, error) + + + CALL h5dwrite_f(dset_id, mem_type_id, buf, error, & + mem_space_id=mspace_id, file_space_id=fspace_id, & + xfer_prp=xfer_plist_id) + <font face=times><i>or</i></font> + CALL h5dwrite_f(dset_id, mem_type_id, buf, error) </PRE> @@ -88,130 +108,241 @@ To read to/write from a dataset, the calling program must contain the following <H3><U>Description</U></H3> The following example shows how to read and write an existing dataset. It opens the file created in the previous example, obtains the dataset -identifier, -<I>/dset</I>, writes the dataset to the file, then reads the dataset back from +identifier for the dataset <code>/dset</code>, +writes the dataset to the file, then reads the dataset back from memory. It then closes the dataset and file. <BR> -[ <A HREF="examples/h5_rdwt.c">Download h5_rdwt.c</A> ] - -<PRE> - -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <hdf5.h> -#define FILE "dset.h5" - -main() { - - hid_t file_id, dataset_id; /* identifiers */ - herr_t status; - int i, j, dset_data[4][6]; - - /* Initialize the dataset. */ - for (i = 0; i < 4; i++) - for (j = 0; j < 6; j++) - dset_data[i][j] = i * 6 + j + 1; - - /* Open an existing file. */ - file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT); - - /* Open an existing dataset. */ - - dataset_id = H5Dopen(file_id, "/dset"); - - /* Write the dataset. */ - status = H5Dwrite(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, - dset_data); - - status = H5Dread(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, - dset_data); +<UL> +[ <A HREF="examples/h5_rdwt.c">C Example</A> ] - <code>h5_rdwt.c</code> <BR> +[ <A HREF="examples/rwdsetexample.f90">FORTRAN Example</A> ] - <code>rwdsetexample.f90</code><BR> +[ <A HREF="examples/java/DatasetRdWt.java">Java Example</A> ] - <code>DatasetRdWt.java</code> <BR> +</UL> - /* Close the dataset. */ - status = H5Dclose(dataset_id); +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. - /* Close the file. */ - status = H5Fclose(file_id); -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ </PRE> <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI> H5Fopen opens an existing file and returns a file identifier. +<LI><code>H5Fopen</code>/<code>h5fopen_f</code> opens an existing file and + returns a file identifier. <PRE> - hid_t H5Fopen (const char *name, unsigned flags, hid_t access_id) -</PRE> -<UL> - <LI> The first argument is the file name. +<I>C</I>: + hid_t H5Fopen (const char *name, unsigned access_mode, hid_t access_prp) + +<I>FORTRAN</I>: + h5fopen_f (name, access_mode, file_id, hdferr, access_prp) - <LI> The second argument is the file access mode. H5F_ACC_RDWR allows a file - to be read from and written to. + name CHARACTER(LEN=*) + access_mode INTEGER + (Possible values: H5F_ACC_RDWR_F, H5F_ACC_RDONLY_F) + file_id INTEGER(HID_T) + hdferr INTEGER + (Possible values: 0 on success and -1 on failure) + access_prp INTEGER(HID_T), OPTIONAL - <LI> The third parameter is the identifier for the file access property list. - H5P_DEFAULT specifies the default file access property list. +</PRE> +<UL> + <LI> The argument <I>name</I> is the filename. + <P> + <LI> The <I>access_mode</I> parameter is the file access mode. + <code>H5F_ACC_RDWR</code> in C + (<code>H5F_ACC_RDWR_F</code> in FORTRAN) + allows read/write access + while <code>H5F_ACC_RDONLY</code> in C + (<code>H5F_ACC_RDONLY_F</code> in FORTRAN) + allows read-only access. + + <P> + <LI> The <I>access_prp</I> parameter identifies the file access property list. + <code>H5P_DEFAULT</code> in C and <code>H5P_DEFAULT_F</code> in FORTRAN + specify the default file access property list. + This parameter is optional in FORTRAN; if it is omitted, the default file + access property list is used. + + <P> + <LI>In FORTRAN, the return code is passed back in the <I>hdferr</I> + parameter: 0 if successful, -1 if not. In C, the function returns + the file identifier if successful, and a negative value otherwise. </UL> <P> -<LI> H5Dopen opens an existing dataset with the name specified by the second - argument at the location specified by the first parameter, and returns an - identifier. +<LI> <code>H5Dopen</code>/<code>h5dopen_f</code> opens an existing dataset + with the name specified by <i>name</i> at the location specified by + <i>loc_id</i>. + For FORTRAN, the return value is passed in the <I>hdferr</I> parameter: + 0 if successful, -1 if not. For C, the function returns the dataset + identifier if successful, and a negative value if not. + <P> +<I>C</I>: <PRE> hid_t H5Dopen (hid_t loc_id, const char *name) </PRE> +<I>FORTRAN</I>: +<PRE> + h5dopen_f(loc_id, name, hdferr) + + loc_id INTEGER(HID_T) + name CHARACTER(LEN=*) + hdferr INTEGER + (Possible values: 0 on success and -1 on failure) +</PRE> + <P> -<LI> H5Dwrite writes raw data from an application buffer to the specified - dataset, converting from the data type and data space of the dataset in - memory to the data type and data space of the dataset in the file. +<LI><code>H5Dwrite</code>/<code>h5dwrite_f</code> writes raw data + from an application buffer to the specified + dataset, converting from the datatype and dataspace of the dataset in + memory to the datatype and dataspace of the dataset in the file. +<P> +<I>C</I>: +<PRE> + herr_t H5Dwrite (hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, + hid_t file_space_id, hid_t xfer_prp, const void * buf) +</PRE> +<I>FORTRAN</I>: <PRE> - herr_t H5Dwrite (hid_t dataset_id, hid_t mem_type_id, hid_t mem_space_id, - hid_t file_space_id, hid_t xfer_plist_id, const void * buf) + h5dwrite_f (dset_id, mem_type_id, buf, hdferr, mem_space_id, & + file_space_id, xfer_prp) + + dset_id INTEGER(HID_T) + mem_type_id INTEGER(HID_T) + buf(*,...*) TYPE + hdferr INTEGER + (Possible values: 0 on success and -1 on failure) + mem_space_id INTEGER(HID_T), OPTIONAL + (Default value: H5S_ALL_F) + file_space_id INTEGER(HID_T), OPTIONAL + (Default value: H5S_ALL_F) + xfer_prp INTEGER(HID_T), OPTIONAL + (Default value: H5P_DEFAULT_F) </PRE> <UL> - <LI> The first parameter is the identifier of the dataset. - - <LI> The second parameter is the identifier of the dataset's datatype in - memory. H5T_NATIVE_INT is an integer data type for the machine on which - the library was compiled. - - <LI> The third parameter is the identifier of the dataset's dataspace in - memory. H5S_ALL indicates that the dataset's dataspace in memory is the - same as that in the file. - - <LI> The fourth parameter is the identifier of the dataset's dataspace in the - file. H5S_ALL indicates that the entire dataspace of the dataset in the - file is referenced. - - <LI> The fifth parameter is the identifier of the data transfer propery list. - H5P_DEFAULT indicates that the default data transfer property list is used. - - <LI> The last parameter is the data buffer. + <LI> The <I>dset_id</I> is the dataset identifier. + <P> + + <LI> The <I>mem_type_id</I> parameter is the identifier of the dataset's + memory datatype. <code>H5T_NATIVE_INT</code> in C + (<code>H5T_NATIVE_INTEGER</code> in FORTRAN) is an integer datatype + for the machine on which the library was compiled. + <P> + + <LI> The <I>mem_space_id</I> parameter is the identifier of the dataset's + memory dataspace. <code>H5S_ALL</code> in C (<code>H5S_ALL_F</code> + in FORTRAN) is the default value and indicates that the whole dataspace + in memory is selected for the I/O operation. + This parameter is optional in FORTRAN; if it is omitted, the default + will be used. + <P> + + <LI> The <I>file_space_id</I> parameter is the identifier of the + dataset's file dataspace. + <code>H5S_ALL</code> in C (<code>H5S_ALL_F</code> in FORTRAN) + is the default value and indicates that the entire dataspace of + the dataset in the file is selected for the I/O operation. + This parameter is optional in FORTRAN; if it is omitted, the default + will be used. + <P> + + <LI> The <I>xfer_prp</I> parameter is the data transfer propery list + identifier. + <code>H5P_DEFAULT</code> in C + (<code>H5P_DEFAULT_F</code> in FORTRAN) is the default value and + indicates that the default data transfer property list is used. + This parameter is optional in FORTRAN; if it is omitted, the default + will be used. + <P> + + <LI> The <I>buf</I> parameter is the data buffer to write. + <P> + + <LI> In FORTRAN, the <I>hdferr</I> parameter is for the error code + passed back: 0 if successful, -1 if not. In C, this function + returns a non-negative value if successful; otherwise it returns + a negative value. </UL> <P> -<LI> H5Dread reads raw data from the specified dataset to an application buffer, +<LI><code>H5Dread</code>/<code>h5dread_f</code> reads raw data from the + specified dataset to an application buffer, converting from the file datatype and dataspace to the memory datatype and dataspace. +<P> +<I>C</I>: <PRE> - herr_t H5Dread (hid_t dataset_id, hid_t mem_type_id, hid_t mem_space_id, - hid_t file_space_id, hid_t xfer_plist_id, void * buf) + herr_t H5Dread (hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, + hid_t file_space_id, hid_t xfer_prp, void * buf) </PRE> -<UL> - <LI> The first parameter is the identifier of the dataset read from. - - <LI> The second parameter is the identifier of the dataset's memory datatype. - - <LI> The third parameter is the identifier of the dataset's memory dataspace. - - <LI> The fourth parameter is the identifier of the dataset's file dataspace. +<I>FORTRAN</I>: +<PRE> + h5dread_f (dset_id, mem_type_id, buf, hdferr, mem_space_id, & + file_space_id, xfer_prp) + + dset_id INTEGER(HID_T) + mem_type_id INTEGER(HID_T) + buf(*,...*) TYPE + hdferr INTEGER + (Possible values: 0 on success and -1 on failure) + mem_space_id INTEGER(HID_T), OPTIONAL + (Default value: H5S_ALL_F) + file_space_id INTEGER(HID_T), OPTIONAL + (Default value: H5S_ALL_F) + xfer_prp INTEGER(HID_T), OPTIONAL + (Default value: H5P_DEFAULT_F) - <LI> The fifth parameter is the identifier of the data transfer propery list. +</PRE> - <LI> The last parameter is the data buffer. +<p> +<UL> + <LI>The <I>dset_id</I> parameter is the dataset identifier. + <P> + + <LI>The <I>mem_type_id</I> parameter is the identifier of the dataset's + memory datatype. <code>H5T_NATIVE_INT</code> in C + (<code>H5T_NATIVE_INTEGER</code> in FORTRAN) is an integer datatype + for the machine on which the library was compiled. + <P> + + <LI>The <I>mem_space_id</I> parameter is the identifier of the dataset's + memory dataspace. <code>H5S_ALL</code> in C (<code>H5S_ALL_F</code> + in FORTRAN) is the default value and indicates that the whole dataspace + in memory is selected for the I/O operation. + This parameter is optional in FORTRAN; if it is omitted, the default + will be used. + <P> + + <LI>The <I>file_space_id</I> parameter is the identifier of the + dataset's file dataspace. + <code>H5S_ALL</code> in C (<code>H5S_ALL_F</code> in FORTRAN) + is the default value and indicates that the entire dataspace of + the dataset in the file is selected for the I/O operation. + This parameter is optional in FORTRAN; if it is omitted, the default + will be used. + + <P> + <LI>The <I>xfer_prp</I> parameter is the data transfer propery list + identifier. + <code>H5P_DEFAULT</code> in C + (<code>H5P_DEFAULT_F</code> in FORTRAN) is the default value and + indicates that the default data transfer property list is used. + This parameter is optional in FORTRAN; if it is omitted, the default + will be used. + <P> + + <LI> The <I>buf</I> parameter is the data buffer to read into. + <P> + + <LI> In FORTRAN, the <I>hdferr</I> parameter is for the error code + passed back: 0 if successful, -1 if not. In C, this function + returns a non-negative value if successful; otherwise it returns + a negative value. +</UL> </UL> -</OL> - <A NAME="fc"> <H3><U>File Contents</U></H3> -Figure 6.1 shows the contents of 'dset.h5'. +Figure 6.1a shows the contents of <code>dset.h5</code> (created by the C program). +<BR> +Figure 6.1b shows the contents of <code>dsetf.h5</code> (created by the FORTRAN +program). <P> - <B>Fig. 6.1</B> <I>'dset.h5' in DDL</I> + <B>Fig. 6.1a</B> <I><code>dset.h5</code> in DDL</I> <PRE> HDF5 "dset.h5" { GROUP "/" { @@ -228,6 +359,26 @@ Figure 6.1 shows the contents of 'dset.h5'. } } </PRE> +<P> + <B>Fig. 6.1b</B> <I><code>dsetf.h5</code> in DDL</I> +<PRE> +HDF5 "dsetf.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 6, 4 ) / ( 6, 4 ) } + DATA { + 1, 7, 13, 19, + 2, 8, 14, 20, + 3, 9, 15, 21, + 4, 10, 16, 22, + 5, 11, 17, 23, + 6, 12, 18, 24 + } + } +} +} +</PRE> @@ -246,8 +397,11 @@ Figure 6.1 shows the contents of 'dset.h5'. <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/references.html b/doc/html/Tutor/references.html index ca73587..fa9a7ca 100644 --- a/doc/html/Tutor/references.html +++ b/doc/html/Tutor/references.html @@ -33,6 +33,9 @@ width=78 height=27 alt="NCSA"><P></A> <A HREF="http://hdf.ncsa.uiuc.edu/HDF5/doc/H5.intro.html">http://hdf.ncsa.uiuc.edu/HDF5/doc/H5.intro.html</A> <BR> Overview of HDF5 with example programs. <P> + <LI><B>Tar file of HDF5 Tutorial Examples</B>: + <A HREF="http://hdf.ncsa.uiuc.edu/training/other-ex5/examples.tar">http://hdf.ncsa.uiuc.edu/training/other-ex5/examples.tar</A> +<P> <LI><B>Other Miscellaneous HDF5 Example Programs:</B> <A HREF="http://hdf.ncsa.uiuc.edu/training/other-ex5/">http://hdf.ncsa.uiuc.edu/training/other-ex5/</A> </UL> @@ -52,7 +55,9 @@ Overview of HDF5 with example programs. <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: September 28, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: November 10, 1999</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> diff --git a/doc/html/Tutor/reftoobj.html b/doc/html/Tutor/reftoobj.html index 43a6375..1860367 100644 --- a/doc/html/Tutor/reftoobj.html +++ b/doc/html/Tutor/reftoobj.html @@ -23,24 +23,19 @@ width=78 height=27 alt="NCSA"><P></A> <UL> <LI><A HREF="#def">References to Objects</A> <LI> <A HREF="#def1">Creating and Storing References to Objects</A> - <LI> Programming Example - <UL> - <LI> <A HREF="#desc1">Description</A> - <LI> <A HREF="#rem1">Remarks</A> - <LI> <A HREF="#fc1">File Contents</A> - </UL> <LI> <A HREF="#def2">Reading References and Accessing Objects Using References</A> <LI> Programming Example <UL> - <LI> <A HREF="#desc2">Description</A> - <LI> <A HREF="#rem2">Remarks</A> + <LI> <A HREF="#desc">Description</A> + <LI> <A HREF="#rem">Remarks</A> + <LI> <A HREF="#fc">File Contents</A> </UL> </UL> <HR> <A NAME="def"> <H2>References to Objects</H2> -In HDF5, objects (i.e. groups, datasets, and named data types) are usually +In HDF5, objects (i.e. groups, datasets, and named datatypes) are usually accessed by name. This access method was discussed in previous sections. There is another way to access stored objects - by reference. <P> @@ -58,398 +53,244 @@ to objects: <OL> <LI> Create the objects or open them if they already exist in the file. <P> -<LI> Create a dataset to store the objects' references. +<LI> Create a dataset to store references to the objects. <P> <LI> Create and store references to the objects in a buffer. <P> -<LI> Write a buffer with the references to the dataset. +<LI> Write the buffer containing the references to the dataset. </OL> +<A NAME="def2"> +<H2>Reading References and Accessing Objects Using References</H2> + +The following steps are involved in reading references to objects and +accessing objects using references: +<OL> +<LI> Open the dataset with the references and read them. The +<CODE>H5T_STD_REF_OBJ</CODE> + datatype must be used to describe the memory datatype. +<P> +<LI> Use the read reference to obtain the identifier of the object the + reference points to. +<P> +<LI> Open the dereferenced object and perform the desired operations. +<P> +<LI> Close all objects when the task is complete. +</OL> <H2> Programming Example</H2> -<A NAME="desc1"> +<A NAME="desc"> <H3><U>Description</U></H3> -The example below creates a group and two datasets and a named data type in the -group. References to these four objects are stored in the dataset in the root -group. [<A HREF="examples/h5_ref2objw.c">Download h5_ref2objw.c</A>] -<PRE> - -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <hdf5.h> - -#define FILE1 "trefer1.h5" - -/* 1-D dataset with fixed dimensions */ -#define SPACE1_NAME "Space1" -#define SPACE1_RANK 1 -#define SPACE1_DIM1 4 - -/* 2-D dataset with fixed dimensions */ -#define SPACE2_NAME "Space2" -#define SPACE2_RANK 2 -#define SPACE2_DIM1 10 -#define SPACE2_DIM2 10 - -int -main(void) { - hid_t fid1; /* HDF5 File IDs */ - hid_t dataset; /* Dataset ID */ - hid_t group; /* Group ID */ - hid_t sid1; /* Dataspace ID */ - hid_t tid1; /* Datatype ID */ - hsize_t dims1[] = {SPACE1_DIM1}; - hobj_ref_t *wbuf; /* buffer to write to disk */ - int *tu32; /* Temporary pointer to int data */ - int i; /* counting variables */ - const char *write_comment="Foo!"; /* Comments for group */ - herr_t ret; /* Generic return value */ - -/* Compound datatype */ -typedef struct s1_t { - unsigned int a; - unsigned int b; - float c; -} s1_t; - - /* Allocate write buffers */ - wbuf=(hobj_ref_t *)malloc(sizeof(hobj_ref_t)*SPACE1_DIM1); - tu32=malloc(sizeof(int)*SPACE1_DIM1); - - /* Create file */ - fid1 = H5Fcreate(FILE1, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - - /* Create dataspace for datasets */ - sid1 = H5Screate_simple(SPACE1_RANK, dims1, NULL); - - /* Create a group */ - group=H5Gcreate(fid1,"Group1",-1); - - /* Set group's comment */ - ret=H5Gset_comment(group,".",write_comment); - - /* Create a dataset (inside Group1) */ - dataset=H5Dcreate(group,"Dataset1",H5T_STD_U32LE,sid1,H5P_DEFAULT); - - for(i=0; i < SPACE1_DIM1; i++) - tu32[i] = i*3; - - /* Write selection to disk */ - ret=H5Dwrite(dataset,H5T_NATIVE_INT,H5S_ALL,H5S_ALL,H5P_DEFAULT,tu32); - - /* Close Dataset */ - ret = H5Dclose(dataset); - - /* Create another dataset (inside Group1) */ - dataset=H5Dcreate(group,"Dataset2",H5T_NATIVE_UCHAR,sid1,H5P_DEFAULT); - - /* Close Dataset */ - ret = H5Dclose(dataset); - - /* Create a datatype to refer to */ - tid1 = H5Tcreate (H5T_COMPOUND, sizeof(s1_t)); - - /* Insert fields */ - ret=H5Tinsert (tid1, "a", HOFFSET(s1_t,a), H5T_NATIVE_INT); - - ret=H5Tinsert (tid1, "b", HOFFSET(s1_t,b), H5T_NATIVE_INT); - - ret=H5Tinsert (tid1, "c", HOFFSET(s1_t,c), H5T_NATIVE_FLOAT); - - /* Save datatype for later */ - ret=H5Tcommit (group, "Datatype1", tid1); - - /* Close datatype */ - ret = H5Tclose(tid1); - - /* Close group */ - ret = H5Gclose(group); - - /* Create a dataset to store references */ - dataset=H5Dcreate(fid1,"Dataset3",H5T_STD_REF_OBJ,sid1,H5P_DEFAULT); - - /* Create reference to dataset */ - ret = H5Rcreate(&wbuf[0],fid1,"/Group1/Dataset1",H5R_OBJECT,-1); - - /* Create reference to dataset */ - ret = H5Rcreate(&wbuf[1],fid1,"/Group1/Dataset2",H5R_OBJECT,-1); - - /* Create reference to group */ - ret = H5Rcreate(&wbuf[2],fid1,"/Group1",H5R_OBJECT,-1); - - /* Create reference to named datatype */ - ret = H5Rcreate(&wbuf[3],fid1,"/Group1/Datatype1",H5R_OBJECT,-1); +The example below first creates a group in the file. +It then creates two datasets and a named datatype in that group. +References to these four objects are stored in a dataset in the root group. +<P> +After that, it opens and reads the reference dataset from the file created +previously, then dereferences the references. - /* Write selection to disk */ - ret=H5Dwrite(dataset,H5T_STD_REF_OBJ,H5S_ALL,H5S_ALL,H5P_DEFAULT,wbuf); +<UL> +[<A HREF="examples/h5_ref2obj.c">C example</A> ] + - <code>h5_ref2obj.c</code><BR> +[<A HREF="examples/refobjexample.f90">FORTRAN example</A> ] + - <code>refobjexample.f90</code> +</UL> +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. +<P> +Following is the output from the examples: +<PRE> + Data has been successfully written to the dataset + Stored datatype is of a FLOAT class +</PRE> - /* Close disk dataspace */ - ret = H5Sclose(sid1); - - /* Close Dataset */ - ret = H5Dclose(dataset); - /* Close file */ - ret = H5Fclose(fid1); - free(wbuf); - free(tu32); - return 0; -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -</PRE> -<A NAME="rem1"> +<A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI> The following code, -<PRE> - dataset = H5Dcreate ( fid1,"Dataset3",H5T_STD_REF_OBJ,sid1,H5P_DEFAULT ); -</PRE> - creates a dataset to store references. Notice that the H5T_SDT_REF_OBJ - data type is used to specify that references to objects will be - stored. The data type H5T_STD_REF_DSETREG is used to store the dataset +<LI> The following code creates a dataset in which to store the references. +<P> +<I><B>C:</B></I> <pre> + dset2_id = H5Dcreate (file_id, dsetname, H5T_STD_REF_OBJ, + space_id, H5P_DEFAULT); +</pre> +<P> +<I><B>FORTRAN:</B></I><pre> + CALL h5dcreate_f (file_id, dsetname, H5T_STD_REF_OBJ, & + space_id, dset2_id, hdferr) +</pre> +<P> + Notice that the <CODE>H5T_SDT_REF_OBJ</CODE> + datatype is used to specify that references to objects will be + stored. The datatype <CODE>H5T_STD_REF_DSETREG</CODE> is + used to store the dataset region references and will be discussed later in this tutorial. <P> -<LI>The next few calls to the H5Rcreate function create references to the -objects and store them in the buffer <I>wbuf</I>. The signature of the -H5Rcreate function is: -<PRE> - herr_t H5Rcreate ( void* buf, hid_t loc_id, const char *name, - H5R_type_t ref_type, hid_t space_id ) -</PRE> +<LI>The next few calls to <CODE>H5Rcreate</CODE> / <CODE>h5rcreate_f</CODE> + create references to the objects. The signature of + <CODE>H5Rcreate</CODE> / <CODE>h5rcreate_f</CODE> is as follows: +<P> +<I><B>C:</B></I> <pre> + herr_t H5Rcreate (void* ref, hid_t loc_id, const char *name, + H5R_type_t ref_type, hid_t space_id) +</pre> +<P> +<I><B>FORTRAN:</B></I> <pre> + h5rcreate_f (loc_id, name, ref, hdferr) + + loc_id IN: INTEGER (HID_T) + name IN: CHARACTER(LEN=*) + ref OUT: TYPE (hobj_ref_t_f) + hdferr OUT: INTEGER +</pre> +<P> + + <UL> - <LI> The first argument specifies the buffer to store the reference. - <LI> The second and third arguments specify the name of the referenced - object. In our example, the file identifier <I>fid1</I> and - absolute name of the dataset "/Group1/Dataset1" were used to - identify the dataset. One could also use the group identifier - of group "Group1" and the relative name of the dataset "Dataset1" - to create the same reference. - <LI> The fourth argument specifies the type of the reference. Our example - uses references to the objects (H5R_OBJECT). Another type of - reference, reference to the dataset region ( H5R_DATASET_REGION), + <LI> The <em>ref</em> argument specifies the buffer + in which to store the reference. +<P> + <LI> The <I>loc_id</I> and <I>name</I> arguments specify the name of + the referenced object. +<P> + <LI> In C, the <I>ref_type</I> argument specifies the type of the + reference. + Our example uses references to objects, <CODE>H5R_OBJECT</CODE>. + References to dataset regions, <CODE>H5R_DATASET_REGION</CODE>, will be discussed later in this tutorial. - <LI> The fifth argument specifies the space identifier. When references - to the objects are created it should be set to -1. +<P> + <LI> In C, the <I>space_id</I> argument specifies the dataspace + identifier. When references + to the objects are created, this argument should be set to -1. +<P> + <LI> In FORTRAN, the return value from the <CODE>h5rcreate_f</CODE> + call is in <I>hdferr</I>: 0 if successful, -1 otherwise. + In C, <CODE>H5Rcreate</CODE> returns a non-negative value if + successful and a negative value otherwise. +</UL> +<P> +<LI><CODE>H5Dwrite</CODE> / <CODE>h5dwrite_f</CODE> writes a + dataset containing the references. + Notice that the <CODE>H5T_SDT_REF_OBJ</CODE> datatype is used to + describe the dataset's memory datatype. +<P> </UL> +<UL> +<LI> <CODE>H5Dread</CODE> / <CODE>h5dread_f</CODE> + reads the dataset containing the + references to the objects. The <CODE>H5T_STD_REF_OBJ</CODE> memory + datatype was + used to read references to memory. +<P> +<LI> <CODE>H5Rdereference</CODE> / <CODE>h5rdereference_f</CODE> obtains + the object's identifier. The signature is as follows: +<P> +<I><B>C</B></I>: <pre> + hid_t H5Rdereference (hid_t dset_id, H5R_type_t ref_type, + void *ref) +</pre> +<P> +<I><B>FORTRAN</B></I>: <pre> + h5rdereference_f (dset_id, ref, obj_id, hdferr) + + dset_id IN: INTEGER (HID_T) + ref IN: TYPE (hobj_ref_t_f) + obj_id OUT: INTEGER (HID_T) + hdferr OUT: INTEGER +</pre> <P> -<LI>The H5Dwrite function writes a dataset with the references to the file. - Notice that the H5T_SDT_REF_OBJ data type is used to describe the - dataset's memory data type. + <UL> + <LI> The <I>dset_id</I> argument is the identifier of the dataset + containing the references. +<P> + <LI> In C, the <I>ref_type</I> argument specifies the reference type. +<P> + <LI> The <I>ref</I> argument is a buffer containing the reference + to be dereferenced. <P> + <LI> The C function returns the identifier of the object that the + reference points to or a negative value if it is unsuccessful. + In FORTRAN, the object identifier is returned in <I>obj_id</I> + and the return code is returned in <I>hdferr</I>. +<P> + In our simplified situation, we know what type of object was + stored in the dataset. When the type of the object is unknown, + <CODE>H5Rget_object_type</CODE> should be used to identify the type + of object the reference points to. + </UL> </UL> -<A NAME="fc1"> + + +<A NAME="fc"> <H3><U>File Contents</U></H3> -The contents of the "trefer1.h5" file created by this example are as follows: -<PRE> - Fig "trefer1.h5" -============================================================================== +<P> +<I><U>HDF5 File Created by C Example</U></I> +<p> +<B>Fig. A</B> <I><code>REF_OBJ.h5</code> in DDL</I> -HDF5 "trefer1.h5" { +<PRE> +HDF5 "REF_OBJ.h5" { GROUP "/" { - DATASET "Dataset3" { - DATATYPE { H5T_REFERENCE } - DATASPACE { SIMPLE ( 4 ) / ( 4 ) } - DATA { - DATASET 0:1696, DATASET 0:2152, GROUP 0:1320, DATATYPE 0:2268 + GROUP "GROUP1" { + GROUP "GROUP2" { } } - GROUP "Group1" { - DATASET "Dataset1" { - DATATYPE { H5T_STD_U32LE } - DATASPACE { SIMPLE ( 4 ) / ( 4 ) } - DATA { - 0, 3, 6, 9 - } - } - DATASET "Dataset2" { - DATATYPE { H5T_STD_U8LE } - DATASPACE { SIMPLE ( 4 ) / ( 4 ) } - DATA { - 0, 0, 0, 0 - } + DATASET "INTEGERS" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 5 ) / ( 5 ) } + DATA { + 1, 2, 3, 4, 5 } - DATATYPE "Datatype1" { - H5T_STD_I32BE "a"; - H5T_STD_I32BE "b"; - H5T_IEEE_F32BE "c"; + } + DATATYPE "MYTYPE" { + } + DATASET "OBJECT_REFERENCES" { + DATATYPE { H5T_REFERENCE } + DATASPACE { SIMPLE ( 4 ) / ( 4 ) } + DATA { + GROUP 0:1320, GROUP 0:2272, DATASET 0:2648, DATATYPE 0:3244 } } } } -=============================================================================== -</PRE> -Notice how the data in dataset "Dataset3" is described. The two numbers -with the colon in between represent a unique identifier of the object. These -numbers are constant for the life of the object. - -<A NAME="def2"> -<H2>Reading References and Accessing Objects Using References</H2> -The following steps are involved: -<OL> -<LI> Open the dataset with the references and read them. The H5T_STD_REF_OBJ - data type must be used to describe the memory data type. -<P> -<LI> Use the read reference to obtain the identifier of the object the - reference points to. -<P> -<LI> Open the dereferenced object and perform the desired operations. -<P> -<LI> Close all objects when the task is complete. -</OL> - -<H2> Programming Example</H2> -<A NAME="desc2"> -<H3><U>Description</U></H3> -The example below opens and reads dataset "Dataset3" from the file created -previously. Then the program dereferences the references to -dataset "Dataset1", the group and the named data type, and opens those objects. -The program reads and displays the dataset's data, the group's comment and -the number of members of the compound data type. -[ <A HREF="examples/h5_ref2objr.c">Download h5_ref2objr.c</A> ] +</PRE> +<I><U>HDF5 File Created by FORTRAN Example</U></I>: +<p> +<B>Fig. B</B> <I><code>FORTRAN.h5</code> in DDL</I> <PRE> -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <stdlib.h> -#include <hdf5.h> - -#define FILE1 "trefer1.h5" - -/* dataset with fixed dimensions */ -#define SPACE1_NAME "Space1" -#define SPACE1_RANK 1 -#define SPACE1_DIM1 4 - -int -main(void) -{ - hid_t fid1; /* HDF5 File IDs */ - hid_t dataset, /* Dataset ID */ - dset2; /* Dereferenced dataset ID */ - hid_t group; /* Group ID */ - hid_t sid1; /* Dataspace ID */ - hid_t tid1; /* Datatype ID */ - hobj_ref_t *rbuf; /* buffer to read from disk */ - int *tu32; /* temp. buffer read from disk */ - int i; /* counting variables */ - char read_comment[10]; - herr_t ret; /* Generic return value */ - - /* Allocate read buffers */ - rbuf = malloc(sizeof(hobj_ref_t)*SPACE1_DIM1); - tu32 = malloc(sizeof(int)*SPACE1_DIM1); - - /* Open the file */ - fid1 = H5Fopen(FILE1, H5F_ACC_RDWR, H5P_DEFAULT); - - /* Open the dataset */ - dataset=H5Dopen(fid1,"/Dataset3"); - - /* Read selection from disk */ - ret=H5Dread(dataset,H5T_STD_REF_OBJ,H5S_ALL,H5S_ALL,H5P_DEFAULT,rbuf); - - /* Open dataset object */ - dset2 = H5Rdereference(dataset,H5R_OBJECT,&rbuf[0]); - - /* Check information in referenced dataset */ - sid1 = H5Dget_space(dset2); - - ret=H5Sget_simple_extent_npoints(sid1); - - /* Read from disk */ - ret=H5Dread(dset2,H5T_NATIVE_INT,H5S_ALL,H5S_ALL,H5P_DEFAULT,tu32); - printf("Dataset data : \n"); - for (i=0; i < SPACE1_DIM1 ; i++) printf (" %d ", tu32[i]); - printf("\n"); - printf("\n"); - - /* Close dereferenced Dataset */ - ret = H5Dclose(dset2); - - /* Open group object */ - group = H5Rdereference(dataset,H5R_OBJECT,&rbuf[2]); - - /* Get group's comment */ - ret=H5Gget_comment(group,".",10,read_comment); - printf("Group comment is %s \n", read_comment); - printf(" \n"); - /* Close group */ - ret = H5Gclose(group); - - /* Open datatype object */ - tid1 = H5Rdereference(dataset,H5R_OBJECT,&rbuf[3]); - - /* Verify correct datatype */ - { - H5T_class_t tclass; - - tclass= H5Tget_class(tid1); - if ((tclass == H5T_COMPOUND)) - printf ("Number of compound datatype members is %d \n", H5Tget_nmembers(tid1)); - printf(" \n"); - } - - /* Close datatype */ - ret = H5Tclose(tid1); - - /* Close Dataset */ - ret = H5Dclose(dataset); - - /* Close file */ - ret = H5Fclose(fid1); - - /* Free memory buffers */ - free(rbuf); - free(tu32); - return 0; -} -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +HDF5 "FORTRAN.h5" { +GROUP "/" { + GROUP "GROUP1" { + GROUP "GROUP2" { + } + } + DATASET "INTEGERS" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 5 ) / ( 5 ) } + DATA { + 1, 2, 3, 4, 5 + } + } + DATATYPE "MyType" { + } + DATASET "OBJECT_REFERENCES" { + DATATYPE { H5T_REFERENCE } + DATASPACE { SIMPLE ( 4 ) / ( 4 ) } + DATA { + GROUP 0:1344, GROUP 0:2320, DATASET 0:2696, DATATYPE 0:3292 + } + } +} +} </PRE> -Following is the output of this program: -<PRE> - -Dataset data : - 0 3 6 9 - -Group comment is Foo! - -Number of compound datatype members is 3 -</PRE> -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -<A NAME="rem2"> -<H3><U>Remarks</U></H3> - -<UL> -<LI> The H5Dread function was used to read dataset "Dataset3" containing the - references to the objects. The H5T_STD_REF_OBJ memory data type was - used to read references to memory. <P> -<LI> H5Rdereference obtains the object's identifier. The signature of this - function is: -<PRE> - hid_t H5Rdereference (hid_t datatset, H5R_type_t ref_type, void *ref) -</PRE> - <UL> - <LI> The first argument is an identifier of the dataset with the references. - <LI> The second argument specifies the reference type. We used - H5R_OBJECT to - specify a reference to an object. Another type is - H5R_DATASET_REGION to specify a reference to a dataset region. - This will be discussed later in this tutorial. - <LI> The third argument is a buffer to store the reference to be read. - <LI> The function returns an identifier of the object the reference - points to. In our simplified situation we know what type was - stored in the dataset. When the type of the object is unknown, then - H5Rget_object_type should be used to identify the type of object - the reference points to. - </UL> -</UL> - +Notice how the data in the reference dataset is described. The two numbers +separated by a colon represent a unique identifier of the object. These +numbers are constant for the life of the object. <!-- BEGIN FOOTER INFO --> @@ -465,8 +306,11 @@ Number of compound datatype members is 3 <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: January 19, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/reftoreg.html b/doc/html/Tutor/reftoreg.html index 37940bf..1beba1d 100644 --- a/doc/html/Tutor/reftoreg.html +++ b/doc/html/Tutor/reftoreg.html @@ -22,17 +22,12 @@ width=78 height=27 alt="NCSA"><P></A> <UL> <LI> <A HREF="#def">References to Dataset Regions</A> <LI> <A HREF="#def1">Creating and Storing References to Dataset Regions</A> - <LI> Programming Example - <UL> - <LI> <A HREF="#desc1">Description</A> - <LI> <A HREF="#rem1">Remarks</A> - <LI> <A HREF="#fc1">File Contents</A> - </UL> <LI> <A HREF="#def2">Reading References to Dataset Regions</A> <LI> Programming Example <UL> - <LI> <A HREF="#desc2">Description</A> - <LI> <A HREF="#rem2">Remarks</A> + <LI> <A HREF="#desc">Description</A> + <LI> <A HREF="#rem">Remarks</A> + <LI> <A HREF="#fc">File Contents</A> </UL> </UL> <HR> @@ -41,481 +36,308 @@ width=78 height=27 alt="NCSA"><P></A> Previously you learned about creating, reading, and writing dataset selections. Here you will learn how to store dataset selections in a file, and how to read them back using references -to the dataset regions. +to dataset regions. <P> A dataset region reference points to the dataset selection by storing the relative file address of the dataset header and the global heap offset of the referenced selection. The selection referenced is located by retrieving the coordinates of the areas in the selection from the global heap. This internal mechanism of storing and retrieving dataset selections is transparent -to the user. A reference to the dataset selection ( region ) is constant for +to the user. A reference to a dataset selection (a region) is constant for the life of the dataset. <A NAME="def1"> <H2>Creating and Storing References to Dataset Regions</H2> The following steps are involved in creating and storing references to -the dataset regions: +dataset regions: <OL> -<LI> Create a dataset to store the dataset regions (selections). +<LI> Create a dataset in which to store the dataset regions (the selections). <P> -<LI> Create selections in the dataset(s). Dataset(s) should already exist in the - file. +<LI> Create selections in the dataset(s). +The dataset(s) should already exist in the file. <P> <LI> Create references to the selections and store them in a buffer. <P> -<LI> Write references to the dataset regions in the file. +<LI> Write the dataset region references to the file. <P> <LI> Close all objects. </OL> +<A NAME="def2"> +<H2>Reading References to Dataset Regions</H2> + +The following steps are involved in reading references to dataset +regions and referenced dataset regions (selections). +<OL> +<LI> Open and read the dataset containing references to the dataset regions. + The datatype <CODE>H5T_STD_REF_DSETREG</CODE> must be used during +the read operation. +<P> +<LI>Use <CODE>H5Rdereference</CODE> / <CODE>h5rdeference_f</CODE> to +obtain the dataset identifier from the read + dataset region reference. + <dir><dir><dir> + <B><font size=-1>OR</font></B> + </dir></dir></dir> + Use <CODE>H5Rget_region</CODE> / <CODE>h5rget_region_f</CODE> to obtain + the dataspace identifier for the dataset + containing the selection from the read dataset region reference. +<P> +<LI> Obtain information about the selection or read selected data from + the dataset. +<P> +<LI> Close all objects when they are no longer needed. +</OL> + <H2> Programming Example</H2> -<A NAME="desc1"> +<A NAME="desc"> <H3><U>Description</U></H3> -The example below creates a dataset in the file. Then it creates a +The example below first creates a dataset in the file. Then it creates a dataset to store references to the dataset regions (selections). The first selection is a 6 x 6 hyperslab. The second selection is a point selection in the same dataset. -References to both selections are created and stored in the buffer, and then +References to both selections are created and stored in the buffer and then written to the dataset in the file. +<P> +After creating the dataset and references, the program reads the dataset +containing the dataset region references. +It reads data from the dereferenced dataset and displays the number of +elements and raw data. Then it reads two selections, a hyperslab selection +and a point selection. The program queries a number of points in the +hyperslab and their coordinates and displays them. Then it queries a number of +selected points and their coordinates and displays the information.<BR> +<P> +To obtain the example, download: +<UL> +[<A HREF="examples/h5_ref2reg.c">C example</A> ] + - <code>h5_ref2reg.c</code><BR> +[<A HREF="examples/refregexample.f90">FORTRAN example</A> ] + - <code>refregexample.f90</code> +</UL> +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. +<P> -[<A HREF="examples/h5_ref2regw.c">Download h5_ref2regw.c</A>] +Following is the output from the examples: +<P> +<I><U>Output of C Example</U></I> <PRE> +Selected hyperslab: +0 0 0 3 3 4 0 0 0 +0 0 0 3 4 4 0 0 0 +Selected points: +1 0 0 0 0 0 0 0 6 +0 0 0 0 0 0 5 0 0 +</PRE> +<I><U>Output of FORTRAN Example</U></I> +<PRE> + Hyperslab selection -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <stdlib.h> -#include <hdf5.h> - -#define FILE2 "trefer2.h5" -#define SPACE1_NAME "Space1" -#define SPACE1_RANK 1 -#define SPACE1_DIM1 4 - -/* Dataset with fixed dimensions */ -#define SPACE2_NAME "Space2" -#define SPACE2_RANK 2 -#define SPACE2_DIM1 10 -#define SPACE2_DIM2 10 - -/* Element selection information */ -#define POINT1_NPOINTS 10 - -int -main(void) -{ - hid_t fid1; /* HDF5 File IDs */ - hid_t dset1, /* Dataset ID */ - dset2; /* Dereferenced dataset ID */ - hid_t sid1, /* Dataspace ID #1 */ - sid2; /* Dataspace ID #2 */ - hsize_t dims1[] = {SPACE1_DIM1}, - dims2[] = {SPACE2_DIM1, SPACE2_DIM2}; - hssize_t start[SPACE2_RANK]; /* Starting location of hyperslab */ - hsize_t stride[SPACE2_RANK]; /* Stride of hyperslab */ - hsize_t count[SPACE2_RANK]; /* Element count of hyperslab */ - hsize_t block[SPACE2_RANK]; /* Block size of hyperslab */ - hssize_t coord1[POINT1_NPOINTS][SPACE2_RANK]; - /* Coordinates for point selection */ - hdset_reg_ref_t *wbuf; /* buffer to write to disk */ - int *dwbuf; /* Buffer for writing numeric data to disk */ - int i; /* counting variables */ - herr_t ret; /* Generic return value */ - - - /* Allocate write & read buffers */ - wbuf=calloc(sizeof(hdset_reg_ref_t), SPACE1_DIM1); - dwbuf=malloc(sizeof(int)*SPACE2_DIM1*SPACE2_DIM2); - - /* Create file */ - fid1 = H5Fcreate(FILE2, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - - /* Create dataspace for datasets */ - sid2 = H5Screate_simple(SPACE2_RANK, dims2, NULL); - - /* Create a dataset */ - dset2=H5Dcreate(fid1,"Dataset2",H5T_STD_U8LE,sid2,H5P_DEFAULT); - - for(i=0; i < SPACE2_DIM1*SPACE2_DIM2; i++) - dwbuf[i]=i*3; - - /* Write selection to disk */ - ret=H5Dwrite(dset2,H5T_NATIVE_INT,H5S_ALL,H5S_ALL,H5P_DEFAULT,dwbuf); - - /* Close Dataset */ - ret = H5Dclose(dset2); - - /* Create dataspace for the reference dataset */ - sid1 = H5Screate_simple(SPACE1_RANK, dims1, NULL); - - /* Create a dataset */ - dset1=H5Dcreate(fid1,"Dataset1",H5T_STD_REF_DSETREG,sid1,H5P_DEFAULT); - - /* Create references */ - - /* Select 6x6 hyperslab for first reference */ - start[0]=2; start[1]=2; - stride[0]=1; stride[1]=1; - count[0]=6; count[1]=6; - block[0]=1; block[1]=1; - ret = H5Sselect_hyperslab(sid2,H5S_SELECT_SET,start,stride,count,block); - - /* Store first dataset region */ - ret = H5Rcreate(&wbuf[0],fid1,"/Dataset2",H5R_DATASET_REGION,sid2); - - /* Select sequence of ten points for second reference */ - coord1[0][0]=6; coord1[0][1]=9; - coord1[1][0]=2; coord1[1][1]=2; - coord1[2][0]=8; coord1[2][1]=4; - coord1[3][0]=1; coord1[3][1]=6; - coord1[4][0]=2; coord1[4][1]=8; - coord1[5][0]=3; coord1[5][1]=2; - coord1[6][0]=0; coord1[6][1]=4; - coord1[7][0]=9; coord1[7][1]=0; - coord1[8][0]=7; coord1[8][1]=1; - coord1[9][0]=3; coord1[9][1]=3; - ret = H5Sselect_elements(sid2,H5S_SELECT_SET,POINT1_NPOINTS,(const hssize_t **)coord1); - - /* Store second dataset region */ - ret = H5Rcreate(&wbuf[1],fid1,"/Dataset2",H5R_DATASET_REGION,sid2); - - /* Write selection to disk */ - ret=H5Dwrite(dset1,H5T_STD_REF_DSETREG,H5S_ALL,H5S_ALL,H5P_DEFAULT,wbuf); - - /* Close all objects */ - ret = H5Sclose(sid1); - ret = H5Dclose(dset1); - ret = H5Sclose(sid2); - - /* Close file */ - ret = H5Fclose(fid1); + 3*0, 2*3, 4, 3*0 + 3*0, 3, 2*4, 3*0 - free(wbuf); - free(dwbuf); - return 0; -} + Point selection -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + 1, 7*0, 6 + 6*0, 5, 2*0 </PRE> -<A NAME="rem1"> +<A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI> The code, -<PRE> - dset1=H5Dcreate(fid1,"Dataset1",H5T_STD_REF_DSETREG,sid1,H5P_DEFAULT); -</PRE> - creates a dataset to store references to the dataset(s) regions(selections). - Notice that the H5T_STD_REF_DSETREG data type is used. +<LI> The following code creates a dataset to store references to the + dataset(s) regions (selections). Notice that the + <CODE>H5T_STD_REF_DSETREG</CODE> datatype is used. +<P> +<I><B>C:</I></B> +<pre> + dset1 = H5Dcreate (file_id, dsetnamer, H5T_STD_REF_DSETREG, + spacer_id, creation_prp); +</pre> +<P> +<I><B>FORTRAN:</B></I> +<pre> + CALL h5dcreate_f (file_id, dsetnamer, H5T_STD_REF_DSETREG, & + spacer_id, dset1, hdferr, creation_prp) +</pre> <P> <LI> This program uses hyperslab and point selections. We used the dataspace - handle <I>sid2</I> for the calls to H5Sselect_hyperslab and - H5Sselect_elements. The handle was created when dataset "Dataset2" was + identifier for the calls to <CODE>H5Sselect_hyperslab</CODE> / + <CODE>h5sselect_hyperslab_f</CODE> and + <CODE>H5Sselect_elements</CODE> / <CODE>h5sselect_elements_f</CODE>. + The identifier was obtained when the dataset was created and it describes the dataset's dataspace. We did not close it when the dataset was closed to decrease the number of function calls used in the example. In a real application program, one should open the dataset and determine - its dataspace using the H5Dget_space function. + its dataspace using the <CODE>H5Dget_space</CODE> / + <CODE>h5dget_space_f</CODE> function. <P> -<LI> H5Rcreate is used to create a dataset region reference and store it in a - buffer. The signature of the function is: -<PRE> - herr_t H5Rcreate(void *buf, hid_t loc_id, const char *name, +<LI> <CODE>H5Rcreate</CODE> / <CODE>h5rcreate_f</CODE> is used to create a +dataset region reference. The signature of the function is as follows: +<P> +<I><B>C</B></I>: +<pre> + herr_t H5Rcreate (void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id) -</PRE> +</pre> +<P> +<I><B>FORTRAN</B></I>: +<pre> + h5rcreate_f (loc_id, name, space_id, ref, hdferr) + + loc_id IN: INTEGER (HID_T) + name IN: CHARACTER (LEN=*) + space_id IN: INTEGER (HID_T) + ref_type OUT: TYPE(hdset_reg_ref_t_f) + hdferr OUT: INTEGER +</pre> +<P> +<UL> + <LI> The <em>ref</em> argument specifies the buffer in which + to store the reference. +<P> + <LI> The <I>loc_id</I> and <I>name</I> arguments specify the + referenced dataset. +<P> + <LI> In C, the <I>ref_type</I> argument specifies the reference type. + Since we are creating references to the dataset regions, + the <CODE>H5R_DATASET_REGION</CODE> datatype is used. +<P> + <LI> The <I>space_id</I> argument is a dataspace identifier. + This dataspace includes a selection in the referenced dataset. +<P> + <LI> In C, the function <CODE>H5Rcreate</CODE> returns a non-negative + value if successful and a negative value otherwise. In FORTRAN, the + return code from the <CODE>h5rcreate_f</CODE> subroutine is + returned in <I>hdferr</I>: 0 if succesful and -1 otherwise. +</UL> +<P> +<LI> The dataset with the region references was read by + <CODE>H5Dread</CODE> / <CODE>h5dread_f</CODE> with + the <CODE>H5T_STD_REF_DSETREG</CODE> datatype specified. +<P> +<LI> The read reference can be used to obtain the dataset identifier, as we + did with the following call: +<P> +<I><B>C:</B></I> +<pre> + dset2 = H5Rdereference (dset1, H5R_DATASET_REGION, &ref_out[0]); +</pre> +<P> +<I><B>FORTRAN:</B></I> +<pre> + CALL h5rdereference_f (dset1, ref_out(1), dset2, hdferr) +</pre> +<P> + or to obtain spacial information ( dataspace and selection ) with the call + to <CODE>H5Rget_region</CODE> / <CODE>h5rget_region_f</CODE>: +<P> +<I><B>C:</B></I> +<pre> + dspace2 = H5Rget_region (dset1, H5R_DATASET_REGION, &ref_out[0]); +</pre> +<P> +<I><B>FORTRAN:</B></I> +<pre> + CALL H5rget_region_f (dset1, ref_out(1), dspace2, hdferr) +</pre> +<P> + The reference to the dataset region has information for both the dataset + itself and its selection. In both calls, <UL> - <LI> The first argument specifies the buffer to store the reference. - <LI> The second and third arguments specify the name of the referenced - dataset. In our example the file identifier <I>fid1</I> and the - absolute name of the dataset "/Dataset2" were used to identify the - dataset. The reference to the region of this dataset is stored in - the buffer <I>buf</I>. - - <LI> The fourth argument specifies the type of the reference. Since we are - creating references to the dataset regions, the H5R_DATASET_REGION - data type is used. - <LI> The fifth argument is a dataspace identifier of the referenced dataset. + <LI> the <em>dset1</em> parameter is the identifier for the dataset + with the region references and +<P> + <LI> the <em>ref_out</em> parameter specifies the type of reference + stored. In this example a reference to the dataset region is stored. </UL> +<P> + The C function returns the dataspace identifier or a + negative value if it is not successful. + In FORTRAN, the dataset identifier or dataspace identifier + is returned in <I>dset2</I> or <I>dspace2</I> + and the return code for the call is returned in <I>hdferr</I>: + 0 if successful and -1 otherwise. +<P> </UL> -<A NAME="fc1"> -<H3><U>File Contents</U></H3> -The contents of the file "trefer2.h5" created by this program are as follows: + +</UL> +<A NAME="fc"> +<H3><U>File Contents</U></H3> +<P> +<I><U>HDF5 File Created by C Example</U></I> +<P> +<B>Fig. A</B> <I><code>REF_REG.h5</code> in DDL</I> <PRE> -HDF5 "trefer2.h5" { + +HDF5 "REF_REG.h5" { GROUP "/" { - DATASET "Dataset1" { + DATASET "MATRIX" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 2, 9 ) / ( 2, 9 ) } + DATA { + 1, 1, 2, 3, 3, 4, 5, 5, 6, + 1, 2, 2, 3, 4, 4, 5, 6, 6 + } + } + DATASET "REGION_REFERENCES" { DATATYPE { H5T_REFERENCE } - DATASPACE { SIMPLE ( 4 ) / ( 4 ) } + DATASPACE { SIMPLE ( 2 ) / ( 2 ) } DATA { - DATASET 0:744 {(2,2)-(7,7)}, DATASET 0:744 {(6,9), (2,2), (8,4), (1,6), - (2,8), (3,2), (0,4), (9,0), (7,1), (3,3)}, NULL, NULL + DATASET 0:744 {(0,3)-(1,5)}, DATASET 0:744 {(0,0), (1,6), (0,8)} } } - DATASET "Dataset2" { - DATATYPE { H5T_STD_U8LE } - DATASPACE { SIMPLE ( 10, 10 ) / ( 10, 10 ) } +} +} + +</PRE> +<I><U>HDF5 File Created by FORTRAN Example</U></I>: +<P> +<B>Fig. B</B> <I><code>FORTRAN.h5</code> in DDL</I> +<PRE> + +HDF5 "FORTRAN.h5" { +GROUP "/" { + DATASET "MATRIX" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 9, 2 ) / ( 9, 2 ) } DATA { - 0, 3, 6, 9, 12, 15, 18, 21, 24, 27, - 30, 33, 36, 39, 42, 45, 48, 51, 54, 57, - 60, 63, 66, 69, 72, 75, 78, 81, 84, 87, - 90, 93, 96, 99, 102, 105, 108, 111, 114, 117, - 120, 123, 126, 129, 132, 135, 138, 141, 144, 147, - 150, 153, 156, 159, 162, 165, 168, 171, 174, 177, - 180, 183, 186, 189, 192, 195, 198, 201, 204, 207, - 210, 213, 216, 219, 222, 225, 228, 231, 234, 237, - 240, 243, 246, 249, 252, 255, 255, 255, 255, 255, - 255, 255, 255, 255, 255, 255, 255, 255, 255, 255 + 1, 1, + 1, 2, + 2, 2, + 3, 3, + 3, 4, + 4, 4, + 5, 5, + 5, 6, + 6, 6 + } + } + DATASET "REGION_REFERENCES" { + DATATYPE { H5T_REFERENCE } + DATASPACE { SIMPLE ( 2 ) / ( 2 ) } + DATA { + DATASET 0:744 {(3,0)-(5,1)}, DATASET 0:744 {(0,0), (6,1), (8,0)} } } } } </PRE> -Notice how raw data of the dataset with the dataset regions is displayed. + +Notice how the raw data in the dataset with the dataset regions is displayed. Each element of the raw data consists of a reference to the dataset (DATASET number1:number2) and its selected region. If the selection is a hyperslab, the corner coordinates of the hyperslab are displayed. For the point selection, the coordinates of each point are displayed. +<!-- Since only two selections were stored, the third and fourth elements of the -dataset "Dataset1" are set to NULL. This was done by the buffer +dataset are set to NULL. This was done by the buffer inizialization in the program. - -<A NAME="def2"> -<H2>Reading References to Dataset Regions</H2> - -The following steps are involved in reading references to the dataset -regions and referenced dataset regions (selections). -<OL> -<LI> Open and read the dataset containing references to the dataset regions. - The data type H5T_STD_REF_DSETREG must be used during read operation. -<P> -<LI>Use H5Rdereference to obtain the dataset identifier from the read - dataset region reference. - <PRE> <B>OR</B> - </PRE> - Use H5Rget_region to obtain the dataspace identifier for the dataset - containing the selection from the read dataset region reference. -<P> -<LI> With the dataspace identifier, the H5S interface functions, - H5Sget_select_*, can be used to obtain information about the - selection. -<P> -<LI> Close all objects when they are no longer needed. -</OL> - -<H2> Programming Example</H2> -<A NAME="desc2"> -<H3><U>Description</U></H3> -The following example reads a dataset containing dataset region references. -It reads data from the dereferenced dataset and displays the number of -elements and raw data. Then it reads two selections: -hyperslab and point. The program queries a number of points in the -hyperslab and the coordinates and displays them. Then it queries a number of -selected points and their coordinates and displays the information.<BR> -[ <A HREF="examples/h5_ref2regr.c">Download h5_ref2regr.c</A> ] -<PRE> -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - - -#include <stdlib.h> -#include <hdf5.h> - -#define FILE2 "trefer2.h5" -#define NPOINTS 10 - -/* 1-D dataset with fixed dimensions */ -#define SPACE1_NAME "Space1" -#define SPACE1_RANK 1 -#define SPACE1_DIM1 4 - -/* 2-D dataset with fixed dimensions */ -#define SPACE2_NAME "Space2" -#define SPACE2_RANK 2 -#define SPACE2_DIM1 10 -#define SPACE2_DIM2 10 - -int -main(void) -{ - hid_t fid1; /* HDF5 File IDs */ - hid_t dset1, /* Dataset ID */ - dset2; /* Dereferenced dataset ID */ - hid_t sid1, /* Dataspace ID #1 */ - sid2; /* Dataspace ID #2 */ - hsize_t * coords; /* Coordinate buffer */ - hsize_t low[SPACE2_RANK]; /* Selection bounds */ - hsize_t high[SPACE2_RANK]; /* Selection bounds */ - hdset_reg_ref_t *rbuf; /* buffer to to read disk */ - int *drbuf; /* Buffer for reading numeric data from disk */ - int i, j; /* counting variables */ - herr_t ret; /* Generic return value */ - - /* Output message about test being performed */ - - /* Allocate write & read buffers */ - rbuf=malloc(sizeof(hdset_reg_ref_t)*SPACE1_DIM1); - drbuf=calloc(sizeof(int),SPACE2_DIM1*SPACE2_DIM2); - - /* Open the file */ - fid1 = H5Fopen(FILE2, H5F_ACC_RDWR, H5P_DEFAULT); - - /* Open the dataset */ - dset1=H5Dopen(fid1,"/Dataset1"); - - /* Read selection from disk */ - ret=H5Dread(dset1,H5T_STD_REF_DSETREG,H5S_ALL,H5S_ALL,H5P_DEFAULT,rbuf); - - /* Try to open objects */ - dset2 = H5Rdereference(dset1,H5R_DATASET_REGION,&rbuf[0]); - - /* Check information in referenced dataset */ - sid1 = H5Dget_space(dset2); - - ret=H5Sget_simple_extent_npoints(sid1); - printf(" Number of elements in the dataset is : %d\n",ret); - - /* Read from disk */ - ret=H5Dread(dset2,H5T_NATIVE_INT,H5S_ALL,H5S_ALL,H5P_DEFAULT,drbuf); - - for(i=0; i < SPACE2_DIM1; i++) { - for (j=0; j < SPACE2_DIM2; j++) printf (" %d ", drbuf[i*SPACE2_DIM2+j]); - printf("\n"); } - - /* Get the hyperslab selection */ - sid2=H5Rget_region(dset1,H5R_DATASET_REGION,&rbuf[0]); - - /* Verify correct hyperslab selected */ - ret = H5Sget_select_npoints(sid2); - printf(" Number of elements in the hyperslab is : %d \n", ret); - ret = H5Sget_select_hyper_nblocks(sid2); - coords=malloc(ret*SPACE2_RANK*sizeof(hsize_t)*2); /* allocate space for the hyperslab blocks */ - ret = H5Sget_select_hyper_blocklist(sid2,0,ret,coords); - printf(" Hyperslab coordinates are : \n"); - printf (" ( %lu , %lu ) ( %lu , %lu ) \n", \ -(unsigned long)coords[0],(unsigned long)coords[1],(unsigned long)coords[2],(unsigned long)coords[3]); - free(coords); - ret = H5Sget_select_bounds(sid2,low,high); - - /* Close region space */ - ret = H5Sclose(sid2); - - /* Get the element selection */ - sid2=H5Rget_region(dset1,H5R_DATASET_REGION,&rbuf[1]); - - /* Verify correct elements selected */ - ret = H5Sget_select_elem_npoints(sid2); - printf(" Number of selected elements is : %d\n", ret); - - /* Allocate space for the element points */ - coords= malloc(ret*SPACE2_RANK*sizeof(hsize_t)); - ret = H5Sget_select_elem_pointlist(sid2,0,ret,coords); - printf(" Coordinates of selected elements are : \n"); - for (i=0; i < 2*NPOINTS; i=i+2) - printf(" ( %lu , %lu ) \n", (unsigned long)coords[i],(unsigned long)coords[i+1]); - - free(coords); - ret = H5Sget_select_bounds(sid2,low,high); - - /* Close region space */ - ret = H5Sclose(sid2); - - /* Close first space */ - ret = H5Sclose(sid1); - - /* Close dereferenced Dataset */ - ret = H5Dclose(dset2); - - /* Close Dataset */ - ret = H5Dclose(dset1); - - /* Close file */ - ret = H5Fclose(fid1); - - /* Free memory buffers */ - free(rbuf); - free(drbuf); - return 0; -} -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -</PRE> -Output of this program is : -<PRE> - - Number of elements in the dataset is : 100 - 0 3 6 9 12 15 18 21 24 27 - 30 33 36 39 42 45 48 51 54 57 - 60 63 66 69 72 75 78 81 84 87 - 90 93 96 99 102 105 108 111 114 117 - 120 123 126 129 132 135 138 141 144 147 - 150 153 156 159 162 165 168 171 174 177 - 180 183 186 189 192 195 198 201 204 207 - 210 213 216 219 222 225 228 231 234 237 - 240 243 246 249 252 255 255 255 255 255 - 255 255 255 255 255 255 255 255 255 255 - Number of elements in the hyperslab is : 36 - Hyperslab coordinates are : - ( 2 , 2 ) ( 7 , 7 ) - Number of selected elements is : 10 - Coordinates of selected elements are : - ( 6 , 9 ) - ( 2 , 2 ) - ( 8 , 4 ) - ( 1 , 6 ) - ( 2 , 8 ) - ( 3 , 2 ) - ( 0 , 4 ) - ( 9 , 0 ) - ( 7 , 1 ) - ( 3 , 3 ) - -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -</PRE> -<A NAME="rem2"> -<H3><U>Remarks</U></H3> -<UL> -<LI> The dataset with the region references was read by H5Dread with - the H5T_STD_REF_DSETREG data type specified. -<P> -<LI> The read reference can be used to obtain the dataset identifier as we - did with the following call: -<PRE> - dset2 = H5Rdereference (dset1,H5R_DATASET_REGION,&rbuf[0]); -</PRE> - or to obtain spacial information ( dataspace and selection ) with the call - to H5Rget_region: -<PRE> - sid2=H5Rget_region(dset1,H5R_DATASET_REGION,&rbuf[0]); -</PRE> - The reference to the dataset region has information for both the dataset - itself and its selection. In both functions: -<UL> - <LI> The first parameter is an identifier of the dataset with the region - references. - <LI> The second parameter specifies the type of reference stored. In - this example a reference to the dataset region is stored. - <LI> The third parameter is a buffer containing the reference of the - specified type. -</UL> -<P> -<LI> This example introduces several H5Sget_select* functions used to obtain - information about selections: - -<UL> - <B>H5Sget_select_npoints:</B> returns the number of elements in the - hyperslab<BR> - <B>H5Sget_select_hyper_nblocks:</B> returns the number of blocks in - the hyperslab<BR> - <B>H5Sget_select_blocklist:</B> returns the "lower left" and "upper right" - coordinates of the blocks in the hyperslab selection<BR> - <B>H5Sget_select_bounds:</B> returns the coordinates of the "minimal" - block containing a hyperslab selection<BR> - <B>H5Sget_select_elem_npoints:</B> returns the number of points in the - element selection<BR> - <B>H5Sget_select_elem_points:</B> returns the coordinates of the element - selection -</UL> -</UL> +--> <!-- BEGIN FOOTER INFO --> @@ -532,8 +354,11 @@ Output of this program is : <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: January 19, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/select.html b/doc/html/Tutor/select.html index 76ef846..2ea4119 100644 --- a/doc/html/Tutor/select.html +++ b/doc/html/Tutor/select.html @@ -1,5 +1,5 @@ <HTML><HEAD> -<TITLE>HDF5 Tutorial - Selections using H5Sselect_hyperslab +<TITLE>HDF5 Tutorial - Hyperslab Selections </TITLE> </HEAD> @@ -13,7 +13,7 @@ width=78 height=27 alt="NCSA"><P></A> [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] <H1> -<BIG><BIG><BIG><FONT COLOR="#c101cd">Selections using H5Sselect_hyperslab</FONT> +<BIG><BIG><BIG><FONT COLOR="#c101cd">Hyperslab Selections</FONT> </BIG></BIG></BIG></H1> <hr noshade size=1> @@ -34,18 +34,21 @@ width=78 height=27 alt="NCSA"><P></A> <HR> <A NAME="def"> <H2>Selecting a Portion of a Dataspace</H2> -Hyperslabs are portions of datasets. A hyperslab selection can be a logically contiguous collection of points in a dataspace, or it +Hyperslabs are portions of datasets. A hyperslab selection can be a +logically contiguous collection of points in a dataspace, or it can be a regular pattern of points or blocks in a dataspace. -You can select a hyperslab to write to/read from with the function -H5Sselect_hyperslab. +You can select a hyperslab to write to or read from with the function +<CODE>H5Sselect_hyperslab</CODE> / <CODE>h5sselect_hyperslab_f</CODE>. <P> <H2> Programming Example</H2> <A NAME="desc"> <H3><U>Description</U></H3> -This example creates a 5 x 6 integer array in a -file called sds.h5. It selects a 3 x 4 hyperslab from the dataset, -as follows (Dimension 0 is offset by 1 and Dimension 1 is offset by 2): +This example creates a 5 x 6 integer array in a file called <code>sds.h5</code> +(<code>sdsf.h5</code> in FORTRAN). It +selects a 3 x 4 hyperslab from the dataset as follows (Dimension 0 is +offset by 1 and Dimension 1 is offset by 2): <P> +<B>5 x 6 array:</B> <TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=172> <TR><TD WIDTH="17%" VALIGN="TOP"> </TD> <TD WIDTH="17%" VALIGN="TOP"> </TD> @@ -171,245 +174,100 @@ follows (with Dimension 0 offset by 3): </TR> </TABLE> <P> -[ <A HREF="examples/h5_hyperslab.c">Download h5_hyperslab.c</A> ] -<PRE> -/************************************************************ - - This example shows how to write and read a hyperslab. It - is derived from the h5_read.c and h5_write.c examples in - the "Introduction to HDF5". - - ************************************************************/ - -#include "hdf5.h" - -#define FILE "sds.h5" -#define DATASETNAME "IntArray" -#define NX_SUB 3 /* hyperslab dimensions */ -#define NY_SUB 4 -#define NX 7 /* output buffer dimensions */ -#define NY 7 -#define NZ 3 -#define RANK 2 -#define RANK_OUT 3 - -#define X 5 /* dataset dimensions */ -#define Y 6 - -int -main (void) -{ - hsize_t dimsf[2]; /* dataset dimensions */ - int data[X][Y]; /* data to write */ - - /* - * Data and output buffer initialization. - */ - hid_t file, dataset; /* handles */ - hid_t dataspace; - hid_t memspace; - hsize_t dimsm[3]; /* memory space dimensions */ - hsize_t dims_out[2]; /* dataset dimensions */ - herr_t status; - - int data_out[NX][NY][NZ ]; /* output buffer */ - - hsize_t count[2]; /* size of the hyperslab in the file */ - hssize_t offset[2]; /* hyperslab offset in the file */ - hsize_t count_out[3]; /* size of the hyperslab in memory */ - hssize_t offset_out[3]; /* hyperslab offset in memory */ - int i, j, k, status_n, rank; - - - -/********************************************************* - This writes data to the HDF5 file. - *********************************************************/ - - /* - * Data and output buffer initialization. - */ - for (j = 0; j < X; j++) { - for (i = 0; i < Y; i++) - data[j][i] = i + j; - } - /* - * 0 1 2 3 4 5 - * 1 2 3 4 5 6 - * 2 3 4 5 6 7 - * 3 4 5 6 7 8 - * 4 5 6 7 8 9 - */ - - /* - * Create a new file using H5F_ACC_TRUNC access, - * the default file creation properties, and the default file - * access properties. - */ - file = H5Fcreate (FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - - /* - * Describe the size of the array and create the data space for fixed - * size dataset. - */ - dimsf[0] = X; - dimsf[1] = Y; - dataspace = H5Screate_simple (RANK, dimsf, NULL); - - /* - * Create a new dataset within the file using defined dataspace and - * default dataset creation properties. - */ - dataset = H5Dcreate (file, DATASETNAME, H5T_STD_I32BE, dataspace, - H5P_DEFAULT); - - /* - * Write the data to the dataset using default transfer properties. - */ - status = H5Dwrite (dataset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, - H5P_DEFAULT, data); - - /* - * Close/release resources. - */ - H5Sclose (dataspace); - H5Dclose (dataset); - H5Fclose (file); - - -/************************************************************* - - This reads the hyperslab from the sds.h5 file just - created, into a 2-dimensional plane of the 3-dimensional - array. - - ************************************************************/ - - for (j = 0; j < NX; j++) { - for (i = 0; i < NY; i++) { - for (k = 0; k < NZ ; k++) - data_out[j][i][k] = 0; - } - } - - /* - * Open the file and the dataset. - */ - file = H5Fopen (FILE, H5F_ACC_RDONLY, H5P_DEFAULT); - dataset = H5Dopen (file, DATASETNAME); - - dataspace = H5Dget_space (dataset); /* dataspace handle */ - rank = H5Sget_simple_extent_ndims (dataspace); - status_n = H5Sget_simple_extent_dims (dataspace, dims_out, NULL); - printf("\nRank: %d\nDimensions: %lu x %lu \n", rank, - (unsigned long)(dims_out[0]), (unsigned long)(dims_out[1])); - - /* - * Define hyperslab in the dataset. - */ - offset[0] = 1; - offset[1] = 2; - count[0] = NX_SUB; - count[1] = NY_SUB; - status = H5Sselect_hyperslab (dataspace, H5S_SELECT_SET, offset, NULL, - count, NULL); - - /* - * Define the memory dataspace. - */ - dimsm[0] = NX; - dimsm[1] = NY; - dimsm[2] = NZ; - memspace = H5Screate_simple (RANK_OUT, dimsm, NULL); - - /* - * Define memory hyperslab. - */ - offset_out[0] = 3; - offset_out[1] = 0; - offset_out[2] = 0; - count_out[0] = NX_SUB; - count_out[1] = NY_SUB; - count_out[2] = 1; - status = H5Sselect_hyperslab (memspace, H5S_SELECT_SET, offset_out, NULL, - count_out, NULL); - - /* - * Read data from hyperslab in the file into the hyperslab in - * memory and display. - */ - status = H5Dread (dataset, H5T_NATIVE_INT, memspace, dataspace, - H5P_DEFAULT, data_out); - printf ("Data:\n "); - for (j = 0; j < NX; j++) { - for (i = 0; i < NY; i++) printf("%d ", data_out[j][i][0]); - printf("\n "); - } - printf("\n"); - /* - * 0 0 0 0 0 0 0 - * 0 0 0 0 0 0 0 - * 0 0 0 0 0 0 0 - * 3 4 5 6 0 0 0 - * 4 5 6 7 0 0 0 - * 5 6 7 8 0 0 0 - * 0 0 0 0 0 0 0 - */ - - /* - * Close and release resources. - */ - H5Dclose (dataset); - H5Sclose (dataspace); - H5Sclose (memspace); - H5Fclose (file); +To obtain the example, download: +<UL> +[ <A HREF="examples/h5_hyperslab.c">C example</A> ] + - <code>h5_hyperslab.c</code><BR> +[ <A HREF="examples/hyperslab.f90">FORTRAN example</A> ] + - <code>hyperslab.f90</code><BR> +[ <A HREF="examples/java/HyperSlab.java">Java example</A> ] + - <code>HyperSlab.java</code> +</UL> +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. +<P> -} -</PRE> <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI>H5Sselect_hyperslab selects a hyperslab region to add to the current -selected region for a specified dataspace. -<PRE> - herr_t H5Sselect_hyperslab (hid_t space_id, H5S_seloper_t op, - const hssize_t *start, const hsize_t *stride, - const hsize_t *count, const hsize_t *block ) -</PRE> +<LI><CODE>H5Sselect_hyperslab</CODE> / <CODE>h5sselect_hyperslab_f</CODE> +selects a hyperslab region to +add to the current selected region for a specified dataspace. +<P> +<I><B>C</B></I>: +<pre> + herr_t H5Sselect_hyperslab (hid_t space_id, H5S_seloper_t operator, + const hssize_t *start, const hsize_t *stride, + const hsize_t *count, const hsize_t *block ) +</pre> +<P> +<I><B>FORTRAN</B></I>: +<pre> + h5sselect_hyperslab_f (space_id, operator, start, count, & + hdferr, stride, block) + + space_id IN: INTEGER(HID_T) + operator IN: INTEGER + start IN: INTEGER(HSSIZE_T), DIMENSION(*) + count IN: INTEGER(HSIZE_T), DIMENSION(*) + hdferr OUT: INTEGER + stride IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL + block IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL +</pre> +<P> <UL> -<LI>The first parameter, <I>space_id</I>, is the dataspace identifier for the +<LI>The parameter <I>space_id</I> is the dataspace identifier for the specified dataspace. -<LI>The second parameter, <I>op</I>, can only be set to H5S_SELECT_SET - in the current release. It replaces the existing selection with the - parameters from this call. Overlapping blocks are not supported. -<LI>The <I>start</I> array determines the starting coordinates of the hyperslab to select. +<P> +<LI>The parameter <I>operator</I> can be set to one of the following: + <dir><DL> + <dt><CODE>H5S_SELECT_SET</CODE> (<CODE>H5S_SELECT_SET_F</CODE> in FORTRAN) + <dd>Replace the existing selection with the parameters from this call. + Overlapping blocks are not supported with this operator. + + <dt><CODE>H5S_SELECT_OR</CODE> (<CODE>H5S_SELECT_OR_F</CODE> in FORTRAN) + <dd>Add the new selection to the existing selection. + </DL></dir> + +<P> +<LI>The <I>start</I> array determines the starting coordinates of the +hyperslab to select. +<P> <LI>The <I>stride</I> array indicates which elements along a dimension are to be selected. +<P> <LI>The <I>count</I> array determines how many positions to select from the dataspace in each dimension. +<P> <LI>The <I>block</I> array determines the size of the element block selected by the dataspace. +<P> +<LI>In C, a non-negative value is returned if successful, and a negative +value otherwise. In FORTRAN, the return value is returned in <I>hdferr</I>: +0 if successful and -1 otherwise. </UL> <P> The <I>start</I>, <I>stride</I>, <I>count</I>, and <I>block</I> arrays must be the same size as the rank of the dataspace. <P> -<LI>This example introduces the following H5Dget_* functions: -<UL> - <B>H5Dget_space:</B> returns an identifier for a copy of the dataspace - of a dataset.<BR> - <B>H5Dget_type:</B> returns an identifier for a copy of the data type - of a dataset.<BR> -</UL> +<LI>The examples introduce the following call: +<dir><dl> + <dt><code>H5Dget_space / h5dget_space_f:</code> + <dd>Returns an identifier for a copy of the dataspace of a dataset.<P> +</dl></dir> +<LI>The C example also introduces the following calls: +<dir><dl> + <dt><code>H5Sget_simple_extent_dims:</code> + <dd>Returns the size and maximum size of each dimension of a dataspace. + <dt><code>H5Sget_simple_extent_ndims:</code> + <dd>Determines the dimensionality (or rank) of a dataspace. +</dl></dir> <P> -<LI>This example introduces the following H5Sget_* functions used to -obtain information about selections: -<UL> - <B>H5Sget_simple_extent_dims:</B> returns the size and maximum sizes - of each dimension of a dataspace.<BR> - <B>H5Sget_simple_extent_ndims:</B> determines the dimensionality - (or rank) of a dataspace. <BR> +The FORTRAN example does not use these calls, though they +are available as <CODE>h5sget_simple_extent_dims_f</CODE> and +<CODE>h5sget_simple_extent_ndims_f</CODE>. + </UL> </UL> </UL> @@ -439,8 +297,11 @@ obtain information about selections: <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/selectc.html b/doc/html/Tutor/selectc.html index e01d9db..4edef82 100644 --- a/doc/html/Tutor/selectc.html +++ b/doc/html/Tutor/selectc.html @@ -1,5 +1,5 @@ <HTML><HEAD> -<TITLE>HDF5 Tutorial - Selections using H5Sselect_elements and H5Scopy +<TITLE>HDF5 Tutorial - Selecting Individual Points and Copying a Dataspace </TITLE> </HEAD> @@ -13,7 +13,8 @@ width=78 height=27 alt="NCSA"><P></A> [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] <H1> -<BIG><BIG><BIG><FONT COLOR="#c101cd">Selections using H5Sselect_elements and H5SCopy</FONT> +<BIG><BIG><BIG><FONT COLOR="#c101cd">Selecting Individual Points and Copying +a Dataspace</FONT> </BIG></BIG></BIG></H1> <hr noshade size=1> @@ -21,7 +22,7 @@ width=78 height=27 alt="NCSA"><P></A> <BODY> <H2>Contents:</H2> <UL> - <LI> <A HREF="#def">Selecting Independent Points and Copying a Dataspace</A> + <LI> <A HREF="#def">Description</A> <LI> Programming Example <UL> <LI> <A HREF="#desc">Description</A> @@ -31,197 +32,125 @@ width=78 height=27 alt="NCSA"><P></A> </UL> <HR> <A NAME="def"> -<H2>Selecting Independent Points and Copying a Dataspace</h2> -You can select independent points to read or write to in a -dataspace by use of the H5Sselect_elements function. +<H2>Description</h2> +You can select independent points to read from or write to in a +dataspace by use of the <CODE>H5Sselect_elements</CODE> / +<CODE>h5sselect_elements_f</CODE> function. <P> -The H5Scopy function allows you to make an exact copy of a dataspace, -which can help cut down on the number of function calls needed when +The <CODE>H5Scopy</CODE> / <CODE>h5scopy_f</CODE> function allows +you to make an exact copy of a dataspace. +This can reduce the number of function calls needed when selecting a dataspace. <P> <H2> Programming Example</H2> + <A NAME="desc"> <H3><U>Description</U></H3> -This example shows you how to use H5Sselect_elements to select individual -points in a dataset and how to use H5Scopy to make a copy of a dataspace. - -[ <A HREF="examples/h5_copy.c">Download h5_copy.c</A> ] -<PRE> -/***********************************************************************/ -/* */ -/* PROGRAM: h5_copy.c */ -/* PURPOSE: Shows how to use the H5SCOPY function. */ -/* DESCRIPTION: */ -/* This program creates two files, copy1.h5, and copy2.h5. */ -/* In copy1.h5, it creates a 3x4 dataset called 'Copy1', */ -/* and write 0's to this dataset. */ -/* In copy2.h5, it create a 3x4 dataset called 'Copy2', */ -/* and write 1's to this dataset. */ -/* It closes both files, reopens both files, selects two */ -/* points in copy1.h5 and writes values to them. Then it */ -/* does an H5Scopy from the first file to the second, and */ -/* writes the values to copy2.h5. It then closes the */ -/* files, reopens them, and prints the contents of the */ -/* two datasets. */ -/* */ -/***********************************************************************/ - -#include "hdf5.h" -#define FILE1 "copy1.h5" -#define FILE2 "copy2.h5" - -#define RANK 2 -#define DIM1 3 -#define DIM2 4 -#define NUMP 2 - -int main (void) -{ - hid_t file1, file2, dataset1, dataset2; - hid_t mid1, mid2, fid1, fid2; - hsize_t fdim[] = {DIM1, DIM2}; - hsize_t mdim[] = {DIM1, DIM2}; - hsize_t start[2], stride[2], count[2], block[2]; - int buf1[DIM1][DIM2]; - int buf2[DIM1][DIM2]; - int bufnew[DIM1][DIM2]; - int val[] = {53, 59}; - hsize_t marray[] = {2}; - hssize_t coord[NUMP][RANK]; - herr_t ret; - uint i, j; - -/***********************************************************************/ -/* */ -/* Create two files containing identical datasets. Write 0's to one */ -/* and 1's to the other. */ -/* */ -/***********************************************************************/ - - for ( i = 0; i < DIM1; i++ ) - for ( j = 0; j < DIM2; j++ ) - buf1[i][j] = 0; - - for ( i = 0; i < DIM1; i++ ) - for ( j = 0; j < DIM2; j++ ) - buf2[i][j] = 1; - - file1 = H5Fcreate(FILE1, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - file2 = H5Fcreate(FILE2, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - - fid1 = H5Screate_simple (RANK, fdim, NULL); - fid2 = H5Screate_simple (RANK, fdim, NULL); - - dataset1 = H5Dcreate (file1, "Copy1", H5T_NATIVE_INT, fid1, H5P_DEFAULT); - dataset2 = H5Dcreate (file2, "Copy2", H5T_NATIVE_INT, fid2, H5P_DEFAULT); - - ret = H5Dwrite(dataset1, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, buf1); - ret = H5Dwrite(dataset2, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, buf2); - - ret = H5Dclose (dataset1); - ret = H5Dclose (dataset2); - - ret = H5Sclose (fid1); - ret = H5Sclose (fid2); - - ret = H5Fclose (file1); - ret = H5Fclose (file2); - -/***********************************************************************/ -/* */ -/* Open the two files. Select two points in one file, write values to */ -/* those point locations, then do H5Scopy and write the values to the */ -/* other file. Close files. */ -/* */ -/***********************************************************************/ - - file1 = H5Fopen (FILE1, H5F_ACC_RDWR, H5P_DEFAULT); - file2 = H5Fopen (FILE2, H5F_ACC_RDWR, H5P_DEFAULT); - dataset1 = H5Dopen (file1, "Copy1"); - dataset2 = H5Dopen (file2, "Copy2"); - fid1 = H5Dget_space (dataset1); - mid1 = H5Screate_simple(1, marray, NULL); - coord[0][0] = 0; coord[0][1] = 3; - coord[1][0] = 0; coord[1][1] = 1; - - ret = H5Sselect_elements (fid1, H5S_SELECT_SET, NUMP, (const hssize_t **)coord); - - ret = H5Dwrite (dataset1, H5T_NATIVE_INT, mid1, fid1, H5P_DEFAULT, val); - - fid2 = H5Scopy (fid1); - - ret = H5Dwrite (dataset2, H5T_NATIVE_INT, mid1, fid2, H5P_DEFAULT, val); - - ret = H5Dclose (dataset1); - ret = H5Dclose (dataset2); - ret = H5Sclose (fid1); - ret = H5Sclose (fid2); - ret = H5Fclose (file1); - ret = H5Fclose (file2); - ret = H5Sclose (mid1); - -/***********************************************************************/ -/* */ -/* Open both files and print the contents of the datasets. */ -/* */ -/***********************************************************************/ - - file1 = H5Fopen (FILE1, H5F_ACC_RDWR, H5P_DEFAULT); - file2 = H5Fopen (FILE2, H5F_ACC_RDWR, H5P_DEFAULT); - dataset1 = H5Dopen (file1, "Copy1"); - dataset2 = H5Dopen (file2, "Copy2"); - - ret = H5Dread (dataset1, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, - H5P_DEFAULT, bufnew); - - printf ("\nDataset 'Copy1' in file 'copy1.h5' contains: \n"); - for (i=0;i<DIM1; i++) { - for (j=0;j<DIM2;j++) printf ("%3d ", bufnew[i][j]); - printf("\n"); - } - - printf ("\nDataset 'Copy2' in file 'copy2.h5' contains: \n"); - - ret = H5Dread (dataset2, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, - H5P_DEFAULT, bufnew); - - for (i=0;i<DIM1; i++) { - for (j=0;j<DIM2;j++) printf ("%3d ", bufnew[i][j]); - printf("\n"); - } - ret = H5Dclose (dataset1); - ret = H5Dclose (dataset2); - ret = H5Fclose (file1); - ret = H5Fclose (file2); +This example shows how to use <CODE>H5Sselect_elements</CODE> / +<CODE>h5sselect_elements_f</CODE> +to select individual points in a dataset and how to use +<CODE>H5Scopy</CODE> / <CODE>h5scopy_f</CODE> +to make a copy of a dataspace. +<UL> +[ <A HREF="examples/h5_copy.c">C example</A> ] + - <code>h5_copy.c</code><BR> +[ <A HREF="examples/selectele.f90">FORTRAN example</A> ] + - <code>selectele.f90</code><BR> +[ <A HREF="examples/java/Copy.java">Java example</A> ] + - <code>Copy.java</code> +</UL> +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -</PRE> <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI>H5Sselect_elements selects array elements to be included in the -selection for a dataspace: -<PRE> - herr_t H5Sselect_elements (hid_t space_id, H5S_seloper_t op, - size_t num_elem, const hssize_t **coord ) -</PRE> +<LI><CODE>H5Sselect_elements</CODE> / <CODE>h5sselect_elements_f</CODE> +selects array elements to be +included in the selection for a dataspace: +<P> +<I><B>C</B></I>: +<pre> + herr_t H5Sselect_elements (hid_t space_id, H5S_seloper_t operator, + size_t num_elements, + const hssize_t **coord ) +</pre> +<P> +<I><B>FORTRAN</B></I>: +<pre> + h5sselect_elements_f (space_id, operator, num_elements, coord, hdferr) + + space_id IN: INTEGER(HID_T) + operator IN: INTEGER + num_elements IN: INTEGER + coord IN: INTEGER(HSSIZE_T), DIMENSION(*,*) + hdferr OUT: INTEGER +</pre> +<P> <UL> -<LI>The <I>space_id</I> parameter is the dataspace identifier.<BR> -<LI>The <I>op</I> parameter currently can only be set to H5S_SELECT_SET and -specifies to replace the existing selection with the parameters from this -call. -<LI>The <I>coord</I> array is a two-dimensional array of size 'dataspace rank' -by the number of elements to be selected, <I>num_elem</I>.<BR> +<LI>The <I>space_id</I> parameter is the dataspace identifier. +<P> +<LI>The <I>operator</I> parameter can be set to one of the following values: +<dir><DL> + <dt><CODE>H5S_SELECT_SET</CODE> (<CODE>H5S_SELECT_SET_F</CODE> in FORTRAN) + <dd>Replace the existing selection with the parameters from this call. + Overlapping blocks are not supported with this operator. + <dt><CODE>H5S_SELECT_OR</CODE> (<CODE>H5S_SELECT_OR_F</CODE> in FORTRAN) + <dd>Add the new selection to the existing selection. +</DL></dir> +<P> +<LI>The <I>coord</I> array is a two-dimensional array of size +<code><em>NUMP</em> x <em>RANK</em></code> in C +(<code><em>RANK</em> x <em>NUMP</em></code> in FORTRAN) +where <code><em>NUMP</em></code> is the number of selected points +and <code><em>RANK</em></code> is the rank of the dataset. +Note that these coordinates are 0-based in C and 1-based in FORTRAN. +<p> + Consider the non-zero elements of the following array: + <pre> + 0 59 0 53 + 0 0 0 0 + 0 0 1 0 </pre> + In C, the <em>coord</em> array selecting these points would be as follows: + <pre> + 0 1 + 0 3 + 2 2 </pre> + While in FORTRAN, the <em>coord</em> array would be as follows: + <pre> + 1 1 3 + 2 4 3 </pre> +<P> +<LI>In C, this function returns a non-negative value if successful and +a negative value otherwise. In FORTRAN, the value returned in <I>hdferr</I> +indicates whether it was successful (0) or not (-1). </UL> <P> -<LI>H5Scopy creates an exact copy of a dataspace: +<LI><CODE>H5Scopy</CODE> / <CODE>h5scopy_f</CODE> creates an exact copy of a dataspace: +<P> +<I><B>C</B></I>: + <PRE> - hid_t H5Scopy(hid_t space_id ) + hid_t H5Scopy (hid_t space_id) </PRE> +<I><B>FORTRAN</B></I>: +<PRE> + h5scopy_f (space_id, new_space_id, hdferr) + + space_id IN: INTEGER(HID_T) + new_space_id OUT: INTEGER(HID_T) + hdferr OUT: INTEGER +</PRE> +<P> <UL> <LI>The <I>space_id</I> parameter is the dataspace identifier to copy. +<P> +<LI>In C, the identifier to the dataspace's copy is returned if the +function is successful and a negative value is returned if not. In +FORTRAN, the new dataspace identifier is returned in <I>new_space_id</I> +and the return value is returned in <I>hdferr</I> ( 0 if successful and +-1 if not). </UL> </UL> </UL> @@ -231,42 +160,83 @@ by the number of elements to be selected, <I>num_elem</I>.<BR> <H3><U>File Contents</U></H3> Following is the DDL for <I>copy1.h5</I> and <I>copy2.h5</I>, as viewed with -the commands "h5dump copy1.h5" and "h5dump copy2.h5". +the following commands:<br> + +<code>h5dump copy1.h5</code> <br> + +<code>h5dump copy2.h5</code> + <P> -<B>Fig. S.1</B> <I>'copy1.h5' in DDL</I> +<HR> +<B><I><U>C</U></B></I>:<P> +<B>Fig. S.1a</B> <I><code>copy1.h5</code> in DDL</I> <PRE> -HDF5 "copy1.h5" { -GROUP "/" { - DATASET "Copy1" { - DATATYPE { H5T_STD_I32BE } - DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) } - DATA { - 0, 59, 0, 53, - 0, 0, 0, 0, - 0, 0, 0, 0 + HDF5 "copy1.h5" { + GROUP "/" { + DATASET "Copy1" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) } + DATA { + 0, 59, 0, 53, + 0, 0, 0, 0, + 0, 0, 0, 0 + } } } -} -} + } </PRE> -<B>Fig. S.2</B> <I>'copy2.h5' in DDL</I> +<B>Fig. S.1b</B> <I><code>copy2.h5</code> in DDL</I> <PRE> -HDF5 "copy2.h5" { -GROUP "/" { - DATASET "Copy2" { - DATATYPE { H5T_STD_I32BE } - DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) } - DATA { - 1, 59, 1, 53, - 1, 1, 1, 1, - 1, 1, 1, 1 + HDF5 "copy2.h5" { + GROUP "/" { + DATASET "Copy2" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) } + DATA { + 1, 59, 1, 53, + 1, 1, 1, 1, + 1, 1, 1, 1 + } } } -} -} - + } +</PRE> +<HR> +<I><B><U>FORTRAN</U></B></I>:<P> +<B>Fig. S.2a</B> <I><code>copy1.h5</code> in DDL</I> +<PRE> + HDF5 "copy1.h5" { + GROUP "/" { + DATASET "Copy1" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 4, 3 ) / ( 4, 3 ) } + DATA { + 0, 0, 0, + 53, 0, 0, + 0, 0, 0, + 59, 0, 0 + } + } + } + } +</PRE> +<B>Fig. S.2b</B> <I><code>copy2.h5</code> in DDL</I> +<PRE> + HDF5 "copy2.h5" { + GROUP "/" { + DATASET "Copy2" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 4, 3 ) / ( 4, 3 ) } + DATA { + 1, 1, 1, + 53, 1, 1, + 1, 1, 1, + 59, 1, 1 + } + } + } + } </PRE> - <!-- BEGIN FOOTER INFO --> @@ -283,8 +253,11 @@ GROUP "/" { <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> diff --git a/doc/html/Tutor/software.html b/doc/html/Tutor/software.html new file mode 100644 index 0000000..03c0929 --- /dev/null +++ b/doc/html/Tutor/software.html @@ -0,0 +1,87 @@ +<HTML><HEAD> +<TITLE>HDF5 Tutorial - Obtaining HDF5 Software</TITLE> +</HEAD> + +<body bgcolor="#ffffff"> + +<!-- BEGIN MAIN BODY --> + +<A HREF="http://www.ncsa.uiuc.edu/"><img border=0 +src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif" +width=78 height=27 alt="NCSA"><P></A> + + [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] +<H1> +<BIG><BIG><BIG><FONT COLOR="#c101cd">Obtaining HDF5 Software</FONT> +</BIG></BIG></BIG></H1> + +<hr noshade size=1> + +<BODY> +If you will be compiling in: +<DL> +<DT><B>C:</B> +<DD>You will need the HDF5 library. We provide pre-compiled binaries +for the platforms on which we tested at: +<BR> +<A HREF="ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/bin/">ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/bin/</A> +<P> +If using the pre-compiled binaries you must +also obtain the GZIP library, as they were compiled with GZIP included, but do +not include this library. We provide the GZIP library for the platforms on +which we tested at: +<BR> +<A HREF="ftp://ftp.ncsa.uiuc.edu/HDF/gzip/">ftp://ftp.ncsa.uiuc.edu/HDF/gzip/</A> +<P> +You can build the HDF5 library yourself, if need be. The source code +can be obtained from: +<BR> +<A HREF="ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/src/">ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/src/</A> +<P> +For further information regarding HDF5, check the HDF5 home page: +<BR> +<A HREF="http://hdf.ncsa.uiuc.edu/HDF5/">http://hdf.ncsa.uiuc.edu/HDF5/</A> +<P> +<DT><B>FORTRAN90:</B> +<DD> With HDF5-1.4-beta2, support for Fortran 90 is included as part of +the installation of the HDF5 library. Download the HDF5-1.4-beta2 source +code and compile it with the <I>--enable-fortran</I> flag. Read the instructions +in the +<A HREF="ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/hdf5-1.4-beta2/RELEASE">RELEASE</A> +file for further details. + +<P> +<DT><B>Java:</B> +<DD>You will need the JHI5 code. Go to the +<A HREF="/java-hdf5-html">Java HDF5 web page</A> +for information on the Java-HDF5 software. The Java Tutorial examples +are included with this tutorial: +<BR> + <A HREF="./examples/java/">./examples/java/</A> +</DL> + + +<!-- BEGIN FOOTER INFO --> + +<P><hr noshade size=1> +<font face="arial,helvetica" size="-1"> + <a href="http://www.ncsa.uiuc.edu/"><img border=0 + src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif" + width=78 height=27 alt="NCSA"><br> + The National Center for Supercomputing Applications</A><br> + <a href="http://www.uiuc.edu/">University of Illinois + at Urbana-Champaign</a><br> + <br> +<!-- <A HREF="helpdesk.mail.html"> --> +<A HREF="mailto:hdfhelp@@ncsa.uiuc.edu"> +hdfhelp@@ncsa.uiuc.edu</A> +<BR> <H6>Last Modified: January 10, 2001</H6><BR> +<!-- modified by Barbara Jones - bljones@@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@@ncsa.uiuc.edu --> +</FONT> +<BR> +<!-- <A HREF="mailto:hdfhelp@@ncsa.uiuc.edu"> --> + +</BODY> +</HTML> + diff --git a/doc/html/Tutor/title.html b/doc/html/Tutor/title.html index 35283b7..4076196 100644 --- a/doc/html/Tutor/title.html +++ b/doc/html/Tutor/title.html @@ -19,8 +19,6 @@ width=78 height=27 alt="NCSA"><P></A> <hr noshade size=1> - -<!-- The following buttons are for use only when the Tutorial is served from the HDF web server. <CENTER> <FONT SIZE="3" FACE="arial,helvetica" COLOR="#c80028"> <B>[</B> <A HREF="http://hdf.ncsa.uiuc.edu/index.html">Home</A> <B>]</B> @@ -28,12 +26,22 @@ width=78 height=27 alt="NCSA"><P></A> <B>[</B> <A HREF="http://hdf.ncsa.uiuc.edu/products.html">Products</A> <B>]</B> <B>[</B> <A HREF="http://hdf.ncsa.uiuc.edu/newsletters.html">Newsletters</A> <B>]</B> <B>[</B> <A HREF="http://hdf.ncsa.uiuc.edu/docs.html">Documentation</A> <B>]</B> +<BR> + </FONT> <BR> </CENTER> -<BR CLEAR=ALL><BR> ---> +<BR CLEAR=ALL><BR> +<BODY> + +<BIG><B>NOTE:</B></BIG> +This tutorial does NOT include the software needed to +<BR> + +compile the examples. You will need to +<A HREF="./software.html">obtain</A> it first. + <H2>Contents:</H2> <H3>Introductory Topics</H3> <OL> @@ -42,11 +50,11 @@ width=78 height=27 alt="NCSA"><P></A> <LI><A HREF="api.html">The HDF5 API</A> <LI><A HREF="crtfile.html">Creating an HDF5 File</A> <LI><A HREF="crtdat.html">Creating a Dataset</A> -<LI><A HREF="rdwt.html">Reading from/Writing to a Dataset</A> +<LI><A HREF="rdwt.html">Reading from or Writing to a Dataset</A> <LI><A HREF="crtatt.html">Creating an Attribute</A> <LI><A HREF="crtgrp.html">Creating a Group</A> -<LI><A HREF="crtgrpar.html">Creating Groups using Absolute/Relative -Names</A> +<LI><A HREF="crtgrpar.html">Creating Groups Using Absolute and + Relative Names</A> <LI><A HREF="crtgrpd.html">Creating Datasets in Groups</A> </OL> <UL> @@ -55,9 +63,9 @@ Names</A> </UL> <H3>Advanced Topics</H3> <UL> -<LI><A HREF="compound.html">Compound Data Types</A> -<LI><A HREF="select.html">Selections using H5Sselect_hyperslab</A> -<LI><A HREF="selectc.html">Selections using H5Sselect_elements and H5SCopy</A> +<LI><A HREF="compound.html">Compound Datatypes</A> +<LI><A HREF="select.html">Dataspace Selection - Hyperslab</A> +<LI><A HREF="selectc.html">Dataspace Selection - Individual Points</A> <LI><A HREF="reftoobj.html">References to Objects</A> <LI><A HREF="reftoreg.html">References to Dataset Regions</A> <LI><A HREF="extend.html">Chunking and Extendible Datasets</A> @@ -86,7 +94,7 @@ Names</A> <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: October 8, 1999</H6><BR> +<BR> <H6>Last Modified: January 10, 2001</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> diff --git a/doc/html/Tutor/util.html b/doc/html/Tutor/util.html index 79dbf28..1dd2a86 100644 --- a/doc/html/Tutor/util.html +++ b/doc/html/Tutor/util.html @@ -76,6 +76,8 @@ h5ls [OPTIONS] FILE [OBJECTS...] <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> +<br> +Describes HDF5 Release 1.2.2, June 2000 <BR> <H6>Last Modified: July 30, 1999</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> @@ -85,5 +87,3 @@ hdfhelp@ncsa.uiuc.edu</A> </BODY> </HTML> - - |