diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 2000-06-07 19:56:04 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 2000-06-07 19:56:04 (GMT) |
| commit | 73ef4b96dba12eb728d28a5e17a8b8c50e7d95f1 (patch) | |
| tree | 212cd8129278b519f7dee09db8e854b4eb1a40e0 | |
| parent | 798760fe15b05171cdd6b1a76ac4ad60479b422d (diff) | |
| download | hdf5-73ef4b96dba12eb728d28a5e17a8b8c50e7d95f1.zip hdf5-73ef4b96dba12eb728d28a5e17a8b8c50e7d95f1.tar.gz hdf5-73ef4b96dba12eb728d28a5e17a8b8c50e7d95f1.tar.bz2 | |
[svn-r2361] Updating "HDF5 Tutorial."
86 files changed, 8900 insertions, 3043 deletions
diff --git a/doc/html/Tutor/Contents.html b/doc/html/Tutor/Contents.html index 49c4a32..4500dd3 100644 --- a/doc/html/Tutor/Contents.html +++ b/doc/html/Tutor/Contents.html @@ -2,13 +2,6 @@ <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. ---> -<center> -<font size=-1><a href="../index.html" target=_top>Return to HDF5 Doc Set</a></font> -</center> <hr> @@ -56,11 +49,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..6b2d136 100644 --- a/doc/html/Tutor/ContentsAdd.html +++ b/doc/html/Tutor/ContentsAdd.html @@ -3,14 +3,6 @@ <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. ---> -<center> -<font size=-1><a href="../index.html" target=_top>Return to HDF5 Doc Set</a></font> -</center> - <hr> <!-- @@ -19,85 +11,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..1d6b5b4 100644 --- a/doc/html/Tutor/ContentsAdv.html +++ b/doc/html/Tutor/ContentsAdv.html @@ -3,14 +3,6 @@ <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. ---> -<center> -<font size=-1><a href="../index.html" target=_top>Return to HDF5 Doc Set</a></font> -</center> - <hr> <!-- @@ -18,85 +10,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..72995aa 100644 --- a/doc/html/Tutor/ContentsFull.html +++ b/doc/html/Tutor/ContentsFull.html @@ -3,14 +3,6 @@ <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. ---> -<center> -<font size=-1><a href="../index.html" target=_top>Return to HDF5 Doc Set</a></font> -</center> - <hr> <!-- @@ -19,79 +11,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..bc893bd 100644 --- a/doc/html/Tutor/ContentsIntro.html +++ b/doc/html/Tutor/ContentsIntro.html @@ -3,14 +3,6 @@ <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. ---> -<center> -<font size=-1><a href="../index.html" target=_top>Return to HDF5 Doc Set</a></font> -</center> - <hr> <!-- @@ -19,85 +11,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/Graphics/RefObject.gif b/doc/html/Tutor/Graphics/RefObject.gif Binary files differindex 250039f..ae9dc05 100755 --- a/doc/html/Tutor/Graphics/RefObject.gif +++ b/doc/html/Tutor/Graphics/RefObject.gif diff --git a/doc/html/Tutor/Graphics/RefRegion.gif b/doc/html/Tutor/Graphics/RefRegion.gif Binary files differindex ae9dc05..250039f 100755 --- a/doc/html/Tutor/Graphics/RefRegion.gif +++ b/doc/html/Tutor/Graphics/RefRegion.gif diff --git a/doc/html/Tutor/answers.html b/doc/html/Tutor/answers.html index 6bc239b..45b6c82 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,7 @@ 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> <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..4921716 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,9 @@ 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> <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..9471e8a 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,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> <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..6b7f89a 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,7 @@ 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> <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..d765a19 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,9 @@ 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> <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..b0bf50d 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,12 @@ 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> <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..1605539 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,7 @@ 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> <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..f396605 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,7 @@ 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> <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..a7baa1e 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,7 @@ 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> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> diff --git a/doc/html/Tutor/examples/attrexample.f90 b/doc/html/Tutor/examples/attrexample.f90 new file mode 100644 index 0000000..43a6854 --- /dev/null +++ b/doc/html/Tutor/examples/attrexample.f90 @@ -0,0 +1,87 @@ +! This example shows how to create and write a dataset attribute. +! It opens the existing file 'dset.h5', obtains the identifier of +! the dataset "/dset", defines attribute's dataspace, +! creates dataset attribute, writes the attribute, and then closes +! the attribute's dataspace, attribute, dataset, and file. + + PROGRAM ATTREXAMPLE + + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + CHARACTER(LEN=8), PARAMETER :: filename = "dsetf.h5" ! File name + CHARACTER(LEN=4), PARAMETER :: dsetname = "dset" ! Dataset name + CHARACTER(LEN=4), PARAMETER :: aname = "attr" ! Attribute name + + INTEGER(HID_T) :: file_id ! File identifier + INTEGER(HID_T) :: dset_id ! Dataset identifier + INTEGER(HID_T) :: attr_id ! Attribute identifier + INTEGER(HID_T) :: aspace_id ! Attribute Dataspace identifier + + INTEGER(HSIZE_T), DIMENSION(1) :: adims = (/2/) ! Attribute dimension + INTEGER, DIMENSION(2) :: attr_data = (/100,200/)! Attribute data + INTEGER :: arank = 1 ! Attribure rank + + INTEGER :: error ! Error flag + + + ! + ! Initialize FORTRAN predefined datatypes. + ! + CALL h5init_types_f(error) + + ! + ! Open an existing file. + ! + CALL h5fopen_f (filename, H5F_ACC_RDWR_F, file_id, error) + + ! + ! Open an existing dataset. + ! + CALL h5dopen_f(file_id, dsetname, dset_id, error) + + ! + ! Create the data space for the attribute. + ! + CALL h5screate_simple_f(arank, adims, aspace_id, error) + + ! + ! Create dataset attribute. + ! + CALL h5acreate_f(dset_id, aname, H5T_NATIVE_INTEGER,aspace_id, & + attr_id, error) + + ! + ! Write the attribute data. + ! + CALL h5awrite_f(attr_id, H5T_NATIVE_INTEGER, attr_data, error) + + ! + ! Close the attribute. + ! + CALL h5aclose_f(attr_id, error) + + ! + ! Terminate access to the data space. + ! + CALL h5sclose_f(aspace_id, error) + + ! + ! End access to the dataset and release resources used by it. + ! + CALL h5dclose_f(dset_id, error) + + ! + ! Close the file. + ! + CALL h5fclose_f(file_id, error) + + ! + ! Close FORTRAN predefined datatypes. + ! + CALL h5close_types_f(error) + + END PROGRAM ATTREXAMPLE + diff --git a/doc/html/Tutor/examples/chunk.f90 b/doc/html/Tutor/examples/chunk.f90 new file mode 100644 index 0000000..70d973a --- /dev/null +++ b/doc/html/Tutor/examples/chunk.f90 @@ -0,0 +1,310 @@ +! +!This example shows how to work with extendible datasets. +!It creates a 3 x 3 extendible dataset, write to that dataset, +!extend the dataset to 10x3, and write to the dataset again +! + + + + + PROGRAM CHUNKEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + ! + !the dataset is stored in file "extf.h5" + ! + CHARACTER(LEN=7), PARAMETER :: filename = "extf.h5" + + ! + !dataset name is "ExtendibleArray" + ! + CHARACTER(LEN=15), PARAMETER :: dsetname = "ExtendibleArray" + + ! + !dataset rank is 2 + ! + INTEGER :: RANK = 2 + + INTEGER(HID_T) :: file_id ! File identifier + INTEGER(HID_T) :: dset_id ! Dataset identifier + INTEGER(HID_T) :: dataspace ! Dataspace identifier + INTEGER(HID_T) :: filespace ! Dataspace identifier + INTEGER(HID_T) :: memspace ! memspace identifier + INTEGER(HID_T) :: cparms !dataset creatation property identifier + + ! + !dataset dimensions at creation time + ! + INTEGER(HSIZE_T), DIMENSION(2) :: dims = (/3,3/) + + ! + !data1 dimensions + ! + INTEGER(HSIZE_T), DIMENSION(2) :: dims1 = (/3,3/) + + ! + !data2 dimensions + ! + INTEGER(HSIZE_T), DIMENSION(2) :: dims2 = (/7,1/) + + ! + !Maximum dimensions + ! + INTEGER(HSIZE_T), DIMENSION(2) :: maxdims + + ! + !data1 dimensions + ! + INTEGER, DIMENSION(3,3) :: data1 + + ! + !data2 dimensions + ! + INTEGER, DIMENSION(7,1) :: data2 + + ! + !Size of the hyperslab in the file + ! + INTEGER(HSIZE_T), DIMENSION(2) :: size + + ! + !hyperslab offset in the file + ! + INTEGER(HSIZE_T), DIMENSION(2) :: offset + + ! + !general purpose integer + ! + INTEGER :: i, j, k + + ! + !flag to check operation success + ! + INTEGER :: error, error_n + + ! + !Variables used in reading data back + ! + INTEGER(HSIZE_T), DIMENSION(2) :: chunk_dims = (/5,2/) + INTEGER(HSIZE_T), DIMENSION(2) :: chunk_dimsr + INTEGER(HSIZE_T), DIMENSION(2) :: dimsr, maxdimsr + INTEGER, DIMENSION(10,3) :: data_out + INTEGER :: rankr, rank_chunk + + ! + !data initialization + ! + do i = 1, 3 + do j = 1, 3 + data1(i,j) = 1 + end do + end do + + do j = 1, 7 + data2(j,1) = 2 + end do + + + ! + !Initialize FORTRAN predifined datatypes + ! + CALL h5init_types_f(error) + + ! + !Create a new file using default properties. + ! + CALL h5fcreate_f(filename, H5F_ACC_TRUNC_F, file_id, error) + + + ! + !Create the data space with unlimited dimensions. + ! + maxdims = (/H5S_UNLIMITED_f, H5S_UNLIMITED_f/) + + CALL h5screate_simple_f(RANK, dims, dataspace, error, maxdims) + + ! + !Modify dataset creation properties, i.e. enable chunking + ! + CALL h5pcreate_f(H5P_DATASET_CREATE_F, cparms, error) + + CALL h5pset_chunk_f(cparms, RANK, chunk_dims, error) + + ! + !Create a new dataset within the file using cparms creation properties. + ! + !CALL h5dcreate_f(file_id, dsetname, H5T_NATIVE_INT_F, dataspace, & + CALL h5dcreate_f(file_id, dsetname, H5T_NATIVE_INTEGER, dataspace, & + dset_id, error, cparms) + + ! + !Extend the dataset. This call assures that dataset is 3 x 3. + ! + size(1) = 3 + size(2) = 3 + CALL h5dextend_f(dset_id, size, error) + + + ! + !Select a hyperslab. + ! + CALL h5dget_space_f(dset_id, filespace, error) + offset(1) = 0; + offset(2) = 0; + CALL h5sselect_hyperslab_f(filespace, H5S_SELECT_SET_F, & + offset, dims1, error) + + ! + !Write the data to the hyperslab. + ! + !CALL H5Dwrite_f(dset_id, H5T_NATIVE_INT_F, data1, error, & + CALL H5Dwrite_f(dset_id, H5T_NATIVE_INTEGER, data1, error, & + filespace, dataspace) + + ! + !Extend the dataset. Dataset becomes 10 x 3. + ! + dims(1) = dims1(1) + dims2(1); + size(1) = dims(1); + size(2) = dims(2); + CALL h5dextend_f(dset_id, size, error) + + ! + !Select a hyperslab. + ! + CALL h5dget_space_f(dset_id, filespace, error) + offset(1) = 3; + offset(2) = 0; + CALL h5sselect_hyperslab_f(filespace, H5S_SELECT_SET_F, & + offset, dims2, error) + + ! + !create memory dataspace. + ! + CALL h5screate_simple_f(RANK, dims2, memspace, error) + + ! + !Write the data to the hyperslab. + ! + !CALL H5Dwrite_f(dset_id, H5T_NATIVE_INT_F, data2, error, & + CALL H5Dwrite_f(dset_id, H5T_NATIVE_INTEGER, data2, error, & + mem_space_id=memspace, file_space_id=filespace) + + ! + !Close the dataspace for the dataset. + ! + CALL h5sclose_f(dataspace, error) + CALL h5sclose_f(filespace, error) + + ! + !Close the memoryspace. + ! + CALL h5sclose_f(memspace, error) + + ! + !Close the dataset. + ! + CALL h5dclose_f(dset_id, error) + + ! + !Close the property list. + ! + CALL h5pclose_f(cparms, error) + + ! + !Close the file. + ! + CALL h5fclose_f(file_id, error) + + ! + !read the data back + ! + !Open the file. + ! + CALL h5fopen_f (filename, H5F_ACC_RDONLY_F, file_id, error) + + ! + !Open the dataset. + ! + CALL h5dopen_f(file_id, dsetname, dset_id, error) + + ! + !Get dataset's dataspace handle. + ! + CALL h5dget_space_f(dset_id, dataspace, error) + + ! + !Get dataspace's rank. + ! + CALL h5sget_simple_extent_ndims_f(dataspace, rankr, error) + + + ! + !Get dataspace's dimensinons. + ! + CALL h5sget_simple_extent_dims_f(dataspace, dimsr, maxdimsr, error) + + + ! + !Get creation property list. + ! + CALL h5dget_create_plist_f(dset_id, cparms, error) + + ! + !Get chunk dimensions. + ! + CALL h5pget_chunk_f(cparms, 2, chunk_dimsr, error) + + ! + !create memory dataspace. + ! + CALL h5screate_simple_f(rankr, dimsr, memspace, error) + + ! + !Read data + ! + !CALL H5Dread_f(dset_id, H5T_NATIVE_INT_F, data_out, error, & + CALL H5Dread_f(dset_id, H5T_NATIVE_INTEGER, data_out, error, & + memspace, dataspace) + + ! + !Print data + ! + do i = 1, dimsr(1) + print *, (data_out(i,j), j = 1,dimsr(2)) + end do + + ! + !Close the dataspace for the dataset. + ! + CALL h5sclose_f(dataspace, error) + + ! + !Close the memoryspace. + ! + CALL h5sclose_f(memspace, error) + + ! + !Close the dataset. + ! + CALL h5dclose_f(dset_id, error) + + ! + !Close the file. + ! + CALL h5fclose_f(file_id, error) + + ! + !Close the property list. + ! + CALL h5pclose_f(cparms, error) + + ! + ! Close FORTRAN predefined datatypes. + ! + CALL h5close_types_f(error) + + END PROGRAM CHUNKEXAMPLE diff --git a/doc/html/Tutor/examples/dsetexample.f90 b/doc/html/Tutor/examples/dsetexample.f90 new file mode 100644 index 0000000..00974a9 --- /dev/null +++ b/doc/html/Tutor/examples/dsetexample.f90 @@ -0,0 +1,70 @@ +! +! The following example shows how to create an empty dataset. +! It creates a file called 'dsetf.h5', defines the +! dataset dataspace, creates a dataset which is a 4x6 integer array, +! and then closes the dataspace, the dataset, and the file. +! + + PROGRAM DSETEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + CHARACTER(LEN=8), PARAMETER :: filename = "dsetf.h5" ! File name + CHARACTER(LEN=4), PARAMETER :: dsetname = "dset" ! Dataset name + + INTEGER(HID_T) :: file_id ! File identifier + INTEGER(HID_T) :: dset_id ! Dataset identifier + INTEGER(HID_T) :: dspace_id ! Dataspace identifier + + + INTEGER(HSIZE_T), DIMENSION(2) :: dims = (/4,6/) ! Dataset dimensions + INTEGER :: rank = 2 ! Dataset rank + + INTEGER :: error ! Error flag + + ! + ! Initialize FORTRAN predefined datatypes. + ! + CALL h5init_types_f(error) + + ! + ! Create a new file using default properties. + ! + CALL h5fcreate_f(filename, H5F_ACC_TRUNC_F, file_id, error) + + ! + ! Create the dataspace. + ! + CALL h5screate_simple_f(rank, dims, dspace_id, error) + + ! + ! Create the dataset with default properties. + ! + CALL h5dcreate_f(file_id, dsetname, H5T_NATIVE_INTEGER, dspace_id, & + dset_id, error) + + ! + ! End access to the dataset and release resources used by it. + ! + CALL h5dclose_f(dset_id, error) + + ! + ! Terminate access to the data space. + ! + CALL h5sclose_f(dspace_id, error) + + ! + ! Close the file. + ! + CALL h5fclose_f(file_id, error) + + ! + ! Close FORTRAN predefined datatypes. + ! + CALL h5close_types_f(error) + + END PROGRAM DSETEXAMPLE + + diff --git a/doc/html/Tutor/examples/fileexample.f90 b/doc/html/Tutor/examples/fileexample.f90 new file mode 100644 index 0000000..33c3bc2 --- /dev/null +++ b/doc/html/Tutor/examples/fileexample.f90 @@ -0,0 +1,27 @@ +! +! The following example demonstrates how to create and close an HDF5 file. +! It creates a file called 'file.h5', and then closes the file. +! + + PROGRAM FILEEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + CHARACTER(LEN=8), PARAMETER :: filename = "filef.h5" ! File name + INTEGER(HID_T) :: file_id ! File identifier + + INTEGER :: error ! Error flag + + ! + ! Create a new file using default properties. + ! + CALL h5fcreate_f(filename, H5F_ACC_TRUNC_F, file_id, error) + + ! + ! Terminate access to the file. + ! + CALL h5fclose_f(file_id, error) + + END PROGRAM FILEEXAMPLE diff --git a/doc/html/Tutor/examples/groupexample.f90 b/doc/html/Tutor/examples/groupexample.f90 new file mode 100644 index 0000000..148a796 --- /dev/null +++ b/doc/html/Tutor/examples/groupexample.f90 @@ -0,0 +1,42 @@ +! +! The following example shows how to create and close a group. +! It creates a file called 'group.h5', creates a group +! called MyGroup in the root group, and then closes the group and file. +! + + + PROGRAM GROUPEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + CHARACTER(LEN=9), PARAMETER :: filename = "groupf.h5" ! File name + CHARACTER(LEN=7), PARAMETER :: groupname = "MyGroup" ! Group name + + INTEGER(HID_T) :: file_id ! File identifier + INTEGER(HID_T) :: group_id ! Group identifier + + INTEGER :: error ! Error flag + + ! + ! Create a new file using default properties. + ! + CALL h5fcreate_f(filename, H5F_ACC_TRUNC_F, file_id, error) + + ! + ! Create a group named "/MyGroup" in the file. + ! + CALL h5gcreate_f(file_id, groupname, group_id, error) + + ! + ! Close the group. + ! + CALL h5gclose_f(group_id, error) + + ! + ! Terminate access to the file. + ! + CALL h5fclose_f(file_id, error) + + END PROGRAM GROUPEXAMPLE diff --git a/doc/html/Tutor/examples/grpdsetexample.f90 b/doc/html/Tutor/examples/grpdsetexample.f90 new file mode 100644 index 0000000..75bc335 --- /dev/null +++ b/doc/html/Tutor/examples/grpdsetexample.f90 @@ -0,0 +1,136 @@ +! +! 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. +! Absolute and relative dataset names are used. +! + + + PROGRAM GRPDSETEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + CHARACTER(LEN=10), PARAMETER :: filename = "groupsf.h5" ! File name + CHARACTER(LEN=15), PARAMETER :: groupname = "MyGroup/Group_A" ! Group name + CHARACTER(LEN=13), PARAMETER :: dsetname1 = "MyGroup/dset1" ! Dataset name + CHARACTER(LEN=5), PARAMETER :: dsetname2 = "dset2" ! dataset name + + INTEGER(HID_T) :: file_id ! File identifier + INTEGER(HID_T) :: group_id ! Group identifier + INTEGER(HID_T) :: dataset_id ! Dataset identifier + INTEGER(HID_T) :: dataspace_id ! Data space identifier + + INTEGER :: i, j + INTEGER :: error ! Error flag + + INTEGER, DIMENSION(3,3) :: dset1_data ! Data arrays + INTEGER, DIMENSION(2,10) :: dset2_data ! + + INTEGER(HSIZE_T), DIMENSION(2) :: dims1 = (/3,3/) ! Datasets dimensions + INTEGER(HSIZE_T), DIMENSION(2) :: dims2 = (/2,10/)! + + INTEGER :: rank = 2 ! Datasets rank + + ! + !Initialize dset1_data array + ! + do i = 1, 3 + do j = 1, 3 + dset1_data(i,j) = j; + end do + end do + + + ! + !Initialize dset2_data array + ! + do i = 1, 2 + do j = 1, 10 + dset2_data(i,j) = j; + end do + end do + + ! + ! Initialize FORTRAN predefined datatypes. + ! + CALL h5init_types_f(error) + + ! + ! Open an existing file. + ! + CALL h5fopen_f (filename, H5F_ACC_RDWR_F, file_id, error) + + ! + ! Create the data space for the first dataset. + ! + CALL h5screate_simple_f(rank, dims1, dataspace_id, error) + + ! + ! Create a dataset in group "MyGroup" with default properties. + ! + CALL h5dcreate_f(file_id, dsetname1, H5T_NATIVE_INTEGER, dataspace_id, & + dataset_id, error) + + ! + ! Write the first dataset. + ! + CALL h5dwrite_f(dataset_id, H5T_NATIVE_INTEGER, dset1_data, error) + + ! + ! Close the dataspace for the first dataset. + ! + CALL h5sclose_f(dataspace_id, error) + + ! + ! Close the first dataset. + ! + CALL h5dclose_f(dataset_id, error) + + ! + ! Open an existing group in the specified file. + ! + CALL h5gopen_f(file_id, groupname, group_id, error) + + ! + !Create the data space for the second dataset. + ! + CALL h5screate_simple_f(rank, dims2, dataspace_id, error) + + ! + ! Create the second dataset in group "Group_A" with default properties. + ! + CALL h5dcreate_f(group_id, dsetname2, H5T_NATIVE_INTEGER, dataspace_id, & + dataset_id, error) + + ! + ! Write the second dataset. + ! + CALL h5dwrite_f(dataset_id, H5T_NATIVE_INTEGER, dset2_data, error) + + ! + ! Close the dataspace for the second dataset. + ! + CALL h5sclose_f(dataspace_id, error) + + ! + ! Close the second dataset. + ! + CALL h5dclose_f(dataset_id, error) + + ! + ! Close the group. + ! + CALL h5gclose_f(group_id, error) + + ! + ! Close the file. + ! + CALL h5fclose_f(file_id, error) + + ! + ! Close FORTRAN predefined datatypes. + ! + CALL h5close_types_f(error) + + END PROGRAM GRPDSETEXAMPLE diff --git a/doc/html/Tutor/examples/grpit.f90 b/doc/html/Tutor/examples/grpit.f90 new file mode 100644 index 0000000..66fb09e --- /dev/null +++ b/doc/html/Tutor/examples/grpit.f90 @@ -0,0 +1,189 @@ +! +! In this example we iterate through the members of the groups. +! + + + PROGRAM GRPITEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + CHARACTER(LEN=11), PARAMETER :: filename = "iteratef.h5" ! File name + CHARACTER(LEN=7), PARAMETER :: groupname1 = "MyGroup" ! Group name + CHARACTER(LEN=15), PARAMETER :: groupname2 = "Group_A" ! Group name + CHARACTER(LEN=13), PARAMETER :: dsetname1 = "dset1" ! Dataset name + CHARACTER(LEN=5), PARAMETER :: dsetname2 = "dset2" ! + + CHARACTER(LEN=20) :: name_buffer ! Buffer to hold object's name + INTEGER :: type ! Type of the object + INTEGER :: nmembers ! Number of group members + + INTEGER(HID_T) :: file_id ! File identifier + INTEGER(HID_T) :: dataset1_id ! Dataset1 identifier + INTEGER(HID_T) :: dataset2_id ! Dataset2 identifier + INTEGER(HID_T) :: dataspace1_id ! Data space identifier + INTEGER(HID_T) :: dataspace2_id ! Data space identifier + INTEGER(HID_T) :: group1_id, group2_id ! Group identifiers + + INTEGER :: i, j + + INTEGER :: error ! Error flag + + INTEGER, DIMENSION(3,3) :: dset1_data ! Arrays to hold data + INTEGER, DIMENSION(2,10) :: dset2_data ! + + INTEGER(HSIZE_T), DIMENSION(2) :: dims1 = (/3,3/) ! Dataset dimensions + INTEGER(HSIZE_T), DIMENSION(2) :: dims2 = (/2,10/)! + INTEGER :: rank = 2 ! Datasets rank + + ! + ! Initialize dset1_data array. + ! + do i = 1, 3 + do j = 1, 3 + dset1_data(i,j) = j; + end do + end do + + + ! + ! Initialize dset2_data array. + ! + do i = 1, 2 + do j = 1, 10 + dset2_data(i,j) = j; + end do + end do + + ! + ! Initialize FORTRAN predefined datatypes. + ! + CALL h5init_types_f(error) + + ! + ! Create a new file using default properties. + ! + CALL h5fcreate_f(filename, H5F_ACC_TRUNC_F, file_id, error) + + ! + ! Create group "MyGroup" in the root group using absolute name. + ! + CALL h5gcreate_f(file_id, groupname1, group1_id, error) + + ! + ! Create group "Group_A" in group "MyGroup" using relative name. + ! + CALL h5gcreate_f(group1_id, groupname2, group2_id, error) + + ! + ! Create the data space for the first dataset. + ! + CALL h5screate_simple_f(rank, dims1, dataspace1_id, error) + + ! + ! Create a dataset in group "MyGroup" with default properties. + ! + CALL h5dcreate_f(group1_id, dsetname1, H5T_NATIVE_INTEGER, dataspace1_id, & + dataset1_id, error) + + ! + ! Write the first dataset. + ! + CALL h5dwrite_f(dataset1_id, H5T_NATIVE_INTEGER, dset1_data, error) + + ! + ! Create the data space for the second dataset. + ! + CALL h5screate_simple_f(rank, dims2, dataspace2_id, error) + + ! + ! Create the second dataset in group "Group_A" with default properties + ! + CALL h5dcreate_f(group2_id, dsetname2, H5T_NATIVE_INTEGER, dataspace2_id, & + dataset2_id, error) + + ! + ! Write the second dataset + ! + CALL h5dwrite_f(dataset2_id, H5T_NATIVE_INTEGER, dset2_data, error) + + ! + ! Get number of members in the root group. + ! + CALL h5gn_members_f(file_id, "/", nmembers, error) + write(*,*) "Number of root group member is " , nmembers + + ! + ! Print each group member's name and type. + ! + do i = 0, nmembers - 1 + CALL h5gget_obj_info_idx_f(file_id, "/", i, name_buffer, type, & + error) + write(*,*) name_buffer, type + end do + + ! + ! Get number of members in MyGroup. + ! + CALL h5gn_members_f(file_id, "MyGroup", nmembers, error) + write(*,*) "Number of group MyGroup member is ", nmembers + + ! + ! Print each group member's name and type in "MyGroup" group. + ! + do i = 0, nmembers - 1 + CALL h5gget_obj_info_idx_f(file_id, groupname1, i, name_buffer, type, & + error) + write(*,*) name_buffer, type + end do + + + ! + ! Get number of members in MyGroup/Group_A. + ! + CALL h5gn_members_f(file_id, "MyGroup/Group_A", nmembers, error) + write(*,*) "Number of group MyGroup/Group_A member is ", nmembers + + ! + ! Print each group member's name and type in "MyGroup/Group_A" group. + ! + do i = 0, nmembers - 1 + CALL h5gget_obj_info_idx_f(file_id,"MyGroup/Group_A" , i, name_buffer, type, & + error) + write(*,*) name_buffer, type + end do + + ! + ! Close the dataspace for the first dataset. + ! + CALL h5sclose_f(dataspace1_id, error) + + ! + ! Close the first dataset. + ! + CALL h5dclose_f(dataset1_id, error) + + ! + ! Close the dataspace for the second dataset. + ! + CALL h5sclose_f(dataspace2_id, error) + + ! + ! Close the second dataset. + ! + CALL h5dclose_f(dataset2_id, error) + + ! + ! Close the groups. + ! + CALL h5gclose_f(group1_id, error) + + CALL h5gclose_f(group2_id, error) + + ! + ! Close the file. + ! + CALL h5fclose_f(file_id, error) + + END PROGRAM GRPITEXAMPLE diff --git a/doc/html/Tutor/examples/grpsexample.f90 b/doc/html/Tutor/examples/grpsexample.f90 new file mode 100644 index 0000000..9f9c867 --- /dev/null +++ b/doc/html/Tutor/examples/grpsexample.f90 @@ -0,0 +1,58 @@ +! +! 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 to the specified group. +! + + PROGRAM GRPSEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + CHARACTER(LEN=10), PARAMETER :: filename = "groupsf.h5" ! File name + CHARACTER(LEN=8), PARAMETER :: groupname1 = "/MyGroup" ! Group name + CHARACTER(LEN=16), PARAMETER :: groupname2 = "/MyGroup/Group_A" + ! Group name + CHARACTER(LEN=7), PARAMETER :: groupname3 = "Group_B" ! Group name + + INTEGER(HID_T) :: file_id ! File identifier + INTEGER(HID_T) :: group1_id, group2_id, group3_id ! Group identifiers + + INTEGER :: error ! Error flag + + ! + ! Create a new file using default properties. + ! + CALL h5fcreate_f(filename, H5F_ACC_TRUNC_F, file_id, error) + + ! + ! Create group "MyGroup" in the root group using absolute name. + ! + CALL h5gcreate_f(file_id, groupname1, group1_id, error) + + ! + ! Create group "Group_A" in group "MyGroup" using absolute name. + ! + CALL h5gcreate_f(file_id, groupname2, group2_id, error) + + ! + ! Create group "Group_B" in group "MyGroup" using relative name. + ! + CALL h5gcreate_f(group1_id, groupname3, group3_id, error) + + ! + ! Close the groups. + ! + CALL h5gclose_f(group1_id, error) + CALL h5gclose_f(group2_id, error) + CALL h5gclose_f(group3_id, error) + + ! + ! Terminate access to the file. + ! + CALL h5fclose_f(file_id, error) + + END PROGRAM GRPSEXAMPLE diff --git a/doc/html/Tutor/examples/hyperslab.f90 b/doc/html/Tutor/examples/hyperslab.f90 new file mode 100644 index 0000000..0be4b60 --- /dev/null +++ b/doc/html/Tutor/examples/hyperslab.f90 @@ -0,0 +1,199 @@ +! +! This example shows how to write and read a hyperslab. +! + + PROGRAM SELECTEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + CHARACTER(LEN=7), PARAMETER :: filename = "sdsf.h5" ! File name + CHARACTER(LEN=8), PARAMETER :: dsetname = "IntArray" ! Dataset name + + INTEGER(HID_T) :: file_id ! File identifier + INTEGER(HID_T) :: dset_id ! Dataset identifier + INTEGER(HID_T) :: dataspace ! Dataspace identifier + INTEGER(HID_T) :: memspace ! memspace identifier + + INTEGER(HSIZE_T), DIMENSION(3) :: dimsm = (/7,7,3/) ! Dataset dimensions + ! in memory + INTEGER(HSIZE_T), DIMENSION(2) :: dims_out ! Buffer to read in dataset + ! dimesions + INTEGER(HSIZE_T), DIMENSION(2) :: dimsf = (/5,6/) ! Dataset dimensions. + + INTEGER(HSIZE_T), DIMENSION(2) :: count = (/3,4/) + ! Size of the hyperslab in the file + INTEGER(HSIZE_T), DIMENSION(2) :: offset = (/1,2/) + !hyperslab offset in the file + INTEGER(HSIZE_T), DIMENSION(3) :: count_out = (/3,4,1/) + !Size of the hyperslab in memory + INTEGER(HSIZE_T), DIMENSION(3) :: offset_out = (/3,0,0/) + !hyperslab offset in memory + INTEGER, DIMENSION(5,6) :: data ! Data to write + INTEGER, DIMENSION(7,7,3) :: data_out ! Output buffer + INTEGER :: dsetrank = 2 ! Dataset rank ( in file ) + INTEGER :: memrank = 3 ! Dataset rank ( in memory ) + INTEGER :: rank + INTEGER :: i, j, k + + INTEGER :: error, error_n ! Error flags + + + ! + ! Write data to the HDF5 file. + ! + + ! + ! Data initialization. + ! + do i = 1, 5 + do j = 1, 6 + data(i,j) = (i-1) + (j-1); + end do + end do + ! + ! 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 + ! + + ! + ! Initialize FORTRAN predefined datatypes + ! + CALL h5init_types_f(error) + + ! + ! Create a new file using default properties. + ! + CALL h5fcreate_f(filename, H5F_ACC_TRUNC_F, file_id, error) + + ! + ! Create the data space for the dataset. + ! + CALL h5screate_simple_f(dsetrank, dimsf, dataspace, error) + + ! + ! Create the dataset with default properties. + ! + CALL h5dcreate_f(file_id, dsetname, H5T_NATIVE_INTEGER, dataspace, & + dset_id, error) + + ! + ! Write the dataset. + ! + CALL h5dwrite_f(dset_id, H5T_NATIVE_INTEGER, data, error) + + ! + ! Close the dataspace for the dataset. + ! + CALL h5sclose_f(dataspace, error) + + ! + ! Close the dataset. + ! + CALL h5dclose_f(dset_id, error) + + ! + ! Close the file. + ! + CALL h5fclose_f(file_id, error) + + ! + ! This part of the code reads the hyperslab from the sds.h5 file just + ! created, into a 2-dimensional plane of the 3-dimensional dataset. + ! + + ! + ! Initialize data_out array. + ! + do i = 1, 7 + do j = 1, 7 + do k = 1,3 + data_out(i,j,k) = 0; + end do + end do + end do + + ! + ! Open the file. + ! + CALL h5fopen_f (filename, H5F_ACC_RDONLY_F, file_id, error) + + ! + ! Open the dataset. + ! + CALL h5dopen_f(file_id, dsetname, dset_id, error) + + ! + ! Get dataset's dataspace identifier. + ! + CALL h5dget_space_f(dset_id, dataspace, error) + + ! + ! Select hyperslab in the dataset. + ! + CALL h5sselect_hyperslab_f(dataspace, H5S_SELECT_SET_F, & + offset, count, error) + ! + ! Create memory dataspace. + ! + CALL h5screate_simple_f(memrank, dimsm, memspace, error) + + ! + ! Select hyperslab in memory. + ! + CALL h5sselect_hyperslab_f(memspace, H5S_SELECT_SET_F, & + offset_out, count_out, error) + + ! + ! Read data from hyperslab in the file into the hyperslab in + ! memory and display. + ! + CALL H5Dread_f(dset_id, H5T_NATIVE_INTEGER, data_out, error, & + memspace, dataspace) + + ! + ! Display data_out array + ! + do i = 1, 7 + print *, (data_out(i,j,1), j = 1,7) + end do + + ! 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 the dataspace for the dataset. + ! + CALL h5sclose_f(dataspace, error) + + ! + ! Close the memoryspace. + ! + CALL h5sclose_f(memspace, error) + + ! + ! Close the dataset. + ! + CALL h5dclose_f(dset_id, error) + + ! + ! Close the file. + ! + CALL h5fclose_f(file_id, error) + + ! + ! Close FORTRAN predefined datatypes. + ! + CALL h5close_types_f(error) + + END PROGRAM SELECTEXAMPLE diff --git a/doc/html/Tutor/examples/java/Compound.java b/doc/html/Tutor/examples/java/Compound.java new file mode 100644 index 0000000..219e1c1 --- /dev/null +++ b/doc/html/Tutor/examples/java/Compound.java @@ -0,0 +1,540 @@ +/****************************************************************** + * Compound.java (for HDF5 tutorial lesson 11) + * + * -- Creating a compound data type + * (a java conversion from compound.c) + * + ******************************************************************/ + +import ncsa.hdf.hdf5lib.*; +import ncsa.hdf.hdf5lib.exceptions.*; + +public class Compound +{ + public static void main (String []argv) + { + final String FILE = "SDScompound.h5"; + final String DATASETNAME = "ArrayOfStructures"; + final int LENGTH = 10; + final int RANK = 1; + + /* First structure and dataset */ + /* an array of LENGTH 'complex' numbers */ + byte[] data1 = new byte[LENGTH * 16]; + + int[] AR = new int[1]; + float[] BR = new float[1]; + double[] CR = new double[1]; + + byte [] ARec = new byte[4]; + byte [] BRec = new byte[4]; + byte [] CRec = new byte[8]; + + int s1_tid; /* File datatype identifier */ + + /* Second structure (subset of s1_t) and dataset*/ + byte[] data2 = new byte[LENGTH * 12]; + int s2_tid; /* Memory datatype handle */ + + /* Third "structure" ( will be used to read float field of s1) */ + int s3_tid; /* Memory datatype handle */ + float[] s3 = new float[LENGTH]; + + int i; + int file, dataset, space; /* Handles */ + int status; + long[] dim = new long[1]; /* Dataspace dimensions */ + dim[0] = LENGTH; + + /* + * Initialize the data + */ + for (i = 0; i < LENGTH; i++) + { + AR[0] = (int) i; + BR[0] = (float) i * i; + CR[0] = (double) 1. / (i + 1); + + ARec = HDFNativeData.intToByte (0, 1, AR); + BRec = HDFNativeData.floatToByte (0, 1, BR); + CRec = HDFNativeData.doubleToByte (0, 1, CR); + + System.arraycopy (ARec, 0, data1, (i * 16), 4); + System.arraycopy (BRec, 0, data1, (i * 16) + 4, 4); + System.arraycopy (CRec, 0, data1, (i * 16) + 8, 8); + } + + /* + * Create the data space. + */ + space = H5Screate_simple_wrap (RANK, dim, null); + + /* + * Create the file. + */ + file = H5Fcreate_wrap (FILE, HDF5Constants.H5F_ACC_TRUNC, + HDF5Constants.H5P_DEFAULT, + HDF5Constants.H5P_DEFAULT); + + /* + * Create the memory data type. + */ + s1_tid = H5Tcreate_wrap (HDF5Constants.H5T_COMPOUND, 16); + H5Tinsert_wrap (s1_tid, "a_name", 0, + H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT)); + H5Tinsert_wrap (s1_tid, "b_name", 4, + H5.J2C (HDF5CDataTypes.JH5T_NATIVE_FLOAT)); + H5Tinsert_wrap (s1_tid, "c_name", 8, + H5.J2C (HDF5CDataTypes.JH5T_NATIVE_DOUBLE)); + + /* + * Create the dataset. + */ + dataset = H5Dcreate_wrap (file, DATASETNAME, s1_tid, + space, HDF5Constants.H5P_DEFAULT); + + /* + * Wtite data to the dataset; + */ + status = H5Dwrite_wrap (dataset, s1_tid, + HDF5Constants.H5S_ALL, HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, data1); + + /* + * Release resources + */ + H5Tclose_wrap (s1_tid); + H5Sclose_wrap (space); + H5Dclose_wrap (dataset); + H5Fclose_wrap (file); + + /* + * Open the file and the dataset. + */ + file = H5Fopen_wrap (FILE, HDF5Constants.H5F_ACC_RDONLY, + HDF5Constants.H5P_DEFAULT); + + dataset = H5Dopen_wrap (file, DATASETNAME); + + /* + * Create a data type for s2 + */ + s2_tid = H5Tcreate_wrap (HDF5Constants.H5T_COMPOUND, 12); + H5Tinsert_wrap (s2_tid, "c_name", 0, + H5.J2C (HDF5CDataTypes.JH5T_NATIVE_DOUBLE)); + H5Tinsert_wrap (s2_tid, "a_name", 8, + H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT)); + + /* + * Read two fields c and a from s1 dataset. Fields in the file + * are found by their names "c_name" and "a_name". + */ + status = H5Dread_wrap (dataset, s2_tid, HDF5Constants.H5S_ALL, + HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, data2); + + /* + * Display the fields. Convert from bytes into numbers. + */ + System.out.println ("\nField c : "); + for( i = 0; i < LENGTH; i++) { + System.arraycopy (data2, (i*12), CRec, 0, 8); + CR = HDFNativeData.byteToDouble(0, 1, CRec); + System.out.print (CR[0]+" "); + } + System.out.println (); + + System.out.println("\nField a :"); + for( i = 0; i < LENGTH; i++) { + System.arraycopy (data2, (i*12)+8, ARec, 0, 4); + AR = HDFNativeData.byteToInt(0, 1, ARec); + System.out.print (AR[0]+" "); + } + System.out.println (); + + /* + * Create a data type for s3. + */ + s3_tid = H5Tcreate_wrap (HDF5Constants.H5T_COMPOUND, 4); + + status = + H5Tinsert_wrap (s3_tid, "b_name", 0, + H5.J2C (HDF5CDataTypes.JH5T_NATIVE_FLOAT)); + + /* + * Read field b from s1 dataset. Field in the file is found by its name. + */ + status = H5Dread_wrap (dataset, s3_tid, HDF5Constants.H5S_ALL, + HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, s3); + + /* + * Display the field. Data is read directly into array of 'float'. + */ + System.out.println (); + System.out.println ("Field b :"); + for( i = 0; i < LENGTH; i++) { + System.out.print (s3[i]+" "); + } + System.out.println (); + + /* + * Release resources + */ + H5Tclose_wrap (s2_tid); + H5Tclose_wrap (s3_tid); + H5Dclose_wrap (dataset); + H5Fclose_wrap (file); + } + + + // Help function for creating a new file + public static int H5Fcreate_wrap (String name, int flags, + int create_id, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fcreate (name, flags, create_id, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Fcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Fcreate_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for adding another member to the compound + // datatype datatype_id. + public static int H5Tinsert_wrap (int type_id, String name, + long offset, int field_id) + { + int status = -1; + try + { + // Adding another member to the compound datatype datatype_id. + status = H5.H5Tinsert (type_id, name, offset, field_id); + + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Tinsert_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Tinsert_wrap() with HDF5Exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for creating the memory data type. + public static int H5Tcreate_wrap (int dclass, int size) + { + int datatype_id = -1; // memory data type identifier + try + { + // Create the memory data type. + datatype_id = H5.H5Tcreate (dclass, size); + + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Tcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Tcreate_wrap() with other Exception: " + + e.getMessage()); + } + return datatype_id; + } + + + // Help function for opening an existing file + public static int H5Fopen_wrap (String name, int flags, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fopen (name, flags, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Fopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Fopen_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for opening an existing dataset + public static int H5Dopen_wrap (int loc_id, String name) + { + int dataset_id = -1; // dataset identifier + + try + { + // Opening an existing dataset + dataset_id = H5.H5Dopen (loc_id, name); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Dopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Dopen_wrap() with other Exception: " + + e.getMessage()); + } + return dataset_id; + } + + + // Help function for creating a new simple dataspace and opening it + // for access + public static int H5Screate_simple_wrap (int rank, long dims[], + long maxdims[]) + { + int dataspace_id = -1; // dataspace identifier + + try + { + // Create the data space for the dataset. + dataspace_id = H5.H5Screate_simple (rank, dims, maxdims); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Screate_simple_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Screate_simple_wrap() with other Exception: " + + e.getMessage()); + } + return dataspace_id; + } + + + // Help function for creating a dataset + public static int H5Dcreate_wrap (int loc_id, String name, int type_id, + int space_id, int create_plist_id) + { + int dataset_id = -1; // dataset identifier + + try + { + // Create the dataset + dataset_id = H5.H5Dcreate (loc_id, name, type_id, space_id, + create_plist_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Dcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Dcreate_wrap() with other Exception: " + + e.getMessage()); + } + return dataset_id; + } + + + // Help function for writing the dataset + public static int H5Dwrite_wrap (int dataset_id, int mem_type_id, + int mem_space_id, int file_space_id, + int xfer_plist_id, Object buf) + { + int status = -1; + + try + { + // Write the dataset. + status = H5.H5Dwrite (dataset_id, mem_type_id, mem_space_id, + file_space_id, xfer_plist_id, buf); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Dwrite_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Dwrite_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for reading the dataset + public static int H5Dread_wrap (int dataset_id, int mem_type_id, + int mem_space_id, int file_space_id, + int xfer_plist_id, Object obj) + { + int status = -1; + + try + { + // Read the dataset. + status = H5.H5Dread (dataset_id, mem_type_id, mem_space_id, + file_space_id, xfer_plist_id, obj); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Dread_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Dread_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + + // Help function for terminating access to the data space. + public static int H5Sclose_wrap (int dataspace_id) + { + int status = -1; + + try + { + // Terminate access to the data space. + status = H5.H5Sclose (dataspace_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Sclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Sclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for releasing a datatype. + public static int H5Tclose_wrap (int type_id) + { + int status = -1; + + try + { + // Releasing a datatype. + status = H5.H5Tclose (type_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Tclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Tclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for ending access to the dataset and releasing + // resources used by it. + public static int H5Dclose_wrap (int dataset_id) + { + int status = -1; + + try + { + // End access to the dataset and release resources used by it. + status = H5.H5Dclose (dataset_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Dclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Dclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the file. + public static int H5Fclose_wrap (int file_id) + { + int status = -1; + + try + { + // Terminate access to the file. + status = H5.H5Fclose (file_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Compound.H5Fclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Compound.H5Fclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } +} diff --git a/doc/html/Tutor/examples/java/Copy.java b/doc/html/Tutor/examples/java/Copy.java new file mode 100644 index 0000000..f174210 --- /dev/null +++ b/doc/html/Tutor/examples/java/Copy.java @@ -0,0 +1,541 @@ +/****************************************************************** + * Copy.java (for HDF5 tutorial lesson 13) + * + * -- Showing how to use the H5SCOPY function. + * (a java conversion from h5_copy.c) + * + ******************************************************************/ + +import ncsa.hdf.hdf5lib.*; +import ncsa.hdf.hdf5lib.exceptions.*; + +public class Copy +{ + public static void main (String []argv) + { + final String FILE1 = "copy1.h5"; + final String FILE2 = "copy2.h5"; + + final int RANK = 2; + final int DIM1 = 3; + final int DIM2 = 4; + final int NUMP = 2; + + int file1, file2, dataset1, dataset2; + int mid1, mid2, fid1, fid2; + long[] fdim = new long[2]; + fdim[0] = DIM1; + fdim[1] = DIM2; + long[] mdim = new long[2]; + fdim[0] = DIM1; + fdim[1] = DIM2; + + long[] start = new long[2]; + long[] stride = new long[2]; + long[] count = new long[2]; + long[] block = new long[2]; + + int[][] buf1 = new int[DIM1][DIM2]; + int[][] buf2 = new int[DIM1][DIM2]; + int[][] bufnew = new int[DIM1][DIM2]; + + int[] val = new int[2]; + val[0] = 53; + val[1] = 59; + + long[] marray = {2}; + long[][] coord = new long[NUMP][RANK]; + int ret; + int 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_wrap (FILE1, HDF5Constants.H5F_ACC_TRUNC, + HDF5Constants.H5P_DEFAULT, + HDF5Constants.H5P_DEFAULT); + file2 = H5Fcreate_wrap (FILE2, HDF5Constants.H5F_ACC_TRUNC, + HDF5Constants.H5P_DEFAULT, + HDF5Constants.H5P_DEFAULT); + + fid1 = H5Screate_simple_wrap (RANK, fdim, null); + fid2 = H5Screate_simple_wrap (RANK, fdim, null); + + dataset1 = H5Dcreate_wrap + (file1, "Copy1", H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), fid1, + HDF5Constants.H5P_DEFAULT); + + dataset2 = H5Dcreate_wrap + (file2, "Copy2", H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), fid2, + HDF5Constants.H5P_DEFAULT); + + + ret = H5Dwrite_wrap (dataset1, H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + HDF5Constants.H5S_ALL, HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, buf1); + + ret = H5Dwrite_wrap (dataset2, H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + HDF5Constants.H5S_ALL, HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, buf2); + + ret = H5Dclose_wrap (dataset1); + ret = H5Dclose_wrap (dataset2); + + ret = H5Sclose_wrap (fid1); + ret = H5Sclose_wrap (fid2); + + ret = H5Fclose_wrap (file1); + ret = H5Fclose_wrap (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_wrap (FILE1, HDF5Constants.H5F_ACC_RDWR, + HDF5Constants.H5P_DEFAULT); + + file2 = H5Fopen_wrap (FILE2, HDF5Constants.H5F_ACC_RDWR, + HDF5Constants.H5P_DEFAULT); + + dataset1 = H5Dopen_wrap (file1, "Copy1"); + dataset2 = H5Dopen_wrap (file2, "Copy2"); + + fid1 = H5Dget_space_wrap (dataset1); + mid1 = H5Screate_simple_wrap (1, marray, null); + + coord[0][0] = 0; coord[0][1] = 3; + coord[1][0] = 0; coord[1][1] = 1; + + ret = H5Sselect_elements_wrap (fid1, HDF5Constants.H5S_SELECT_SET, + NUMP, coord); + + ret = H5Dwrite_wrap (dataset1, H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + mid1, fid1, HDF5Constants.H5P_DEFAULT, val); + + fid2 = H5Scopy_wrap (fid1); + + ret = H5Dwrite_wrap (dataset2, H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + mid1, fid2, HDF5Constants.H5P_DEFAULT, val); + + ret = H5Dclose_wrap (dataset1); + ret = H5Dclose_wrap (dataset2); + ret = H5Sclose_wrap (fid1); + ret = H5Sclose_wrap (fid2); + ret = H5Fclose_wrap (file1); + ret = H5Fclose_wrap (file2); + ret = H5Sclose_wrap (mid1); + + +/***********************************************************************/ +/* */ +/* Open both files and print the contents of the datasets. */ +/* */ +/***********************************************************************/ + + file1 = H5Fopen_wrap (FILE1, HDF5Constants.H5F_ACC_RDWR, + HDF5Constants.H5P_DEFAULT); + file2 = H5Fopen_wrap (FILE2, HDF5Constants.H5F_ACC_RDWR, + HDF5Constants.H5P_DEFAULT); + dataset1 = H5Dopen_wrap (file1, "Copy1"); + dataset2 = H5Dopen_wrap (file2, "Copy2"); + + ret = H5Dread_wrap (dataset1, H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + HDF5Constants.H5S_ALL, HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, bufnew); + + System.out.println ("\nDataset 'Copy1' in file 'copy1.h5' contains: "); + + for (i = 0;i < DIM1; i++) + { + for (j = 0;j < DIM2; j++) + System.out.print (bufnew[i][j]); + System.out.println (); + } + + System.out.println ("\nDataset 'Copy2' in file 'copy2.h5' contains: "); + + ret = H5Dread_wrap (dataset2, H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + HDF5Constants.H5S_ALL, HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, bufnew); + + for (i = 0;i < DIM1; i++) + { + for (j = 0;j < DIM2; j++) + System.out.print (bufnew[i][j]); + System.out.println (); + } + + ret = H5Dclose_wrap (dataset1); + ret = H5Dclose_wrap (dataset2); + ret = H5Fclose_wrap (file1); + ret = H5Fclose_wrap (file2); + } + + + // Help function for creating a new file + public static int H5Fcreate_wrap (String name, int flags, + int create_id, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fcreate (name, flags, create_id, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Fcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Fcreate_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for opening an existing file + public static int H5Fopen_wrap (String name, int flags, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fopen (name, flags, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Fopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Fopen_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for opening an existing dataset + public static int H5Dopen_wrap (int loc_id, String name) + { + int dataset_id = -1; // dataset identifier + + try + { + // Opening an existing dataset + dataset_id = H5.H5Dopen (loc_id, name); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Dopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Dopen_wrap() with other Exception: " + + e.getMessage()); + } + return dataset_id; + } + + + // Help function for creating a new simple dataspace and opening it + // for access + public static int H5Screate_simple_wrap (int rank, long dims[], + long maxdims[]) + { + int dataspace_id = -1; // dataspace identifier + + try + { + // Create the data space for the dataset. + dataspace_id = H5.H5Screate_simple (rank, dims, maxdims); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Screate_simple_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Screate_simple_wrap() with other Exception: " + + e.getMessage()); + } + return dataspace_id; + } + + + // Help function for getting an identifier for a copy of + // the dataspace for a dataset + public static int H5Dget_space_wrap (int dataset_id) + { + int dataspace_id = -1; + + try + { + // Returning an identifier for a copy of the dataspace for a dataset + dataspace_id = H5.H5Dget_space (dataset_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Dget_space_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Dget_space_wrap() with other Exception: " + + e.getMessage()); + } + return dataspace_id; + } + + + // Help function for selecting array elements to be included in + // the selection for the space_id dataspace. + public static int H5Sselect_elements_wrap (int space_id, int op, + int num_elements, + long coord2D[][]) + { + int status = -1; + + try + { + status = H5.H5Sselect_elements (space_id, op, num_elements, + coord2D); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Sselect_elements_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Sselect_elements_wrap() with other Exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for creating a new dataspace which is an exact + // copy of the dataspace identified by space_id. + public static int H5Scopy_wrap (int space_id) + { + int dataspace_id = -1; + + try + { + dataspace_id = H5.H5Scopy(space_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println ("Copy.H5Scopy_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println ("Copy.H5Scopy_wrap() with other Exception: " + + e.getMessage()); + } + return dataspace_id; + } + + + // Help function for creating a dataset + public static int H5Dcreate_wrap (int loc_id, String name, int type_id, + int space_id, int create_plist_id) + { + int dataset_id = -1; // dataset identifier + + try + { + // Create the dataset + dataset_id = H5.H5Dcreate (loc_id, name, type_id, space_id, + create_plist_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Dcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Dcreate_wrap() with other Exception: " + + e.getMessage()); + } + return dataset_id; + } + + + // Help function for writing the dataset + public static int H5Dwrite_wrap (int dataset_id, int mem_type_id, + int mem_space_id, int file_space_id, + int xfer_plist_id, Object buf) + { + int status = -1; + + try + { + // Write the dataset. + status = H5.H5Dwrite (dataset_id, mem_type_id, mem_space_id, + file_space_id, xfer_plist_id, buf); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Dwrite_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Dwrite_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for reading the dataset + public static int H5Dread_wrap (int dataset_id, int mem_type_id, + int mem_space_id, int file_space_id, + int xfer_plist_id, Object obj) + { + int status = -1; + + try + { + // Read the dataset. + status = H5.H5Dread (dataset_id, mem_type_id, mem_space_id, + file_space_id, xfer_plist_id, obj); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Dread_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Dread_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the data space. + public static int H5Sclose_wrap (int dataspace_id) + { + int status = -1; + + try + { + // Terminate access to the data space. + status = H5.H5Sclose (dataspace_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Sclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Sclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for ending access to the dataset and releasing + // resources used by it. + public static int H5Dclose_wrap (int dataset_id) + { + int status = -1; + + try + { + // End access to the dataset and release resources used by it. + status = H5.H5Dclose (dataset_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Dclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Dclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the file. + public static int H5Fclose_wrap (int file_id) + { + int status = -1; + + try + { + // Terminate access to the file. + status = H5.H5Fclose (file_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("Copy.H5Fclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("Copy.H5Fclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } +} diff --git a/doc/html/Tutor/examples/java/CreateAttribute.java b/doc/html/Tutor/examples/java/CreateAttribute.java new file mode 100644 index 0000000..c926422 --- /dev/null +++ b/doc/html/Tutor/examples/java/CreateAttribute.java @@ -0,0 +1,302 @@ +/****************************************************************** + * CreateAttribute.java (for HDF5 tutorial lesson 7) + * + * -- Creating and Writing a dataset attribute + * (a java conversion from h5_crtatt.c) + * + ******************************************************************/ + +import ncsa.hdf.hdf5lib.*; +import ncsa.hdf.hdf5lib.exceptions.*; + +public class CreateAttribute +{ + public static void main(String []argv) + { + final String FILE = "dset.h5"; + int file_id = -1; // file identifier + int dataset_id = -1; // dataset identifier + int attribute_id = -1; + int dataspace_id = -1; // dataspace identifier + long[] dims = new long[1]; + int[] attr_data = new int[2]; + int status = -1; + + // Initialize the attribute data. + attr_data[0] = 100; + attr_data[1] = 200; + + // Open an existing file. + file_id = H5Fopen_wrap (FILE, HDF5Constants.H5F_ACC_RDWR, + HDF5Constants.H5P_DEFAULT); + + // Open an existing dataset. + dataset_id = H5Dopen_wrap (file_id, "/dset"); + + // Create the data space for the attribute. + dims[0] = 2; + dataspace_id = H5Screate_simple_wrap (1, dims, null); + + // Create a dataset attribute. + attribute_id = H5Acreate_wrap + (dataset_id, "attr", + H5.J2C (HDF5CDataTypes.JH5T_STD_I32BE), + dataspace_id, HDF5Constants.H5P_DEFAULT); + + // Write the attribute data. + status = H5Awrite_wrap + (attribute_id, + H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + attr_data); + + // Close the attribute. + status = H5Aclose_wrap (attribute_id); + + // Close the dataspace. + status = H5Sclose_wrap (dataspace_id); + + // Close to the dataset. + status = H5Dclose_wrap (dataset_id); + + // Close the file. + status = H5Fclose_wrap (file_id); + } + + + // Help function for opening an existing file + public static int H5Fopen_wrap (String name, int flags, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fopen (name, flags, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateAttribute.H5Fopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateAttribute.H5Fopen_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for opening an existing dataset + public static int H5Dopen_wrap (int loc_id, String name) + { + int dataset_id = -1; // dataset identifier + + try + { + // Opening an existing dataset + dataset_id = H5.H5Dopen (loc_id, name); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateAttribute.H5Dopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateAttribute.H5Dopen_wrap() with other Exception: " + + e.getMessage()); + } + return dataset_id; + } + + + // Create the data space for the attribute. + public static int H5Screate_simple_wrap (int rank, long dims[], + long maxdims[]) + { + int dataspace_id = -1; // dataspace identifier + + try + { + // Create the data space for the dataset. + dataspace_id = H5.H5Screate_simple (rank, dims, maxdims); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateAttribute.H5Screate_simple_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + + } + catch (Exception e) + { + System.out.println + ("CreateAttribute.H5Screate_simple_wrap() with other Exception: " + + e.getMessage()); + } + return dataspace_id; + } + + + // Help function for creating a dataset attribute. + public static int H5Acreate_wrap (int loc_id, String name, int type_id, + int space_id, int create_plist) + { + int attribute_id = -1; // attribute identifier + + try + { + // Create the dataset + attribute_id = H5.H5Acreate (loc_id, name, type_id, space_id, + create_plist); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateAttribute.H5Acreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateAttribute.H5Acreate_wrap() with other Exception: " + + e.getMessage()); + } + return attribute_id; + } + + + // Help function for writing the attribute data. + public static int H5Awrite_wrap (int attr_id, int mem_type_id, + Object buf) + { + int status = -1; + + try + { + // Write the attribute data. + status = H5.H5Awrite (attr_id, mem_type_id, buf); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateAttribute.H5Awrite_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateAttribute.H5Awrite_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for closing the attribute + public static int H5Aclose_wrap (int attribute_id) + { + int status = -1; + + try + { + // Close the dataset + status = H5.H5Aclose (attribute_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateAttribute.H5Aclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateAttribute.H5Aclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for closing the dataset + public static int H5Dclose_wrap (int dataset_id) + { + int status = -1; + + try + { + // Close the dataset + status = H5.H5Dclose (dataset_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateAttribute.H5Dclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateAttribute.H5Dclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for closing the dataspace + public static int H5Sclose_wrap (int dataspace_id) + { + int status = -1; + + try + { + // Terminate access to the data space. + status = H5.H5Sclose (dataspace_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateAttribute.H5Sclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateAttribute.H5Sclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the file. + public static int H5Fclose_wrap (int file_id) + { + int status = -1; + + try + { + // Terminate access to the file. + status = H5.H5Fclose (file_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateAttribute.H5Fclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateAttribute.H5Fclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } +} diff --git a/doc/html/Tutor/examples/java/CreateDataset.java b/doc/html/Tutor/examples/java/CreateDataset.java new file mode 100644 index 0000000..05f3f6b --- /dev/null +++ b/doc/html/Tutor/examples/java/CreateDataset.java @@ -0,0 +1,210 @@ +/****************************************************************** + * CreateDataset.java (for HDF5 tutorial lesson 5) + * + * -- Creating a HDF5 Dataset + * (a java conversion from h5_crtdat.c) + * + ******************************************************************/ + +import ncsa.hdf.hdf5lib.*; +import ncsa.hdf.hdf5lib.exceptions.*; + +public class CreateDataset +{ + public static void main(String []argv) + { + final String FILE = "dset.h5"; + int file_id = -1; // file identifier + int dataset_id = -1; // dataset identifier + int dataspace_id = -1; // dataspace identifier + long[] dims = new long[2]; + int status = -1; + + // Create a new file using default properties. + file_id = H5Fcreate_wrap (FILE, HDF5Constants.H5F_ACC_TRUNC, + HDF5Constants.H5P_DEFAULT, + HDF5Constants.H5P_DEFAULT); + + // Create the data space for the dataset. + dims[0] = 4; + dims[1] = 6; + dataspace_id = H5Screate_simple_wrap (2, dims, null); + + // Create the dataset. + dataset_id = + H5Dcreate_wrap (file_id, "/dset", + H5.J2C (HDF5CDataTypes.JH5T_STD_I32BE), + dataspace_id, HDF5Constants.H5P_DEFAULT); + + // End access to the dataset and release resources used by it. + status = H5Dclose_wrap (dataset_id); + + // Terminate access to the data space. + status = H5Sclose_wrap (dataspace_id); + + // Close the file. + status = H5Fclose_wrap (file_id); + } + + + // Help function for creating a new file + public static int H5Fcreate_wrap (String name, int flags, + int create_id, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fcreate (name, flags, create_id, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateDataset.H5Fcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateDataset.H5Fcreate_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for creating a new simple dataspace and opening it + // for access + public static int H5Screate_simple_wrap (int rank, long dims[], + long maxdims[]) + { + int dataspace_id = -1; // dataspace identifier + + try + { + // Create the data space for the dataset. + dataspace_id = H5.H5Screate_simple (rank, dims, maxdims); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateDataset.H5Screate_simple_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateDataset.H5Screate_simple_wrap() with other Exception: " + + e.getMessage()); + } + return dataspace_id; + } + + + // Help function for creating a dataset + public static int H5Dcreate_wrap (int loc_id, String name, int type_id, + int space_id, int create_plist_id) + { + int dataset_id = -1; // dataset identifier + + try + { + // Create the dataset + dataset_id = H5.H5Dcreate (loc_id, name, type_id, space_id, + create_plist_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateDataset.H5Dcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateDataset.H5Dcreate_wrap() with other Exception: " + + e.getMessage()); + } + return dataset_id; + } + + + // Help function for ending access to the dataset and releasing + // resources used by it. + public static int H5Dclose_wrap (int dataset_id) + { + int status = -1; + + try + { + // End access to the dataset and release resources used by it. + status = H5.H5Dclose (dataset_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateDataset.H5Dclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateDataset.H5Dclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the data space. + public static int H5Sclose_wrap (int dataspace_id) + { + int status = -1; + + try + { + // Terminate access to the data space. + status = H5.H5Sclose (dataspace_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateDataset.H5Sclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateDataset.H5Sclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the file. + public static int H5Fclose_wrap (int file_id) + { + int status = -1; + + try + { + // Terminate access to the file. + status = H5.H5Fclose (file_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateDataset.H5Fclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateDataset.H5Fclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } +} + diff --git a/doc/html/Tutor/examples/java/CreateFile.java b/doc/html/Tutor/examples/java/CreateFile.java new file mode 100644 index 0000000..550b263 --- /dev/null +++ b/doc/html/Tutor/examples/java/CreateFile.java @@ -0,0 +1,83 @@ +/****************************************************************** + * CreateFile.java (for HDF5 tutorial lesson 4) + * + * -- Creating a HDF5 file + * (a java conversion from h5_crtfile.c) + * + ******************************************************************/ + +import ncsa.hdf.hdf5lib.*; +import ncsa.hdf.hdf5lib.exceptions.*; + +public class CreateFile +{ + public static void main(String []argv) + { + final String FILE = "file.h5"; + int file_id = -1; // file identifier + int status = -1; + + file_id = H5Fcreate_wrap (FILE, HDF5Constants.H5F_ACC_TRUNC, + HDF5Constants.H5P_DEFAULT, + HDF5Constants.H5P_DEFAULT); + status = H5Fclose_wrap (file_id); + } + + + // Help function for creating a new file + public static int H5Fcreate_wrap (String name, int flags, + int create_id, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fcreate (name, flags, create_id, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateFile.H5Fcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateFile.H5Fcreate_wrap() with other Exception: " + + e.getMessage()); + } + + System.out.println ("\nThe file name is: " + name); + System.out.println ("The file ID is: " + file_id); + + return file_id; + } + + + // Help function for terminating access to the file. + public static int H5Fclose_wrap (int file_id) + { + int status = -1; + + try + { + // Terminate access to the file. + status = H5.H5Fclose (file_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateFile.H5Fclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateFile.H5Fclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } +} + + diff --git a/doc/html/Tutor/examples/java/CreateFileInput.java b/doc/html/Tutor/examples/java/CreateFileInput.java new file mode 100644 index 0000000..0e7fd4d --- /dev/null +++ b/doc/html/Tutor/examples/java/CreateFileInput.java @@ -0,0 +1,118 @@ +/****************************************************************** + * CreateFileInput.java (for HDF5 tutorial Lesson 4) + * + * -- Creating a HDF5 file + * (another java conversion from h5_crtfile.c, give user two options: + * one for library path and one for file name, if user chooses + * nothing, then the default file name is used.) + * + ******************************************************************/ + +import java.lang.System; +import java.util.*; +import ncsa.hdf.hdf5lib.*; +import ncsa.hdf.hdf5lib.exceptions.*; + +public class CreateFileInput +{ + // The run command should be like: + // "./runCreateFileInput -l /usr/lib/hdf5.dll -f ./open.h5" + public static void main(String []argv) + { + int file_id = -1; // file identifier + int status = -1; + String libpath = null; + String filename = null; + + for (int i = 0; i < argv.length; i++) + { + if ("-l".equalsIgnoreCase (argv[i])) + libpath = argv[++i]; + + if ("-f".equalsIgnoreCase (argv[i])) + filename = argv[++i]; + } + + if (libpath != null) + { + Properties pros = System.getProperties (); + pros.put (H5.H5PATH_PROPERTY_KEY, libpath); + + /* + this function call could be used in Java 1.2 + System.setProperty (H5.H5PATH_PROPERTY_KEY, libpath); + */ + } + + if (filename == null) + { + filename = "file.h5"; // if no input file name, use the default name + } + + file_id = H5Fcreate_wrap (filename, + HDF5Constants.H5F_ACC_TRUNC, + HDF5Constants.H5P_DEFAULT, + HDF5Constants.H5P_DEFAULT); + status = H5Fclose_wrap (filename, file_id); + } + + + // Help function for creating a new file + public static int H5Fcreate_wrap (String name, int flags, + int create_id, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fcreate (name, flags, create_id, access_id); + + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateFileInput.H5Fcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateFileInput.H5Fcreate_wrap() with other Exception: " + + e.getMessage()); + } + + System.out.println ("\nThe file name is: " + name); + System.out.println ("The file ID is: " + file_id); + + return file_id; + } + + + // Help function for terminating access to the file. + public static int H5Fclose_wrap (String name, int file_id) + { + int status = -1; + + try + { + // Terminate access to the file. + status = H5.H5Fclose (file_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateFileInput.H5Fclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateFileInput.H5Fclose_wrap() with other exception: " + + e.getMessage()); + } + + return status; + } +} + + diff --git a/doc/html/Tutor/examples/java/CreateGroup.java b/doc/html/Tutor/examples/java/CreateGroup.java new file mode 100644 index 0000000..48ef4af --- /dev/null +++ b/doc/html/Tutor/examples/java/CreateGroup.java @@ -0,0 +1,139 @@ +/****************************************************************** + * CreateGroup.java (for HDF5 tutorial lesson 8) + * + * -- Creating and closing a group + * (a java conversion from h5_crtgrp.c) + * + ******************************************************************/ + +import ncsa.hdf.hdf5lib.*; +import ncsa.hdf.hdf5lib.exceptions.*; + +public class CreateGroup +{ + public static void main(String []argv) + { + final String FILE = "group.h5"; + int file_id = -1; // file identifier + int group_id = -1; // group identifier + int status = -1; + + // Create a new file using default properties. + file_id = H5Fcreate_wrap (FILE, HDF5Constants.H5F_ACC_TRUNC, + HDF5Constants.H5P_DEFAULT, + HDF5Constants.H5P_DEFAULT); + + // Create a group named "/MyGroup" in the file. + group_id = H5Gcreate_wrap (file_id, "/MyGroup", 0); + + // Close the group. + status = H5Gclose_wrap (group_id); + + // Close the file. + status = H5Fclose_wrap (file_id); + } + + + // Help function for creating a new file + public static int H5Fcreate_wrap (String name, int flags, + int create_id, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fcreate (name, flags, create_id, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroup.H5Fcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroup.H5Fcreate_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for creating a group named "/MyGroup" in the file. + public static int H5Gcreate_wrap (int loc_id, String name, int size_hint) + { + int group_id = -1; // group identifier + try + { + // Create a group + group_id = H5.H5Gcreate (loc_id, name, size_hint); + + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroup.H5Gcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroup.H5Gcreate_wrap() with other Exception: " + + e.getMessage()); + } + return group_id; + } + + + // Help function for closing the group + public static int H5Gclose_wrap (int group_id) + { + int status = -1; + + try + { + // Close the group + status = H5.H5Gclose (group_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroup.H5Gclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroup.H5Gclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the file. + public static int H5Fclose_wrap (int file_id) + { + int status = -1; + + try + { + // Terminate access to the file. + status = H5.H5Fclose (file_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroup.H5Fclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroup.H5Fclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } +} diff --git a/doc/html/Tutor/examples/java/CreateGroupAR.java b/doc/html/Tutor/examples/java/CreateGroupAR.java new file mode 100644 index 0000000..672f1d1 --- /dev/null +++ b/doc/html/Tutor/examples/java/CreateGroupAR.java @@ -0,0 +1,152 @@ +/****************************************************************** + * CreateGroupAR.java (for HDF5 tutorial lesson 9) + * + * -- Creating groups using absolute and relative names. + * (a java conversion from h5_crtgrpar.c) + * + ******************************************************************/ + +import ncsa.hdf.hdf5lib.*; +import ncsa.hdf.hdf5lib.exceptions.*; + +public class CreateGroupAR +{ + public static void main(String []argv) + { + final String FILE = "groups.h5"; + int file_id = -1; // file identifier + int group1_id = -1; // group identifier + int group2_id = -1; + int group3_id = -1; + + int status = -1; + + // Create a new file using default properties. + file_id = H5Fcreate_wrap (FILE, HDF5Constants.H5F_ACC_TRUNC, + HDF5Constants.H5P_DEFAULT, + HDF5Constants.H5P_DEFAULT); + + // Create group "MyGroup" in the root group using absolute name. + group1_id = H5Gcreate_wrap (file_id, "/MyGroup", 0); + + + // Create group "Group_A" in group "MyGroup" using absolute name. + group2_id = H5Gcreate_wrap (file_id, "/MyGroup/Group_A", 0); + + // Create group "Group_B" in group "MyGroup" using relative name. + group3_id = H5Gcreate_wrap (group1_id, "Group_B", 0); + + // Close groups. + status = H5Gclose_wrap (group1_id); + status = H5Gclose_wrap (group2_id); + status = H5Gclose_wrap (group3_id); + + // Close the file. + status = H5Fclose_wrap (file_id); + } + + + // Help function for creating a new file + public static int H5Fcreate_wrap (String name, int flags, + int create_id, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fcreate (name, flags, create_id, access_id); + + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupAR.H5Fcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupAR.H5Fcreate_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for creating a group named "/MyGroup" in the file. + public static int H5Gcreate_wrap (int loc_id, String name, int size_hint) + { + int group_id = -1; // group identifier + try + { + // Create a group + group_id = H5.H5Gcreate (loc_id, name, size_hint); + + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupAR.H5Gcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupAR.H5Gcreate_wrap() with other Exception: " + + e.getMessage()); + } + return group_id; + } + + + // Help function for closing the group + public static int H5Gclose_wrap (int group_id) + { + int status = -1; + + try + { + // Close the group + status = H5.H5Gclose (group_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupAR.H5Gclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupAR.H5Gclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the file. + public static int H5Fclose_wrap (int file_id) + { + int status = -1; + + try + { + // Terminate access to the file. + status = H5.H5Fclose (file_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupAR.H5Fclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupAR.H5Fclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } +} diff --git a/doc/html/Tutor/examples/java/CreateGroupDataset.java b/doc/html/Tutor/examples/java/CreateGroupDataset.java new file mode 100644 index 0000000..f0fbeaa --- /dev/null +++ b/doc/html/Tutor/examples/java/CreateGroupDataset.java @@ -0,0 +1,340 @@ +/****************************************************************** + * CreateGroupDataset.java (for HDF5 tutorial lesson 10) + * + * -- Creating a dataset in a particular group + * (a java conversion from h5_crtgrpd.c) + * + ******************************************************************/ + +import ncsa.hdf.hdf5lib.*; +import ncsa.hdf.hdf5lib.exceptions.*; + +public class CreateGroupDataset +{ + public static void main(String []argv) + { + final String FILE = "groups.h5"; + int file_id = -1; // file identifier + int group_id = -1; // group identifier + int dataset_id; + int dataspace_id; + int status = -1; + + long[] dims = new long[2]; + int[][] dset1_data = new int[3][3]; + int[][] dset2_data = new int[2][10]; + int i = -1, j = -1; + + // 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_wrap (FILE, HDF5Constants.H5F_ACC_RDWR, + HDF5Constants.H5P_DEFAULT); + + // Create the data space for the first dataset. + dims[0] = 3; + dims[1] = 3; + dataspace_id = H5Screate_simple_wrap (2, dims, null); + + // Create a dataset in group "MyGroup". + dataset_id = + H5Dcreate_wrap (file_id, "/MyGroup/dset1", + H5.J2C (HDF5CDataTypes.JH5T_STD_I32BE), + dataspace_id, HDF5Constants.H5P_DEFAULT); + + // Write the first dataset. + status = H5Dwrite_wrap + (dataset_id, + H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + HDF5Constants.H5S_ALL, HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, dset1_data); + + // Close the data space for the first dataset. + status = H5Sclose_wrap (dataspace_id); + + // Close the first dataset. + status = H5Dclose_wrap (dataset_id); + + // Open an existing group of the specified file. + group_id = H5Gopen_wrap (file_id, "/MyGroup/Group_A"); + + // Create the data space for the second dataset. + dims[0] = 2; + dims[1] = 10; + dataspace_id = H5Screate_simple_wrap (2, dims, null); + + // Create the second dataset in group "Group_A". + dataset_id = + H5Dcreate_wrap (group_id, "dset2", + H5.J2C (HDF5CDataTypes.JH5T_STD_I32BE), + dataspace_id, HDF5Constants.H5P_DEFAULT); + + // Write the second dataset. + status = H5Dwrite_wrap + (dataset_id, + H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + HDF5Constants.H5S_ALL, HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, dset2_data); + + // Close the data space for the second dataset. + status = H5Sclose_wrap (dataspace_id); + + // Close the second dataset + status = H5Dclose_wrap (dataset_id); + + // Close the group. + status = H5Gclose_wrap (group_id); + + // Close the file. + status = H5Fclose_wrap (file_id); + } + + + // Help function for opening an existing file + public static int H5Fopen_wrap (String name, int flags, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fopen (name, flags, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupDataset.H5Fopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupDataset.H5Fopen_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for creating a new simple dataspace and opening it + // for access + public static int H5Screate_simple_wrap (int rank, long dims[], + long maxdims[]) + { + int dataspace_id = -1; // dataspace identifier + + try + { + // Create the data space for the dataset. + dataspace_id = H5.H5Screate_simple (rank, dims, maxdims); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupDataset.H5Screate_simple_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupDataset.H5Screate_simple_wrap() with other Exception: " + + e.getMessage()); + } + return dataspace_id; + } + + + // Help function for creating a dataset + public static int H5Dcreate_wrap (int loc_id, String name, int type_id, + int space_id, int create_plist_id) + { + int dataset_id = -1; // dataset identifier + + try + { + // Create the dataset + dataset_id = H5.H5Dcreate (loc_id, name, type_id, space_id, + create_plist_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupDataset.H5Dcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupDataset.H5Dcreate_wrap() with other Exception: " + + e.getMessage()); + } + return dataset_id; + } + + + // Help function for writing the dataset + public static int H5Dwrite_wrap (int dataset_id, int mem_type_id, + int mem_space_id, int file_space_id, + int xfer_plist_id, Object buf) + { + int status = -1; + + try + { + // Write the dataset. + status = H5.H5Dwrite (dataset_id, mem_type_id, mem_space_id, + file_space_id, xfer_plist_id, buf); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupDataset.H5Dwrite_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupDataset.H5Dwrite_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the data space. + public static int H5Sclose_wrap (int dataspace_id) + { + int status = -1; + + try + { + // Terminate access to the data space. + status = H5.H5Sclose (dataspace_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupDataset.H5Sclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupDataset.H5Sclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for ending access to the dataset and releasing + // resources used by it. + public static int H5Dclose_wrap (int dataset_id) + { + int status = -1; + + try + { + // End access to the dataset and release resources used by it. + status = H5.H5Dclose (dataset_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupDataset.H5Dclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupDataset.H5Dclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for opening a group + public static int H5Gopen_wrap (int loc_id, String name) + { + int group_id = -1; // group identifier + try + { + // Create a group + group_id = H5.H5Gopen (loc_id, name); + + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupDataset.H5Gopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupDataset.H5Gopen_wrap() with other Exception: " + + e.getMessage()); + } + return group_id; + } + + + // Help function for closing the group + public static int H5Gclose_wrap (int group_id) + { + int status = -1; + + try + { + // Close the group + status = H5.H5Gclose (group_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupDataset.H5Gclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupDataset.H5Gclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the file. + public static int H5Fclose_wrap (int file_id) + { + int status = -1; + + try + { + // Terminate access to the file. + status = H5.H5Fclose (file_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("CreateGroupDataset.H5Fclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("CreateGroupDataset.H5Fclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } +} diff --git a/doc/html/Tutor/examples/java/DatasetRdWt.java b/doc/html/Tutor/examples/java/DatasetRdWt.java new file mode 100644 index 0000000..4c26d0f --- /dev/null +++ b/doc/html/Tutor/examples/java/DatasetRdWt.java @@ -0,0 +1,213 @@ +/****************************************************************** + * DatasetRdWt.java (for HDF5 tutorial lesson 6) + * + * -- Reading and Writing an existing Dataset + * (a java conversion from h5_rdwt.c) + * + ******************************************************************/ + +import ncsa.hdf.hdf5lib.*; +import ncsa.hdf.hdf5lib.exceptions.*; + +public class DatasetRdWt +{ + public static void main(String []argv) + { + final String FILE = "dset.h5"; + int file_id = -1; // file identifier + int dataset_id = -1; // dataset identifier + int status = -1; + int[][] dset_data = new int[4][6]; + + // Initialize the dataset. + for (int i = 0; i < 4; i++) + for (int j = 0; j < 6; j++) + dset_data[i][j] = i * 6 + j + 1; + + // Open an existing file + file_id = H5Fopen_wrap (FILE, HDF5Constants.H5F_ACC_RDWR, + HDF5Constants.H5P_DEFAULT); + + // Open an existing dataset. + dataset_id = H5Dopen_wrap (file_id, "/dset"); + + // Write the dataset. + status = H5Dwrite_wrap + (dataset_id, H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + HDF5Constants.H5S_ALL, HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, dset_data); + + status = H5Dread_wrap + (dataset_id, H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + HDF5Constants.H5S_ALL, HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, dset_data); + + // Close the dataset. + status = H5Dclose_wrap (dataset_id); + + // Close the file. + status = H5Fclose_wrap (file_id); + } + + + // Help function for opening an existing file + public static int H5Fopen_wrap (String name, int flags, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fopen (name, flags, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("DatasetRdWt.H5Fopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("DatasetRdWt.H5Fopen_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for opening an existing dataset + public static int H5Dopen_wrap (int loc_id, String name) + { + int dataset_id = -1; // dataset identifier + + try + { + // Opening an existing dataset + dataset_id = H5.H5Dopen (loc_id, name); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("DatasetRdWt.H5Dopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("DatasetRdWt.H5Dopen_wrap() with other Exception: " + + e.getMessage()); + } + return dataset_id; + } + + + // Help function for writing the dataset + public static int H5Dwrite_wrap (int dataset_id, int mem_type_id, + int mem_space_id, int file_space_id, + int xfer_plist_id, Object buf) + { + int status = -1; + + try + { + // Write the dataset. + status = H5.H5Dwrite (dataset_id, mem_type_id, mem_space_id, + file_space_id, xfer_plist_id, buf); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("DatasetRdWt.H5Dwrite_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("DatasetRdWt.H5Dwrite_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for reading the dataset + public static int H5Dread_wrap (int dataset_id, int mem_type_id, + int mem_space_id, int file_space_id, + int xfer_plist_id, Object obj) + { + int status = -1; + + try + { + // Read the dataset. + status = H5.H5Dread (dataset_id, mem_type_id, mem_space_id, + file_space_id, xfer_plist_id, obj); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("DatasetRdWt.H5Dread_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("DatasetRdWt.H5Dread_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for ending access to the dataset and releasing + // resources used by it. + public static int H5Dclose_wrap (int dataset_id) + { + int status = -1; + + try + { + // End access to the dataset and release resources used by it. + status = H5.H5Dclose (dataset_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("DatasetRdWt.H5Dclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("DatasetRdWt.H5Dclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the file. + public static int H5Fclose_wrap (int file_id) + { + int status = -1; + + try + { + // Terminate access to the file. + status = H5.H5Fclose (file_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("DatasetRdWt.H5Fclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("DatasetRdWt.H5Fclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } +} diff --git a/doc/html/Tutor/examples/java/HyperSlab.java b/doc/html/Tutor/examples/java/HyperSlab.java new file mode 100644 index 0000000..5f8818d --- /dev/null +++ b/doc/html/Tutor/examples/java/HyperSlab.java @@ -0,0 +1,590 @@ +/****************************************************************** + * HyperSlab.java (for HDF5 tutorial lesson 12) + * + * -- Writing and reading a hyperslab + * (a java conversion from h5_hyperslab.c) + * + ******************************************************************/ + +import ncsa.hdf.hdf5lib.*; +import ncsa.hdf.hdf5lib.exceptions.*; + +public class HyperSlab +{ + public static void main (String []argv) + { + final String FILE = "sds.h5"; + final String DATASETNAME = "IntArray"; + final int NX_SUB = 3; /* hyperslab dimensions */ + final int NY_SUB = 4; + final int NX = 7; /* output buffer dimensions */ + final int NY = 7; + final int NZ = 3; + final int RANK = 2; + final int RANK_OUT = 3; + final int X = 5; /* dataset dimensions */ + final int Y = 6; + + long[] dimsf = new long[2]; /* dataset dimensions */ + int[][] data = new int[X][Y]; /* data to write */ + + /* + * Data and output buffer initialization. + */ + int file, dataset; /* handles */ + int dataspace; + int memspace; + long[] dimsm = new long[3]; /* memory space dimensions */ + long[] dims_out = new long[2]; /* dataset dimensions */ + int status; + + int[][][] data_out = new int[NX][NY][NZ]; /* output buffer */ + + long[] count = new long[2]; /* size of the hyperslab in the file */ + long[] offset = new long[2]; /* hyperslab offset in the file */ + long[] count_out = new long[3]; /* size of the hyperslab in memory */ + long[] offset_out = new long[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_wrap (FILE, HDF5Constants.H5F_ACC_TRUNC, + HDF5Constants.H5P_DEFAULT, + HDF5Constants.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_wrap (RANK, dimsf, null); + + /* + * Create a new dataset within the file using defined dataspace and + * default dataset creation properties. + */ + dataset = H5Dcreate_wrap + (file, DATASETNAME, H5.J2C (HDF5CDataTypes.JH5T_STD_I32BE), + dataspace, HDF5Constants.H5P_DEFAULT); + + /* + * Write the data to the dataset using default transfer properties. + */ + status = H5Dwrite_wrap + (dataset, H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + HDF5Constants.H5S_ALL, HDF5Constants.H5S_ALL, + HDF5Constants.H5P_DEFAULT, data); + + /* + * Close/release resources. + */ + H5Sclose_wrap (dataspace); + H5Dclose_wrap (dataset); + H5Fclose_wrap (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_wrap (FILE, HDF5Constants.H5F_ACC_RDONLY, + HDF5Constants.H5P_DEFAULT); + dataset = H5Dopen_wrap (file, DATASETNAME); + + dataspace = H5Dget_space_wrap (dataset); /* dataspace handle */ + rank = H5Sget_simple_extent_ndims_wrap (dataspace); + status_n = H5Sget_simple_extent_dims_wrap (dataspace, dims_out, null); + + System.out.println ("Rank: " + rank); + System.out.println ("Dimensions: "+ dims_out[0] + " x " + 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_wrap (dataspace, + HDF5Constants.H5S_SELECT_SET, + offset, null, count, null); + + /* + * Define the memory dataspace. + */ + dimsm[0] = NX; + dimsm[1] = NY; + dimsm[2] = NZ; + memspace = H5Screate_simple_wrap (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_wrap (memspace, + HDF5Constants.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_wrap (dataset, H5.J2C (HDF5CDataTypes.JH5T_NATIVE_INT), + memspace, dataspace, HDF5Constants.H5P_DEFAULT, + data_out); + + System.out.println ("Data:"); + for (j = 0; j < NX; j++) + { + for (i = 0; i < NY; i++) + System.out.print (data_out[j][i][0]); + System.out.println (); + } + System.out.println (); + + /* + * 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_wrap (dataset); + H5Sclose_wrap (dataspace); + H5Sclose_wrap (memspace); + H5Fclose_wrap (file); + } + + + // Help function for creating a new file + public static int H5Fcreate_wrap (String name, int flags, + int create_id, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fcreate (name, flags, create_id, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Fcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Fcreate_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for opening an existing file + public static int H5Fopen_wrap (String name, int flags, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fopen (name, flags, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Fopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Fopen_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + } + + + // Help function for opening an existing dataset + public static int H5Dopen_wrap (int loc_id, String name) + { + int dataset_id = -1; // dataset identifier + + try + { + // Opening an existing dataset + dataset_id = H5.H5Dopen (loc_id, name); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Dopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Dopen_wrap() with other Exception: " + + e.getMessage()); + } + return dataset_id; + } + + + // Help function for creating a new simple dataspace and opening it + // for access + public static int H5Screate_simple_wrap (int rank, long dims[], + long maxdims[]) + { + int dataspace_id = -1; // dataspace identifier + + try + { + // Create the data space for the dataset. + dataspace_id = H5.H5Screate_simple (rank, dims, maxdims); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Screate_simple_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Screate_simple_wrap() with other Exception: " + + e.getMessage()); + } + return dataspace_id; + } + + + // Help function for getting an identifier for a copy of + // the dataspace for a dataset + public static int H5Dget_space_wrap (int dataset_id) + { + int dataspace_id = -1; + + try + { + // Returning an identifier for a copy of the dataspace for a dataset + dataspace_id = H5.H5Dget_space (dataset_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Dget_space_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Dget_space_wrap() with other Exception: " + + e.getMessage()); + } + return dataspace_id; + } + + + // Help function for determining the dimensionality (or rank) of + // a dataspace + public static int H5Sget_simple_extent_ndims_wrap (int space_id) + { + int rank = -1; + + try + { + // Determine the dimensionality (or rank) of a dataspace. + rank = H5.H5Sget_simple_extent_ndims (space_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Sget_simple_extent_ndims_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Sget_simple_extent_ndims_wrap() with other Exception: " + + e.getMessage()); + } + return rank; + } + + + // Help function for returning the size and maximum sizes of each + // dimension of a dataspace through the dims and maxdims parameters. + public static int H5Sget_simple_extent_dims_wrap (int space_id, + long dims[], + long maxdims[]) + { + int dimension_number = -1; + + try + { + dimension_number = H5.H5Sget_simple_extent_dims (space_id, dims, + maxdims); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Sget_simple_extent_dims_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Sget_simple_extent_dims_wrap() with other Exception: " + + e.getMessage()); + } + return dimension_number; + } + + + // Help function for selecting a hyperslab region to add to the + // current selected region for the dataspace specified by space_id. + public static int H5Sselect_hyperslab_wrap (int space_id, int op, + long start[], long stride[], + long count[], long block[]) + { + int status = -1; + + try + { + status = H5.H5Sselect_hyperslab (space_id, op, start, stride, + count, block); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Sselect_hyperslab_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Sselect_hyperslab_wrap() with other Exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for creating a dataset + public static int H5Dcreate_wrap (int loc_id, String name, int type_id, + int space_id, int create_plist_id) + { + int dataset_id = -1; // dataset identifier + + try + { + // Create the dataset + dataset_id = H5.H5Dcreate (loc_id, name, type_id, space_id, + create_plist_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Dcreate_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Dcreate_wrap() with other Exception: " + + e.getMessage()); + } + return dataset_id; + } + + + // Help function for writing the dataset + public static int H5Dwrite_wrap (int dataset_id, int mem_type_id, + int mem_space_id, int file_space_id, + int xfer_plist_id, Object buf) + { + int status = -1; + + try + { + // Write the dataset. + status = H5.H5Dwrite (dataset_id, mem_type_id, mem_space_id, + file_space_id, xfer_plist_id, buf); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Dwrite_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Dwrite_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for reading the dataset + public static int H5Dread_wrap (int dataset_id, int mem_type_id, + int mem_space_id, int file_space_id, + int xfer_plist_id, Object obj) + { + int status = -1; + + try + { + // Read the dataset. + status = H5.H5Dread (dataset_id, mem_type_id, mem_space_id, + file_space_id, xfer_plist_id, obj); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Dread_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Dread_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the data space. + public static int H5Sclose_wrap (int dataspace_id) + { + int status = -1; + + try + { + // Terminate access to the data space. + status = H5.H5Sclose (dataspace_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Sclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Sclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for ending access to the dataset and releasing + // resources used by it. + public static int H5Dclose_wrap (int dataset_id) + { + int status = -1; + + try + { + // End access to the dataset and release resources used by it. + status = H5.H5Dclose (dataset_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Dclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Dclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } + + + // Help function for terminating access to the file. + public static int H5Fclose_wrap (int file_id) + { + int status = -1; + + try + { + // Terminate access to the file. + status = H5.H5Fclose (file_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("HyperSlab.H5Fclose_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("HyperSlab.H5Fclose_wrap() with other exception: " + + e.getMessage()); + } + return status; + } +} diff --git a/doc/html/Tutor/examples/java/Makefile b/doc/html/Tutor/examples/java/Makefile new file mode 100644 index 0000000..a70ab0b --- /dev/null +++ b/doc/html/Tutor/examples/java/Makefile @@ -0,0 +1,92 @@ +# Generated automatically from Makefile.in by configure. +# /*======================================================================= +# UNIVERSITY OF ILLINOIS (UI), NATIONAL CENTER FOR SUPERCOMPUTING +# APPLICATIONS (NCSA), Software Distribution Policy for Public Domain +# Software +# +# NCSA HDF Version 5 source code and documentation are in the public +# domain, available without fee for education, research, non-commercial and +# commercial purposes. Users may distribute the binary or source code to +# third parties provided that this statement appears on all copies and that +# no charge is made for such copies. +# +# UI MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE SOFTWARE FOR ANY +# PURPOSE. IT IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. THE +# UI SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY THE USER OF THIS +# SOFTWARE. The software may have been developed under agreements between +# the UI and the Federal Government which entitle the Government to certain +# rights. +# +# We ask, but do not require that the following message be include in all +# derived works: +# +# Portions developed at the National Center for Supercomputing Applications +# at the University of Illinois at Urbana-Champaign. +# +# By copying this program, you, the user, agree to abide by the conditions +# and understandings with respect to any software which is marked with a +# public domain notice. +# +# =======================================================================*/ +# + + +JAVAC = /usr/java1.2/bin/javac +FIND = /bin/find + +CLASSPATH=/usr/java1.2/jre/lib/rt.jar:/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 + + +.SUFFIXES: .java .class + +.java.class: + $(JAVAC) -classpath $(CLASSPATH) $< + +tutorial: ./Compound.class \ + ./Copy.class \ + ./CreateAttribute.class \ + ./CreateDataset.class \ + ./CreateFile.class \ + ./CreateFileInput.class \ + ./CreateGroup.class \ + ./CreateGroupAR.class \ + ./CreateGroupDataset.class \ + ./DatasetRdWt.class \ + ./HyperSlab.class + chmod u+x *.sh + +clean: clean-classes + +distclean: clean-classes clean-data + rm config.cache config.status config.log + rm -rf ./Makefile + +clean-classes: + $(FIND) . \( -name '#*' -o -name '*~' -o -name '*.class' \) -exec rm -f {} \; ;\ + +clean-data: + rm -rf *.h5 + +Compound: ./Compound.class +Copy: ./Copy.class +CreateAttribute: ./CreateAttribute.class +CreateDataset: ./CreateDataset.class +CreateFile: ./CreateFile.class +CreateFileInput: ./CreateFileInput.class +CreateGroup: ./CreateGroup.class +CreateGroupAR: ./CreateGroupAR.class +CreateGroupDataset: ./CreateGroupDataset.class +DatasetRdWt: ./DatasetRdWt.class +HyperSlab: ./HyperSlab.class + +CLASSES= ./Compound.class \ + ./Copy.class \ + ./CreateAttribute.class \ + ./CreateDataset.class \ + ./CreateFileInput.class \ + ./CreateFile.class \ + ./CreateGroup.class \ + ./CreateGroupAR.class \ + ./CreateGroupDataset.class \ + ./DatasetRdWt.class \ + ./HyperSlab.class diff --git a/doc/html/Tutor/examples/java/Makefile.in b/doc/html/Tutor/examples/java/Makefile.in new file mode 100644 index 0000000..e6bd408 --- /dev/null +++ b/doc/html/Tutor/examples/java/Makefile.in @@ -0,0 +1,91 @@ +# /*======================================================================= +# UNIVERSITY OF ILLINOIS (UI), NATIONAL CENTER FOR SUPERCOMPUTING +# APPLICATIONS (NCSA), Software Distribution Policy for Public Domain +# Software +# +# NCSA HDF Version 5 source code and documentation are in the public +# domain, available without fee for education, research, non-commercial and +# commercial purposes. Users may distribute the binary or source code to +# third parties provided that this statement appears on all copies and that +# no charge is made for such copies. +# +# UI MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE SOFTWARE FOR ANY +# PURPOSE. IT IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. THE +# UI SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY THE USER OF THIS +# SOFTWARE. The software may have been developed under agreements between +# the UI and the Federal Government which entitle the Government to certain +# rights. +# +# We ask, but do not require that the following message be include in all +# derived works: +# +# Portions developed at the National Center for Supercomputing Applications +# at the University of Illinois at Urbana-Champaign. +# +# By copying this program, you, the user, agree to abide by the conditions +# and understandings with respect to any software which is marked with a +# public domain notice. +# +# =======================================================================*/ +# + + +JAVAC = @JAVAC@ +FIND = @FIND@ + +CLASSPATH=@CLASSPATH@ + + +.SUFFIXES: .java .class + +.java.class: + $(JAVAC) -classpath $(CLASSPATH) $< + +tutorial: ./Compound.class \ + ./Copy.class \ + ./CreateAttribute.class \ + ./CreateDataset.class \ + ./CreateFile.class \ + ./CreateFileInput.class \ + ./CreateGroup.class \ + ./CreateGroupAR.class \ + ./CreateGroupDataset.class \ + ./DatasetRdWt.class \ + ./HyperSlab.class + chmod u+x *.sh + +clean: clean-classes + +distclean: clean-classes clean-data + rm config.cache config.status config.log + rm -rf ./Makefile + +clean-classes: + $(FIND) . \( -name '#*' -o -name '*~' -o -name '*.class' \) -exec rm -f {} \; ;\ + +clean-data: + rm -rf *.h5 + +Compound: ./Compound.class +Copy: ./Copy.class +CreateAttribute: ./CreateAttribute.class +CreateDataset: ./CreateDataset.class +CreateFile: ./CreateFile.class +CreateFileInput: ./CreateFileInput.class +CreateGroup: ./CreateGroup.class +CreateGroupAR: ./CreateGroupAR.class +CreateGroupDataset: ./CreateGroupDataset.class +DatasetRdWt: ./DatasetRdWt.class +HyperSlab: ./HyperSlab.class + +CLASSES= ./Compound.class \ + ./Copy.class \ + ./CreateAttribute.class \ + ./CreateDataset.class \ + ./CreateFileInput.class \ + ./CreateFile.class \ + ./CreateGroup.class \ + ./CreateGroupAR.class \ + ./CreateGroupDataset.class \ + ./DatasetRdWt.class \ + ./HyperSlab.class diff --git a/doc/html/Tutor/examples/java/README b/doc/html/Tutor/examples/java/README new file mode 100644 index 0000000..95c9360 --- /dev/null +++ b/doc/html/Tutor/examples/java/README @@ -0,0 +1,21 @@ +These files are Java versions of the example programs used in +the HDF-5 tutoral: + http://hdf.ncsa.uiuc.edu/training/hdf5/ + +The examples here correspond to the examples explained in the first 13 +sections of the tutorial. + +Lesson C program Java program Topic + +4 h5_crtfile.c CreateFile.java Create an HDF-5 file. +5 h5_crtdat.c CreateDataset.java Create a dataset. +6 h5_rdwt.c DatasetRdWt.java Write/Read a dataset. +7 h5_crtatt.c CreateAttribute.java Create an attribute. +8 h5_crtgrp.c CreateGroup.java Create a group. +9 h5_crtgrpar.c CreateGroupAR.java Abs. and Rel. paths. +10 h5_crtgrpd.c CreateGroupDataset.java Create dataset in grp. + +11 h5_compound.c Compound.java Compound datatype +12 h5_hyperslab.c Hyperslab.java Selection of hyperslab +13 h5_copy.c Copy.java Selection of elements + diff --git a/doc/html/Tutor/examples/java/readme.html b/doc/html/Tutor/examples/java/readme.html new file mode 100644 index 0000000..ac96004 --- /dev/null +++ b/doc/html/Tutor/examples/java/readme.html @@ -0,0 +1,192 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.61 [en] (WinNT; I) [Netscape]"> + <title>readme</title> +</head> +<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B" alink="#FF0000"> + +<h3> +<b>HDF 5 Tutorial Examples in Java</b></h3> + +<p><br>These files are Java versions of the example programs used in the +HDF-5 tutoral: +<br> <a href="http://hdf.ncsa.uiuc.edu/training/hdf5/">http://hdf.ncsa.uiuc.edu/training/hdf5/</a> +<p>The examples here correspond to the examples explained in the first +13 sections of the tutorial. +<br> +<br> +<table BORDER CELLPADDING=2 WIDTH="100%" > +<tr> +<td> +<center><b>Lesson</b></center> +</td> + +<td> +<center><b>Topic</b></center> +</td> + +<td> +<center><b>C file</b></center> +</td> + +<td> +<center><b>Java file</b></center> +</td> +</tr> + +<tr> +<td><a href="http://hdf.ncsa.uiuc.edu/training/hdf5/crtfile.html">Lesson +4</a></td> + +<td>Create an HDF-5 file.</td> + +<td>h5_crtfile.c</td> + +<td>CreateFile.java</td> +</tr> + +<tr> +<td><a href="http://hdf.ncsa.uiuc.edu/training/hdf5/crtdat.html">Lesson +5</a></td> + +<td>Create a Dataset in an HDF-5 file</td> + +<td>h5_crtdat.c</td> + +<td>CreateDataset.java</td> +</tr> + +<tr> +<td><a href="http://hdf.ncsa.uiuc.edu/training/hdf5/rdwt.html">Lesson 6</a></td> + +<td>Write and Read data in a dataset</td> + +<td>h5_rdwt.c</td> + +<td>DatasetRdWt.java</td> +</tr> + +<tr> +<td><a href="http://hdf.ncsa.uiuc.edu/training/hdf5/crtatt.html">Lesson +7</a></td> + +<td>Create an attribute.</td> + +<td>h5_crtatt.c</td> + +<td>CreateAttribute.java</td> +</tr> + +<tr> +<td><a href="http://hdf.ncsa.uiuc.edu/training/hdf5/crtgrp.html">Lesson +8</a></td> + +<td>Create a group.</td> + +<td>h5_crtgrp.c</td> + +<td>CreateGroup.java</td> +</tr> + +<tr> +<td><a href="http://hdf.ncsa.uiuc.edu/training/hdf5/crtgrpar.html">Lesson +9</a></td> + +<td>Using Absolute and relative paths</td> + +<td>h5_crtgrpar.c</td> + +<td>CreateGroupAR.java</td> +</tr> + +<tr> +<td><a href="http://hdf.ncsa.uiuc.edu/training/hdf5/crtgrpd.html">Lesson +10</a></td> + +<td>Create a dataset in a group.</td> + +<td>h5_crtgrpd.c</td> + +<td>CreateGroupDataset.java</td> +</tr> + +<tr> +<td><a href="http://hdf.ncsa.uiuc.edu/training/hdf5/compound.html">Lesson +11</a></td> + +<td>Using Compound Datatypes</td> + +<td>h5_compound.c</td> + +<td>Compound.java</td> +</tr> + +<tr> +<td><a href="http://hdf.ncsa.uiuc.edu/training/hdf5/select.html">Lesson +12</a></td> + +<td>Selection of a hyperslab.</td> + +<td>h5_hyperslab.c</td> + +<td>Hyperslab.java</td> +</tr> + +<tr> +<td><a href="http://hdf.ncsa.uiuc.edu/training/hdf5/selectc.html">Lesson +13</a></td> + +<td>Selection of elements.</td> + +<td>h5_copy.c</td> + +<td>Copy.java</td> +</tr> +</table> + +<p> +<hr><b>Some Explanation About Tutorial Examples</b> +<p>The Java tutorial programs try to stay close to the corresponding C +program. The main function's structure almost same as C program, with one +call for each HDF5 library function. For example, where the C program has +a call to <b>H5Fopen()</b>, the Java program has a call to <b>H5Fopen_wrap()</b>. +<p>The wrapper functions call the HDF-5 library using the Java HDF-5 Interface +(JHI5). The HDF-5 C interface returns error codes; these are represented +by Java Exceptions in the JHI5. The wrapper function catches the exception +and prints a message. +<p>For example, the <b>H5Fopen_wrap() </b>method calls the JHI5, and catches +any exceptions which may occur: +<pre> <b>public static int H5Fopen_wrap (String name, int flags, int access_id) + { + int file_id = -1; // file identifier + try + { + // Create a new file using default file properties. + file_id = H5.H5Fopen (name, flags, access_id); + } + catch (HDF5Exception hdf5e) + { + System.out.println + ("DatasetRdWt.H5Fopen_wrap() with HDF5Exception: " + + hdf5e.getMessage()); + } + catch (Exception e) + { + System.out.println + ("DatasetRdWt.H5Fopen_wrap() with other Exception: " + + e.getMessage()); + } + return file_id; + }</b></pre> + +<p><br> +<hr noshade size=1><a href="http://www.ncsa.uiuc.edu/"><img SRC="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif" ALT="NCSA" BORDER=0 ></a> +<br><font face="arial,helvetica"><font size=-1><a href="http://www.ncsa.uiuc.edu/">The +National Center for Supercomputing Applications</a></font></font> +<br><font face="arial,helvetica"><font size=-1><a href="http://www.uiuc.edu/">University +of Illinois at Urbana-Champaign</a></font></font> +<p><font face="arial,helvetica"><font size=-1><a href="mailto:hdfhelp@ncsa.uiuc.edu">hdfhelp@ncsa.uiuc.edu</a></font></font> +</body> +</html> diff --git a/doc/html/Tutor/examples/java/runCompound.sh b/doc/html/Tutor/examples/java/runCompound.sh new file mode 100644 index 0000000..ef2be38 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCompound.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=/afs/ncsa/projects/hdf/java/java2/mcgrath/arabica/New5 +HDF5LIB=/afs/ncsa/projects/hdf/release/prehdf5-1.2.1/SunOS_5.7/lib + +#make this relative to the source root... +PWD=/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/solaris" + +export CLASSPATH +export LD_LIBRARY_PATH + +/usr/java1.2/bin/java Compound $* diff --git a/doc/html/Tutor/examples/java/runCompound.sh.in b/doc/html/Tutor/examples/java/runCompound.sh.in new file mode 100644 index 0000000..bc58088 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCompound.sh.in @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=@JH5INST@ +HDF5LIB=@HDF5LIB@ + +#make this relative to the source root... +PWD=@PWD@ +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/@JAVATARG@" + +export CLASSPATH +export LD_LIBRARY_PATH + +@JAVA@ Compound $* diff --git a/doc/html/Tutor/examples/java/runCopy.sh b/doc/html/Tutor/examples/java/runCopy.sh new file mode 100644 index 0000000..de71783 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCopy.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=/afs/ncsa/projects/hdf/java/java2/mcgrath/arabica/New5 +HDF5LIB=/afs/ncsa/projects/hdf/release/prehdf5-1.2.1/SunOS_5.7/lib + +#make this relative to the source root... +PWD=/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/solaris" + +export CLASSPATH +export LD_LIBRARY_PATH + +/usr/java1.2/bin/java Copy $* diff --git a/doc/html/Tutor/examples/java/runCopy.sh.in b/doc/html/Tutor/examples/java/runCopy.sh.in new file mode 100644 index 0000000..2fd8a46 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCopy.sh.in @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=@JH5INST@ +HDF5LIB=@HDF5LIB@ + +#make this relative to the source root... +PWD=@PWD@ +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/@JAVATARG@" + +export CLASSPATH +export LD_LIBRARY_PATH + +@JAVA@ Copy $* diff --git a/doc/html/Tutor/examples/java/runCreateAttribute.sh b/doc/html/Tutor/examples/java/runCreateAttribute.sh new file mode 100644 index 0000000..419abce --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateAttribute.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=/afs/ncsa/projects/hdf/java/java2/mcgrath/arabica/New5 +HDF5LIB=/afs/ncsa/projects/hdf/release/prehdf5-1.2.1/SunOS_5.7/lib + +#make this relative to the source root... +PWD=/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/solaris" + +export CLASSPATH +export LD_LIBRARY_PATH + +/usr/java1.2/bin/java CreateAttribute $* diff --git a/doc/html/Tutor/examples/java/runCreateAttribute.sh.in b/doc/html/Tutor/examples/java/runCreateAttribute.sh.in new file mode 100644 index 0000000..83bcdc7 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateAttribute.sh.in @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=@JH5INST@ +HDF5LIB=@HDF5LIB@ + +#make this relative to the source root... +PWD=@PWD@ +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/@JAVATARG@" + +export CLASSPATH +export LD_LIBRARY_PATH + +@JAVA@ CreateAttribute $* diff --git a/doc/html/Tutor/examples/java/runCreateDataset.sh b/doc/html/Tutor/examples/java/runCreateDataset.sh new file mode 100644 index 0000000..371e811 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateDataset.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=/afs/ncsa/projects/hdf/java/java2/mcgrath/arabica/New5 +HDF5LIB=/afs/ncsa/projects/hdf/release/prehdf5-1.2.1/SunOS_5.7/lib + +#make this relative to the source root... +PWD=/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/solaris" + +export CLASSPATH +export LD_LIBRARY_PATH + +/usr/java1.2/bin/java CreateDataset $* diff --git a/doc/html/Tutor/examples/java/runCreateDataset.sh.in b/doc/html/Tutor/examples/java/runCreateDataset.sh.in new file mode 100644 index 0000000..606e153 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateDataset.sh.in @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=@JH5INST@ +HDF5LIB=@HDF5LIB@ + +#make this relative to the source root... +PWD=@PWD@ +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/@JAVATARG@" + +export CLASSPATH +export LD_LIBRARY_PATH + +@JAVA@ CreateDataset $* diff --git a/doc/html/Tutor/examples/java/runCreateFile.sh b/doc/html/Tutor/examples/java/runCreateFile.sh new file mode 100644 index 0000000..e32c0ab --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateFile.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=/afs/ncsa/projects/hdf/java/java2/mcgrath/arabica/New5 +HDF5LIB=/afs/ncsa/projects/hdf/release/prehdf5-1.2.1/SunOS_5.7/lib + +#make this relative to the source root... +PWD=/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/solaris" + +export CLASSPATH +export LD_LIBRARY_PATH + +/usr/java1.2/bin/java CreateFile $* diff --git a/doc/html/Tutor/examples/java/runCreateFile.sh.in b/doc/html/Tutor/examples/java/runCreateFile.sh.in new file mode 100644 index 0000000..bf48b9c --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateFile.sh.in @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=@JH5INST@ +HDF5LIB=@HDF5LIB@ + +#make this relative to the source root... +PWD=@PWD@ +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/@JAVATARG@" + +export CLASSPATH +export LD_LIBRARY_PATH + +@JAVA@ CreateFile $* diff --git a/doc/html/Tutor/examples/java/runCreateFileInput.sh b/doc/html/Tutor/examples/java/runCreateFileInput.sh new file mode 100644 index 0000000..fa12f06 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateFileInput.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=/afs/ncsa/projects/hdf/java/java2/mcgrath/arabica/New5 +HDF5LIB=/afs/ncsa/projects/hdf/release/prehdf5-1.2.1/SunOS_5.7/lib + +#make this relative to the source root... +PWD=/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/solaris" + +export CLASSPATH +export LD_LIBRARY_PATH + +/usr/java1.2/bin/java CreateFileInput $* diff --git a/doc/html/Tutor/examples/java/runCreateFileInput.sh.in b/doc/html/Tutor/examples/java/runCreateFileInput.sh.in new file mode 100644 index 0000000..776eac5 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateFileInput.sh.in @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=@JH5INST@ +HDF5LIB=@HDF5LIB@ + +#make this relative to the source root... +PWD=@PWD@ +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/@JAVATARG@" + +export CLASSPATH +export LD_LIBRARY_PATH + +@JAVA@ CreateFileInput $* diff --git a/doc/html/Tutor/examples/java/runCreateGroup.sh b/doc/html/Tutor/examples/java/runCreateGroup.sh new file mode 100644 index 0000000..ee9deee --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateGroup.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=/afs/ncsa/projects/hdf/java/java2/mcgrath/arabica/New5 +HDF5LIB=/afs/ncsa/projects/hdf/release/prehdf5-1.2.1/SunOS_5.7/lib + +#make this relative to the source root... +PWD=/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/solaris" + +export CLASSPATH +export LD_LIBRARY_PATH + +/usr/java1.2/bin/java CreateGroup $* diff --git a/doc/html/Tutor/examples/java/runCreateGroup.sh.in b/doc/html/Tutor/examples/java/runCreateGroup.sh.in new file mode 100644 index 0000000..e2eadb5 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateGroup.sh.in @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=@JH5INST@ +HDF5LIB=@HDF5LIB@ + +#make this relative to the source root... +PWD=@PWD@ +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/@JAVATARG@" + +export CLASSPATH +export LD_LIBRARY_PATH + +@JAVA@ CreateGroup $* diff --git a/doc/html/Tutor/examples/java/runCreateGroupAR.sh b/doc/html/Tutor/examples/java/runCreateGroupAR.sh new file mode 100644 index 0000000..2619a11 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateGroupAR.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=/afs/ncsa/projects/hdf/java/java2/mcgrath/arabica/New5 +HDF5LIB=/afs/ncsa/projects/hdf/release/prehdf5-1.2.1/SunOS_5.7/lib + +#make this relative to the source root... +PWD=/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/solaris" + +export CLASSPATH +export LD_LIBRARY_PATH + +/usr/java1.2/bin/java CreateGroupAR $* diff --git a/doc/html/Tutor/examples/java/runCreateGroupAR.sh.in b/doc/html/Tutor/examples/java/runCreateGroupAR.sh.in new file mode 100644 index 0000000..d61d852 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateGroupAR.sh.in @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=@JH5INST@ +HDF5LIB=@HDF5LIB@ + +#make this relative to the source root... +PWD=@PWD@ +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/@JAVATARG@" + +export CLASSPATH +export LD_LIBRARY_PATH + +@JAVA@ CreateGroupAR $* diff --git a/doc/html/Tutor/examples/java/runCreateGroupDataset.sh b/doc/html/Tutor/examples/java/runCreateGroupDataset.sh new file mode 100644 index 0000000..15b7bfa --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateGroupDataset.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=/afs/ncsa/projects/hdf/java/java2/mcgrath/arabica/New5 +HDF5LIB=/afs/ncsa/projects/hdf/release/prehdf5-1.2.1/SunOS_5.7/lib + +#make this relative to the source root... +PWD=/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/solaris" + +export CLASSPATH +export LD_LIBRARY_PATH + +/usr/java1.2/bin/java CreateGroupDataset $* diff --git a/doc/html/Tutor/examples/java/runCreateGroupDataset.sh.in b/doc/html/Tutor/examples/java/runCreateGroupDataset.sh.in new file mode 100644 index 0000000..af2b4b5 --- /dev/null +++ b/doc/html/Tutor/examples/java/runCreateGroupDataset.sh.in @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=@JH5INST@ +HDF5LIB=@HDF5LIB@ + +#make this relative to the source root... +PWD=@PWD@ +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/@JAVATARG@" + +export CLASSPATH +export LD_LIBRARY_PATH + +@JAVA@ CreateGroupDataset $* diff --git a/doc/html/Tutor/examples/java/runDatasetRdWt.sh b/doc/html/Tutor/examples/java/runDatasetRdWt.sh new file mode 100644 index 0000000..a049ea8 --- /dev/null +++ b/doc/html/Tutor/examples/java/runDatasetRdWt.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=/afs/ncsa/projects/hdf/java/java2/mcgrath/arabica/New5 +HDF5LIB=/afs/ncsa/projects/hdf/release/prehdf5-1.2.1/SunOS_5.7/lib + +#make this relative to the source root... +PWD=/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/solaris" + +export CLASSPATH +export LD_LIBRARY_PATH + +/usr/java1.2/bin/java DatasetRdWt $* diff --git a/doc/html/Tutor/examples/java/runDatasetRdWt.sh.in b/doc/html/Tutor/examples/java/runDatasetRdWt.sh.in new file mode 100644 index 0000000..ad3a049 --- /dev/null +++ b/doc/html/Tutor/examples/java/runDatasetRdWt.sh.in @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=@JH5INST@ +HDF5LIB=@HDF5LIB@ + +#make this relative to the source root... +PWD=@PWD@ +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/@JAVATARG@" + +export CLASSPATH +export LD_LIBRARY_PATH + +@JAVA@ DatasetRdWt $* diff --git a/doc/html/Tutor/examples/java/runHyperSlab.sh b/doc/html/Tutor/examples/java/runHyperSlab.sh new file mode 100644 index 0000000..549f807 --- /dev/null +++ b/doc/html/Tutor/examples/java/runHyperSlab.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=/afs/ncsa/projects/hdf/java/java2/mcgrath/arabica/New5 +HDF5LIB=/afs/ncsa/projects/hdf/release/prehdf5-1.2.1/SunOS_5.7/lib + +#make this relative to the source root... +PWD=/afs/ncsa.uiuc.edu/projects/hdf/java/java2/mcgrath/arabica/java-hdf5 +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/solaris" + +export CLASSPATH +export LD_LIBRARY_PATH + +/usr/java1.2/bin/java HyperSlab $* diff --git a/doc/html/Tutor/examples/java/runHyperSlab.sh.in b/doc/html/Tutor/examples/java/runHyperSlab.sh.in new file mode 100644 index 0000000..f515fc9 --- /dev/null +++ b/doc/html/Tutor/examples/java/runHyperSlab.sh.in @@ -0,0 +1,17 @@ +#!/bin/sh + +JH5INSTALLDIR=@JH5INST@ +HDF5LIB=@HDF5LIB@ + +#make this relative to the source root... +PWD=@PWD@ +LIBDIR=$JH5INSTALLDIR"/lib" + +CLASSPATH=".:"$LIBDIR"/jhdf5.jar" + +LD_LIBRARY_PATH=$HDF5LIB":"$LIBDIR"/@JAVATARG@" + +export CLASSPATH +export LD_LIBRARY_PATH + +@JAVA@ HyperSlab $* diff --git a/doc/html/Tutor/examples/mount.f90 b/doc/html/Tutor/examples/mount.f90 new file mode 100644 index 0000000..b9c8772 --- /dev/null +++ b/doc/html/Tutor/examples/mount.f90 @@ -0,0 +1,183 @@ +! +!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. +! + + PROGRAM MOUNTEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + ! + !the respective filename is "mount1.h5" and "mount2.h5" + ! + CHARACTER(LEN=9), PARAMETER :: filename1 = "mount1.h5" + CHARACTER(LEN=9), PARAMETER :: filename2 = "mount2.h5" + + ! + !data space rank and dimensions + ! + INTEGER, PARAMETER :: RANK = 2 + INTEGER, PARAMETER :: NX = 4 + INTEGER, PARAMETER :: NY = 5 + + ! + ! File identifiers + ! + INTEGER(HID_T) :: file1_id, file2_id + + ! + ! Group identifier + ! + INTEGER(HID_T) :: gid + + ! + ! dataset identifier + ! + INTEGER(HID_T) :: dset_id + + ! + ! data space identifier + ! + INTEGER(HID_T) :: dataspace + + ! + ! data type identifier + ! + INTEGER(HID_T) :: dtype_id + + ! + !The dimensions for the dataset. + ! + INTEGER(HSIZE_T), DIMENSION(2) :: dims = (/NX,NY/) + + ! + !flag to check operation success + ! + INTEGER :: error + + ! + !general purpose integer + ! + INTEGER :: i, j + + ! + !data buffers + ! + INTEGER, DIMENSION(NX,NY) :: data_in, data_out + + ! + !Initialize FORTRAN predifined datatypes + ! + CALL h5init_types_f(error) + + ! + !Initialize data_in buffer + ! + do i = 1, NX + do j = 1, NY + data_in(i,j) = (i-1) + (j-1) + end do + end do + + ! + !Create first file "mount1.h5" using default properties. + ! + CALL h5fcreate_f(filename1, H5F_ACC_TRUNC_F, file1_id, error) + + ! + !Create group "/G" inside file "mount1.h5". + ! + CALL h5gcreate_f(file1_id, "/G", gid, error) + + ! + !close file and group identifiers. + ! + CALL h5gclose_f(gid, error) + CALL h5fclose_f(file1_id, error) + + ! + !Create second file "mount2.h5" using default properties. + ! + CALL h5fcreate_f(filename2, H5F_ACC_TRUNC_F, file2_id, error) + + ! + !Create data space for the dataset. + ! + CALL h5screate_simple_f(RANK, dims, dataspace, error) + + ! + !Create dataset "/D" inside file "mount2.h5". + ! + CALL h5dcreate_f(file2_id, "/D", H5T_NATIVE_INTEGER, dataspace, & + dset_id, error) + + ! + ! Write data_in to the dataset + ! + CALL h5dwrite_f(dset_id, H5T_NATIVE_INTEGER, data_in, error) + + ! + !close file, dataset and dataspace identifiers. + ! + CALL h5sclose_f(dataspace, error) + CALL h5dclose_f(dset_id, error) + CALL h5fclose_f(file2_id, error) + + ! + !reopen both files. + ! + CALL h5fopen_f (filename1, H5F_ACC_RDONLY_F, file1_id, error) + CALL h5fopen_f (filename2, H5F_ACC_RDONLY_F, file2_id, error) + + ! + !mount the second file under the first file's "/G" group. + ! + CALL h5fmount_f (file1_id, "/G", file2_id, error) + + + ! + !Access dataset D in the first file under /G/D name. + ! + CALL h5dopen_f(file1_id, "/G/D", dset_id, error) + + ! + !Get dataset's data type. + ! + CALL h5dget_type_f(dset_id, dtype_id, error) + + ! + !Read the dataset. + ! + CALL h5dread_f(dset_id, dtype_id, data_out, error) + + ! + !Print out the data. + ! + do i = 1, NX + print *, (data_out(i,j), j = 1, NY) + end do + + + ! + !Close dset_id and dtype_id. + ! + CALL h5dclose_f(dset_id, error) + CALL h5tclose_f(dtype_id, error) + + ! + !unmount the second file. + ! + CALL h5funmount_f(file1_id, "/G", error); + + ! + !Close both files. + ! + CALL h5fclose_f(file1_id, error) + CALL h5fclose_f(file2_id, error) + + END PROGRAM MOUNTEXAMPLE + diff --git a/doc/html/Tutor/examples/refobjexample.f90 b/doc/html/Tutor/examples/refobjexample.f90 new file mode 100644 index 0000000..a1c0a44 --- /dev/null +++ b/doc/html/Tutor/examples/refobjexample.f90 @@ -0,0 +1,136 @@ +! +! This program shows how to create and store references to the objects. +! Program creates a file, two groups, a dataset to store integer data and +! a dataset to store references to the objects. +! Stored references are used to open the objects they are point to. +! Data is written to the dereferenced dataset, and class type is displayed for +! the shared datatype. +! + PROGRAM OBJ_REFERENCES + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + CHARACTER(LEN=10), PARAMETER :: filename = "FORTRAN.h5" ! File + CHARACTER(LEN=8), PARAMETER :: dsetnamei = "INTEGERS" ! Dataset with the integer data + CHARACTER(LEN=17), PARAMETER :: dsetnamer = "OBJECT_REFERENCES" ! Dataset wtih object + ! references + CHARACTER(LEN=6), PARAMETER :: groupname1 = "GROUP1" ! Groups in the file + CHARACTER(LEN=6), PARAMETER :: groupname2 = "GROUP2" ! + + INTEGER(HID_T) :: file_id ! File identifier + INTEGER(HID_T) :: grp1_id ! Group identifiers + INTEGER(HID_T) :: grp2_id ! + INTEGER(HID_T) :: dset_id ! Dataset identifiers + INTEGER(HID_T) :: dsetr_id ! + INTEGER(HID_T) :: type_id ! Type identifier + INTEGER(HID_T) :: space_id ! Dataspace identifiers + INTEGER(HID_T) :: spacer_id ! + INTEGER :: error + INTEGER(HSIZE_T), DIMENSION(1) :: dims = (/5/) + INTEGER(HSIZE_T), DIMENSION(1) :: dimsr= (/4/) + INTEGER(HSIZE_T), DIMENSION(1) :: my_maxdims = (/5/) + INTEGER :: rank = 1 + INTEGER :: rankr = 1 + TYPE(hobj_ref_t_f), DIMENSION(4) :: ref + TYPE(hobj_ref_t_f), DIMENSION(4) :: ref_out + INTEGER, DIMENSION(5) :: data = (/1, 2, 3, 4, 5/) + INTEGER :: class + ! + ! Initialize FORTRAN predefined datatypes + ! + CALL h5init_types_f(error) + ! + ! Create a file + ! + CALL h5fcreate_f(filename, H5F_ACC_TRUNC_F, file_id, error) + ! Default file access and file creation + ! properties are used. + ! + ! Create a group in the file + ! + CALL h5gcreate_f(file_id, groupname1, grp1_id, error) + ! + ! Create a group inside the created gorup + ! + CALL h5gcreate_f(grp1_id, groupname2, grp2_id, error) + ! + ! Create dataspaces for datasets + ! + CALL h5screate_simple_f(rank, dims, space_id, error, maxdims=my_maxdims) + CALL h5screate_simple_f(rankr, dimsr, spacer_id, error) + ! + ! Create integer dataset + ! + CALL h5dcreate_f(file_id, dsetnamei, H5T_NATIVE_INTEGER, space_id, & + dset_id, error) + ! + ! Create dataset to store references to the objects + ! + CALL h5dcreate_f(file_id, dsetnamer, H5T_STD_REF_OBJ, spacer_id, & + dsetr_id, error) + ! + ! Create a datatype and store in the file + ! + CALL h5tcopy_f(H5T_NATIVE_REAL, type_id, error) + CALL h5tcommit_f(file_id, "MyType", type_id, error) + ! + ! Close dataspaces, groups and integer dataset + ! + CALL h5sclose_f(space_id, error) + CALL h5sclose_f(spacer_id, error) + CALL h5tclose_f(type_id, error) + CALL h5dclose_f(dset_id, error) + CALL h5gclose_f(grp1_id, error) + CALL h5gclose_f(grp2_id, error) + ! + ! Craete references to two groups, integer dataset and shared datatype + ! and write it to the dataset in the file + ! + CALL h5rcreate_f(file_id, groupname1, ref(1), error) + CALL h5rcreate_f(file_id, "/GROUP1/GROUP2", ref(2), error) + CALL h5rcreate_f(file_id, dsetnamei, ref(3), error) + CALL h5rcreate_f(file_id, "MyType", ref(4), error) + CALL h5dwrite_f(dsetr_id, H5T_STD_REF_OBJ, ref, error) + ! + ! Close the dataset + ! + CALL h5dclose_f(dsetr_id, error) + ! + ! Reopen the dataset with object references and read references to the buffer + ! + CALL h5dopen_f(file_id, dsetnamer,dsetr_id,error) + CALL h5dread_f(dsetr_id, H5T_STD_REF_OBJ, ref_out, error) + ! + ! Dereference the third reference. We know that it is a dataset. On practice + ! one should use h5rget_object_type_f function to find out + ! the type of an object the reference points to. + ! + CALL h5rdereference_f(dsetr_id, ref(3), dset_id, error) + ! + ! Write data to the dataset. + ! + CALL h5dwrite_f(dset_id, H5T_NATIVE_INTEGER, data, error) + if (error .eq. 0) write(*,*) "Data has been successfully written to the dataset " + ! + ! Dereference the fourth reference. We know that it is a datatype. On practice + ! one should use h5rget_object_type_f function to find out + ! the type of an object the reference points to. + ! + CALL h5rdereference_f(dsetr_id, ref(4), type_id, error) + ! + ! Get datatype class and display it if it is of a FLOAT class. + ! + CALL h5tget_class_f(type_id, class, error) + if(class .eq. H5T_FLOAT_F) write(*,*) "Stored datatype is of a FLOAT class" + ! + ! Close all objects. + ! + CALL h5dclose_f(dset_id, error) + CALL h5tclose_f(type_id, error) + CALL h5dclose_f(dsetr_id, error) + CALL h5fclose_f(file_id, error) + + END PROGRAM OBJ_REFERENCES + + diff --git a/doc/html/Tutor/examples/refregexample.f90 b/doc/html/Tutor/examples/refregexample.f90 new file mode 100644 index 0000000..3a5bea4 --- /dev/null +++ b/doc/html/Tutor/examples/refregexample.f90 @@ -0,0 +1,159 @@ +! +! This program shows how to create, store and dereference references +! to the dataset regions. +! Program creates a file and writes two dimensional integer dataset +! to it. Then program creates and stores references to the hyperslab +! and 3 points selected in the integer dataset, in the second dataset. +! Program reopens the second dataset, reads and dereferences region +! references, and then reads and displays selected data from the +! integer dataset. +! + PROGRAM REG_REFERENCE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + CHARACTER(LEN=10), PARAMETER :: filename = "FORTRAN.h5" + CHARACTER(LEN=6), PARAMETER :: dsetnamev = "MATRIX" + CHARACTER(LEN=17), PARAMETER :: dsetnamer = "REGION_REFERENCES" + + INTEGER(HID_T) :: file_id ! File identifier + INTEGER(HID_T) :: space_id ! Dataspace identifier + INTEGER(HID_T) :: spacer_id ! Dataspace identifier + INTEGER(HID_T) :: dsetv_id ! Dataset identifier + INTEGER(HID_T) :: dsetr_id ! Dataset identifier + INTEGER :: error + TYPE(hdset_reg_ref_t_f) , DIMENSION(2) :: ref ! Buffers to store references + TYPE(hdset_reg_ref_t_f) , DIMENSION(2) :: ref_out ! + INTEGER(HSIZE_T), DIMENSION(2) :: dims = (/2,9/) ! Datasets dimensions + INTEGER(HSIZE_T), DIMENSION(1) :: dimsr = (/2/) ! + INTEGER(HSSIZE_T), DIMENSION(2) :: start + INTEGER(HSIZE_T), DIMENSION(2) :: count + INTEGER :: rankr = 1 + INTEGER :: rank = 2 + INTEGER , DIMENSION(2,9) :: data + INTEGER , DIMENSION(2,9) :: data_out = 0 + INTEGER(HSSIZE_T) , DIMENSION(2,3) :: coord + INTEGER ::num_points = 3 ! Number of selected points + INTEGER :: i, j + coord = reshape((/1,1,2,7,1,9/), (/2,3/)) ! Coordinates of selected points + data = reshape ((/1,1,1,2,2,2,3,3,3,4,4,4,5,5,5,6,6,6/), (/2,9/)) + ! + ! Initialize FORTRAN predefined datatypes. + ! + CALL h5init_types_f(error) + ! + ! Create a new file. + ! + CALL h5fcreate_f(filename, H5F_ACC_TRUNC_F, file_id, error) + ! Default file access and file creation + ! properties are used. + ! + ! Create dataspaces: + ! + ! for dataset with references to dataset regions + ! + CALL h5screate_simple_f(rankr, dimsr, spacer_id, error) + ! + ! for integer dataset + ! + CALL h5screate_simple_f(rank, dims, space_id, error) + ! + ! Create and write datasets: + ! + ! Integer dataset + ! + CALL h5dcreate_f(file_id, dsetnamev, H5T_NATIVE_INTEGER, space_id, & + dsetv_id, error) + CALL h5dwrite_f(dsetv_id, H5T_NATIVE_INTEGER, data, error) + CALL h5dclose_f(dsetv_id, error) + ! + ! Dataset with references + ! + CALL h5dcreate_f(file_id, dsetnamer, H5T_STD_REF_DSETREG, spacer_id, & + dsetr_id, error) + ! + ! Create a reference to the hyperslab selection. + ! + start(1) = 0 + start(2) = 3 + count(1) = 2 + count(2) = 3 + CALL h5sselect_hyperslab_f(space_id, H5S_SELECT_SET_F, & + start, count, error) + CALL h5rcreate_f(file_id, dsetnamev, space_id, ref(1), error) + ! + ! Create a reference to elements selection. + ! + CALL h5sselect_none_f(space_id, error) + CALL h5sselect_elements_f(space_id, H5S_SELECT_SET_F, rank, num_points,& + coord, error) + CALL h5rcreate_f(file_id, dsetnamev, space_id, ref(2), error) + ! + ! Write dataset with the references. + ! + CALL h5dwrite_f(dsetr_id, H5T_STD_REF_DSETREG, ref, error) + ! + ! Close all objects. + ! + CALL h5sclose_f(space_id, error) + CALL h5sclose_f(spacer_id, error) + CALL h5dclose_f(dsetr_id, error) + CALL h5fclose_f(file_id, error) + ! + ! Reopen the file to test selections. + ! + CALL h5fopen_f (filename, H5F_ACC_RDWR_F, file_id, error) + CALL h5dopen_f(file_id, dsetnamer, dsetr_id, error) + ! + ! Read references to the dataset regions. + ! + CALL h5dread_f(dsetr_id, H5T_STD_REF_DSETREG, ref_out, error) + ! + ! Dereference the first reference. + ! + CALL H5rdereference_f(dsetr_id, ref_out(1), dsetv_id, error) + CALL H5rget_region_f(dsetr_id, ref_out(1), space_id, error) + ! + ! Read selected data from the dataset. + ! + CALL h5dread_f(dsetv_id, H5T_NATIVE_INTEGER, data_out, error, & + mem_space_id = space_id, file_space_id = space_id) + write(*,*) "Hyperslab selection" + write(*,*) + do i = 1,2 + write(*,*) (data_out (i,j), j = 1,9) + enddo + write(*,*) + CALL h5sclose_f(space_id, error) + CALL h5dclose_f(dsetv_id, error) + data_out = 0 + ! + ! Dereference the second reference. + ! + CALL H5rdereference_f(dsetr_id, ref_out(2), dsetv_id, error) + CALL H5rget_region_f(dsetr_id, ref_out(2), space_id, error) + ! + ! Read selected data from the dataset. + ! + CALL h5dread_f(dsetv_id, H5T_NATIVE_INTEGER, data_out, error, & + mem_space_id = space_id, file_space_id = space_id) + write(*,*) "Point selection" + write(*,*) + do i = 1,2 + write(*,*) (data_out (i,j), j = 1,9) + enddo + ! + ! Close all objects + ! + CALL h5sclose_f(space_id, error) + CALL h5dclose_f(dsetv_id, error) + CALL h5dclose_f(dsetr_id, error) + ! + ! Close FORTRAN predefined datatypes. + ! + CALL h5close_types_f(error) + + END PROGRAM REG_REFERENCE + + diff --git a/doc/html/Tutor/examples/rwdsetexample.f90 b/doc/html/Tutor/examples/rwdsetexample.f90 new file mode 100644 index 0000000..085b4e8 --- /dev/null +++ b/doc/html/Tutor/examples/rwdsetexample.f90 @@ -0,0 +1,78 @@ +! +! The following example shows how to write and read to/from an existing dataset. +! It opens the file created in the previous example, obtains the dataset +! identifier, writes the data to the dataset in the file, +! then reads the dataset to memory. +! + + + PROGRAM RWDSETEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + CHARACTER(LEN=8), PARAMETER :: filename = "dsetf.h5" ! File name + CHARACTER(LEN=4), PARAMETER :: dsetname = "dset" ! Dataset name + + INTEGER(HID_T) :: file_id ! File identifier + INTEGER(HID_T) :: dset_id ! Dataset identifier + + INTEGER :: error ! Error flag + INTEGER :: i, j + + INTEGER, DIMENSION(4,6) :: dset_data, data_out ! Data buffers + + ! + ! Initialize the dset_data array. + ! + do i = 1, 4 + do j = 1, 6 + dset_data(i,j) = (i-1)*6 + j; + end do + end do + + ! + ! Initialize FORTRAN predefined datatypes + ! + CALL h5init_types_f(error) + + ! + ! Open an existing file. + ! + CALL h5fopen_f (filename, H5F_ACC_RDWR_F, file_id, error) + + ! + ! Open an existing dataset. + ! + CALL h5dopen_f(file_id, dsetname, dset_id, error) + + ! + ! Write the dataset. + ! + CALL h5dwrite_f(dset_id, H5T_NATIVE_INTEGER, dset_data, error) + + ! + ! Read the dataset. + ! + CALL h5dread_f(dset_id, H5T_NATIVE_INTEGER, data_out, error) + + ! + ! Close the dataset. + ! + CALL h5dclose_f(dset_id, error) + + ! + ! Close the file. + ! + CALL h5fclose_f(file_id, error) + + ! + ! Close FORTRAN predefined datatypes. + ! + CALL h5close_types_f(error) + + END PROGRAM RWDSETEXAMPLE + + + diff --git a/doc/html/Tutor/examples/selectele.f90 b/doc/html/Tutor/examples/selectele.f90 new file mode 100644 index 0000000..04a6478 --- /dev/null +++ b/doc/html/Tutor/examples/selectele.f90 @@ -0,0 +1,282 @@ +! +! 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 +! uses an H5Scopy to write the same selection to copy2.h5. +! Program reopens the files, and reads and prints the contents of +! the two datasets. +! + + PROGRAM SELECTEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + CHARACTER(LEN=8), PARAMETER :: filename1 = "copy1.h5" ! File name + CHARACTER(LEN=8), PARAMETER :: filename2 = "copy2.h5" ! + CHARACTER(LEN=5), PARAMETER :: dsetname1 = "Copy1" ! Dataset name + CHARACTER(LEN=5), PARAMETER :: dsetname2 = "Copy2" ! + + INTEGER, PARAMETER :: RANK = 2 ! Dataset rank + + INTEGER, PARAMETER :: NUMP = 2 ! Number of points selected + + INTEGER(HID_T) :: file1_id ! File1 identifier + INTEGER(HID_T) :: file2_id ! File2 identifier + INTEGER(HID_T) :: dset1_id ! Dataset1 identifier + INTEGER(HID_T) :: dset2_id ! Dataset2 identifier + INTEGER(HID_T) :: dataspace1 ! Dataspace identifier + INTEGER(HID_T) :: dataspace2 ! Dataspace identifier + INTEGER(HID_T) :: memspace ! memspace identifier + + INTEGER(HSIZE_T), DIMENSION(1) :: dimsm = (/2/) + ! Memory dataspace dimensions + INTEGER(HSIZE_T), DIMENSION(2) :: dimsf = (/3,4/) + ! File dataspace dimensions + INTEGER(HSSIZE_T), DIMENSION(RANK,NUMP) :: coord ! Elements coordinates + ! in the file + + INTEGER, DIMENSION(3,4) :: buf1, buf2, bufnew ! Data buffers + INTEGER, DIMENSION(2) :: val = (/53, 59/) ! Values to write + + INTEGER :: memrank = 1 ! Rank of the dataset in memory + + INTEGER :: i, j + + INTEGER :: error ! Error flag + LOGICAL :: status + + + ! + ! Create two files containing identical datasets. Write 0's to one + ! and 1's to the other. + ! + + ! + ! Data initialization. + ! + do i = 1, 3 + do j = 1, 4 + buf1(i,j) = 0; + end do + end do + + do i = 1, 3 + do j = 1, 4 + buf2(i,j) = 1; + end do + end do + + ! + ! Initialize FORTRAN predefined datatypes + ! + CALL h5init_types_f(error) + + ! + ! Create file1, file2 using default properties. + ! + CALL h5fcreate_f(filename1, H5F_ACC_TRUNC_F, file1_id, error) + + CALL h5fcreate_f(filename2, H5F_ACC_TRUNC_F, file2_id, error) + + ! + ! Create the data space for the datasets. + ! + CALL h5screate_simple_f(RANK, dimsf, dataspace1, error) + + CALL h5screate_simple_f(RANK, dimsf, dataspace2, error) + + ! + ! Create the datasets with default properties. + ! + CALL h5dcreate_f(file1_id, dsetname1, H5T_NATIVE_INTEGER, dataspace1, & + dset1_id, error) + + CALL h5dcreate_f(file2_id, dsetname2, H5T_NATIVE_INTEGER, dataspace2, & + dset2_id, error) + + ! + ! Write the datasets. + ! + CALL h5dwrite_f(dset1_id, H5T_NATIVE_INTEGER, buf1, error) + + CALL h5dwrite_f(dset2_id, H5T_NATIVE_INTEGER, buf2, error) + + ! + ! Close the dataspace for the datasets. + ! + CALL h5sclose_f(dataspace1, error) + + CALL h5sclose_f(dataspace2, error) + + ! + ! Close the datasets. + ! + CALL h5dclose_f(dset1_id, error) + + CALL h5dclose_f(dset2_id, error) + + ! + ! Close the files. + ! + CALL h5fclose_f(file1_id, error) + + CALL h5fclose_f(file2_id, error) + + ! + ! 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. + ! + + ! + ! Open the files. + ! + CALL h5fopen_f (filename1, H5F_ACC_RDWR_F, file1_id, error) + + CALL h5fopen_f (filename2, H5F_ACC_RDWR_F, file2_id, error) + + ! + ! Open the datasets. + ! + CALL h5dopen_f(file1_id, dsetname1, dset1_id, error) + + CALL h5dopen_f(file2_id, dsetname2, dset2_id, error) + + ! + ! Get dataset1's dataspace identifier. + ! + CALL h5dget_space_f(dset1_id, dataspace1, error) + + ! + ! Create memory dataspace. + ! + CALL h5screate_simple_f(memrank, dimsm, memspace, error) + + ! + ! Set the selected point positions. Because Fortran array index starts + ! from 1, so add one to the actual select points in C. + ! + coord(1,1) = 1 + coord(2,1) = 2 + coord(1,2) = 1 + coord(2,2) = 4 + + ! + ! Select the elements in file space. + ! + CALL h5sselect_elements_f(dataspace1, H5S_SELECT_SET_F, RANK, NUMP,& + coord, error) + + ! + ! Write value into the selected points in dataset1. + ! + CALL H5dwrite_f(dset1_id, H5T_NATIVE_INTEGER, val, error, & + mem_space_id=memspace, file_space_id=dataspace1) + + ! + ! Copy the daspace1 into dataspace2. + ! + CALL h5scopy_f(dataspace1, dataspace2, error) + + ! + ! Write value into the selected points in dataset2. + ! + CALL H5dwrite_f(dset2_id, H5T_NATIVE_INTEGER, val, error, & + mem_space_id=memspace, file_space_id=dataspace2) + + ! + ! Close the dataspace for the datasets. + ! + CALL h5sclose_f(dataspace1, error) + + CALL h5sclose_f(dataspace2, error) + + ! + ! Close the memoryspace. + ! + CALL h5sclose_f(memspace, error) + + ! + ! Close the datasets. + ! + CALL h5dclose_f(dset1_id, error) + + CALL h5dclose_f(dset2_id, error) + + ! + ! Close the files. + ! + CALL h5fclose_f(file1_id, error) + + CALL h5fclose_f(file2_id, error) + + ! + ! Open both files and print the contents of the datasets. + ! + + ! + ! Open the files. + ! + CALL h5fopen_f (filename1, H5F_ACC_RDWR_F, file1_id, error) + + CALL h5fopen_f (filename2, H5F_ACC_RDWR_F, file2_id, error) + + ! + ! Open the datasets. + ! + CALL h5dopen_f(file1_id, dsetname1, dset1_id, error) + + CALL h5dopen_f(file2_id, dsetname2, dset2_id, error) + + ! + ! Read dataset from the first file. + ! + CALL h5dread_f(dset1_id, H5T_NATIVE_INTEGER, bufnew, error) + + ! + ! Display the data read from dataset "Copy1" + ! + write(*,*) "The data in dataset Copy1 is: " + do i = 1, 3 + print *, (bufnew(i,j), j = 1,4) + end do + + ! + ! Read dataset from the second file. + ! + CALL h5dread_f(dset2_id, H5T_NATIVE_INTEGER, bufnew, error) + + ! + ! Display the data read from dataset "Copy2" + ! + write(*,*) "The data in dataset Copy2 is: " + do i = 1, 3 + print *, (bufnew(i,j), j = 1,4) + end do + + ! + ! Close datasets. + ! + CALL h5dclose_f(dset1_id, error) + + CALL h5dclose_f(dset2_id, error) + + ! + ! Close files. + ! + CALL h5fclose_f(file1_id, error) + + CALL h5fclose_f(file2_id, error) + + ! + ! Close FORTRAN predefined datatypes. + ! + CALL h5close_types_f(error) + + END PROGRAM SELECTEXAMPLE diff --git a/doc/html/Tutor/extend.html b/doc/html/Tutor/extend.html index 03b5972..55ff9e9 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,9 @@ 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> <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..4ed3a12 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,9 @@ 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> <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..edec3e2 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,7 @@ 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> <H6>Last Modified: January 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> diff --git a/doc/html/Tutor/img001.gif b/doc/html/Tutor/img001.gif Binary files differindex b79c6d6..8ed766c 100644 --- a/doc/html/Tutor/img001.gif +++ b/doc/html/Tutor/img001.gif diff --git a/doc/html/Tutor/img002.gif b/doc/html/Tutor/img002.gif Binary files differindex 67585ef..e65f785 100644 --- a/doc/html/Tutor/img002.gif +++ b/doc/html/Tutor/img002.gif diff --git a/doc/html/Tutor/img003.gif b/doc/html/Tutor/img003.gif Binary files differindex ac1dcf9..0dec000 100644 --- a/doc/html/Tutor/img003.gif +++ b/doc/html/Tutor/img003.gif diff --git a/doc/html/Tutor/img004.gif b/doc/html/Tutor/img004.gif Binary files differindex d48dbab..26ff731 100644 --- a/doc/html/Tutor/img004.gif +++ b/doc/html/Tutor/img004.gif diff --git a/doc/html/Tutor/img005.gif b/doc/html/Tutor/img005.gif Binary files differindex 3383dc6..aa57847 100644 --- a/doc/html/Tutor/img005.gif +++ b/doc/html/Tutor/img005.gif diff --git a/doc/html/Tutor/intro.html b/doc/html/Tutor/intro.html index abf664c..31b5cc9 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,9 @@ 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> <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..6ba6349 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,9 @@ 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> <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..2677d4d 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>mount.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,9 @@ 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> <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/questions.html b/doc/html/Tutor/questions.html index 26153f3..5cf5d4d 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,7 @@ 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> <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..74c1122 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,9 @@ 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> <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..4fc58aa 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,7 @@ 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> <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..193d9c2 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,9 @@ 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> <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..c5be33f 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,9 @@ 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> <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..459043d 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,9 @@ 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> <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..dec7b1f 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,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> <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/title.html b/doc/html/Tutor/title.html index 35283b7..36f724a 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> @@ -31,9 +29,47 @@ width=78 height=27 alt="NCSA"><P></A> </FONT> <BR> </CENTER> + <BR CLEAR=ALL><BR> ---> +<BODY> +<HR> +<BIG><B>NOTE:</B></BIG> +This tutorial does NOT include the software needed to compile the +examples. You will need to obtain this first:<P> +<UL> + <B>C:</B> +<UL>Obtain the HDF5 library. We provide pre-compiled binaries for the +platforms on which we tested at +<A HREF="ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/bin">ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/bin</A>. +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: +<A HREF="ftp://ftp.ncsa.uiuc.edu/HDF/gzip/">ftp://ftp.ncsa.uiuc.edu/HDF/gzip/</A> +</UL> +<P> + <B>FORTRAN90</B>: +<UL> +Obtain the +<A HREF="ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/bin">HDF5 libraries</A>, +<A HREF="ftp://ftp.ncsa.uiuc.edu/HDF/gzip/">GZIP library</A>, and +the HDF5 Fortran90 library. Currently we only provide the source code +for the HDF5 Fortran90 library at: + +<A HREF="ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/fortran/">ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/fortran/</A> +<P> +The HDF5 Fortran90 library was tested on Solaris, IRIX64, and Digital Unix. +</UL> + <BR> + <B>Java</B>: You will need the JHI5 code. Go to the +<A HREF="/java-hdf5-html">Java HDF5 web page</A> +for more details. + +</UL> +<HR> + <H2>Contents:</H2> <H3>Introductory Topics</H3> <OL> @@ -42,11 +78,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 +91,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 +122,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: June 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> </FONT> <BR> |
