From 9348ba920eecacd35adde6c4573cc85c6033dc65 Mon Sep 17 00:00:00 2001 From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com> Date: Mon, 12 Sep 2022 22:37:01 -0500 Subject: 1 12 doxygen merge from 1.10 (#2094) --- CTestConfig.cmake | 2 +- configure.ac | 6 +- doxygen/CMakeLists.txt | 2 +- doxygen/Doxyfile.in | 4 +- doxygen/aliases | 8 + doxygen/dox/GettingStarted.dox | 101 +- doxygen/dox/IntroHDF5.dox | 627 +++ doxygen/dox/LearnBasics.dox | 183 + doxygen/dox/LearnBasics1.dox | 1023 ++++ doxygen/dox/LearnBasics2.dox | 1159 +++++ doxygen/dox/LearnBasics3.dox | 1015 ++++ doxygen/dox/LearnHDFView.dox | 472 ++ doxygen/dox/UsersGuide.dox | 2 +- doxygen/dox/ViewTools.dox | 1198 +++++ doxygen/dox/ViewTools2.dox | 786 +++ doxygen/dox/ViewToolsJPSS.dox | 763 +++ doxygen/examples/fortran_menu.md | 46 +- doxygen/examples/high_level_menu.md | 12 +- doxygen/hdf5doxy_layout.xml | 2 +- doxygen/img/DataGroup.png | Bin 0 -> 41665 bytes doxygen/img/LBDsetSubRWProg.png | Bin 0 -> 18297 bytes doxygen/img/StormDataset.png | Bin 0 -> 21441 bytes doxygen/img/cmpnddtype.png | Bin 0 -> 19354 bytes doxygen/img/crtatt.png | Bin 0 -> 30414 bytes doxygen/img/crtdset.png | Bin 0 -> 18200 bytes doxygen/img/crtf-pic.png | Bin 0 -> 14322 bytes doxygen/img/crtgrp.png | Bin 0 -> 15588 bytes doxygen/img/dataset.png | Bin 0 -> 25110 bytes doxygen/img/datasetwdata.png | Bin 0 -> 71012 bytes doxygen/img/dataspace.png | Bin 0 -> 15883 bytes doxygen/img/dataspace1.png | Bin 0 -> 11510 bytes doxygen/img/datatype.png | Bin 0 -> 11848 bytes doxygen/img/fileobj.png | Bin 0 -> 108220 bytes doxygen/img/group.png | Bin 0 -> 122668 bytes doxygen/img/hdfview-anthrstrm-img.png | Bin 0 -> 68911 bytes doxygen/img/hdfview-anthrstrm-sprdsht.png | Bin 0 -> 63861 bytes doxygen/img/hdfview-anthrstrm.png | Bin 0 -> 46472 bytes doxygen/img/hdfview-imgicon.png | Bin 0 -> 81394 bytes doxygen/img/hdfview-imgprop.png | Bin 0 -> 83103 bytes doxygen/img/hdfview-imgsubset.png | Bin 0 -> 82068 bytes doxygen/img/hdfview-newcmpd.png | Bin 0 -> 100495 bytes doxygen/img/hdfview-newimgsubset.png | Bin 0 -> 85051 bytes doxygen/img/hdfview-prop.png | Bin 0 -> 114672 bytes doxygen/img/hdfview-qf.png | Bin 0 -> 170686 bytes doxygen/img/hdfview-regref.png | Bin 0 -> 231317 bytes doxygen/img/hdfview-regref1.png | Bin 0 -> 134813 bytes doxygen/img/hdfview-regref2.png | Bin 0 -> 195189 bytes doxygen/img/hdfview-regrefval.png | Bin 0 -> 56209 bytes doxygen/img/hdfview-table.png | Bin 0 -> 61329 bytes doxygen/img/hdfview-tree.png | Bin 0 -> 38283 bytes doxygen/img/imgLBDsetCreate.gif | Bin 0 -> 954 bytes doxygen/img/imgLBDsetSubRW11.png | Bin 0 -> 23645 bytes doxygen/img/imgLBDsetSubRW12.png | Bin 0 -> 25324 bytes doxygen/img/imgLBDsetSubRW31.png | Bin 0 -> 17212 bytes doxygen/img/imgLBDsetSubRW32.png | Bin 0 -> 18201 bytes doxygen/img/imgLBDsetSubRW33.png | Bin 0 -> 17781 bytes doxygen/img/imgLBFile.gif | Bin 0 -> 635 bytes doxygen/img/imggrpcreate.gif | Bin 0 -> 928 bytes doxygen/img/imggrpdsets.gif | Bin 0 -> 1812 bytes doxygen/img/imggrps.gif | Bin 0 -> 1644 bytes doxygen/img/newgroupimage.png | Bin 0 -> 44700 bytes doxygen/img/noattrs.png | Bin 0 -> 43386 bytes doxygen/img/properties.png | Bin 0 -> 50472 bytes doxygen/img/scarletletter.png | Bin 0 -> 51013 bytes doxygen/img/showasimage.png | Bin 0 -> 66016 bytes doxygen/img/storm.png | Bin 0 -> 41590 bytes doxygen/img/tutr-lochk.png | Bin 0 -> 9419 bytes doxygen/img/tutr-lochks.png | Bin 0 -> 9652 bytes doxygen/img/tutr-locons.png | Bin 0 -> 8133 bytes doxygen/img/vol_architecture.png | Bin 0 -> 46329 bytes fortran/src/H5Aff.F90 | 1596 +++--- fortran/src/H5Dff.F90 | 1362 +++--- fortran/src/H5Eff.F90 | 227 +- fortran/src/H5Fff.F90 | 898 ++-- fortran/src/H5Gff.F90 | 1139 ++--- fortran/src/H5Iff.F90 | 314 +- fortran/src/H5Lff.F90 | 1176 ++--- fortran/src/H5Off.F90 | 847 ++-- fortran/src/H5Pff.F90 | 7580 +++++++++-------------------- fortran/src/H5Rff.F90 | 732 ++- fortran/src/H5Sff.F90 | 1489 ++---- fortran/src/H5Tff.F90 | 2600 +++------- fortran/src/H5VLff.F90 | 254 +- fortran/src/H5Zff.F90 | 160 +- fortran/src/H5_buildiface.F90 | 4 +- fortran/src/H5_ff.F90 | 342 +- hl/fortran/src/H5DSff.F90 | 395 +- hl/fortran/src/H5IMff.F90 | 698 ++- hl/fortran/src/H5LTff.F90 | 1535 +++--- hl/fortran/src/H5TBff.F90 | 911 ++-- hl/src/H5DOpublic.h | 6 +- hl/src/H5DSpublic.h | 6 +- hl/src/H5IMpublic.h | 8 +- hl/src/H5LTpublic.h | 6 +- hl/src/H5PTpublic.h | 6 +- hl/src/H5TBpublic.h | 6 +- java/src/hdf/hdf5lib/H5.java | 186 +- src/H5ACpublic.h | 4 +- src/H5Dpublic.h | 2 +- src/H5Emodule.h | 20 +- src/H5Imodule.h | 4 + src/H5Lmodule.h | 4 + src/H5Omodule.h | 4 + src/H5PLmodule.h | 4 + src/H5Ppublic.h | 2 +- src/H5Rmodule.h | 4 + src/H5VLmodule.h | 4 +- src/H5Zmodule.h | 4 + src/H5public.h | 2 +- 109 files changed, 16213 insertions(+), 15739 deletions(-) create mode 100644 doxygen/dox/IntroHDF5.dox create mode 100644 doxygen/dox/LearnBasics.dox create mode 100644 doxygen/dox/LearnBasics1.dox create mode 100644 doxygen/dox/LearnBasics2.dox create mode 100644 doxygen/dox/LearnBasics3.dox create mode 100644 doxygen/dox/LearnHDFView.dox create mode 100644 doxygen/dox/ViewTools.dox create mode 100644 doxygen/dox/ViewTools2.dox create mode 100644 doxygen/dox/ViewToolsJPSS.dox create mode 100644 doxygen/img/DataGroup.png create mode 100644 doxygen/img/LBDsetSubRWProg.png create mode 100644 doxygen/img/StormDataset.png create mode 100644 doxygen/img/cmpnddtype.png create mode 100644 doxygen/img/crtatt.png create mode 100644 doxygen/img/crtdset.png create mode 100644 doxygen/img/crtf-pic.png create mode 100644 doxygen/img/crtgrp.png create mode 100644 doxygen/img/dataset.png create mode 100644 doxygen/img/datasetwdata.png create mode 100644 doxygen/img/dataspace.png create mode 100644 doxygen/img/dataspace1.png create mode 100644 doxygen/img/datatype.png create mode 100644 doxygen/img/fileobj.png create mode 100644 doxygen/img/group.png create mode 100644 doxygen/img/hdfview-anthrstrm-img.png create mode 100644 doxygen/img/hdfview-anthrstrm-sprdsht.png create mode 100644 doxygen/img/hdfview-anthrstrm.png create mode 100644 doxygen/img/hdfview-imgicon.png create mode 100644 doxygen/img/hdfview-imgprop.png create mode 100644 doxygen/img/hdfview-imgsubset.png create mode 100644 doxygen/img/hdfview-newcmpd.png create mode 100644 doxygen/img/hdfview-newimgsubset.png create mode 100644 doxygen/img/hdfview-prop.png create mode 100644 doxygen/img/hdfview-qf.png create mode 100644 doxygen/img/hdfview-regref.png create mode 100644 doxygen/img/hdfview-regref1.png create mode 100644 doxygen/img/hdfview-regref2.png create mode 100644 doxygen/img/hdfview-regrefval.png create mode 100644 doxygen/img/hdfview-table.png create mode 100644 doxygen/img/hdfview-tree.png create mode 100644 doxygen/img/imgLBDsetCreate.gif create mode 100644 doxygen/img/imgLBDsetSubRW11.png create mode 100644 doxygen/img/imgLBDsetSubRW12.png create mode 100644 doxygen/img/imgLBDsetSubRW31.png create mode 100644 doxygen/img/imgLBDsetSubRW32.png create mode 100644 doxygen/img/imgLBDsetSubRW33.png create mode 100644 doxygen/img/imgLBFile.gif create mode 100644 doxygen/img/imggrpcreate.gif create mode 100644 doxygen/img/imggrpdsets.gif create mode 100644 doxygen/img/imggrps.gif create mode 100644 doxygen/img/newgroupimage.png create mode 100644 doxygen/img/noattrs.png create mode 100644 doxygen/img/properties.png create mode 100644 doxygen/img/scarletletter.png create mode 100644 doxygen/img/showasimage.png create mode 100644 doxygen/img/storm.png create mode 100644 doxygen/img/tutr-lochk.png create mode 100644 doxygen/img/tutr-lochks.png create mode 100644 doxygen/img/tutr-locons.png create mode 100755 doxygen/img/vol_architecture.png diff --git a/CTestConfig.cmake b/CTestConfig.cmake index 7066376..98f3ad2 100644 --- a/CTestConfig.cmake +++ b/CTestConfig.cmake @@ -12,7 +12,7 @@ ## This file should be placed in the root directory of your project. ## Then modify the CMakeLists.txt file in the root directory of your ## project to incorporate the testing dashboard. -## # The following are required to uses Dart and the Cdash dashboard +## # The following are required to use Dart and the CDash dashboard ## ENABLE_TESTING() ## INCLUDE(CTest) set (CTEST_PROJECT_NAME "HDF5") diff --git a/configure.ac b/configure.ac index b90ed20..68d573d 100644 --- a/configure.ac +++ b/configure.ac @@ -1212,6 +1212,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then AC_SUBST([DOXYGEN_PACKAGE]) AC_SUBST([DOXYGEN_VERSION_STRING]) + AC_SUBST([DOXYGEN_DIR]) AC_SUBST([DOXYGEN_INCLUDE_ALIASES]) AC_SUBST([DOXYGEN_PROJECT_LOGO]) AC_SUBST([DOXYGEN_PROJECT_BRIEF]) @@ -1236,6 +1237,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then # SRCDIR Environment variables used inside doxygen macro for the source location: DOXYGEN_PACKAGE=${PACKAGE_NAME} DOXYGEN_VERSION_STRING=${PACKAGE_VERSION} + DOXYGEN_DIR='$(SRCDIR)/doxygen' DOXYGEN_INCLUDE_ALIASES='$(SRCDIR)/doxygen/aliases' DOXYGEN_PROJECT_LOGO='$(SRCDIR)/doxygen/img/HDFG-logo.png' DOXYGEN_PROJECT_BRIEF='' @@ -1248,14 +1250,14 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then DOXYGEN_HTML_HEADER='$(SRCDIR)/doxygen/hdf5_header.html' DOXYGEN_HTML_FOOTER='$(SRCDIR)/doxygen/hdf5_footer.html' DOXYGEN_HTML_EXTRA_STYLESHEET='$(SRCDIR)/doxygen/hdf5doxy.css' - DOXYGEN_HTML_EXTRA_FILES='$(SRCDIR)/doxygen/hdf5_navtree_hacks.js $(SRCDIR)/doxygen/img/FF-IH_FileGroup.gif $(SRCDIR)/doxygen/img/FF-IH_FileObject.gif $(SRCDIR)/doxygen/img/FileFormatSpecChunkDiagram.jpg $(SRCDIR)/doxygen/img/ftv2node.png $(SRCDIR)/doxygen/img/ftv2pnode.png $(SRCDIR)/doxygen/img/HDFG-logo.png $(SRCDIR)/doxygen/img/IOFlow2.gif $(SRCDIR)/doxygen/img/IOFlow3.gif $(SRCDIR)/doxygen/img/IOFlow.gif $(SRCDIR)/doxygen/img/PaletteExample1.gif $(SRCDIR)/doxygen/img/Palettes.fm.anc.gif' + DOXYGEN_HTML_EXTRA_FILES='$(SRCDIR)/doxygen/hdf5_navtree_hacks.js' DOXYGEN_TAG_FILE=hdf5.tag DOXYGEN_SERVER_BASED_SEARCH=NO DOXYGEN_EXTERNAL_SEARCH=NO DOXYGEN_SEARCHENGINE_URL= DOXYGEN_STRIP_FROM_PATH='$(SRCDIR)' DOXYGEN_STRIP_FROM_INC_PATH='$(SRCDIR)' - DOXYGEN_PREDEFINED='H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD' + DOXYGEN_PREDEFINED='H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD H5_DOXYGEN_FORTRAN' DX_INIT_DOXYGEN([HDF5], [./doxygen/Doxyfile], [hdf5lib_docs]) fi diff --git a/doxygen/CMakeLists.txt b/doxygen/CMakeLists.txt index 17d8da7..472c4dc 100644 --- a/doxygen/CMakeLists.txt +++ b/doxygen/CMakeLists.txt @@ -29,7 +29,7 @@ if (DOXYGEN_FOUND) set (DOXYGEN_SEARCHENGINE_URL) set (DOXYGEN_STRIP_FROM_PATH ${HDF5_SOURCE_DIR}) set (DOXYGEN_STRIP_FROM_INC_PATH ${HDF5_SOURCE_DIR}) - set (DOXYGEN_PREDEFINED "H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD") + set (DOXYGEN_PREDEFINED "H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD H5_DOXYGEN_FORTRAN") # This configure and individual custom targets work together # Replace variables inside @@ with the current values diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 6f29c0b..ce08db2 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -280,13 +280,13 @@ OPTIMIZE_OUTPUT_FOR_C = YES # qualified scopes will look different, etc. # The default value is: NO. -OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_OUTPUT_JAVA = YES # Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran # sources. Doxygen will then generate output that is tailored for Fortran. # The default value is: NO. -OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_FOR_FORTRAN = YES # Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL # sources. Doxygen will then generate output that is tailored for VHDL. diff --git a/doxygen/aliases b/doxygen/aliases index d684b63..dc79623 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -360,3 +360,11 @@ ALIASES += storage_type="
#H5G_STORAGE_TYPE_COMPACTCompac ALIASES += str_pad_type="
#H5T_STR_NULLTERM0Null terminate (as C does)
#H5T_STR_NULLPAD1Pad with zeros
#H5T_STR_SPACEPAD2Pad with spaces (as FORTRAN does)
" ALIASES += see_virtual=" \see Supporting Functions: H5Pget_layout(), H5Pset_layout(), H5Sget_regular_hyperslab(), H5Sis_regular_hyperslab(), H5Sselect_hyperslab() \see VDS Functions: H5Pget_virtual_count(), H5Pget_virtual_dsetname(), H5Pget_virtual_filename(), H5Pget_virtual_prefix(), H5Pget_virtual_printf_gap(), H5Pget_virtual_srcspace(), H5Pget_virtual_view(), H5Pget_virtual_vspace(), H5Pset_virtual(), H5Pset_virtual_prefix(), H5Pset_virtual_printf_gap(), H5Pset_virtual_view()" ALIASES += obj_info_fields="
FlagPurpose
#H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
#H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
#H5O_INFO_NUM_ATTRS Fill in the num_attrs field
#H5O_INFO_HDRFill in the num_attrs field
#H5O_INFO_META_SIZEFill in the meta_size field
#H5O_INFO_ALL#H5O_INFO_BASIC | #H5O_INFO_TIME | #H5O_INFO_NUM_ATTRS | #H5O_INFO_HDR | #H5O_INFO_META_SIZE
" + +################################################################################ +# FORTRAN +################################################################################ + +ALIASES += fortran_error="Returns 0 if successful and -1 if it fails." +ALIASES += fortran_approved="The preferred API, Fortran 2003 version." +ALIASES += fortran_obsolete="Obsolete API, use the Fortran 2003 version instead." diff --git a/doxygen/dox/GettingStarted.dox b/doxygen/dox/GettingStarted.dox index 880491d..29c5033 100644 --- a/doxygen/dox/GettingStarted.dox +++ b/doxygen/dox/GettingStarted.dox @@ -1,3 +1,100 @@ -/** \page GettingStarted \Code{Hello, HDF5!} +/** @page GettingStarted Getting Started with HDF5 - */ \ No newline at end of file +Navigate back: \ref index "Main" +
+ +\section sec_learn Learning HDF5 +There are several resources for learning about HDF5. The HDF Group provides an on-line HDF5 tutorial, +documentation, examples, and videos. There are also tutorials provided by other organizations that are very useful for learning about HDF5. + +\subsection subsec_learn_intro The HDF Group Resources +For a quick introduction to HDF5 see the following: + + + + + + + + + + + + + +
+@ref IntroHDF5 + +A very brief introduction to HDF5 and the HDF5 programming model and APIs +
+@ref LearnHDFView + +A tutorial for learning how to use HDFView. NO programming involved! +
+@ref LearnBasics + +Step by step instructions for learning HDF5 that include programming examples +
+ +\subsection subsec_learn_tutor The HDF Group Tutorials and Examples +These tutorials and examples are available for learning about the HDF5 High Level APIs, tools, +Parallel HDF5, and the HDF5-1.10 VDS and SWMR new features: + + + + + + + + + + + + + + + + + + + + + + + + + +
+Using the High Level APIs + +\ref H5LT \ref H5IM \ref H5TB \ref H5PT \ref H5DS +
+Introduction to Parallel HDF5 + +A brief introduction to Parallel HDF5. If you are new to HDF5 please see the @ref LearnBasics topic first. +
+\ref ViewTools + +\li @ref LearnHDFView +\li @ref ViewToolsCommand +\li @ref ViewToolsJPSS +
+HDF5-1.10 New Features + +\li Introduction to the Virtual Dataset - VDS +\li Introduction to Single-Writer/Multiple-Reader (SWMR) +
+Example Programs + +\ref HDF5Examples +
+Videos + +\li Introduction to HDF5 +\li Parallel HDF5 +
+ +
+Navigate back: \ref index "Main" + +*/ diff --git a/doxygen/dox/IntroHDF5.dox b/doxygen/dox/IntroHDF5.dox new file mode 100644 index 0000000..ec46217 --- /dev/null +++ b/doxygen/dox/IntroHDF5.dox @@ -0,0 +1,627 @@ +/** @page IntroHDF5 Introduction to HDF5 + +Navigate back: \ref index "Main" / \ref GettingStarted +
+ +\section sec_intro_desc HDF5 Description +HDF5 consists of a file format for storing HDF5 data, a data model for logically organizing and accessing +HDF5 data from an application, and the software (libraries, language interfaces, and tools) for working with this format. + +\subsection subsec_intro_desc_file File Format +HDF5 consists of a file format for storing HDF5 data, a data model for logically organizing and accessing HDF5 data from an application, +and the software (libraries, language interfaces, and tools) for working with this format. + +\subsection subsec_intro_desc_dm Data Model +The HDF5 Data Model, also known as the HDF5 Abstract (or Logical) Data Model consists of +the building blocks for data organization and specification in HDF5. + +An HDF5 file (an object in itself) can be thought of as a container (or group) that holds +a variety of heterogeneous data objects (or datasets). The datasets can be images, tables, +graphs, and even documents, such as PDF or Excel: + + + + + +
+\image html fileobj.png +
+ +The two primary objects in the HDF5 Data Model are groups and datasets. + +There are also a variety of other objects in the HDF5 Data Model that support groups and datasets, +including datatypes, dataspaces, properties and attributes. + +\subsubsection subsec_intro_desc_dm_group Groups +HDF5 groups (and links) organize data objects. Every HDF5 file contains a root group that can +contain other groups or be linked to objects in other files. + + + + + + +
There are two groups in the HDF5 file depicted above: Viz and SimOut. +Under the Viz group are a variety of images and a table that is shared with the SimOut group. +The SimOut group contains a 3-dimensional array, a 2-dimensional array and a link to a 2-dimensional +array in another HDF5 file.
+\image html group.png +
+ +Working with groups and group members 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. +\li / signifies the root group. +\li /foo signifies a member of the root group called foo. +\li /foo/zoo signifies a member of the group foo, which in turn is a member of the root group. + +\subsubsection subsec_intro_desc_dm_dset Datasets +HDF5 datasets organize and contain the “raw” data values. A dataset consists of metadata +that describes the data, in addition to the data itself: + + + + + + +
In this picture, the data is stored as a three dimensional dataset of size 4 x 5 x 6 with an integer datatype. +It contains attributes, Time and Pressure, and the dataset is chunked and compressed.
+\image html dataset.png +
+ +Datatypes, dataspaces, properties and (optional) attributes are HDF5 objects that describe a dataset. +The datatype describes the individual data elements. + +\subsection subsec_intro_desc_props Datatypes, Dataspaces, Properties and Attributes + +\subsubsection subsec_intro_desc_prop_dtype Datatypes +The datatype describes the individual data elements in a dataset. It provides complete information for +data conversion to or from that datatype. + + + + + + +
In the dataset depicted, each element of the dataset is a 32-bit integer.
+\image html datatype.png +
+ +Datatypes in HDF5 can be grouped into: +
    +
  • +Pre-Defined Datatypes: These are datatypes that are created by HDF5. They are actually opened (and closed) +by HDF5 and can have different values from one HDF5 session to the next. There are two types of pre-defined datatypes: +
      +
    • +Standard datatypes are the same on all platforms and are what you see in an HDF5 file. Their names are of the form +H5T_ARCH_BASE where ARCH is an architecture name and BASE is a pro­gramming type name. For example, #H5T_IEEE_F32BE +indicates a standard Big Endian floating point type. +
      • +
    • +Native datatypes are used to simplify memory operations (reading, writing) and are NOT the same on different platforms. +For example, #H5T_NATIVE_INT indicates an int (C). +
      • +
    +
    • +
  • +Derived Datatypes: These are datatypes that are created or derived from the pre-defined datatypes. +An example of a commonly used derived datatype is a string of more than one character. Compound datatypes +are also derived types. A compound datatype can be used to create a simple table, and can also be nested, +in which it includes one more other compound datatypes. + + + + + +
    This is an example of a dataset with a compound datatype. Each element in the dataset consists +of a 16-bit integer, a character, a 32-bit integer, and a 2x3x2 array of 32-bit floats (the datatype). +It is a 2-dimensional 5 x 3 array (the dataspace). The datatype should not be confused with the dataspace. +
    +\image html cmpnddtype.png +
    +
    • +
+ +\subsubsection subsec_intro_desc_prop_dspace Dataspaces +A dataspace describes the layout of a dataset’s data elements. It can consist of no elements (NULL), +a single element (scalar), or a simple array. + + + + + + +
This image illustrates a dataspace that is an array with dimensions of 5 x 3 and a rank (number of dimensions) of 2.
+\image html dataspace1.png +
+ +A dataspace can have dimensions that are fixed (unchanging) or unlimited, which means they can grow +in size (i.e. they are extendible). + +There are two roles of a dataspace: +\li It contains the spatial information (logical layout) of a dataset stored in a file. This includes the rank and dimensions of a dataset, which are a permanent part of the dataset definition. +\li It describes an application’s data buffers and data elements participating in I/O. In other words, it can be used to select a portion or subset of a dataset. + + + + + + +
The dataspace is used to describe both the logical layout of a dataset and a subset of a dataset.
+\image html dataspace.png +
+ +\subsubsection subsec_intro_desc_prop_property Properties +A property is a characteristic or feature of an HDF5 object. There are default properties which +handle the most common needs. These default properties can be modified using the HDF5 Property +List API to take advantage of more powerful or unusual features of HDF5 objects. + + + + + +
+\image html properties.png +
+ +For example, the data storage layout property of a dataset is contiguous by default. For better +performance, the layout can be modified to be chunked or chunked and compressed: + +\subsubsection subsec_intro_desc_prop_attr Attributes +Attributes can optionally be associated with HDF5 objects. They have two parts: a name and a value. +Attributes are accessed by opening the object that they are attached to so are not independent objects. +Typically an attribute is small in size and contains user metadata about the object that it is attached to. + +Attributes look similar to HDF5 datasets in that they have a datatype and dataspace. However, they +do not support partial I/O operations, and they cannot be compressed or extended. + +\subsection subsec_intro_desc_soft HDF5 Software +The HDF5 software is written in C and includes optional wrappers for C++, FORTRAN (90 and F2003), +and Java. The HDF5 binary distribution consists of the HDF5 libraries, include files, command-line +utilities, scripts for compiling applications, and example programs. + +\subsubsection subsec_intro_desc_soft_apis HDF5 APIs and Libraries +There are APIs for each type of object in HDF5. For example, all C routines in the HDF5 library +begin with a prefix of the form H5*, where * is one or two uppercase letters indicating the type +of object on which the function operates: +\li @ref H5A Attribute Interface +\li @ref H5D Dataset Interface +\li @ref H5F File Interface + +The HDF5 High Level APIs simplify many of the steps required to create and access objects, as well +as providing templates for storing objects. Following is a list of the High Level APIs: +\li @ref H5LT – simplifies steps in creating datasets and attributes +\li @ref H5IM – defines a standard for storing images in HDF5 +\li @ref H5TB – condenses the steps required to create tables +\li @ref H5DS – provides a standard for dimension scale storage +\li @ref H5PT – provides a standard for storing packet data + +\subsubsection subsec_intro_desc_soft_tools Tools +Useful tools for working with HDF5 files include: +\li h5dump: A utility to dump or display the contents of an HDF5 File +\li h5cc, h5c++, h5fc: Unix scripts for compiling applications +\li HDFView: A java browser to view HDF (HDF4 and HDF5) files + +

h5dump

+The h5dump utility displays the contents of an HDF5 file in Data Description Language (\ref DDLBNF110). +Below is an example of h5dump output for an HDF5 file that contains no objects: +\code +$ h5dump file.h5 + HDF5 "file.h5" { + GROUP "/" { + } + } +\endcode + +With large files and datasets the output from h5dump can be overwhelming. +There are options that can be used to examine specific parts of an HDF5 file. +Some useful h5dump options are included below: +\code + -H, --header Display header information only (no data) + -d Display a dataset with a specified path and name + -p Display properties + -n Display the contents of the file +\endcode + +

h5cc, h5fc, h5c++

+The built HDF5 binaries include the h5cc, h5fc, h5c++ compile scripts for compiling applications. +When using these scripts there is no need to specify the HDF5 libraries and include files. +Compiler options can be passed to the scripts. + +

HDFView

+The HDFView tool allows browsing of data in HDF (HDF4 and HDF5) files. + +\section sec_intro_pm Introduction to the HDF5 Programming Model and APIs +The HDF5 Application Programming Interface is extensive, but a few functions do most of the work. + +To introduce the programming model, examples in Python and C are included below. The Python examples +use the HDF5 Python APIs (h5py). See the Examples from "Learning the Basics" page for complete examples +that can be downloaded and run for C, FORTRAN, C++, Java and Python. + +The general paradigm for working with objects in HDF5 is to: +\li Open the object. +\li Access the object. +\li Close the object. + +The library imposes an order on the operations by argument dependencies. For example, a file must be +opened before a dataset because the dataset open call requires a file handle as an argument. Objects +can be closed in any order. However, once an object is closed it no longer can be accessed. + +Keep the following in mind when looking at the example programs included in this section: +
    +
  • +
      +
    • +C routines begin with the prefix “H5*” where * is a single letter indicating the object on which the +operation is to be performed. +
      • +
    • +FORTRAN routines are similar; they begin with “h5*” and end with “_f”. +
      • +
    • +Java routines are similar; the routine names begin with “H5*” and are prefixed with “H5.” as the class. Constants are +in the HDF5Constants class and are prefixed with "HDF5Constants.". The function arguments +are usually similar, @see @ref HDF5LIB +
      • +
    +For example: +
      +
    • +File Interface:
      • #H5Fopen (C)
      • h5fopen_f (FORTRAN)
      • H5.H5Fopen (Java)
      +
      • +
    • +Dataset Interface:
      • #H5Dopen (C)
      • h5dopen_f (FORTRAN)
      • H5.H5Dopen (Java)
      +
      • +
    • +Dataspace interface:
      • #H5Sclose (C)
      • h5sclose_f (FORTRAN)
      • H5.H5Sclose (Java)
      +
      • +
    +The HDF5 Python APIs use methods associated with specific objects. +
    • +
  • +For portability, the HDF5 library has its own defined types. Some common types that you will see +in the example code are: +
      +
    • +#hid_t is used for object handles +
      • +
    • +hsize_t is used for dimensions +
      • +
    • +#herr_t is used for many return values +
      • +
    +
    • +
  • +Language specific files must be included in applications: +
      +
    • +Python: Add "import h5py / import numpy" +
      • +
    • +C: Add "#include hdf5.h" +
      • +
    • +FORTRAN: Add "USE HDF5" and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface +
      • +
    • +Java: Add "import hdf.hdf5lib.H5; + import hdf.hdf5lib.HDF5Constants;" +
      • +
    +
    • +
+ +\subsection subsec_intro_pm_file Steps to create a file +To create an HDF5 file you must: +\li Specify property lists (or use the defaults). +\li Create the file. +\li Close the file (and property lists if needed). + +Example: + + + + + +
The following Python and C examples create a file, file.h5, and then close it. +The resulting HDF5 file will only contain a root group:
+\image html crtf-pic.png +
+ +Calling h5py.File with ‘w’ for the file access flag will create a new HDF5 file and overwrite +an existing file with the same name. “file” is the file handle returned from opening the file. +When finished with the file, it must be closed. When not specifying property lists, the default +property lists are used: + + + + + +
+Python +\code + import h5py + file = h5py.File (‘file.h5’, ‘w’) + file.close () +\endcode +
+ +The H5Fcreate function creates an HDF5 file. #H5F_ACC_TRUNC is the file access flag to create a new +file and overwrite an existing file with the same name, and #H5P_DEFAULT is the value specified to +use a default property list. + + + + + +
+C +\code + #include “hdf5.h” + + int main() { + hid_t file_id; + herr_t status; + + file_id = H5Fcreate ("file.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + status = H5Fclose (file_id); + } +\endcode +
+ +\subsection subsec_intro_pm_dataset Steps to create a dataset +As described previously, an HDF5 dataset consists of the raw data, as well as the metadata that +describes the data (datatype, spatial information, and properties). To create a dataset you must: +\li Define the dataset characteristics (datatype, dataspace, properties). +\li Decide which group to attach the dataset to. +\li Create the dataset. +\li Close the dataset handle from step 3. + +Example: + + + + + +
The code excerpts below show the calls that need to be made to create a 4 x 6 integer dataset dset +in a file dset.h5. The dataset will be located in the root group:
+\image html crtdset.png +
+ +With Python, the creation of the dataspace is included as a parameter in the dataset creation method. +Just one call will create a 4 x 6 integer dataset dset. A pre-defined Big Endian 32-bit integer datatype +is specified. The create_dataset method creates the dataset in the root group (the file object). +The dataset is close by the Python interface. + + + + + +
+Python +\code + dataset = file.create_dataset("dset",(4, 6), h5py.h5t.STD_I32BE) +\endcode +
+ +To create the same dataset in C, you must specify the dataspace with the #H5Screate_simple function, +create the dataset by calling #H5Dcreate, and then close the dataspace and dataset with calls to #H5Dclose +and #H5Sclose. #H5P_DEFAULT is specified to use a default property list. Note that the file identifier +(file_id) is passed in as the first parameter to #H5Dcreate, which creates the dataset in the root group. + + + + + +
+C +\code + // Create the dataspace 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, H5P_DEFAULT, H5P_DEFAULT); + + // Close the dataset and dataspace + status = H5Dclose(dataset_id); + status = H5Sclose(dataspace_id); +\endcode +
+ +\subsection subsec_intro_pm_write Writing to or reading from a dataset +Once you have created or opened a dataset you can write to it: + + + + + +
+Python +\code + data = np.zeros((4,6)) + for i in range(4): + for j in range(6): + data[i][j]= i*6+j+1 + + dataset[...] = data <-- Write data to dataset + data_read = dataset[...] <-- Read data from dataset +\endcode +
+ +#H5S_ALL is passed in for the memory and file dataspace parameters to indicate that the entire dataspace +of the dataset is specified. These two parameters can be modified to allow subsetting of a dataset. +The native predefined datatype, #H5T_NATIVE_INT, is used for reading and writing so that HDF5 will do +any necessary integer conversions: + + + + + +
+C +\code + 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); +\endcode +
+ +\subsection subsec_intro_pm_group Steps to create a group +An HDF5 group is a structure containing zero or more HDF5 objects. Before you can create a group you must +obtain the location identifier of where the group is to be created. Following are the steps that are required: +\li Decide where to put the group – in the “root group” (or file identifier) or in another group. Open the group if it is not already open. +\li Define properties or use the default. +\li Create the group. +\li Close the group. + + + + + + +
Creates attributes that are attached to the dataset dset
+\image html crtgrp.png +
+ +The code below opens the dataset dset.h5 with read/write permission and creates a group MyGroup in the root group. +Properties are not specified so the defaults are used: + + + + + +
+Python +\code + import h5py + file = h5py.File('dset.h5', 'r+') + group = file.create_group ('MyGroup') + file.close() +\endcode +
+ +To create the group MyGroup in the root group, you must call #H5Gcreate, passing in the file identifier returned +from opening or creating the file. The default property lists are specified with #H5P_DEFAULT. The group is then +closed: + + + + + +
+C +\code + group_id = H5Gcreate (file_id, "MyGroup", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + status = H5Gclose (group_id); +\endcode +
+ +\subsection subsec_intro_pm_attr Steps to create and write to an attribute +To create an attribute you must open the object that you wish to attach the attribute to. Then you can create, +access, and close the attribute as needed: +\li Open the object that you wish to add an attribute to. +\li Create the attribute +\li Write to the attribute +\li Close the attribute and the object it is attached to. + + + + + + +
Creates attributes that are attached to the dataset dset
+\image html crtatt.png +
+ +The dataspace, datatype, and data are specified in the call to create an attribute in Python: + + + + + +
+Python +\code + dataset.attrs["Units"] = “Meters per second” <-- Create string + attr_data = np.zeros((2,)) + attr_data[0] = 100 + attr_data[1] = 200 + dataset.attrs.create("Speed", attr_data, (2,), “i”) <-- Create Integer +\endcode +
+ +To create an integer attribute in C, you must create the dataspace, create the attribute, write +to it and then close it in separate steps: + + + + + +
+C +\code + hid_t 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; + + // Create the data space for the attribute. + dims = 2; + dataspace_id = H5Screate_simple(1, &dims, NULL); + + // Create a dataset attribute. + attribute_id = H5Acreate2 (dataset_id, "Units", H5T_STD_I32BE, + dataspace_id, H5P_DEFAULT, H5P_DEFAULT); + + // Write the attribute data. + status = H5Awrite(attribute_id, H5T_NATIVE_INT, attr_data); + + // Close the attribute. + status = H5Aclose(attribute_id); + + // Close the dataspace. + status = H5Sclose(dataspace_id); +\endcode +
+ +
+Navigate back: \ref index "Main" / \ref GettingStarted + + +@page HDF5Examples HDF5 Examples +Example programs of how to use HDF5 are provided below. +For HDF-EOS specific examples, see the examples +of how to access and visualize NASA HDF-EOS files using IDL, MATLAB, and NCL on the +HDF-EOS Tools and Information Center page. + +\section secHDF5Examples Examples +\li \ref LBExamples +\li Examples by API +\li Examples in the Source Code +\li Other Examples + +\section secHDF5ExamplesCompile How To Compile +For information on compiling in C, C++ and Fortran, see: \ref LBCompiling + +\section secHDF5ExamplesOther Other Examples +IDL, MATLAB, and NCL Examples for HDF-EOS +Examples of how to access and visualize NASA HDF-EOS files using IDL, MATLAB, and NCL. + +Miscellaneous Examples +These (very old) examples resulted from working with users, and are not fully tested. Most of them are in C, with a few in Fortran and Java. + +Using Special Values +These examples show how to create special values in an HDF5 application. + +*/ diff --git a/doxygen/dox/LearnBasics.dox b/doxygen/dox/LearnBasics.dox new file mode 100644 index 0000000..298672d --- /dev/null +++ b/doxygen/dox/LearnBasics.dox @@ -0,0 +1,183 @@ +/** @page LearnBasics Learning the Basics + +Navigate back: \ref index "Main" / \ref GettingStarted +
+ +\section secIntro Introduction +The following topics cover the basic features in HDF5. The topics build on each other and are +intended to be completed in order. Some sections use files created in earlier sections. The +examples used can also be found on the \ref LBExamples +page and in the HDF5 source code (C, C++, Fortran). + +\section Topics Topics +\li @subpage LBFileOrg +\li @subpage LBAPI +\li @subpage LBProg +\li @subpage LBFileCreate +\li @subpage LBDsetCreate +\li @subpage LBDsetRW +\li @subpage LBAttrCreate +\li @subpage LBGrpCreate +\li @subpage LBGrpCreateNames +\li @subpage LBGrpDset +\li @subpage LBDsetSubRW +\li @subpage LBDatatypes +\li @subpage LBPropsList +\li @subpage LBDsetLayout +\li @subpage LBExtDset +\li @subpage LBComDset +\li @subpage LBContents +\li @subpage LBQuiz +\li @subpage LBQuizAnswers +\li @subpage LBCompiling +\li @subpage LBTraining + +
+Navigate back: \ref index "Main" / \ref GettingStarted + + +@page LBExamples Examples from Learning the Basics + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBExamples +These examples are used in the \ref LearnBasics topic. See \ref LBCompiling for details on compiling them. +PLEASE NOTE that the example programs are listed in the order they are expected to be run. Some example +programs use files created in earlier examples. + +\section secLBExamplesSrc HDF5 Source Code Examples +These examples (C, C++, Fortran) are provided in the HDF5 source code and (Unix) binaries. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Feature +Examples +Comments +
Create a file +C Fortran C++ Java Python + +
Create a dataset +C Fortran C++ Java Python + +
Read and write to a dataset +C Fortran C++ Java Python + +
Create an attribute +C Fortran C++ Java Python + +
Create a group +C Fortran C++ Java Python + +
Create groups in a file using absolute and relative paths +C Fortran C++ Java Python + +
Create datasets in a group +C Fortran C++ Java Python + +
Create a file and dataset and select/read a subset from the dataset +C Fortran C++ Java Python +Also see examples to Write by row (and column) below. +
Create an extendible (unlimited dimension) dataset +C Fortran C++ Java Python +Also see examples to Extend by row (and column) below +
Create a chunked and compressed dataset +C Fortran C++ Java Python + +
+ +*See HDF5Mathematica for user-contributed +HDF5 Mathematica Wrappers and Introductory Tutorial Examples. The examples use P/Invoke. + +\section secLBExamplesAddl Additional Examples +These examples make minor changes to the tutorial examples. + + + + + + + + + + + + + + + + + + + + + +
Feature +Examples +
Write by row +C Fortran +
Write by column +C Fortran +
Extend by row +C Fortran +
Extend by column +C Fortran +
+ + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +*/ diff --git a/doxygen/dox/LearnBasics1.dox b/doxygen/dox/LearnBasics1.dox new file mode 100644 index 0000000..a9b6d0e --- /dev/null +++ b/doxygen/dox/LearnBasics1.dox @@ -0,0 +1,1023 @@ +/** @page LBFileOrg HDF5 File Organization + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBFileOrg HDF5 file +An HDF5 file is a container for storing a variety of scientific data and is composed of two primary types of objects: groups and datasets. + +\li HDF5 group: a grouping structure containing zero or more HDF5 objects, together with supporting metadata +\li HDF5 dataset: a multidimensional array of data elements, together with supporting metadata + +Any HDF5 group or dataset may have an associated attribute list. An HDF5 attribute is a user-defined HDF5 structure +that provides extra information about an HDF5 object. + +Working with groups and datasets is similar in many ways to working with directories and files in UNIX. As with UNIX +directories and files, an HDF5 object in an HDF5 file is often referred to by its full path name (also called an absolute path name). + +\li / signifies the root group. + +\li /foo signifies a member of the root group called foo. + +\li /foo/zoo signifies a member of the group foo, which in turn is a member of the root group. + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBAPI The HDF5 API + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBAPI HDF5 C API +The HDF5 library provides several interfaces, or APIs. These APIs provide routines for creating, +accessing, and manipulating HDF5 files and objects. + +The library itself is implemented in C. To facilitate the work of FORTRAN 90, C++ and Java programmers, +HDF5 function wrappers have been developed in each of these languages. This tutorial discusses the use +of the C functions and the FORTRAN wrappers. + +All C routines in the HDF5 library begin with a prefix of the form H5*, 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 h5 and end with _f. +Java routine names begin with “H5*” and are prefixed with “H5.” as the class. Constants are +in the HDF5Constants class and are prefixed with "HDF5Constants.". +The APIs are listed below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
API +DESCRIPTION +
H5 +Library Functions: general-purpose H5 functions +
H5A +Annotation Interface: attribute access and manipulation routines +
H5D +Dataset Interface: dataset access and manipulation routines +
H5E +Error Interface: error handling routines +
H5F +File Interface: file access routines +
H5G +Group Interface: group creation and operation routines +
H5I +Identifier Interface: identifier routines +
H5L +Link Interface: link routines +
H5O +Object Interface: object routines +
H5P +Property List Interface: object property list manipulation routines +
H5R +Reference Interface: reference routines +
H5S +Dataspace Interface: dataspace definition and access routines +
H5T +Datatype Interface: datatype creation and manipulation routines +
H5Z +Compression Interface: compression routine(s) +
+ +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBProg Programming Issues + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +Keep the following in mind when looking at the example programs included in this tutorial: + +\section LBProgAPI APIs vary with different languages +\li C routines begin with the prefix “H5*” where * is a single letter indicating the object on which the operation is to be performed: + + + + + + + + +
File Interface: #H5Fopen
Dataset Interface:#H5Dopen
+ +\li FORTRAN routines begin with “h5*” and end with “_f”: + + + + + + + + +
File Interface: h5fopen_f
Dataset Interface:h5dopen_f
+ +\li Java routine names begin with “H5*” and are prefixed with “H5.” as the class. Constants are +in the HDF5Constants class and are prefixed with "HDF5Constants.".: + + + + + + + + +
File Interface: H5.H5Fopen
Dataset Interface:H5.H5Dopen
+ +\li APIS for languages like C++, Java, and Python use methods associated with specific objects. + +\section LBProgTypes HDF5 library has its own defined types +\li #hid_t is used for object handles +\li hsize_t is used for dimensions +\li #herr_t is used for many return values + +\section LBProgLang Language specific files must be included in applications +
    +
  • +Python: Add "import h5py / import numpy" +
    • +
  • +C: Add "#include hdf5.h" +
    • +
  • +FORTRAN: Add "USE HDF5" and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface +
    • +
  • +Java: Add "import hdf.hdf5lib.H5; + import hdf.hdf5lib.HDF5Constants;" +
    • +
+ +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBFileCreate Creating an HDF5 File + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +An HDF5 file is a binary file containing scientific data and supporting metadata. +\section secLBFileCreate HDF5 File Access +To create an HDF5 file, an application must specify not only a file name, but a file access mode, +a file creation property list, and a file access property list. These terms are described below: +
    +
  • File access mode:
    +When creating a file, the file access mode specifies the action to take if the file already exists: +
      +
    • #H5F_ACC_TRUNC specifies that if the file already exists, the current contents will be deleted so +that the application can rewrite the file with new data. +
      • +
    • #H5F_ACC_EXCL specifies that the open will fail if the file already exists. If the file does not +already exist, the file access parameter is ignored. +
      • +
    +In either case, the application has both read and write access to the successfully created file. +
    +Note that there are two different access modes for opening existing files: +
      +
    • #H5F_ACC_RDONLY specifies that the application has read access but will not be allowed to write any data. +
      • +
    • #H5F_ACC_RDWR specifies that the application has read and write access. +
      • +
    +
    • +
  • File creation property list:
    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, #H5P_DEFAULT, is used.
    + *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. +
    • +
  • File access property list:
    The file access property list is used to +control different methods of performing I/O on files. It also can be used to control how a file +is closed (whether or not to delay the actual file close until all objects in a file are closed). +The default file access property list, #H5P_DEFAULT, is used in this tutorial. +
    • +
+ +Please refer to the \ref sec_file section of the \ref UG and \ref H5F section in the \ref RM for +detailed information regarding file access/creation property lists and access modes. + +The steps to create and close an HDF5 file are as follows: +
    +
  1. Specify the file creation and access property lists, if necessary.
    2. +
  2. Create the file.
    3. +
  3. Close the file, and if necessary, close the property lists.
    4. +
+ +\section secLBFileExample Programming Example + +\subsection subsecLBFileExampleDesc Description +The following example code demonstrates how to create and close an HDF5 file. + +C +\code +#include "hdf5.h" + #define FILE "file.h5" + + int 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); + + /* Terminate access to the file. */ + status = H5Fclose(file_id); + } +\endcode + +Fortran +\code + 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 + +! +! Initialize FORTRAN interface. +! + CALL h5open_f (error) + ! + ! 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) +! +! Close FORTRAN interface. +! + CALL h5close_f(error) + END PROGRAM FILEEXAMPLE +\endcode + +See \ref LBExamples for the examples used in the Learning the Basics tutorial. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection subsecLBFileExampleRem Remarks +\li In C: The include file hdf5.h contains definitions and declarations and must be included +in any program that uses the HDF5 library. +
+In FORTRAN: The module HDF5 contains definitions and declarations and must be used in any +program that uses the HDF5 library. Also note that #H5open MUST be called at the beginning of an HDF5 Fortran +application (prior to any HDF5 calls) to initialize the library and variables. The #H5close call MUST be at +the end of the HDF5 Fortran application. +\li #H5Fcreate creates an HDF5 file and returns the file identifier.
+For Fortran, the file creation property list and file access property list are optional. They can be omitted if the +default values are to be used.
+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 always /. +\li #H5Fclose terminates access to an HDF5 file.
+When an HDF5 file is no longer accessed by a program, #H5Fclose must be called to release the resources used by the file. +This call is mandatory.
+Note that if #H5Fclose is called for a file, but one or more objects within the file remain open, those objects will +remain accessible until they are individually closed. This can cause access problems for other users, if objects were +inadvertently left open. A File Access property controls how the file is closed. + +\subsection subsecLBFileExampleCont File Contents +The HDF Group has developed tools for examining the contents of HDF5 files. The tool used throughout the HDF5 tutorial +is the HDF5 dumper, h5dump, which displays the file contents in human-readable form. The output of h5dump is an ASCII +display formatted according to the HDF5 DDL grammar. This grammar is defined, using Backus-Naur Form, in the +\ref DDLBNF110. + +To view the HDF5 file contents, simply type: +\code +h5dump +\endcode + + + + + + +
Describe the file contents of file.h5 using a directed graph.
+\image html imgLBFile.gif +
+ +The text description of file.h5, as generated by h5dump. The HDF5 file called file.h5 +contains a group called /, or the root group. (The file called filef.h5, created by the FORTRAN version of the example, +has the same output except that the filename shown is filef.h5.) +\code +HDF5 "file.h5" { + GROUP "/" { + } + } +\endcode + +\subsection subsecLBFileExampleDDL File Definition in DDL +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 \ref DDLBNF110. + +The following symbol definitions are used in the DDL: +\code + ::= defined as + a token with the name tname + | one of or + * zero or more occurrences of +\endcode + +The simplified DDL for file definition is as follows: +\code + ::= HDF5 "" { } + + ::= GROUP "/" { * + * } + + ::= + + ::= | +\endcode + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBDsetCreate Creating a Dataset +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +A dataset is a multidimensional array of data elements, together with supporting metadata. To create +a dataset, the application program must specify the location at which to create the dataset, the +dataset name, the datatype and dataspace of the data array, and the property lists. + +\section secLBDsetCreateDtype Datatypes +A datatype is a collection of 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 datatype. + +There are two categories of datatypes in HDF5: +
    +
  • Pre-defined: These datatypes are opened and closed by HDF5.
    +Pre-defined datatypes can be atomic or composite: +
    • Atomic datatypes cannot be decomposed into smaller datatype units at the API level. For example: integer, float, reference, string.
      • +
    • Composite datatypes are aggregations of one or more datatypes. For example: array, variable length, enumeration, compound.
    +
    • +
  • Derived: These datatypes are created or derived from the pre-defined types.
    +A simple example of creating a derived datatype is using the string datatype, H5T_C_S1, to create strings of more than one character:
    +\code + hid_t strtype; // Datatype ID + herr_t status; + + strtype = H5Tcopy (H5T_C_S1); + status = H5Tset_size (strtype, 5); // create string of length 5 +\endcode +
    • +
+ +Shown below is the HDF5 pre-defined datatypes. +\code + +-- integer + +-- floating point + +---- atomic ----+-- date and time + | +-- character string + HDF5 datatypes --| +-- bitfield + | +-- opaque + | + +---- compound +\endcode + +Some of the HDF5 predefined atomic datatypes are listed below. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Examples of HDF5 predefined datatypes
DatatypeDescription
H5T_STD_I32LEFour-byte, little-endian, signed, two's complement integer
H5T_STD_U16BETwo-byte, big-endian, unsigned integer
H5T_IEEE_F32BEFour-byte, big-endian, IEEE floating point
H5T_IEEE_F64LEEight-byte, little-endian, IEEE floating point
H5T_C_S1One-byte, null-terminated string of eight-bit characters
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Examples of HDF5 predefined native datatypes
Native DatatypeCorresponding C or FORTRAN Type
C
H5T_NATIVE_INTint
H5T_NATIVE_FLOATfloat
H5T_NATIVE_CHARchar
H5T_NATIVE_DOUBLEdouble
H5T_NATIVE_LDOUBLElong double
Fortran
H5T_NATIVE_INTEGERinteger
H5T_NATIVE_REALreal
H5T_NATIVE_DOUBLEdouble precision
H5T_NATIVE_CHARACTERcharacter
+ +In this tutorial, we consider only HDF5 predefined integers. + +For further information on datatypes, see \ref sec_datatype in the \ref UG, in addition to the \ref LBDatatypes tutorial topic. + +\section secLBDsetCreateDspace Datasets and Dataspaces +A dataspace describes the dimensionality of the data array. A dataspace is either a regular N-dimensional +array of data points, called a simple dataspace, or a more general collection of data points organized +in another manner, called a complex dataspace. In this tutorial, we only consider simple dataspaces. + +HDF5 dataspaces +\code + +-- simple + HDF5 dataspaces --| + +-- complex +\endcode +The dimensions of a dataset can be fixed (unchanging), or they may be 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. + +\section secLBDsetCreateProp Property Lists +Property lists are a mechanism for modifying the default behavior when creating or accessing objects. For +more information on property lists see the \ref LBPropsList tutorial topic. + +The following property lists can be specified when creating a dataset: +\li Dataset Creation Property List
+When creating a dataset, HDF5 allows the user to specify how raw data is organized and/or compressed on +disk. This information is stored in a dataset creation property list and passed to the dataset interface. +The raw data on disk can be stored contiguously (in the same linear way that it is organized in memory), +partitioned into chunks, stored externally, etc. In this tutorial, we use the default dataset creation +property list (contiguous storage layout and no compression). For more information about dataset creation +property lists, see \ref sec_dataset in the \ref UG. +\li Link Creation Property List
+The link creation property list governs creation of the link(s) by which a new dataset is accessed and the +creation of any intermediate groups that may be missing. +\li Dataset Access Property List
+Dataset access property lists are properties that can be specified when accessing a dataset. + +\section secLBDsetCreateSteps Steps to Create a Dataset +To create an empty dataset (no data written) the following steps need to be taken: +
    +
  1. Obtain the location identifier where the dataset is to be created.
    2. +
  2. Define or specify the dataset characteristics: +
      +
    1. Define a datatype or specify a pre-defined datatype.
      2. +
    2. Define a dataspace.
      3. +
    3. Specify the property list(s) or use the default.
      4. +
    3. +
  3. Create the dataset.
    4. +
  4. Close the datatype, the dataspace, and the property list(s) if necessary.
    5. +
  5. Close the dataset.
    6. +
+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 the definition of +the datatype and dataspace. In this tutorial, we use the HDF5 predefined datatypes (integer) and consider +only simple dataspaces. Hence, only the creation of dataspace objects is needed. + +\section secLBDsetCreateHL High Level APIs +The High Level \ref H5LT include functions that simplify and condense the steps for +creating datasets in HDF5. The examples in the following section use the standard APIs. For a +quick start you may prefer to look at the \ref H5LT at this time. + +If you plan to work with images, please look at the High Level \ref H5IM, as well. + +\section secLBDsetCreateProg Programming Example + +\subsection subsecLBDsetCreateProgDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example shows how to create an empty dataset. It creates a file called dset.h5 +in the C version (dsetf.h5 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. + +For details on compiling an HDF5 application: [ \ref LBCompiling ] + +\subsection subsecLBDsetCreateProgRem Remarks +#H5Screate_simple creates a new simple dataspace and returns a dataspace identifier. +#H5Sclose releases and terminates access to a dataspace. + +C +\code + dataspace_id = H5Screate_simple (rank, dims, maxdims); + status = H5Sclose (dataspace_id ); +\endcode + +FORTRAN +\code + CALL h5screate_simple_f (rank, dims, dataspace_id, hdferr, maxdims=max_dims) + or + CALL h5screate_simple_f (rank, dims, dataspace_id, hdferr) + + CALL h5sclose_f (dataspace_id, hdferr) +\endcode + +#H5Dcreate creates an empty dataset at the specified location and returns a dataset identifier. +#H5Dclose closes the dataset and releases the resource used by the dataset. This call is mandatory. + +C +\code + dataset_id = H5Dcreate(file_id, "/dset", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + status = H5Dclose (dataset_id); +\endcode + +FORTRAN +\code + CALL h5dcreate_f (loc_id, name, type_id, dataspace_id, dset_id, hdferr) + CALL h5dclose_f (dset_id, hdferr) +\endcode + +Note that if using the pre-defined datatypes in FORTRAN, then a call must be made to initialize and terminate access to the pre-defined datatypes: +\code + CALL h5open_f (hdferr) + CALL h5close_f (hdferr) +\endcode + +H5open must be called before any HDF5 library subroutine calls are made; +H5close must be called after the final HDF5 library subroutine call. + +See the programming example for an illustration of the use of these calls. + +\subsection subsecLBDsetCreateContent File Contents +The contents of the file dset.h5 (dsetf.h5 for FORTRAN) are shown below: + + + + + +
Contents of dset.h5 ( dsetf.h5)
+\image html imgLBDsetCreate.gif +
+ + + + + + + + +
dset.h5 in DDLdsetf.h5 in DDL
+\code +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 + } + } +} +} +\endcode + +\code +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 + } + } +} +} +\endcode +
+Note in above that #H5T_STD_I32BE, a 32-bit Big Endian integer, is an HDF atomic datatype. + +\subsection subsecLBDsetCreateProgDDL Dataset Definition in DDL +The following is the simplified DDL dataset definition: +\code + ::= DATASET "" { + + + * } + + ::= DATATYPE { } + + ::= DATASPACE { SIMPLE / } + + ::= +\endcode + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBDsetRW Reading From and Writing To a Dataset +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBDsetRW Dataset I/O Operation +During a dataset I/O operation, the library transfers raw data between memory 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: +\li The dataset +\li The dataset's datatype in memory +\li The dataset's dataspace in memory +\li The dataset's dataspace in the file +\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 + +The steps to read from or write to a dataset are as follows: +
    +
  1. Obtain the dataset identifier.
    2. +
  2. Specify the memory datatype.
    3. +
  3. Specify the memory dataspace.
    4. +
  4. Specify the file dataspace.
    5. +
  5. Specify the transfer properties.
    6. +
  6. Perform the desired operation on the dataset.
    7. +
  7. Close the dataset.
    8. +
  8. Close the dataspace, datatype, and property list if necessary.
    9. +
+ +To read from or write to a dataset, the #H5Dread and #H5Dwrite routines are used. + +C +\code + status = H5Dread (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf ); + status = H5Dwrite (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf); +\endcode + +Fortran +\code + CALL h5dread_f(dset_id, mem_type_id, buf, dims, error, & + mem_space_id=mspace_id, file_space_id=fspace_id, & + xfer_prp=xfer_plist_id) + or + CALL h5dread_f(dset_id, mem_type_id, buf, dims, error) + + + CALL h5dwrite_f(dset_id, mem_type_id, buf, dims, error, & + mem_space_id=mspace_id, file_space_id=fspace_id, & + xfer_prp=xfer_plist_id) + or + CALL h5dwrite_f(dset_id, mem_type_id, buf, dims, error) +\endcode + +\section secLBDsetRWHL High Level APIs +The High Level \ref H5LT include functions that simplify and condense the steps for creating and +reading datasets. Please be sure to review them, in addition to this tutorial. + +\section secLBDsetRWEx Programming Example + +\subsection secLBDsetRWExDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example shows how to read and write an existing dataset. It opens the file created in the previous example, +obtains the dataset identifier for the dataset /dset, writes the dataset to the file, then reads +the dataset back. It then closes the dataset and file. + +Note that #H5S_ALL is passed in for both the memory and file dataspace parameters in the read and write calls. +This indicates that the entire dataspace of the dataset will be read or written to. #H5S_ALL by itself does not +necessarily have this meaning. See the \ref RM entry for #H5Dread or #H5Dwrite for more information on using #H5S_ALL. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection secLBDsetRWExRem Remarks +#H5Fopen opens an existing file and returns a file identifier. + +#H5Dopen opens an existing dataset with the specified name and location. + +#H5Dwrite 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. Specifying #H5S_ALL +for both the memory and file dataspaces indicates that the entire dataspace of the dataset is to be written to. +#H5S_ALL by itself does not necessarily have this meaning. See the \ref RM entry for #H5Dwrite for more information +on using #H5S_ALL. + +#H5Dread reads raw data from the specified dataset to an application buffer, converting from the file datatype and +dataspace to the memory datatype and dataspace. Specifying #H5S_ALL for both the memory and file dataspaces +indicates that the entire dataspace of the dataset is to be read. #H5S_ALL by itself does not necessarily have +this meaning. See the \ref RM entry for #H5Dread for more information on using #H5S_ALL. + +\subsection secLBDsetRWExCont File Contents + +Shown below is the contents of dset.h5 (created by the C program). + +dset.h5 in DDL +\code + 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 + } + } + } + } +\endcode + +Shown below is the contents of dsetf.h5 (created by the FORTRAN program). + +dsetf.h5 in DDL +\code + 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 + } + } + } + } +\endcode + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBAttrCreate Creating an Attribute +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +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, read, and write an attribute. + +\section secLBAttrCreate Creating an attribute +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. + +The steps to create an attribute are as follows: +
    +
  1. Obtain the object identifier that the attribute is to be attached to.
    2. +
  2. Define the characteristics of the attribute and specify the attribute creation property list. +
      +
    • Define the datatype.
      • +
    • Define the dataspace.
      • +
    • Specify the attribute creation property list.
      • +
    3. +
  3. Create the attribute.
    4. +
  4. Close the attribute and datatype, dataspace, and attribute creation property list, if necessary.
    5. +
+ +To create and close an attribute, the calling program must use #H5Acreate and #H5Aclose. For example: + +C +\code + attr_id = H5Acreate (dataset_id, "Units", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT, H5P_DEFAULT) + status = H5Aclose (attr_id); +\endcode + +Fortran +\code + CALL h5acreate_f (dset_id, attr_nam, type_id, space_id, attr_id, & + hdferr, creation_prp=creat_plist_id) + or + CALL h5acreate_f (dset_id, attr_nam, type_id, space_id, attr_id, hdferr) + + CALL h5aclose_f (attr_id, hdferr) +\endcode + +\section secLBAttrCreateRW Reading/Writing an attribute +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 datatype. + +The steps to read or write an attribute are as follows. +
    +
  1. Obtain the attribute identifier.
    2. +
  2. Specify the attribute's memory datatype.
    3. +
  3. Perform the desired operation.
    4. +
  4. Close the memory datatype if necessary.
    5. +
+ +To read and/or write an attribute, the calling program must contain the #H5Aread and/or +#H5Awrite routines. For example: + +C +\code + status = H5Aread (attr_id, mem_type_id, buf); + status = H5Awrite (attr_id, mem_type_id, buf); +\endcode + +Fortran +\code + CALL h5awrite_f (attr_id, mem_type_id, buf, dims, hdferr) + CALL h5aread_f (attr_id, mem_type_id, buf, dims, hdferr) +\endcode + +\section secLBAttrCreateHL High Level APIs +The High Level \ref H5LT include functions that simplify and condense the steps for creating and +reading datasets. Please be sure to review them, in addition to this tutorial. + +\section secLBAttrCreateRWEx Programming Example + +\subsection secLBAttrCreateRWExDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example shows how to create and write a dataset attribute. It opens an existing file dset.h5 +in C (dsetf.h5 in FORTRAN), obtains the identifier of the dataset /dset, defines +the attribute's dataspace, creates the dataset attribute, writes the attribute, and then closes the attribute's +dataspace, attribute, dataset, and file. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection secLBAttrCreateRWExRem Remarks +#H5Acreate creates an attribute which is attached to the object specified by the first parameter, and returns an identifier. + +#H5Awrite writes the entire attribute, and returns the status of the write. + +When an attribute is no longer accessed by a program, #H5Aclose must be called to release the attribute from use. +An #H5Aclose/h5aclose_f call is mandatory. + +\subsection secLBAttrCreateRWExCont File Contents + +Shown below is the contents and the attribute definition of dset.h5 (created by the C program). + +dset.h5 in DDL +\code +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 + } +} +} +} +} +\endcode + +Shown below is the contents and the attribute definition of dsetf.h5 (created by the FORTRAN program). + +dsetf.h5 in DDL +\code +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 + } +} +} +} +} +\endcode + +\subsection secLBAttrCreateRWExDDL Attribute Definition in DDL + +HDF5 Attribute Definition +\code + ::= ATTRIBUTE "" { + + } +\endcode + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +*/ diff --git a/doxygen/dox/LearnBasics2.dox b/doxygen/dox/LearnBasics2.dox new file mode 100644 index 0000000..ffcb971 --- /dev/null +++ b/doxygen/dox/LearnBasics2.dox @@ -0,0 +1,1159 @@ +/** @page LBGrpCreate Creating an Group +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBGrpCreate Creating an group +An HDF5 group is a structure containing zero or more HDF5 objects. The two primary HDF5 objects are groups and datasets. To create a group, the calling program must: +
    +
  1. Obtain the location identifier where the group is to be created.
    2. +
  2. Create the group.
    3. +
  3. Close the group.
    4. +
+ +To create a group, the calling program must call #H5Gcreate. +To close the group, #H5Gclose must be called. The close call is mandatory. + +For example: + +C +\code + group_id = H5Gcreate(file_id, "/MyGroup", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + status = H5Gclose (group_id); +\endcode + +Fortran +\code + CALL h5gcreate_f (loc_id, name, group_id, error) + CALL h5gclose_f (group_id, error) +\endcode + +\section secLBGrpCreateRWEx Programming Example + +\subsection secLBGrpCreateRWExDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example shows how to create and close a group. It creates a file called group.h5 in C +(groupf.h5 for FORTRAN), creates a group called MyGroup in the root group, and then closes the group and file. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection secLBGrpCreateRWExCont File Contents + +Shown below is the contents and the definition of the group of group.h5 (created by the C program). +(The FORTRAN program creates the HDF5 file groupf.h5 and the resulting DDL shows the filename +groupf.h5 in the first line.) + + + + + +
The Contents of group.h5.
+\image html imggrpcreate.gif +
+ +group.h5 in DDL +\code +HDF5 "group.h5" { +GROUP "/" { + GROUP "MyGroup" { + } +} +} +\endcode + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBGrpCreateNames Creating Groups using Absolute and Relative Names +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +Recall that to create an HDF5 object, we have to specify the location where the object is to be created. +This location is determined by the identifier of an HDF5 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 the previous example, we used the file identifier and the absolute name /MyGroup to create a group. + +In this section, we discuss HDF5 names and show how to use absolute and relative names. + +\section secLBGrpCreateNames Names +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 may be composed of any number of component names separated by slashes, with any of the component +names being the special name . (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. A special case is the name / (or equivalent) which +refers to the root group. + +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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Location TypeObject NameDescription
File identifier/foo/barThe object bar in group foo in the root group.
Group identifier/foo/barThe object bar in group foo 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.
File identifier/The root group of the specified file.
Group identifier/The root group of the file containing the specified group.
Group identifierfoo/barThe object bar in group foo in the specified group.
File identifier.The root group of the file.
Group identifier.The specified group.
Other identifier.The specified object.
+ +\section secLBGrpCreateNamesEx Programming Example + +\subsection secLBGrpCreateNamesExDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The 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 while the third group is created using a group identifier and a name relative to the specified group. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection secLBGrpCreateNamesExRem Remarks +#H5Gcreate 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. + +The first #H5Gcreate/h5gcreate_f creates the group MyGroup in the root group of the specified file. + +The second #H5Gcreate/h5gcreate_f 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. + +The third #H5Gcreate/h5gcreate_f creates the group Group_B in the specified group. + +\subsection secLBGrpCreateNamesExCont File Contents + +Shown below is the contents and the definition of the group of groups.h5 (created by the C program). +(The FORTRAN program creates the HDF5 file groupsf.h5 and the resulting DDL shows the filename +groupsf.h5 in the first line.) + + + + + +
The Contents of groups.h5.
+\image html imggrps.gif +
+ +groups.h5 in DDL +\code +HDF5 "groups.h5" { +GROUP "/" { + GROUP "MyGroup" { + GROUP "Group_A" { + } + GROUP "Group_B" { + } + } +} +} +\endcode + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBGrpDset Creating Datasets in Groups +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBGrpDset Datasets in Groups +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 refer to a group, then the dataset is created in that group. + +\section secLBGrpDsetEx Programming Example + +\subsection secLBGrpDsetExDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example shows how to create a dataset in a particular group. It opens the file created in the previous example and creates two datasets: + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection secLBGrpDsetExCont File Contents + +Shown below is the contents and the definition of the group of groups.h5 (created by the C program). +(The FORTRAN program creates the HDF5 file groupsf.h5 and the resulting DDL shows the filename +groupsf.h5 in the first line.) + + + + + +
The contents of the file groups.h5 (groupsf.h5 for FORTRAN)
+\image html imggrpdsets.gif +
+ +groups.h5 in DDL +\code +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 + } +} +} +} +} +\endcode + +groupsf.h5 in DDL +\code +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 + } +} +} +} +} +\endcode + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBDsetSubRW Reading From or Writing To a Subset of a Dataset +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBDsetSubRW Dataset Subsets +There are two ways that you can select a subset in an HDF5 dataset and read or write to it: +
  • +Hyperslab Selection: The #H5Sselect_hyperslab call selects a logically contiguous +collection of points in a dataspace, or a regular pattern of points or blocks in a dataspace. +
  • +Element Selection: The #H5Sselect_elements call selects elements in an array. +
+ +HDF5 allows you to read from or write to a portion or subset of a dataset by: +\li Selecting a Subset of the Dataset's Dataspace, +\li Selecting a Memory Dataspace, +\li Reading From or Writing to a Dataset Subset. + +\section secLBDsetSubRWSel Selecting a Subset of the Dataset's Dataspace +First you must obtain the dataspace of a dataset in a file by calling #H5Dget_space. + +Then select a subset of that dataspace by calling #H5Sselect_hyperslab. The offset, count, stride +and block parameters of this API define the shape and size of the selection. They must be arrays +with the same number of dimensions as the rank of the dataset's dataspace. These arrays ALL work +together to define a selection. A change to one of these arrays can affect the others. +\li \em offset: An array that specifies the offset of the starting element of the specified hyperslab. +\li \em count: An array that determines how many blocks to select from the dataspace in each dimension. If the block +size for a dimension is one then the count is the number of elements along that dimension. +\li \em stride: An array that allows you to sample elements along a dimension. For example, a stride of one (or NULL) +will select every element along a dimension, a stride of two will select every other element, and a stride of three +will select an element after every two elements. +\li \em block: An array that determines the size of the element block selected from a dataspace. If the block size +is one or NULL then the block size is a single element in that dimension. + +\section secLBDsetSubRWMem Selecting a Memory Dataspace +You must select a memory dataspace in addition to a file dataspace before you can read a subset from or write a subset +to a dataset. A memory dataspace can be specified by calling #H5Screate_simple. + +The memory dataspace passed to the read or write call must contain the same number of elements as the file dataspace. +The number of elements in a dataspace selection can be determined with the #H5Sget_select_npoints API. + +\section secLBDsetSubRWSub Reading From or Writing To a Dataset Subset +To read from or write to a dataset subset, the #H5Dread and #H5Dwrite routines are used. The memory and file dataspace +identifiers from the selections that were made are passed into the read or write call. For example (C): +\code + status = H5Dwrite (.., .., memspace_id, dataspace_id, .., ..); +\endcode + +\section secLBDsetSubRWProg Programming Example + +\subsection subsecLBDsetSubRWProgDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example creates an 8 x 10 integer dataset in an HDF5 file. It then selects and writes to a 3 x 4 subset +of the dataset created with the dimensions offset by 1 x 2. (If using Fortran, the dimensions will be swapped. +The dataset will be 10 x 8, the subset will be 4 x 3, and the offset will be 2 x 1.) + +PLEASE NOTE that the examples and images below were created using C. + +The following image shows the dataset that gets written originally, and the subset of data that gets modified +afterwards. Dimension 0 is vertical and Dimension 1 is horizontal as shown below: + + + + +
+\image html LBDsetSubRWProg.png +
+ +The subset on the right above is created using these values for offset, count stride, and block: +\code +offset = {1, 2} + +count = {3, 4} + +stride = {1, 1} + +block = {1, 1} +\endcode + +\subsection subsecLBDsetSubRWProgExper Experiments with Different Selections +Following are examples of changes that can be made to the example code provided to better understand +how to make selections. + +\subsubsection subsubsecLBDsetSubRWProgExperOne Example 1 +By default the example code will select and write to a 3 x 4 subset. You can modify the count +parameter in the example code to select a different subset, by changing the value of +DIM0_SUB (C, C++) / dim0_sub (Fortran) near the top. Change its value to 7 to create a 7 x 4 subset: + + + + +
+\image html imgLBDsetSubRW11.png +
+ +If you were to change the subset to 8 x 4, the selection would be beyond the extent of the dimension: + + + + +
+\image html imgLBDsetSubRW12.png +
+ +The write will fail with the error: "file selection+offset not within extent" + +\subsubsection subsubsecLBDsetSubRWProgExperTwo Example 2 +In the example code provided, the memory and file dataspaces passed to the H5Dwrite call have the +same size, 3 x 4 (DIM0_SUB x DIM1_SUB). Change the size of the memory dataspace to be 4 x 4 so that +they do not match, and then compile: +\code + dimsm[0] = DIM0_SUB + 1; + dimsm[1] = DIM1_SUB; + memspace_id = H5Screate_simple (RANK, dimsm, NULL); +\endcode +The code will fail with the error: "src and dest data spaces have different sizes" + +How many elements are in the memory and file dataspaces that were specified above? Add these lines: +\code + hssize_t size; + + /* Just before H5Dwrite call the following */ + size = H5Sget_select_npoints (memspace_id); + printf ("\nmemspace_id size: %i\n", size); + size = H5Sget_select_npoints (dataspace_id); + printf ("dataspace_id size: %i\n", size); +\endcode + +You should see these lines followed by the error: +\code + memspace_id size: 16 + dataspace_id size: 12 +\endcode + +\subsubsection subsubsecLBDsetSubRWProgExperThree Example 3 +This example shows the selection that occurs if changing the values of the offset, count, +stride and block parameters in the example code. + +This will select two blocks. The count array specifies the number of blocks. The block array +specifies the size of a block. The stride must be modified to accommodate the block size. + + + + +
+\image html imgLBDsetSubRW31.png +
+ +Now try modifying the count as shown below. The write will fail because the selection goes beyond the extent of the dimension: + + + + +
+\image html imgLBDsetSubRW32.png +
+ +If the offset were 1x1 (instead of 1x2), then the selection can be made: + + + + +
+\image html imgLBDsetSubRW33.png +
+ +The selections above were tested with the +h5_subsetbk.c +example code. The memory dataspace was defined as one-dimensional. + +\subsection subsecLBDsetSubRWProgRem Remarks +\li In addition to #H5Sselect_hyperslab, this example introduces the #H5Dget_space call to obtain the dataspace of a dataset. +\li If using the default values for the stride and block parameters of #H5Sselect_hyperslab, then, for C you can specify NULL +for these parameters, rather than passing in an array for each, and for Fortran 90 you can omit these parameters. + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBDatatypes Datatype Basics +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBDtype What is a Datatype? +A datatype is a collection of datatype properties which provide complete information for data conversion to or from that datatype. + +Datatypes in HDF5 can be grouped as follows: +\li Pre-Defined Datatypes: These are datatypes that are created by HDF5. They are actually opened +(and closed) by HDF5, and can have a different value from one HDF5 session to the next. +\li Derived Datatypes: These are datatypes that are created or derived from the pre-defined datatypes. +Although created from pre-defined types, they represent a category unto themselves. An example of a commonly used derived +datatype is a string of more than one character. + +\section secLBDtypePre Pre-defined Datatypes +The properties of pre-defined datatypes are: +\li Pre-defined datatypes are opened and closed by HDF5. +\li A pre-defined datatype is a handle and is NOT PERSISTENT. Its value can be different from one HDF5 session to the next. +\li Pre-defined datatypes are Read-Only. +\li As mentioned, other datatypes can be derived from pre-defined datatypes. + +There are two types of pre-defined datatypes, standard (file) and native. + +

Standard

+A standard (or file) datatype can be: +
    +
  • Atomic: A datatype which cannot be decomposed into smaller datatype units at the API level. +The atomic datatypes are: +
      +
    • integer
      • +
    • float
      • +
    • string (1-character)
      • +
    • date and time
      • +
    • bitfield
      • +
    • reference
      • +
    • opaque
      • +
    +
    • +
  • Composite: An aggregation of one or more datatypes. +Composite datatypes include: +
      +
    • array
      • +
    • variable length
      • +
    • enumeration
      • +
    • compound datatypes
      • +
    +Array, variable length, and enumeration datatypes are defined in terms of a single atomic datatype, +whereas a compound datatype is a datatype composed of a sequence of datatypes. +
    • +
+ + + + + + + + +
Notes
+\li Standard pre-defined datatypes are the SAME on all platforms. +\li They are the datatypes that you see in an HDF5 file. +\li They are typically used when creating a dataset. +
+ +

Native

+Native pre-defined datatypes are used for memory operations, such as reading and writing. They are +NOT THE SAME on different platforms. They are similar to C type names, and are aliased to the +appropriate HDF5 standard pre-defined datatype for a given platform. + +For example, when on an Intel based PC, #H5T_NATIVE_INT is aliased to the standard pre-defined type, +#H5T_STD_I32LE. On a MIPS machine, it is aliased to #H5T_STD_I32BE. + + + + + + + +
Notes
+\li Native datatypes are NOT THE SAME on all platforms. +\li Native datatypes simplify memory operations (read/write). The HDF5 library automatically converts as needed. +\li Native datatypes are NOT in an HDF5 File. The standard pre-defined datatype that a native datatype corresponds +to is what you will see in the file. +
+ +

Pre-Defined

+The following table shows the native types and the standard pre-defined datatypes they correspond +to. (Keep in mind that HDF5 can convert between datatypes, so you can specify a buffer of a larger +type for a dataset of a given type. For example, you can read a dataset that has a short datatype +into a long integer buffer.) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Some HDF5 pre-defined native datatypes and corresponding standard (file) type
C TypeHDF5 Memory TypeHDF5 File Type*
Integer
int#H5T_NATIVE_INT#H5T_STD_I32BE or #H5T_STD_I32LE
short#H5T_NATIVE_SHORT#H5T_STD_I16BE or #H5T_STD_I16LE
long#H5T_NATIVE_LONG#H5T_STD_I32BE, #H5T_STD_I32LE, + #H5T_STD_I64BE or #H5T_STD_I64LE
long long#H5T_NATIVE_LLONG#H5T_STD_I64BE or #H5T_STD_I64LE
unsigned int#H5T_NATIVE_UINT#H5T_STD_U32BE or #H5T_STD_U32LE
unsigned short#H5T_NATIVE_USHORT#H5T_STD_U16BE or #H5T_STD_U16LE
unsigned long#H5T_NATIVE_ULONG#H5T_STD_U32BE, #H5T_STD_U32LE, + #H5T_STD_U64BE or #H5T_STD_U64LE
unsigned long long#H5T_NATIVE_ULLONG#H5T_STD_U64BE or #H5T_STD_U64LE
Float
float#H5T_NATIVE_FLOAT#H5T_IEEE_F32BE or #H5T_IEEE_F32LE
double#H5T_NATIVE_DOUBLE#H5T_IEEE_F64BE or #H5T_IEEE_F64LE
+ + + + + + + + + + + + + + + + + + + + + + + +
Some HDF5 pre-defined native datatypes and corresponding standard (file) type
F90 TypeHDF5 Memory TypeHDF5 File Type*
integerH5T_NATIVE_INTEGER#H5T_STD_I32BE(8,16) or #H5T_STD_I32LE(8,16)
realH5T_NATIVE_REAL#H5T_IEEE_F32BE or #H5T_IEEE_F32LE
double-precision#H5T_NATIVE_DOUBLE#H5T_IEEE_F64BE or #H5T_IEEE_F64LE
+ + + + + +
* Note that the HDF5 File Types listed are those that are most commonly created. + The file type created depends on the compiler switches and platforms being + used. For example, on the Cray an integer is 64-bit, and using #H5T_NATIVE_INT (C) + or H5T_NATIVE_INTEGER (F90) would result in an #H5T_STD_I64BE file type.
+ +The following code is an example of when you would use standard pre-defined datatypes vs. native types: +\code + #include "hdf5.h" + + main() { + + hid_t file_id, dataset_id, dataspace_id; + herr_t status; + hsize_t dims[2]={4,6}; + int i, j, dset_data[4][6]; + + for (i = 0; i < 4; i++) + for (j = 0; j < 6; j++) + dset_data[i][j] = i * 6 + j + 1; + + file_id = H5Fcreate ("dtypes.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + + dataspace_id = H5Screate_simple (2, dims, NULL); + + dataset_id = H5Dcreate (file_id, "/dset", H5T_STD_I32BE, dataspace_id, + H5P_DEFAULT); + + status = H5Dwrite (dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, + H5P_DEFAULT, dset_data); + + status = H5Dclose (dataset_id); + + status = H5Fclose (file_id); + } +\endcode +By using the native types when reading and writing, the code that reads from or writes to a dataset +can be the same for different platforms. + +Can native types also be used when creating a dataset? Yes. However, just be aware that the resulting +datatype in the file will be one of the standard pre-defined types and may be different than expected. + +What happens if you do not use the correct native datatype for a standard (file) datatype? Your data +may be incorrect or not what you expect. + +\section secLBDtypeDer Derived Datatypes +ANY pre-defined datatype can be used to derive user-defined datatypes. + +To create a datatype derived from a pre-defined type: +
    +
  1. Make a copy of the pre-defined datatype: +\code + tid = H5Tcopy (H5T_STD_I32BE); +\endcode +
    2. +
  2. Change the datatype.
    3. +
+ +There are numerous datatype functions that allow a user to alter a pre-defined datatype. See +\ref subsecLBDtypeSpecStr below for a simple example. + +Refer to the \ref H5T in the \ref RM. Example functions are #H5Tset_size and #H5Tset_precision. + +\section secLBDtypeSpec Specific Datatypes +On the Examples by API +page under Datatypes +you will find many example programs for creating and reading datasets with different datatypes. + +Below is additional information on some of the datatypes. See +the Examples by API +page for examples of these datatypes. + +\subsection subsecLBDtypeSpec Array Datatype vs Array Dataspace +#H5T_ARRAY is a datatype, and it should not be confused with the dataspace of a dataset. The dataspace +of a dataset can consist of a regular array of elements. For example, the datatype for a dataset +could be an atomic datatype like integer, and the dataset could be an N-dimensional appendable array, +as specified by the dataspace. See #H5Screate and #H5Screate_simple for details. + +Unlimited dimensions and subsetting are not supported when using the #H5T_ARRAY datatype. + +The #H5T_ARRAY datatype was primarily created to address the simple case of a compound datatype +when all members of the compound datatype are of the same type and there is no need to subset by +compound datatype members. Creation of such a datatype is more efficient and I/O also requires +less work, because there is no alignment involved. + +\subsection subsecLBDtypeSpecArr Array Datatype +The array class of datatypes, #H5T_ARRAY, allows the construction of true, homogeneous, +multi-dimensional arrays. Since these are homogeneous arrays, each element of the array +will be of the same datatype, designated at the time the array is created. + +Users may be confused by this datatype, as opposed to a dataset with a simple atomic +datatype (eg. integer) that is an array. See subsecLBDtypeSpec for more information. + +Arrays can be nested. Not only is an array datatype used as an element of an HDF5 dataset, +but the elements of an array datatype may be of any datatype, including another array datatype. + +Array datatypes cannot be subdivided for I/O; the entire array must be transferred from one +dataset to another. + +Within certain limitations, outlined in the next paragraph, array datatypes may be N-dimensional +and of any dimension size. Unlimited dimensions, however, are not supported. Functionality similar +to unlimited dimension arrays is available through the use of variable-length datatypes. + +The maximum number of dimensions, i.e., the maximum rank, of an array datatype is specified by +the HDF5 library constant #H5S_MAX_RANK. The minimum rank is 1 (one). All dimension sizes must +be greater than 0 (zero). + +One array datatype may only be converted to another array datatype if the number of dimensions +and the sizes of the dimensions are equal and the datatype of the first array's elements can be +converted to the datatype of the second array's elements. + +\subsubsection subsubsecLBDtypeSpecArrAPI Array Datatype APIs +There are three functions that are specific to array datatypes: one, #H5Tarray_create, for creating +an array datatype, and two, #H5Tget_array_ndims and #H5Tget_array_dims +for working with existing array datatypes. + +

Creating

+The function #H5Tarray_create creates a new array datatype object. Parameters specify +\li the base datatype of each element of the array, +\li the rank of the array, i.e., the number of dimensions, +\li the size of each dimension, and +\li the dimension permutation of the array, i.e., whether the elements of the array are listed in C or FORTRAN order. + +

Working with existing array datatypes

+When working with existing arrays, one must first determine the the rank, or number of dimensions, of the array. + +The function #H5Tget_array_dims returns the rank of a specified array datatype. + +In many instances, one needs further information. The function #H5Tget_array_dims retrieves the +permutation of the array and the size of each dimension. + +\subsection subsecLBDtypeSpecCmpd Compound + +\subsubsection subsubsecLBDtypeSpecCmpdProp Properties of compound datatypes +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 of a compound datatype +you need to refer to various properties of the data compound datatype: +\li It is of class compound. +\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 datatype. +\li Each member is referenced by an index number between zero and N-1, where N is the number of members in the compound datatype. +\li Each member has a name which is unique among its siblings in a compound datatype. +\li Each member has a fixed byte offset, which is the first byte (smallest byte address) of that member in a compound datatype. +\li Each member can be a small array of up to four dimensions. + +Properties of members of a compound datatype are defined when the member is added to the compound type and cannot be subsequently modified. + +\subsubsection subsubsecLBDtypeSpecCmpdDef Defining compound datatypes +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. + +Member names. Each member must have a descriptive name, which is the key used to uniquely identify +the member within the compound datatype. A member name in an HDF5 datatype does not necessarily +have to be the same as the name of the corresponding member in the C struct in memory, although +this is often the case. Nor does one need to define all members of the C struct in the HDF5 +compound datatype (or vice versa). + +Offsets. Usually a C struct will be defined to hold a data point in memory, and the offsets of the +members in memory will be the offsets of the struct members from the beginning of an instance of the +struct. The library defines the macro to compute the offset of a member within a struct: +\code + HOFFSET(s,m) +\endcode +This macro computes the offset of member m within a struct variable s. + +Here is an example in which a compound datatype is created to describe complex numbers whose type +is defined by the complex_t struct. +\code +typedef struct { + double re; /*real part */ + double im; /*imaginary part */ +} complex_t; + +complex_t tmp; /*used only to compute offsets */ +hid_t complex_id = H5Tcreate (H5T_COMPOUND, sizeof tmp); +H5Tinsert (complex_id, "real", HOFFSET(tmp,re), H5T_NATIVE_DOUBLE); +H5Tinsert (complex_id, "imaginary", HOFFSET(tmp,im), H5T_NATIVE_DOUBLE); +\endcode + +\subsection subsecLBDtypeSpecRef Reference +There are two types of Reference datatypes in HDF5: +\li \ref subsubsecLBDtypeSpecRefObj +\li \ref subsubsecLBDtypeSpecRefDset + +\subsubsection subsubsecLBDtypeSpecRefObj Reference to objects +In HDF5, objects (i.e. groups, datasets, and named datatypes) are usually accessed by name. +There is another way to access stored objects -- by reference. + +An object reference is based on the relative file address of the object header in the file +and is constant for the life of the object. Once a reference to an object is created and +stored in a dataset in the file, it can be used to dereference the object it points to. +References are handy for creating a file index or for grouping related objects by storing +references to them in one dataset. + +

Creating and storing references to objects

+The following steps are involved in creating and storing file references to objects: +
    +
  1. Create the objects or open them if they already exist in the file.
    2. +
  2. Create a dataset to store the objects' references, by specifying #H5T_STD_REF_OBJ as the datatype
    3. +
  3. Create and store references to the objects in a buffer, using #H5Rcreate.
    4. +
  4. Write a buffer with the references to the dataset, using #H5Dwrite with the #H5T_STD_REF_OBJ datatype.
    5. +
+ +

Reading references and accessing objects using references

+The following steps are involved: +
    +
  1. Open the dataset with the references and read them. The #H5T_STD_REF_OBJ datatype must be used to describe the memory datatype.
    2. +
  2. Use the read reference to obtain the identifier of the object the reference points to using #H5Rdereference.
    3. +
  3. Open the dereferenced object and perform the desired operations.
    4. +
  4. Close all objects when the task is complete.
    5. +
+ +\subsubsection subsubsecLBDtypeSpecRefDset Reference to a dataset region +A dataset region reference points to a dataset selection in another dataset. +A reference to the dataset selection (region) is constant for the life of the dataset. + +

Creating and storing references to dataset regions

+The following steps are involved in creating and storing references to a dataset region: +\li Create a dataset to store the dataset region (selection), by passing in #H5T_STD_REF_DSETREG for the datatype when calling #H5Dcreate. +\li Create selection(s) in existing dataset(s) using #H5Sselect_hyperslab and/or #H5Sselect_elements. +\li Create reference(s) to the selection(s) using #H5Rcreate and store them in a buffer. +\li Write the references to the dataset regions in the file. +\li Close all objects. + +

Reading references to dataset regions

+The following steps are involved in reading references to dataset regions and referenced dataset regions (selections). +
    +
  1. Open and read the dataset containing references to the dataset regions. +The datatype #H5T_STD_REF_DSETREG must be used during read operation.
    2. +
  2. Use #H5Rdereference to obtain the dataset identifier from the read dataset region reference. + OR + Use #H5Rget_region to obtain the dataspace identifier for the dataset containing the selection from the read dataset region reference. +
    3. +
  3. With the dataspace identifier, the \ref H5S interface functions, H5Sget_select_*, +can be used to obtain information about the selection.
    4. +
  4. Close all objects when they are no longer needed.
    5. +
+ +The dataset with the region references was read by #H5Dread with the #H5T_STD_REF_DSETREG datatype specified. + +The read reference can be used to obtain the dataset identifier by calling #H5Rdereference or by obtaining +obtain spacial information (dataspace and selection) with the call to #H5Rget_region. + +The reference to the dataset region has information for both the dataset itself and its selection. In both functions: +\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. + +This example introduces several H5Sget_select_* functions used to obtain information about selections: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Examples of HDF5 predefined datatypes
FunctionDescription
#H5Sget_select_npointsReturns the number of elements in the hyperslab
#H5Sget_select_hyper_nblocksReturns the number of blocks in the hyperslab
#H5Sget_select_hyper_blocklistReturns the "lower left" and "upper right" coordinates of the blocks in the hyperslab selection
#H5Sget_select_boundsReturns the coordinates of the "minimal" block containing a hyperslab selection
#H5Sget_select_elem_npointsReturns the number of points in the element selection
#H5Sget_select_elem_pointlistReturns the coordinates of points in the element selection
+ +\subsection subsecLBDtypeSpecStr String +A simple example of creating a derived datatype is using the string datatype, +#H5T_C_S1 (#H5T_FORTRAN_S1) to create strings of more than one character. Strings +can be stored as either fixed or variable length, and may have different rules +for padding of unused storage. + +\subsubsection subsecLBDtypeSpecStrFix Fixed Length 5-character String Datatype +\code + hid_t strtype; /* Datatype ID */ + herr_t status; + + strtype = H5Tcopy (H5T_C_S1); + status = H5Tset_size (strtype, 5); /* create string of length 5 */ +\endcode + +\subsubsection subsecLBDtypeSpecStrVar Variable Length String Datatype +\code + strtype = H5Tcopy (H5T_C_S1); + status = H5Tset_size (strtype, H5T_VARIABLE); +\endcode + +The ability to derive datatypes from pre-defined types allows users to create any number of datatypes, +from simple to very complex. + +As the term implies, variable length strings are strings of varying lengths. They are stored internally +in a heap, potentially impacting efficiency in the following ways: +\li Heap storage requires more space than regular raw data storage. +\li Heap access generally reduces I/O efficiency because it requires individual read or write operations +for each data element rather than one read or write per dataset or per data selection. +\li A variable length dataset consists of pointers to the heaps of data, not the actual data. Chunking +and filters, including compression, are not available for heaps. + +See \ref subsubsec_datatype_other_strings in the \ref UG, for more information on how fixed and variable +length strings are stored. + +\subsection subsecLBDtypeSpecVL Variable Length +Variable-length (VL) datatypes are sequences of an existing datatype (atomic, VL, or compound) +which are not fixed in length from one dataset location to another. In essence, they are similar +to C character strings -- a sequence of a type which is pointed to by a particular type of +pointer -- although they are implemented more closely to FORTRAN strings by including an explicit +length in the pointer instead of using a particular value to terminate the sequence. + +VL datatypes are useful to the scientific community in many different ways, some of which are listed below: +
    +
  • Ragged arrays: Multi-dimensional ragged arrays can be implemented with the last (fastest changing) +dimension being ragged by using a VL datatype as the type of the element stored. (Or as a field in a compound datatype.) +
    • +
  • Fractal arrays: If a compound datatype has a VL field of another compound type with VL fields +(a nested VL datatype), this can be used to implement ragged arrays of ragged arrays, to whatever +nesting depth is required for the user. +
    • +
  • Polygon lists: A common storage requirement is to efficiently store arrays of polygons with +different numbers of vertices. VL datatypes can be used to efficiently and succinctly describe an +array of polygons with different numbers of vertices. +
    • +
  • Character strings: Perhaps the most common use of VL datatypes will be to store C-like VL character +strings in dataset elements or as attributes of objects. +
    • +
  • Indices: An array of VL object references could be used as an index to all the objects in a file +which contain a particular sequence of dataset values. Perhaps an array something like the following: +\code + Value1: Object1, Object3, Object9 + Value2: Object0, Object12, Object14, Object21, Object22 + Value3: Object2 + Value4: + Value5: Object1, Object10, Object12 + . + . +\endcode +
    • +
  • Object Tracking: An array of VL dataset region references can be used as a method of tracking +objects or features appearing in a sequence of datasets. Perhaps an array of them would look like: +\code + Feature1: Dataset1:Region, Dataset3:Region, Dataset9:Region + Feature2: Dataset0:Region, Dataset12:Region, Dataset14:Region, + Dataset21:Region, Dataset22:Region + Feature3: Dataset2:Region + Feature4: + Feature5: Dataset1:Region, Dataset10:Region, Dataset12:Region + . + . +\endcode +
    • +
+ +\subsubsection subsubsecLBDtypeSpecVLMem Variable-length datatype memory management +With each element possibly being of different sequence lengths for a dataset with a VL datatype, +the memory for the VL datatype must be dynamically allocated. Currently there are two methods +of managing the memory for VL datatypes: the standard C malloc/free memory allocation routines +or a method of calling user-defined memory management routines to allocate or free memory. Since +the memory allocated when reading (or writing) may be complicated to release, an HDF5 routine is +provided to traverse a memory buffer and free the VL datatype information without leaking memory. + +\subsubsection subsubsecLBDtypeSpecVLDiv Variable-length datatypes cannot be divided +VL datatypes are designed so that they cannot be subdivided by the library with selections, etc. +This design was chosen due to the complexities in specifying selections on each VL element of a +dataset through a selection API that is easy to understand. Also, the selection APIs work on +dataspaces, not on datatypes. At some point in time, we may want to create a way for dataspaces +to have VL components to them and we would need to allow selections of those VL regions, but +that is beyond the scope of this document. + +\subsubsection subsubsecLBDtypeSpecVLErr What happens if the library runs out of memory while reading? +It is possible for a call to #H5Dread to fail while reading in VL datatype information if the memory +required exceeds that which is available. In this case, the #H5Dread call will fail gracefully and any +VL data which has been allocated prior to the memory shortage will be returned to the system via the +memory management routines detailed below. It may be possible to design a partial read API function +at a later date, if demand for such a function warrants. + +\subsubsection subsubsecLBDtypeSpecVLStr Strings as variable-length datatypes +Since character strings are a special case of VL data that is implemented in many different ways on +different machines and in different programming languages, they are handled somewhat differently from +other VL datatypes in HDF5. + +HDF5 has native VL strings for each language API, which are stored the same way on disk, but are +exported through each language API in a natural way for that language. When retrieving VL strings +from a dataset, users may choose to have them stored in memory as a native VL string or in HDF5's +#hvl_t struct for VL datatypes. + +VL strings may be created in one of two ways: by creating a VL datatype with a base type of +#H5T_C_S1 and setting its length to #H5T_VARIABLE. The second method is used to access native VL strings in memory. The +library will convert between the two types, but they are stored on disk using different datatypes +and have different memory representations. + +Multi-byte character representations, such as \em UNICODE or \em wide characters in C/C++, will need the +appropriate character and string datatypes created so that they can be described properly through +the datatype API. Additional conversions between these types and the current ASCII characters +will also be required. + +Variable-width character strings (which might be compressed data or some other encoding) are not +currently handled by this design. We will evaluate how to implement them based on user feedback. + +\subsubsection subsubsecLBDtypeSpecVLAPIs Variable-length datatype APIs + +

Creation

+VL datatypes are created with the #H5Tvlen_create function as follows: +\code +type_id = H5Tvlen_create(hid_t base_type_id); +\endcode +The base datatype will be the datatype that the sequence is composed of, characters for character +strings, vertex coordinates for polygon lists, etc. The base datatype specified for the VL datatype +can be of any HDF5 datatype, including another VL datatype, a compound datatype, or an atomic datatype. + +

Querying base datatype of VL datatype

+It may be necessary to know the base datatype of a VL datatype before memory is allocated, etc. +The base datatype is queried with the #H5Tget_super function, described in the \ref H5T documentation. + +

Querying minimum memory required for VL information

+It order to predict the memory usage that #H5Dread may need to allocate to store VL data while +reading the data, the #H5Dvlen_get_buf_size function is provided: +\code +herr_t H5Dvlen_get_buf_size(hid_t dataset_id, hid_t type_id, hid_t space_id, hsize_t *size) +\endcode +This routine checks the number of bytes required to store the VL data from the dataset, using +the \em space_id for the selection in the dataset on disk and the \em type_id for the memory representation +of the VL data in memory. The *\em size value is modified according to how many bytes are required +to store the VL data in memory. + +

Specifying how to manage memory for the VL datatype

+The memory management method is determined by dataset transfer properties passed into the +#H5Dread and #H5Dwrite functions with the dataset transfer property list. + +Default memory management is set by using #H5P_DEFAULT for the dataset transfer +property list identifier. If #H5P_DEFAULT is used with #H5Dread, the system \em malloc and \em free +calls will be used for allocating and freeing memory. In such a case, #H5P_DEFAULT should +also be passed as the property list identifier to #H5Dvlen_reclaim. + +The rest of this subsection is relevant only to those who choose not to use default memory management. + +The user can choose whether to use the system \em malloc and \em free calls or user-defined, or custom, +memory management functions. If user-defined memory management functions are to be used, the +memory allocation and free routines must be defined via #H5Pset_vlen_mem_manager(), as follows: +\code +herr_t H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc, void *alloc_info, H5MM_free_t free, void *free_info) +\endcode +The \em alloc and \em free parameters identify the memory management routines to be used. If the user +has defined custom memory management routines, \em alloc and/or \em free should be set to make those +routine calls (i.e., the name of the routine is used as the value of the parameter); if the user +prefers to use the system's \em malloc and/or \em free, the \em alloc and \em free parameters, respectively, should be set to \em NULL + +The prototypes for the user-defined functions would appear as follows: +\code +typedef void *(*H5MM_allocate_t)(size_t size, void *info) ; typedef void (*H5MM_free_t)(void *mem, void *free_info) ; +\endcode +The \em alloc_info and \em free_info parameters can be used to pass along any required information to +the user's memory management routines. + +In summary, if the user has defined custom memory management routines, the name(s) of the routines +are passed in the \em alloc and \em free parameters and the custom routines' parameters are passed in the +\em alloc_info and \em free_info parameters. If the user wishes to use the system \em malloc and \em free functions, +the \em alloc and/or \em free parameters are set to \em NULL and the \em alloc_info and \em free_info parameters are ignored. + +

Recovering memory from VL buffers read in

+The complex memory buffers created for a VL datatype may be reclaimed with the #H5Dvlen_reclaim +function call, as follows: +\code +herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void *buf); +\endcode + +The \em type_id must be the datatype stored in the buffer, \em space_id describes the selection for the +memory buffer to free the VL datatypes within, \em plist_id is the dataset transfer property list +which was used for the I/O transfer to create the buffer, and \em buf is the pointer to the buffer +to free the VL memory within. The VL structures (#hvl_t) in the user's buffer are modified to zero +out the VL information after it has been freed. + +If nested VL datatypes were used to create the buffer, this routine frees them from the bottom up, +releasing all the memory without creating memory leaks. + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +*/ diff --git a/doxygen/dox/LearnBasics3.dox b/doxygen/dox/LearnBasics3.dox new file mode 100644 index 0000000..2fe0f52 --- /dev/null +++ b/doxygen/dox/LearnBasics3.dox @@ -0,0 +1,1015 @@ +/** @page LBPropsList Property Lists Basics +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBPList What is a Property (or Property List)? +In HDF5, a property or property list is a characteristic or feature associated with an HDF5 object. +There are default properties which handle the most common needs. These default properties are +specified by passing in #H5P_DEFAULT for the Property List parameter of a function. Default properties +can be modified by use of the \ref H5P interface and function parameters. + +The \ref H5P API allows a user to take advantage of the more powerful features in HDF5. It typically +supports unusual cases when creating or accessing HDF5 objects. There is a programming model for +working with Property Lists in HDF5 (see below). + +For examples of modifying a property list, see these tutorial topics: +\li \see \ref LBDsetLayout +\li \see \ref LBExtDset +\li \see \ref LBComDset + +There are many Property Lists associated with creating and accessing objects in HDF5. See the +\ref H5P Interface documentation in the HDF5 \ref RM for a list of the different +properties associated with HDF5 interfaces. + +In summary: +\li Properties are features of HDF5 objects, that can be changed by use of the Property List API and function parameters. +\li Property lists provide a mechanism for adding functionality to HDF5 calls without increasing the number of arguments used for a given call. +\li The Property List API supports unusual cases when creating and accessing HDF5 objects. + +\section secLBPListProg Programming Model +Default properties are specified by simply passing in #H5P_DEFAULT (C) / H5P_DEFAULT_F (F90) for +the property list parameter in those functions for which properties can be changed. + +The programming model for changing a property list is as follows: +\li Create a copy or "instance" of the desired pre-defined property type, using the #H5Pcreate call. This +will return a property list identifier. Please see the \ref RM entry for #H5Pcreate, for a comprehensive +list of the property types. +\li With the property list identifier, modify the property, using the \ref H5P APIs. +\li Modify the object feature, by passing the property list identifier into the corresponding HDF5 object function. +\li Close the property list when done, using #H5Pclose. + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBDsetLayout Dataset Storage Layout +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBDsetLayoutDesc Description of a Dataset + +\section secLBDsetLayout Dataset Storage Layout +The storage information, or storage layout, defines how the raw data values in the dataset are +physically stored on disk. There are three ways that a dataset can be stored: +\li contiguous +\li chunked +\li compact + +See the #H5Pset_layout/#H5Pget_layout APIs for details. + +\subsection subsecLBDsetLayoutCont Contiguous +If the storage layout is contiguous, then the raw data values will be stored physically adjacent +to each other in the HDF5 file (in one contiguous block). This is the default layout for a dataset. +In other words, if you do not explicitly change the storage layout for the dataset, then it will +be stored contiguously. + + + + +
+\image html tutr-locons.png +
+ +\subsection subsecLBDsetLayoutChunk Chunked +With a chunked storage layout the data is stored in equal-sized blocks or chunks of +a pre-defined size. The HDF5 library always writes and reads the entire chunk: + + + + +
+\image html tutr-lochk.png +
+ +Each chunk is stored as a separate contiguous block in the HDF5 file. There is a chunk index +which keeps track of the chunks associated with a dataset: + + + + +
+\image html tutr-lochks.png +
+ + +\subsubsection susubsecLBDsetLayoutChunkWhy Why Chunking ? +Chunking is required for enabling compression and other filters, as well as for creating extendible +or unlimited dimension datasets. + +It is also commonly used when subsetting very large datasets. Using the chunking layout can +greatly improve performance when subsetting large datasets, because only the chunks required +will need to be accessed. However, it is easy to use chunking without considering the consequences +of the chunk size, which can lead to strikingly poor performance. + +Note that a chunk always has the same rank as the dataset and the chunk's dimensions do not need +to be factors of the dataset dimensions. + +Writing or reading a chunked dataset is transparent to the application. You would use the same +set of operations that you would use for a contiguous dataset. For example: +\code + H5Dopen (...); + H5Sselect_hyperslab (...); + H5Dread (...); +\endcode + +\subsubsection susubsecLBDsetLayoutChunkProb Problems Using Chunking +Issues that can cause performance problems with chunking include: +\li Chunks are too small. +If a very small chunk size is specified for a dataset it can cause the dataset to be excessively +large and it can result in degraded performance when accessing the dataset. The smaller the chunk +size the more chunks that HDF5 has to keep track of, and the more time it will take to search for a chunk. +\li Chunks are too large. +An entire chunk has to be read and uncompressed before performing an operation. There can be a +performance penalty for reading a small subset, if the chunk size is substantially larger than +the subset. Also, a dataset may be larger than expected if there are chunks that only contain a +small amount of data. +\li A chunk does not fit in the Chunk Cache. +Every chunked dataset has a chunk cache associated with it that has a default size of 1 MB. The +purpose of the chunk cache is to improve performance by keeping chunks that are accessed frequently +in memory so that they do not have to be accessed from disk. If a chunk is too large to fit in the +chunk cache, it can significantly degrade performance. However, the size of the chunk cache can be +increased by calling #H5Pset_chunk_cache. + +It is a good idea to: +\li Avoid very small chunk sizes, and be aware of the 1 MB chunk cache size default. +\li Test the data with different chunk sizes to determine the optimal chunk size to use. +\li Consider the chunk size in terms of the most common access patterns that will be used once the dataset has been created. + +\subsection subsecLBDsetLayoutCom Compact +A compact dataset is one in which the raw data is stored in the object header of the dataset. +This layout is for very small datasets that can easily fit in the object header. + +The compact layout can improve storage and access performance for files that have many very tiny +datasets. With one I/O access both the header and data values can be read. The compact layout reduces +the size of a file, as the data is stored with the header which will always be allocated for a dataset. +However, the object header is 64 KB in size, so this layout can only be used for very small datasets. + +\section secLBDsetLayoutProg Programming Model to Modify the Storage Layout +To modify the storage layout, the following steps must be done: +\li Create a Dataset Creation Property list. (See #H5Pcreate) +\li Modify the property list. +To use chunked storage layout, call: #H5Pset_chunk +To use the compact storage layout, call: #H5Pset_layout +\li Create a dataset with the modified property list. (See #H5Dcreate) +\li Close the property list. (See #H5Pclose) +For example code, see the \ref HDF5Examples page. +Specifically look at the Examples by API. +There are examples for different languages. + +The C example to create a chunked dataset is: +h5ex_d_chunk.c +The C example to create a compact dataset is: +h5ex_d_compact.c + +\section secLBDsetLayoutChange Changing the Layout after Dataset Creation +The dataset layout is a Dataset Creation Property List. This means that once the dataset has been +created the dataset layout cannot be changed. The h5repack utility can be used to write a file +to a new with a new layout. + +\section secLBDsetLayoutSource Sources of Information +Chunking in HDF5 +(See the documentation on Advanced Topics in HDF5) +\see \ref sec_plist in the HDF5 \ref UG. + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + + +@page LBExtDset Extendible Datasets +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBExtDsetCreate Creating an Extendible Dataset +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. + +HDF5 requires you to use chunking to define extendible datasets. This makes it possible to extend +datasets efficiently without having to excessively reorganize storage. (To use chunking efficiently, +be sure to see the advanced topic, Chunking in HDF5.) + +The following operations are required in order to extend a dataset: +\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. +\li Create the dataset. +\li Extend the size of the dataset. + +\section secLBExtDsetProg Programming Example + +\subsection subsecLBExtDsetProgDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The 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. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection subsecLBExtDsetProgRem Remarks +\li An unlimited dimension dataspace is specified with the #H5Screate_simple call, by passing in +#H5S_UNLIMITED as an element of the maxdims array. +\li The #H5Pcreate call creates a new property as an instance of a property list class. For creating +an extendible array dataset, pass in #H5P_DATASET_CREATE for the property list class. +\li The #H5Pset_chunk call modifies a Dataset Creation Property List instance to store a chunked +layout dataset and sets the size of the chunks used. +\li To extend an unlimited dimension dataset use the the #H5Dset_extent call. Please be aware that +after this call, the dataset's dataspace must be refreshed with #H5Dget_space before more data can be accessed. +\li The #H5Pget_chunk call retrieves the size of chunks for the raw data of a chunked layout dataset. +\li Once there is no longer a need for a Property List instance, it should be closed with the #H5Pclose call. + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBComDset Compressed Datasets +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBComDsetCreate Creating a Compressed Dataset +HDF5 requires you to use chunking to create a compressed dataset. (To use chunking efficiently, +be sure to see the advanced topic, Chunking in HDF5.) + +The following operations are required in order to create a compressed dataset: +\li Create a dataset creation property list. +\li Modify the dataset creation property list instance to enable chunking and to enable compression. +\li Create the dataset. +\li Close the dataset creation property list and dataset. + +For more information on compression, see the FAQ question on Using Compression in HDF5. + +\section secLBComDsetProg Programming Example + +\subsection subsecLBComDsetProgDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example creates a chunked and ZLIB compressed dataset. It also includes comments for what needs +to be done to create an SZIP compressed dataset. The example then reopens the dataset, prints the +filter information, and reads the dataset. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection subsecLBComDsetProgRem Remarks +\li The #H5Pset_chunk call modifies a Dataset Creation Property List instance to store a chunked layout +dataset and sets the size of the chunks used. +\li The #H5Pset_deflate call modifies the Dataset Creation Property List instance to use ZLIB or DEFLATE +compression. The #H5Pset_szip call modifies it to use SZIP compression. There are different compression +parameters required for each compression method. +\li SZIP compression can only be used with atomic datatypes that are integer, float, or char. It cannot be +applied to compound, array, variable-length, enumerations, or other user-defined datatypes. The call +to #H5Dcreate will fail if attempting to create an SZIP compressed dataset with a non-allowed datatype. +The conflict can only be detected when the property list is used. + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBContents Discovering the Contents of an HDF5 File +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBContents Discovering what is in an HDF5 file +HDFView and h5dump are standalone tools which cannot be called within an application, and using +#H5Dopen and #H5Dread require that you know the name of the HDF5 dataset. How would an application +that has no prior knowledge of an HDF5 file be able to determine or discover the contents of it, +much like HDFView and h5dump? + +The answer is that there are ways to discover the contents of an HDF5 file, by using the +\ref H5G, \ref H5L and \ref H5O APIs: +\li The \ref H5G interface (covered earlier) consists of routines for working with groups. A group is +a structure that can be used to organize zero or more HDF5 objects, not unlike a Unix directory. +\li The \ref H5L interface consists of link routines. A link is a path between groups. The \ref H5L interface +allows objects to be accessed by use of these links. +\li The \ref H5O interface consists of routines for working with objects. Datasets, groups, and committed +datatypes are all objects in HDF5. + +Interface routines that simplify the process: +\li #H5Literate traverses the links in a specified group, in the order of the specified index, using a +user-defined callback routine. (A callback function is one that will be called when a certain condition +is met, at a certain point in the future.) +\li #H5Ovisit / #H5Lvisit recursively visit all objects/links accessible from a specified object/group. + + +\section secLBContentsProg Programming Example + +\subsection subsecLBContentsProgUsing Using #H5Literate, #H5Lvisit and #H5Ovisit +For example code, see the \ref HDF5Examples page. +Specifically look at the Examples by API. +There are examples for different languages, where examples of using #H5Literate and #H5Ovisit/#H5Lvisit are included. + +The h5ex_g_traverse example traverses a file using H5Literate: +\li C: h5ex_g_traverse.c +\li F90: h5ex_g_traverse_F03.f90 + +The h5ex_g_visit example traverses a file using H5Ovisit and H5Lvisit: +\li C: h5ex_g_visit.c +\li F90: h5ex_g_visit_F03.f90 + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBQuiz Learning the basics QUIZ +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\ref LBFileOrg +
    +
  1. Name and describe the two primary objects that can be stored in an HDF5 file. +
    2. +
  2. What is an attribute? +
    3. +
  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. +
    4. +
+ +\ref LBAPI +
    +
  1. Describe the purpose of each of the following HDF5 APIs: +\code + H5A, H5D, H5E, H5F, H5G, H5T, H5Z +\endcode +
    2. +
+ +\ref LBFileCreate +
    +
  1. What two HDF5 routines must be called to create an HDF5 file? +
    2. +
  2. What include file must be included in any file that uses the HDF5 library? +
    3. +
  3. 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? +
    4. +
+ +\ref LBDsetCreate +
    +
  1. Name and describe two major datatype categories. +
    2. +
  2. List the HDF5 atomic datatypes. Give an example of a predefined datatype. How would you create a string dataset? +
    3. +
  3. What does the dataspace describe? What are the major characteristics of the simple dataspace? +
    4. +
  4. What information needs to be passed to the #H5Dcreate function, i.e., what information is needed to describe a dataset at creation time? +
    5. +
+ + +\ref LBDsetRW +
    +
  1. What are six pieces of information which need to be specified for reading and writing a dataset? +
    2. +
  2. Why are both the memory dataspace and file dataspace needed for read/write operations, while only the memory datatype is required? +
    3. +
  3. In Figure 6.1, what does this line mean? +\code +DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } +\endcode +
    4. +
+ + +\ref LBAttrCreate +
    +
  1. What is an attribute? +
    2. +
  2. Can partial I/O operations be performed on attributes? +
    3. +
+ + +\ref LBGrpCreate +
    +
  1. What are the two primary objects that can be included in a group? +
    2. +
+ + +\ref LBGrpCreateNames +
    +
  1. Group names can be specified in two ways. What are these two types of group names? +
    2. +
  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? +
    3. +
+ + +\ref LBGrpDset +
    +
  1. Describe a way to access the dataset moo described in the previous section +(question 2) using a relative name. Describe a way to access the same dataset using an absolute name. +
    2. +
+ +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBQuizAnswers Learning the basics QUIZ with Answers +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\ref LBFileOrg +
    +
  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. +
  2. What is an attribute? + + + + + +
    Answer +An HDF5 attribute is a user-defined HDF5 structure that provides extra information about an HDF5 object. +
    +
    3. +
  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 +
    +
    4. +
+ +\ref LBAPI +
    +
  1. Describe the purpose of each of the following HDF5 APIs: +\code + H5A, H5D, H5E, H5F, H5G, H5T, H5Z +\endcode + + + + + +
    Answer +H5A: Attribute access and manipulation routines +
    +H5D: Dataset access and manipulation routines +
    +H5E: Error handling routines H5F: 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 +
    +
    2. +
+ +\ref LBFileCreate +
    +
  1. What two HDF5 routines must be called to create an HDF5 file? + + + + + +
    Answer +#H5Fcreate and #H5Fclose. +
    +
    2. +
  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. +
  3. 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? + + + + + +
    Answer +The root group. +
    +
    4. +
+ +\ref LBDsetCreate +
    +
  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 and compound datatypes, or small arrays of such types. +
    +
    2. +
  2. List the HDF5 atomic datatypes. Give an example of a predefined datatype. How would you create a string dataset? + + + + + +
    Answer +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:
    +\li #H5T_IEEE_F32LE - 4-byte little-endian, IEEE floating point +\li #H5T_NATIVE_INT - native integer + +You would create a string dataset with the #H5T_C_S1 datatype, and set the size of the string with the #H5Tset_size call. +
    +
    3. +
  3. What does the dataspace describe? What are the major characteristics of the simple dataspace? + + + + + +
    Answer +The dataspace describes the dimensionality of the dataset. A simple dataspace is characterized by its rank and dimension sizes. +
    +
    4. +
  4. What information needs to be passed to the #H5Dcreate function, i.e., what information is needed to describe a dataset at creation time? + + + + + +
    Answer +The dataset location, name, dataspace, datatype, and dataset creation property list. +
    +
    5. +
+ + +\ref LBDsetRW +
    +
  1. What are six pieces of information which need to be specified for reading and writing a dataset? + + + + + +
    Answer +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. +
    +
    2. +
  2. Why are both the memory dataspace and file dataspace needed for read/write operations, while only the memory datatype is required? + + + + + +
    Answer +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. +
    +
    3. +
  3. In Figure 6.1, what does this line mean? +\code +DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } +\endcode + + + + + +
    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). +
    +
    4. +
+ + +\ref LBAttrCreate +
    +
  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. +
  2. Can partial I/O operations be performed on attributes? + + + + + +
    Answer +No. +
    +
    3. +
+ + +\ref LBGrpCreate +
    +
  1. What are the two primary objects that can be included in a group? + + + + + +
    Answer +A group and a dataset. +
    +
    2. +
+ + +\ref LBGrpCreateNames +
    +
  1. Group names can be specified in two ways. What are these two types of group names? + + + + + +
    Answer +Relative and absolute. +
    +
    2. +
  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 +
    +
    3. +
+ + +\ref LBGrpDset +
    +
  1. Describe a way to access the dataset moo described in the previous section +(question 2) using a relative name. Describe a way to access the same dataset using an absolute name. + + + + + +
    Answer +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 obtained in Step 2. +\code +gid = H5Gopen (file_id, "/foo", 0); /* absolute path */ +gid1 = H5Gopen (gid, "boo", 0); /* relative path */ +did = H5Dopen (gid1, "moo"); /* relative path */ +\endcode +Access the group /foo and get the group ID. Access the dataset boo/moo with the group ID just obtained. +\code +gid = H5Gopen (file_id, "/foo", 0); /* absolute path */ +did = H5Dopen (gid, "boo/moo"); /* relative path */ +\endcode +Access the dataset with an absolute path. +\code +did = H5Dopen (file_id, "/foo/boo/moo"); /* absolute path */ +\endcode +
    +
    2. +
+ +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBCompiling Compiling HDF5 Applications +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +\section secLBCompiling Tools and Instructions on Compiling +Compiling applications to use the HDF5 Library can be as simple as executing: +\code +h5cc -o myprog myprog.c +\endcode + +As an application's file base evolves, there are better solutions using autotools and makefiles or +CMake and CMakeLists.txt files. Many tutorials and references can be found with a simple search. + +This tutorial section will discuss the use of compile scripts on Linux. +See the \ref secLBCompilingVS section for compiling with Visual Studio. + +\section secLBCompilingLinux Compile Scripts +When the library is built, the following compile scripts are included: +\li h5cc: compile script for HDF5 C programs +\li h5fc: compile script for HDF5 F90 programs +\li h5c++: compile script for HDF5 C++ programs + +These scripts are easilye used to compile single file applications, such as those included in the tutorial. + + + + + +
Warning +The h5cc/h5fc/h5c++ compile scripts are included when building with configure. Versions of +these compile scripts have also been added to CMake for Linux ONLY. The CMake versions rely on pkgconfig files. +
+ +

Examples of Using the Unix Compile Scripts:

+Following are examples of compiling and running an application with the Unix compile scripts: +\code + h5fc myprog.f90 + ./a.out + + h5cc -o myprog myprog.c + ./myprog +\endcode + +To see how the libraries linked in with a compile script were configured and built, use the +-showconfig option. For example, if using h5cc type: +\code + h5cc -showconfig +\endcode + +

Detailed Description of Unix Compile Scripts:

+The h5cc, h5c++, and h5fc compile scripts come with the HDF5 binary distributions (include files, +libraries, and utilities) for the platforms we support. The h5c++ and h5fc utilities are ONLY present +if the library was built with C++ and Fortran. + +\section secLBCompilingVS Using Visual Studio + + 1. If you are building on 64-bit Windows, find the "Platform" dropdown + and select "x64". Also select the correct Configuration (Debug, Release, RelWithDebInfo, etc) + + 2. Set up path for external headers + + The HDF5 install path settings will need to be in the project property sheets per project. + Go to "Project" and select "Properties", find "Configuration Properties", + and then "C/C++". + + 2.1 Add the header path to the "Additional Include Directories" setting. Under "C/C++" + find "General" and select "Additional Include Directories". Select "Edit" from the dropdown + and add the HDF5 install/include path to the list. + (Ex: "C:\Program Files\HDF_Group\HDF5\1.10.9\include") + + 2.2 Building applications with the dynamic/shared hdf5 libraries requires + that the "H5_BUILT_AS_DYNAMIC_LIB" compile definition be used. Under "C/C++" + find "Preprocessor" and select "Preprocessor Definitions". Select "Edit" from the dropdown + and add "H5_BUILT_AS_DYNAMIC_LIB" to the list. + + 3. Set up path for external libraries + + The HDF5 install path/lib settings will need to be in the project property sheets per project. + Go to "Project" and select "Properties", find "Configuration Properties", + and then "Linker". + + 3.1 Add the libraries to the "Additional Dependencies" setting. Under "Linker" + find "Input" and select "Additional Dependencies". Select "Edit" from the dropdown + and add the required HDF5 install/lib path to the list. + (Ex: "C:\Program Files\HDF_Group\HDF5\1.10.9\lib\hdf5.lib") + + 3.2 For static builds, the external libraries should be added. + For example, to compile a C++ application, enter: + libhdf5_cpp.lib libhdf5.lib libz.lib libszaec.lib libaec.lib + +\section secLBCompilingLibs HDF5 Libraries +Following are the libraries included with HDF5. Whether you are using the Unix compile scripts or +Makefiles, or are compiling on Windows, these libraries are or may need to be specified. The order +they are specified is important on Linux: + + + + + + + + + + + + + + +
HDF5 Static Libraries
LibraryLinux NameMac NameWindows Name
+\code +HDF5 High Level C++ APIs +HDF5 C++ Library +HDF5 High Level Fortran APIs +HDF5 Fortran Library +HDF5 High Level C APIs +HDF5 C Library +\endcode + +\code +libhdf5_hl_cpp.a +libhdf5_cpp.a +libhdf5hl_fortran.a +libhdf5_fortran.a +libhdf5_hl.a +libhdf5.a +\endcode + +\code +libhdf5_hl_cpp.a +libhdf5_cpp.a +libhdf5hl_fortran.a +libhdf5_fortran.a +libhdf5_hl.a +libhdf5.a +\endcode + +Windows +\code +libhdf5_hl_cpp.lib +libhdf5_cpp.lib +libhdf5hl_fortran.lib +libhdf5_fortran.lib +libhdf5_hl.lib +libhdf5.lib +\endcode +
+ + + + + + + + + + + + + + +
HDF5 Shared Libraries
LibraryLinux NameMac NameWindows Name
+\code +HDF5 High Level C++ APIs +HDF5 C++ Library +HDF5 High Level Fortran APIs +HDF5 Fortran Library +HDF5 High Level C APIs +HDF5 C Library +\endcode + +\code +libhdf5_hl_cpp.so +libhdf5_cpp.so +libhdf5hl_fortran.so +libhdf5_fortran.so +libhdf5_hl.so +libhdf5.so +\endcode + +\code +libhdf5_hl_cpp.dylib +libhdf5_cpp.dylib +libhdf5hl_fortran.dylib +libhdf5_fortran.dylib +libhdf5_hl.dylib +libhdf5.dylib +\endcode + +\code +hdf5_hl_cpp.lib +hdf5_cpp.lib +hdf5hl_fortran.lib +hdf5_fortran.lib +hdf5_hl.lib +hdf5.lib +\endcode +
+ + + + + + + + + + + + + + + +
External Libraries
LibraryLinux NameMac NameWindows Name
+\code +SZIP Compression Library +SZIP Compression Library +ZLIB or DEFLATE Compression Library +\endcode + +\code +libszaec.a +libaec.a +libz.a +\endcode + +\code +libszaec.a +libaec.a +libz.a +\endcode + +\code +libszaec.lib +libaec.lib +libz.lib +\endcode +
+ +The pre-compiled binaries, in particular, are built (if at all possible) with these libraries as well as with +SZIP and ZLIB. If using shared libraries you may need to add the path to the library to LD_LIBRARY_PATH on Linux +or on WINDOWS you may need to add the path to the bin folder to PATH. + +\section secLBCompilingCMake Compiling an Application with CMake + +\subsection subsecLBCompilingCMakeScripts CMake Scripts for Building Applications +Simple scripts are provided for building applications with different languages and options. +See CMake Scripts for Building Applications. + +For a more complete script (and to help resolve issues) see the script provided with the HDF5 Examples project. + +\subsection subsecLBCompilingCMakeExamples HDF5 Examples +The installed HDF5 can be verified by compiling the HDF5 Examples project, included with the CMake built HDF5 binaries +in the share folder or you can go to the HDF5 Examples github repository. + +Go into the share directory and follow the instructions in USING_CMake_examples.txt to build the examples. + +In general, users must first set the HDF5_ROOT environment variable to the installed location of the CMake +configuration files for HDF5. For example, on Windows the following path might be set: + +\code + HDF5_ROOT=C:/Program Files/HDF_Group/HDF5/1.N.N +\endcode + +\subsection subsecLBCompilingCMakeTroubless Troubleshooting CMake +

How do you use find_package with HDF5?

+To use find_package you will first need to make sure that HDF5_ROOT is set correctly. For setting this +environment variable see the Preconditions in the USING_HDF5_CMake.txt file in the share directory. + +See the CMakeLists.txt file provided with these examples for how to use find_package with HDF5. + +Please note that the find_package invocation changed to require "shared" or "static": +\code + FIND_PACKAGE(HDF5 COMPONENTS C HL NO_MODULE REQUIRED shared) + FIND_PACKAGE(HDF5 COMPONENTS C HL NO_MODULE REQUIRED static) +\endcode + +Previously, the find_package invocation was: +\code + FIND_PACKAGE(HDF5 COMPONENTS C HL NO_MODULE REQUIRED) +\endcode + +

My platform/compiler is not included. Can I still use the configuration files?

+Yes, you can but you will have to edit the HDF5_Examples.cmake file and update the variable: +\code + CTEST_CMAKE_GENERATOR +\endcode + +The generators for your platform can be seen by typing: +\code + cmake --help +\endcode + +

What do I do if the build fails?

+I received an error during the build and the application binary is not in the +build directory as I expected. How do I determine what the problem is? + +If the error is not clear, then the first thing you may want to do is replace the -V (Dash Uppercase Vee) +option for ctest in the build script to -VV (Dash Uppercase Vee Uppercase Vee). Then remove the build +directory and re-run the build script. The output should be more verbose. + +If the error is still not clear, then check the log files. You will find those in the build directory. +For example, on Unix the log files will be in: +\code + build/Testing/Temporary/ +\endcode +There are log files for the configure, test, and build. + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBTraining Training Videos +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +
+ +Training Videos + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +*/ diff --git a/doxygen/dox/LearnHDFView.dox b/doxygen/dox/LearnHDFView.dox new file mode 100644 index 0000000..b1f632c --- /dev/null +++ b/doxygen/dox/LearnHDFView.dox @@ -0,0 +1,472 @@ +/** @page LearnHDFView Learning HDF5 with HDFView + +Navigate back: \ref index "Main" / \ref GettingStarted +
+ +This tutorial enables you to get a feel for HDF5 by using the HDFView browser. It does NOT require +any programming experience. + +\section sec_learn_hv_install HDFView Installation +\li Download and install HDFView. It can be downloaded from the Download HDFView page. +\li Obtain the storm1.txt text file, used in the tutorial. + +\section sec_learn_hv_begin Begin Tutorial +Once you have HDFView installed, bring it up and you are ready to begin the tutorial. + + + + + + +
+Unable to complete tutorial because fields are greyed out? +
+This tutorial requires that the default HDFView File Access Mode be Read / Write. If fields are greyed out so that you cannot select them, then the File Access Mode is Read Only. + +To change the File Access Mode follow these steps: +
    +
  • Bring up HDFView
    • +
  • Left-mouse click on the Tools pull-down menu and select User Options.
    • +
  • A Preferences window pops up with the General Settings tab selected. +About half-way down you will see Default File Access Mode. +Select Read / Write.
    • +
  • Click on Apply and Close at the bottom of the window.
    • +
  • Close down HDFView.
    • +
  • Bring HDFView back up and try the tutorial again.
    • +PLEASE BE AWARE that selecting a File Access Mode of Read / Write can result in changes to the timestamp of HDF files that are viewed with HDFView. In general, a File Access Mode +of Read Only should be used to ensure that this does not occur. +
+
+ +\subsection subsec_learn_hv_begin_topics Topics Covered +Following are the topics covered in the tutorial. The first topic creates the file that is used in +the subsequent topics. +
    +
  • @ref subsec_learn_hv_topics_file
    • +
  • @ref subsec_learn_hv_topics_image
    • +
  • @ref subsec_learn_hv_topics_attr
    • +
  • @ref subsec_learn_hv_topics_compress
    • +
  • @ref subsec_learn_hv_topics_subset
    • +
  • @ref subsec_learn_hv_topics_table
    • +
+ +\section sec_learn_hv_topics Topics + +\subsection subsec_learn_hv_topics_file Creating a New HDF5 File with a Contiguous Dataset +The steps below describe how to create a file (storm.h5), group (/Data), and a contiguous dataset +(/Data/Storm) using HDFView. A group is an HDF5 object that allows objects to be collected together. +A dataset is an array of data values. A contiguous dataset is one that is stored as a single block +in the HDF5 file. +
    +
  • Select the File pull-down menu at the top left, and then select New -> HDF5.
    • +
  • Specify a location and type in storm.h5 for the name of your file, and click on the Save button. +You will see the storm.h5 file in the TableView: + + + + +
    +\image html storm.png +
    +
    • +
  • Right click on storm.h5, and select New -> Group.
    • +
  • Enter Data for the name of the group and then click the Ok button. You will see the group Data in the TableView. + + + + +
    +\image html DataGroup.png +
    +
    • +
  • Right click on the group Data and select New -> Dataset.
    • +
  • A window pops up on the right. Fill in the information as follows, and then click Ok (leave the +Datatype information as is): + + + + + + + + + + + + + +
    Dataset Name +Storm +
    Under Dataspace, Current size +57x57 +
    Layout +Contiguous (default) +
    +
    • +
  • Click to expand the Data group in the tree view to see the Storm dataset: + + + + +
    +\image html StormDataset.png +
    +
    • +
  • Double left click on the Storm dataset in the tree view. A window with an empty spreadsheet pops open.
    • +
  • Copy the data from the storm1.txt file into the dataset. + +If you downloaded storm1.txt, +then click on the Import/Export Data menu and select Import Data from -> Text File. +Specify a location, select storm1.txt +and click on the Open button. Answer Yes in the dialog box that +pops up (which asks if you wish to paste the selected data). + +Alternately, you can copy/paste directly. Select and copy the data in a separate window. Position your +cursor at (0,0) in your table, and select Paste from the Table menu. + +The values will be entered into the spreadsheet. + + + + +
    +\image html datasetwdata.png +
    +
    • +
  • Table -> Close the dataset, and save the data.
    • +
+ +\subsection subsec_learn_hv_topics_image Displaying a Dataset as an Image +Any dataset can be viewed as an image in HDFView. Below are the steps that demonstrate this. +
    +
  • Right click on Storm in the tree view, and select Open As.
    • +
  • Select the Image button under Display As (near the top) in the Dataset Selection window that pops +up. Then click OK at the bottom of the window to display the image. + + + + +
    +\image html showasimage.png +
    +
    • +
  • The rainbow icon brings you to the Image Palette window. Click on that to play with the palette +(GrayWave probably is the best choice). Close.
    • +
+ +\subsection subsec_learn_hv_topics_attr Creating Attributes +Additional information to describe an object can be stored in attributes. An attribute can be +added to a group or dataset with HDFView. + +The following illustrates how to add an attribute to the group /Data: +
    +
  • Click on the /Data folder in the tree view. You will see two tabs, Object Attribute Info and +General Object Info, in the pane on the right site of the HDFView window. + + + + +
    +\image html noattrs.png +
    +
    • +
  • With the left mouse button, select the Add Attribute button.
    • +
  • Select the Add Attribute button to add an attribute with these values:
    • + + + + + + + + + + + + +
    Name +BatchID +
    Type +INTEGER +
    Size (bits) +32 +
    +
  • Select the Ok button. The attribute will show up under the Object Attribute Info tab.
    • +
  • Double-click the BatchID attribute line to open the data table for BatchID.
    • +
  • Click in the first cell and enter 3343 followed by the enter key.
    • +
  • Table -> Close, answer Yes in the dialog box that +pops up (which asks if you wish to paste the selected data).
    • +
+Adding an attribute to a dataset is very similar to adding an attribute to a group. For example, +the following adds an attribute to the /Storm dataset: +
    +
  • Left mouse click on the /Storm dataset in the tree view. You will see the Object Attribute +Info and General Object Info tabs on the right
    • +
  • In the Object Attribute Info pane select the Add Attribute button and enter an attribute with +these values. (Be sure to add a String Length or the string will be truncated to one character!):
    • + + + + + + + + + + + + +
    Name +Units +
    Type +STRING +
    String Length +3 +
    +
  • Select the Ok button. The attribute will show up under the Object Attribute Info tab.
    • +
  • Double-click the Units attribute line to open the data table for Units.
    • +
  • Click in the first cell and enter m/s followed by the enter key.
    • +
  • Table -> Close, answer Yes in the dialog box that +pops up (which asks if you wish to paste the selected data). + + + + +
    +\image html scarletletter.png +
    +
    • +
+ +\subsection subsec_learn_hv_topics_compress Creating a Compressed and Chunked Dataset +A chunked and compressed dataset can be created using HDFView. A compressed dataset is a dataset +whose size has been compressed to take up less space. In order to compress an HDF5 dataset, the +dataset must be stored with a chunked dataset layout (as multiple chunks that are stored separately +in the file). + +Please note that the chunk sizes used in this topic are for demonstration purposes only. For +information on chunking and specifying an appropriate chunk size, see the +Chunking in HDF5 documentation. + +Also see the HDF5 Tutorial topic on \ref secLBComDsetCreate. +
    +
  • Right click on storm.h5. Select New -> Group.
    • +
  • Enter Image for the name of the group, and click the OK button to create the group. + + + + +
    +\image html newgroupimage.png +
    +
    • +
  • Right click on the Image group, and select New -> Dataset.
    • +
  • Enter the following information for the dataset. Leave the Datatype as is (INTEGER): + + + + + + + + + + + + + + + + + + + + + + + + +
    Dataset name +Another Storm +
    Under Dataspace, Current size +57x57 +
    Storage Layout +Chunked +
    Chunk Size +20x20 +
    Compression +gzip +
    Compression Level +9 +
    +You will see the Another Storm dataset in the Image group: + + + + +
    +\image html hdfview-anthrstrm.png +
    +
    • +
  • Double left-mouse click on the Another Storm dataset to display the spreadsheet: + + + + +
    +\image html hdfview-anthrstrm-sprdsht.png +
    +
    • +
  • Copy the data from the storm1.txt file into the dataset. (See the previous topic for copying +storm1.txt into a dataset.)
    • +
  • Table -> Close, and save the data.
    • +
  • Right click on Another Storm, and select Open As.
    • +
  • Select the Image button in the Dataset Selection window that pops up. Click the Ok button at the +bottom of the window to view the dataset as an image. + + + + +
    +\image html hdfview-anthrstrm-img.png +
    +
    • +
+ +\subsection subsec_learn_hv_topics_subset Creating an Image and a Subset +A previous topic demonstrated how to view any dataset as an image in HDFView. With HDFView you can also +create an image to begin with, as is shown below. +
    +
  • Right click on the Data group and select New -> Image.
    • +
  • A window pops up on the right. Enter the following and then click Ok:
    • + + + + + + + + + + + + +
    Image name +Storm Image +
    Height +57 +
    Width +57 +
    + +
  • Close the dataset.
    • +
  • Expand the Data group to see its contents. You will see the Storm Image dataset. + + + + +
    +\image html hdfview-imgicon.png +
    +
    • +
  • +Add data to the Storm Image dataset as was shown previously: +
      +
    • Right click on Storm Image, and select Open As to open the Dataset Selection window.
      • +
    • Click on the Spreadsheet button at the top left of the Dataset Selection window to view the image +as a spreadsheet.
      • +
    • Copy the data from the storm1.txt file into the dataset.
      • +
    • Close the dataset and save the data.
      • +
    +
    • +
  • Left double click on Storm Image to see the image. Close the dataset.
    • +
  • Right click on Storm Image and select Open As to bring up the Data Selection window.
    • +
  • Select a subset by clicking the left mouse on the image in the window and dragging the mouse. +Notice that the Height and Width values change. Select to display it as an image. Click Ok. + + + + +
    +\image html hdfview-imgsubset.png +
    +
    • +
  • Position the cursor in the middle of the image. Press Shift+Left Mouse button and hold, and then +drag the mouse to select another subset.
    • +
  • Select Image->Write Selection to Image. Enter Subset for the new image name. Click Ok. The Subset +image will appear in the tree view on the left.
    • +
  • Left double click on the image Subset to bring it up on the right. + + + + +
    +\image html hdfview-newimgsubset.png +
    +
    • +
  • Close the Subset image.
    • +
+ +\subsection subsec_learn_hv_topics_table Creating a Table (Compound Dataset) +A dataset with a compound datatype contains data elements that consist of multiple fields. If the +dataspace for the compound dataset is one-dimensional, then the dataset can be viewed as a table in +HDFView, as is shown below. +
    +
  • Right button click on the group Data. Select New -> Compound DS.
    • +
  • A window pops up. Only fill in the following fields: + + + + + + + + + + + + + + + + + +
    Dataset name +Table +
    Dataspace (Current size only) +4 +
    Compound Datatype Properties: +
    Number of Members +    		3 +
    Compound Datatype Properties: +
    Name / Datatype / Size +    		Description / string / 4 +
    Temperature / float / 1 +
    Pressure / double / 1 +
    + + + + + +
    +\image html hdfview-newcmpd.png +
    +
    • +
  • Click Ok at the bottom.
    • +
  • Open the Data group (if it is not open) and double left click on the Table object. + + + + +
    +\image html hdfview-table.png +
    +
    • +
  • Close the dataset.
    • +
+ +
+Navigate back: \ref index "Main" / \ref GettingStarted + +*/ diff --git a/doxygen/dox/UsersGuide.dox b/doxygen/dox/UsersGuide.dox index 6b44d21..a8ff060 100644 --- a/doxygen/dox/UsersGuide.dox +++ b/doxygen/dox/UsersGuide.dox @@ -293,7 +293,7 @@ These documents provide additional information for the use and tuning of specifi
-

HDF5 Examples

+

@ref HDF5Examples

Code examples by API.

diff --git a/doxygen/dox/ViewTools.dox b/doxygen/dox/ViewTools.dox new file mode 100644 index 0000000..0b685a0 --- /dev/null +++ b/doxygen/dox/ViewTools.dox @@ -0,0 +1,1198 @@ +/** @page ViewTools Tools for Viewing and Editing HDF5 Files + +Navigate back: \ref index "Main" / \ref GettingStarted +
+ +\section secToolsBasic Basic Facts about HDF5 +The following are basic facts about HDF5 files to keep in mind while completing these tutorial topics: +\li All HDF5 files contain a root group "/". +\li There are two primary objects in HDF5, a group and a dataset:
+ Groups allow objects to be organized into a group structure, such as a tree.
+ Datasets contain raw data values. +\li Additional information about an HDF5 object may optionally be stored in attributes attached to the object. + +\section secToolsTopics Tutorial Topics + + + + + + + + + + + + + + + + + +
Tutorial TopicDescription
+@ref LearnHDFView +Use HDFView to create, edit and view files. +
+@ref ViewToolsCommand +Use the HDF5 command-line tools for viewing, editing, and comparing HDF5 files. +
@ref ViewToolsJPSS +Use HDF5 tools to examine and work with JPSS NPP files. +
+ +
+Navigate back: \ref index "Main" / \ref GettingStarted + +@page ViewToolsCommand Command-line Tools +Navigate back: \ref index "Main" / \ref GettingStarted +
+ +\section secViewToolsCommandObtain Obtain Tools and Files (Optional) +Pre-built binaries for Linux and Windows are distributed within the respective HDF5 binary release +packages, which can be obtained from the Download HDF5 page. + +HDF5 files can be obtained from various places such as \ref HDF5Examples and HDF-EOS and Tools and +Information Center. Specifically, the following examples are used in this tutorial topic: +\li HDF5 Files created from compiling the \ref LBExamples +\li HDF5 Files on the Examples by API page +\li NPP JPSS files, SVM01_npp.. (gzipped) +and SVM09_npp.. (gzipped) +\li HDF-EOS OMI-Aura file + +\section secViewToolsCommandTutor Tutorial Topics +A variety of command-line tools are included in the HDF5 binary distribution. There are tools to view, +edit, convert and compare HDF5 files. This tutorial discusses the tools by their functionality. It +does not cover all of the HDF5 tools. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Tool CategoryTopicTools Used
@ref ViewToolsView@ref secViewToolsViewContenth5dump and h5ls +
@ref secViewToolsViewDseth5dump and h5ls +
@ref secViewToolsViewGrpsh5dump and h5ls +
@ref secViewToolsViewAttrh5dump +
@ref secViewToolsViewSubh5dump +
@ref secViewToolsViewDtypesh5dump +
@ref ViewToolsEdit@ref secViewToolsEditRemoveh5repack +
@ref secViewToolsEditChangeh5repack +
@ref secViewToolsEditApplyh5repack +
@ref secViewToolsEditCopyh5copy +
@ref secViewToolsEditAddh5jam and h5unjam +
@ref ViewToolsConvert@ref secViewToolsConvertASCIIh5dump +
@ref secViewToolsConvertBinaryh5dump +
@ref secViewToolsConvertExporth5dump and h5import +
+ +
+Navigate back: \ref index "Main" / \ref GettingStarted + +@page ViewToolsView Command-line Tools For Viewing HDF5 Files +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand +
+ +\section secViewToolsViewTOC Contents +
    +
  • \ref secViewToolsViewContent
    • +
  • \ref secViewToolsViewDset
    • +
  • \ref secViewToolsViewGrps
    • +
  • \ref secViewToolsViewAttr
    • +
  • \ref secViewToolsViewSub
    • +
  • \ref secViewToolsViewDtypes
    • +
+ +\section secViewToolsViewContent File Content and Structure +The h5dump and h5ls tools can both be used to view the contents of an HDF5 file. The tools are discussed below: +
    +
  • \ref subsecViewToolsViewContent_h5dump
    • +
  • \ref subsecViewToolsViewContent_h5ls
    • +
+ +\subsection subsecViewToolsViewContent_h5dump h5dump +The h5dump tool dumps or displays the contents of an HDF5 file (textually). By default if you specify no options, +h5dump will display the entire contents of a file. There are many h5dump options for examining specific details +of a file. To see all of the available h5dump options, specify the -h +or --help option: +\code +h5dump -h +\endcode + +The following h5dump options can be helpful in viewing the content and structure of a file: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescriptionComment
-n, --contents +Displays a list of the objects in a file +See @ref subsubsecViewToolsViewContent_h5dumpEx1 +
-n 1, --contents=1 +Displays a list of the objects and attributes in a file +See @ref subsubsecViewToolsViewAttr_h5dumpEx6 +
-H, --header +Displays header information only (no data) +See @ref subsubsecViewToolsViewContent_h5dumpEx2 +
-A 0, --onlyattr=0 +Suppresses the display of attributes +See @ref subsubsecViewToolsViewContent_h5dumpEx2 +
-N P, --any_path=P +Displays any object or attribute that matches path P +See @ref subsubsecViewToolsViewAttr_h5dumpEx6 +
+ +\subsubsection subsubsecViewToolsViewContent_h5dumpEx1 Example 1 +The following command displays a list of the objects in the file OMI-Aura.he5 (an HDF-EOS5 file): +\code +h5dump -n OMI-Aura.he5 +\endcode + +As shown in the output below, the objects (groups, datasets) are listed to the left, followed by their +names. You can see that this file contains two root groups, HDFEOS and HDFEOS INFORMATION: +\code +HDF5 "OMI-Aura.he5" { +FILE_CONTENTS { + group / + group /HDFEOS + group /HDFEOS/ADDITIONAL + group /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES + group /HDFEOS/GRIDS + group /HDFEOS/GRIDS/OMI Column Amount O3 + group /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields + dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/ColumnAmountO3 + dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/RadiativeCloudFraction + dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle + dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/ViewingZenithAngle + group /HDFEOS INFORMATION + dataset /HDFEOS INFORMATION/StructMetadata.0 + } +} +\endcode + +\subsubsection subsubsecViewToolsViewContent_h5dumpEx2 Example 2 +The file structure of the OMI-Aura.he5 file can be seen with the following command. The -A 0 option suppresses the display of attributes: +\code +h5dump -H -A 0 OMI-Aura.he5 +\endcode + +Output of this command is shown below: +\code +HDF5 "OMI-Aura.he5" { +GROUP "/" { + GROUP "HDFEOS" { + GROUP "ADDITIONAL" { + GROUP "FILE_ATTRIBUTES" { + } + } + GROUP "GRIDS" { + GROUP "OMI Column Amount O3" { + GROUP "Data Fields" { + DATASET "ColumnAmountO3" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "RadiativeCloudFraction" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "SolarZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "ViewingZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + } + } + } + } + GROUP "HDFEOS INFORMATION" { + DATASET "StructMetadata.0" { + DATATYPE H5T_STRING { + STRSIZE 32000; + STRPAD H5T_STR_NULLTERM; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SCALAR + } + } +} +} +\endcode + +\subsection subsecViewToolsViewContent_h5ls h5ls +The h5ls tool by default just displays the objects in the root group. It will not display +items in groups beneath the root group unless specified. Useful h5ls options for viewing +file content and structure are: + + + + + + + + + + + + + + + + +
OptionDescriptionComment
-r +Lists all groups and objects recursively +See @ref subsubsecViewToolsViewContent_h5lsEx3 +
-v +Generates verbose output (lists dataset properties, attributes +and attribute values, but no dataset values) + +
+ +\subsubsection subsubsecViewToolsViewContent_h5lsEx3 Example 3 +The following command shows the contents of the HDF-EOS5 file OMI-Aura.he5. The output is similar to h5dump, except that h5ls also shows dataspace information for each dataset: +\code +h5ls -r OMI-Aura.he5 +\endcode + +The output is shown below: +\code +/ Group +/HDFEOS Group +/HDFEOS/ADDITIONAL Group +/HDFEOS/ADDITIONAL/FILE_ATTRIBUTES Group +/HDFEOS/GRIDS Group +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3 Group +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields Group +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ColumnAmountO3 Dataset {720, 1440} +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/RadiativeCloudFraction Dataset {720, 1440} +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/SolarZenithAngle Dataset {720, 1440} +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ViewingZenithAngle Dataset {720, 1440} +/HDFEOS\ INFORMATION Group +/HDFEOS\ INFORMATION/StructMetadata.0 Dataset {SCALAR} +\endcode + +\section secViewToolsViewDset Datasets and Dataset Properties +Both h5dump and h5ls can be used to view specific datasets. +
    +
  • \ref subsecViewToolsViewDset_h5dump
    • +
  • \ref subsecViewToolsViewDset_h5ls
    • +
+ +\subsection subsecViewToolsViewDset_h5dump h5dump +Useful h5dump options for examining specific datasets include: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescriptionComment
-d D, --dataset=D +Displays dataset D +See @ref subsubsecViewToolsViewDset_h5dumpEx4 +
-H, --header +Displays header information only +See @ref subsubsecViewToolsViewDset_h5dumpEx4 +
-p, --properties +Displays dataset filters, storage layout, and fill value properties +See @ref subsubsecViewToolsViewDset_h5dumpEx5 +
-A 0, --onlyattr=0 +Suppresses the display of attributes +See @ref subsubsecViewToolsViewContent_h5dumpEx2 +
-N P, --any_path=P +Displays any object or attribute that matches path P +See @ref subsubsecViewToolsViewAttr_h5dumpEx6 +
+ +\subsubsection subsubsecViewToolsViewDset_h5dumpEx4 Example 4 +A specific dataset can be viewed with h5dump using the -d D option and specifying the entire +path and name of the dataset for D. The path is important in identifying the correct dataset, +as there can be multiple datasets with the same name. The path can be determined by looking at +the objects in the file with h5dump -n. + +The following example uses the groups.h5 file that is created by the +\ref LBExamples +example h5_crtgrpar.c. To display dset1 in the groups.h5 file below, specify dataset +/MyGroup/dset1. The -H option is used to suppress printing of the data values: + +Contents of groups.h5 +\code + $ h5dump -n groups.h5 + HDF5 "groups.h5" { + FILE_CONTENTS { + group / + group /MyGroup + group /MyGroup/Group_A + dataset /MyGroup/Group_A/dset2 + group /MyGroup/Group_B + dataset /MyGroup/dset1 + } + } +\endcode + +Display dataset "dset1" +\code + $ h5dump -d "/MyGroup/dset1" -H groups.h5 + HDF5 "groups.h5" { + DATASET "/MyGroup/dset1" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) } + } + } +\endcode + +\subsubsection subsubsecViewToolsViewDset_h5dumpEx5 Example 5 +The -p option is used to examine the the dataset filters, storage layout, and fill value properties of a dataset. + +This option can be useful for checking how well compression works, or even for analyzing performance +and dataset size issues related to chunking. (The smaller the chunk size, the more chunks that HDF5 +has to keep track of, which increases the size of the file and potentially affects performance.) + +In the file shown below the dataset /DS1 is both chunked and compressed: +\code + $ h5dump -H -p -d "/DS1" h5ex_d_gzip.h5 + HDF5 "h5ex_d_gzip.h5" { + DATASET "/DS1" { + DATATYPE H5T_STD_I32LE + DATASPACE SIMPLE { ( 32, 64 ) / ( 32, 64 ) } + STORAGE_LAYOUT { + CHUNKED ( 4, 8 ) + SIZE 5278 (1.552:1 COMPRESSION) + } + FILTERS { + COMPRESSION DEFLATE { LEVEL 9 } + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 0 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_INCR + } + } + } +\endcode + +You can obtain the h5ex_d_gzip.c program that created this file, as well as the file created, +from the Examples by API page. + +\subsection subsecViewToolsViewDset_h5ls h5ls +Specific datasets can be specified with h5ls by simply adding the dataset path and dataset after the +file name. As an example, this command displays dataset dset2 in the groups.h5 +file used in @ref subsubsecViewToolsViewDset_h5dumpEx4 : +\code +h5ls groups.h5/MyGroup/Group_A/dset2 +\endcode + +Just the dataspace information gets displayed: +\code +dset2 Dataset {2, 10} +\endcode + +The following options can be used to see detailed information about a dataset. + + + + + + + + + + + + + +
OptionDescription
-v, --verbose +Generates verbose output (lists dataset properties, attributes +and attribute values, but no dataset values) +
-d, --data +Displays dataset values +
+ +The output of using -v is shown below: +\code + $ h5ls -v groups.h5/MyGroup/Group_A/dset2 + Opened "groups.h5" with sec2 driver. + dset2 Dataset {2/2, 10/10} + Location: 1:3840 + Links: 1 + Storage: 80 logical bytes, 80 allocated bytes, 100.00% utilization + Type: 32-bit big-endian integer +\endcode + +The output of using -d is shown below: +\code + $ h5ls -d groups.h5/MyGroup/Group_A/dset2 + dset2 Dataset {2, 10} + Data: + (0,0) 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 +\endcode + +\section secViewToolsViewGrps Groups +Both h5dump and h5ls can be used to view specific groups in a file. +
    +
  • \ref subsecViewToolsViewGrps_h5dump
    • +
  • \ref subsecViewToolsViewGrps_h5ls
    • +
+ +\subsection subsecViewToolsViewGrps_h5dump h5dump +The h5dump options that are useful for examining groups are: + + + + + + + + + + + + + + + + + +
OptionDescription
-g G, --group=G +Displays group G and its members +
-H, --header +Displays header information only +
-A 0, --onlyattr=0 +Suppresses the display of attributes +
+ +To view the contents of the HDFEOS group in the OMI file mentioned previously, you can specify the path and name of the group as follows: +\code +h5dump -g "/HDFEOS" -H -A 0 OMI-Aura.he5 +\endcode + +The -A 0 option suppresses attributes and -H suppresses printing of data values: +\code + HDF5 "OMI-Aura.he5" { + GROUP "/HDFEOS" { + GROUP "ADDITIONAL" { + GROUP "FILE_ATTRIBUTES" { + } + } + GROUP "GRIDS" { + GROUP "OMI Column Amount O3" { + GROUP "Data Fields" { + DATASET "ColumnAmountO3" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "RadiativeCloudFraction" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "SolarZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "ViewingZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + } + } + } + } + } +\endcode + +\subsection subsecViewToolsViewGrps_h5ls h5ls +You can view the contents of a group with h5ls/ by specifying the group after the file name. +To use h5ls to view the contents of the /HDFEOS group in the OMI-Aura.he5 file, type: +\code +h5ls -r OMI-Aura.he5/HDFEOS +\endcode + +The output of this command is: +\code + /ADDITIONAL Group + /ADDITIONAL/FILE_ATTRIBUTES Group + /GRIDS Group + /GRIDS/OMI\ Column\ Amount\ O3 Group + /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields Group + /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ColumnAmountO3 Dataset {720, 1440} + /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/RadiativeCloudFraction Dataset {720, 1440} + /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/SolarZenithAngle Dataset {720, 1440} + /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ViewingZenithAngle Dataset {720, 1440} +\endcode + +If you specify the -v option, you can also see the attributes and properties of the datasets. + +\section secViewToolsViewAttr Attributes + +\subsection subsecViewToolsViewAttr_h5dump h5dump +Attributes are displayed by default if using h5dump. Some files contain many attributes, which +can make it difficult to examine the objects in the file. Shown below are options that can help +when using h5dump to work with files that have attributes. + +\subsubsection subsubsecViewToolsViewAttr_h5dumpEx6 Example 6 +The -a A option will display an attribute. However, the path to the attribute must be included +when specifying this option. For example, to see the ScaleFactor attribute in the OMI-Aura.he5 file, type: +\code +h5dump -a "/HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle/ScaleFactor" OMI-Aura.he5 +\endcode + +This command displays: +\code + HDF5 "OMI-Aura.he5" { + ATTRIBUTE "ScaleFactor" { + DATATYPE H5T_IEEE_F64LE + DATASPACE SIMPLE { ( 1 ) / ( 1 ) } + DATA { + (0): 1 + } + } + } +\endcode + +How can you determine the path to the attribute? This can be done by looking at the file contents with the -n 1 option: +\code +h5dump -n 1 OMI-Aura.he5 +\endcode + +Below is a portion of the output for this command: +\code + HDF5 "OMI-Aura.he5" { + FILE_CONTENTS { + group / + group /HDFEOS + group /HDFEOS/ADDITIONAL + group /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/EndUTC + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleDay + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleDayOfYear + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleMonth + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleYear + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/InstrumentName + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/OrbitNumber + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/OrbitPeriod + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/PGEVersion + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/Period + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/ProcessLevel + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/StartUTC + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/TAI93At0zOfGranule + + ... +\endcode + +There can be multiple objects or attributes with the same name in a file. How can you make sure +you are finding the correct object or attribute? You can first determine how many attributes +there are with a specified name, and then examine the paths to them. + +The -N option can be used to display all objects or attributes with a given name. +For example, there are four attributes with the name ScaleFactor in the OMI-Aura.he5 file, +as can be seen below with the -N option: +\code +h5dump -N ScaleFactor OMI-Aura.he5 +\endcode + +It outputs: +\code +HDF5 "OMI-Aura.he5" { +ATTRIBUTE "ScaleFactor" { + DATATYPE H5T_IEEE_F64LE + DATASPACE SIMPLE { ( 1 ) / ( 1 ) } + DATA { + (0): 1 + } +} +ATTRIBUTE "ScaleFactor" { + DATATYPE H5T_IEEE_F64LE + DATASPACE SIMPLE { ( 1 ) / ( 1 ) } + DATA { + (0): 1 + } +} +ATTRIBUTE "ScaleFactor" { + DATATYPE H5T_IEEE_F64LE + DATASPACE SIMPLE { ( 1 ) / ( 1 ) } + DATA { + (0): 1 + } +} +ATTRIBUTE "ScaleFactor" { + DATATYPE H5T_IEEE_F64LE + DATASPACE SIMPLE { ( 1 ) / ( 1 ) } + DATA { + (0): 1 + } +} +} +\endcode + +\subsection subsecViewToolsViewAttr_h5ls h5ls +If you include the -v (verbose) option for h5ls, you will see all of the attributes for the +specified file, dataset or group. You cannot display individual attributes. + +\section secViewToolsViewSub Dataset Subset + +\subsection subsecViewToolsViewSub_h5dump h5dump +If you have a very large dataset, you may wish to subset or see just a portion of the dataset. +This can be done with the following h5dump options. + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescription
-d D, --dataset=D +Dataset D +
-s START, --start=START +Offset or start of subsetting selection +
-S STRIDE, --stride=STRIDE +Stride (sampling along a dimension). The default (unspecified, or 1) selects +every element along a dimension, a value of 2 selects every other element, +a value of 3 selects every third element, ... +
-c COUNT, --count=COUNT +Number of blocks to include in the selection +
-k BLOCK, --block=BLOCK +Size of the block in a hyperslab. The default (unspecified, or 1) is for +the block size to be the size of a single element. +
+ +The START (s), STRIDE (S), COUNT (c), and BLOCK (k) options +define the shape and size of the selection. They are arrays with the same number of dimensions as the rank +of the dataset's dataspace, and they all work together to define the selection. A change to one of +these arrays can affect the others. + +When specifying these h5dump options, a comma is used as the delimiter for each dimension in the +option value. For example, with a 2-dimensional dataset, the option value is specified as "H,W", +where H is the height and W is the width. If the offset is 0 for both dimensions, then +START would be specified as follows: +\code +-s "0,0" +\endcode + +There is also a shorthand way to specify these options with brackets at the end of the dataset name: +\code +-d DATASETNAME[s;S;c;k] +\endcode + +Multiple dimensions are separated by commas. For example, a subset for a 2-dimensional dataset would be specified as follows: +\code +-d DATASETNAME[s,s;S,S;c,c;k,k] +\endcode + +For a detailed understanding of how selections works, see the #H5Sselect_hyperslab API in the \ref RM. + +The dataset SolarZenithAngle in the OMI-Aura.he5 file can be used to illustrate these options. This +dataset is a 2-dimensional dataset of size 720 (height) x 1440 (width). Too much data will be displayed +by simply viewing the specified dataset with the -d option: +\code +h5dump -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" OMI-Aura.he5 +\endcode +Subsetting narrows down the output that is displayed. In the following example, the first +15x10 elements (-c "15,10") are specified, beginning with position (0,0) (-s "0,0"): +\code + h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" -s "0,0" -c "15,10" -w 0 OMI-Aura.he5 +\endcode + +If using the shorthand method, specify: +\code + h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle[0,0;;15,10;]" -w 0 OMI-Aura.he5 +\endcode + +Where, +\par The -d option must be specified + +before +\par subsetting options (if not using the shorthand method). + +The -A 0 option suppresses the printing of attributes. + +The -w 0 option sets the number of columns of output to the maximum allowed value (65535). +This ensures that there are enough columns specified for displaying the data. + +Either command displays: +\code + HDF5 "OMI-Aura.he5" { + DATASET "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + SUBSET { + START ( 0, 0 ); + STRIDE ( 1, 1 ); + COUNT ( 15, 10 ); + BLOCK ( 1, 1 ); + DATA { + (0,0): 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, + (1,0): 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, + (2,0): 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, + (3,0): 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, + (4,0): 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, + (5,0): 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, + (6,0): 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, + (7,0): 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, + (8,0): 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, + (9,0): 77.658, 77.658, 77.658, 77.307, 77.307, 77.307, 77.307, 77.307, 77.307, 77.307, + (10,0): 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.102, 77.102, + (11,0): 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 77.102, 77.102, + (12,0): 76.34, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, + (13,0): 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 77.195, + (14,0): 78.005, 78.005, 78.005, 78.005, 78.005, 78.005, 76.991, 76.991, 76.991, 76.991 + } + } + } + } +\endcode + +What if we wish to read three rows of three elements at a time (-c "3,3"), where each element +is a 2 x 3 block (-k "2,3") and we wish to begin reading from the second row (-s "1,0")? + +You can do that with the following command: +\code + h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" + -s "1,0" -S "2,3" -c "3,3" -k "2,3" -w 0 OMI-Aura.he5 +\endcode + +In this case, the stride must be specified as 2 by 3 (or larger) to accommodate the reading of 2 by 3 blocks. +If it is smaller, the command will fail with the error, +\code +h5dump error: wrong subset selection; blocks overlap. +\endcode + +The output of the above command is shown below: +\code + HDF5 "OMI-Aura.he5" { + DATASET "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + SUBSET { + START ( 1, 0 ); + STRIDE ( 2, 3 ); + COUNT ( 3, 3 ); + BLOCK ( 2, 3 ); + DATA { + (1,0): 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, + (2,0): 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, + (3,0): 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, + (4,0): 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, + (5,0): 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, + (6,0): 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021 + } + } + } + } +\endcode + +\section secViewToolsViewDtypes Datatypes + +\subsection subsecViewToolsViewDtypes_h5dump h5dump +The following datatypes are discussed, using the output of h5dump with HDF5 files from the +Examples by API page: +
    +
  • @ref subsubsecViewToolsViewDtypes_array
    • +
  • @ref subsubsecViewToolsViewDtypes_objref
    • +
  • @ref subsubsecViewToolsViewDtypes_regref
    • +
  • @ref subsubsecViewToolsViewDtypes_string
    • +
+ +\subsubsection subsubsecViewToolsViewDtypes_array Array +Users have been confused by the difference between an Array datatype (#H5T_ARRAY) and a dataset that +(has a dataspace that) is an array. + +Typically, these users want a dataset that has a simple datatype (like integer or float) that is an +array, like the following dataset /DS1. It has a datatype of #H5T_STD_I32LE (32-bit Little-Endian Integer) +and is a 4 by 7 array: +\code +$ h5dump h5ex_d_rdwr.h5 +HDF5 "h5ex_d_rdwr.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_STD_I32LE + DATASPACE SIMPLE { ( 4, 7 ) / ( 4, 7 ) } + DATA { + (0,0): 0, -1, -2, -3, -4, -5, -6, + (1,0): 0, 0, 0, 0, 0, 0, 0, + (2,0): 0, 1, 2, 3, 4, 5, 6, + (3,0): 0, 2, 4, 6, 8, 10, 12 + } + } +} +} +\endcode + +Contrast that with the following dataset that has both an Array datatype and is an array: +\code +$ h5dump h5ex_t_array.h5 +HDF5 "h5ex_t_array.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_ARRAY { [3][5] H5T_STD_I64LE } + DATASPACE SIMPLE { ( 4 ) / ( 4 ) } + DATA { + (0): [ 0, 0, 0, 0, 0, + 0, -1, -2, -3, -4, + 0, -2, -4, -6, -8 ], + (1): [ 0, 1, 2, 3, 4, + 1, 1, 1, 1, 1, + 2, 1, 0, -1, -2 ], + (2): [ 0, 2, 4, 6, 8, + 2, 3, 4, 5, 6, + 4, 4, 4, 4, 4 ], + (3): [ 0, 3, 6, 9, 12, + 3, 5, 7, 9, 11, + 6, 7, 8, 9, 10 ] + } + } +} +} +\endcode + +In this file, dataset /DS1 has a datatype of +\code +H5T_ARRAY { [3][5] H5T_STD_I64LE } +\endcode +and it also has a dataspace of +\code +SIMPLE { ( 4 ) / ( 4 ) } +\endcode +In other words, it is an array of four elements, in which each element is a 3 by 5 array of #H5T_STD_I64LE. + +This dataset is much more complex. Also note that subsetting cannot be done on Array datatypes. + +See this FAQ for more information on the Array datatype. + +\subsubsection subsubsecViewToolsViewDtypes_objref Object Reference +An Object Reference is a reference to an entire object (dataset, group, or named datatype). +A dataset with an Object Reference datatype consists of one or more Object References. +An Object Reference dataset can be used as an index to an HDF5 file. + +The /DS1 dataset in the following file (h5ex_t_objref.h5) is an Object Reference dataset. +It contains two references, one to group /G1 and the other to dataset /DS2: +\code +$ h5dump h5ex_t_objref.h5 +HDF5 "h5ex_t_objref.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_OBJECT } + DATASPACE SIMPLE { ( 2 ) / ( 2 ) } + DATA { + (0): GROUP 1400 /G1 , DATASET 800 /DS2 + } + } + DATASET "DS2" { + DATATYPE H5T_STD_I32LE + DATASPACE NULL + DATA { + } + } + GROUP "G1" { + } +} +} +\endcode + +\subsubsection subsubsecViewToolsViewDtypes_regref Region Reference +A Region Reference is a reference to a selection within a dataset. A selection can be either +individual elements or a hyperslab. In h5dump you will see the name of the dataset along with +the elements or slab that is selected. A dataset with a Region Reference datatype consists of +one or more Region References. + +An example of a Region Reference dataset (h5ex_t_regref.h5) can be found on the +Examples by API page, +under Datatypes. If you examine this dataset with h5dump you will see that /DS1 is a +Region Reference dataset as indicated by its datatype, highlighted in bold below: +\code +$ h5dump h5ex_t_regref.h5 +HDF5 "h5ex_t_regref.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 2 ) / ( 2 ) } + DATA { + DATASET /DS2 {(0,1), (2,11), (1,0), (2,4)}, + DATASET /DS2 {(0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)} + } + } + DATASET "DS2" { + DATATYPE H5T_STD_I8LE + DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) } + DATA { + (0,0): 84, 104, 101, 32, 113, 117, 105, 99, 107, 32, 98, 114, 111, 119, + (0,14): 110, 0, + (1,0): 102, 111, 120, 32, 106, 117, 109, 112, 115, 32, 111, 118, 101, + (1,13): 114, 32, 0, + (2,0): 116, 104, 101, 32, 53, 32, 108, 97, 122, 121, 32, 100, 111, 103, + (2,14): 115, 0 + } + } +} +} +\endcode + +It contains two Region References: +\li A selection of four individual elements in dataset /DS2 : (0,1), (2,11), (1,0), (2,4) +See the #H5Sselect_elements API in the \ref UG for information on selecting individual elements. +\li A selection of these blocks in dataset /DS2 : (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13) +See the #H5Sselect_hyperslab API in the \ref UG for how to do hyperslab selection. + + +If you look at the code that creates the dataset (h5ex_t_regref.c) you will see that the +first reference is created with these calls: +\code + status = H5Sselect_elements (space, H5S_SELECT_SET, 4, coords[0]); + status = H5Rcreate (&wdata[0], file, DATASET2, H5R_DATASET_REGION, space); +\endcode + +where the buffer containing the coordinates to select is: +\code + coords[4][2] = { {0, 1}, + {2, 11}, + {1, 0}, + {2, 4} }, +\endcode + +The second reference is created by calling, +\code + status = H5Sselect_hyperslab (space, H5S_SELECT_SET, start, stride, count, block); + status = H5Rcreate (&wdata[1], file, DATASET2, H5R_DATASET_REGION, space); +\endcode +where start, stride, count, and block have these values: +\code + start[2] = {0, 0}, + stride[2] = {2, 11}, + count[2] = {2, 2}, + block[2] = {1, 3}; +\endcode + +These start, stride, count, and block values will select the elements shown in bold in the dataset: +\code +84 104 101 32 113 117 105 99 107 32 98 114 111 119 110 0 +102 111 120 32 106 117 109 112 115 32 111 118 101 114 32 0 +116 104 101 32 53 32 108 97 122 121 32 100 111 103 115 0 +\endcode + +If you use h5dump to select a subset of dataset +/DS2 with these start, stride, count, and block values, you will see that the same elements are selected: +\code +$ h5dump -d "/DS2" -s "0,0" -S "2,11" -c "2,2" -k "1,3" h5ex_t_regref.h5 +HDF5 "h5ex_t_regref.h5" { +DATASET "/DS2" { + DATATYPE H5T_STD_I8LE + DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) } + SUBSET { + START ( 0, 0 ); + STRIDE ( 2, 11 ); + COUNT ( 2, 2 ); + BLOCK ( 1, 3 ); + DATA { + (0,0): 84, 104, 101, 114, 111, 119, + (2,0): 116, 104, 101, 100, 111, 103 + } + } +} +} +\endcode + +For more information on selections, see the tutorial topic on +@ref LBDsetSubRW. Also see the +\ref secViewToolsViewSub tutorial topic on using h5dump to view a subset. + +\subsubsection subsubsecViewToolsViewDtypes_string String +There are two types of string data, fixed length strings and variable length strings. + +Below is the h5dump output for two files that have the same strings written to them. In one file, +the strings are fixed in length, and in the other, the strings have different sizes (and are variable in size). + +Dataset of Fixed Length Strings +\code +HDF5 "h5ex_t_string.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_STRING { + STRSIZE 7; + STRPAD H5T_STR_SPACEPAD; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SIMPLE { ( 4 ) / ( 4 ) } + DATA { + (0): "Parting", "is such", "sweet ", "sorrow." + } + } +} +} +\endcode + +Dataset of Variable Length Strings +\code +HDF5 "h5ex_t_vlstring.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_STRING { + STRSIZE H5T_VARIABLE; + STRPAD H5T_STR_SPACEPAD; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SIMPLE { ( 4 ) / ( 4 ) } + DATA { + (0): "Parting", "is such", "sweet", "sorrow." + } + } +} +} +\endcode + +You might wonder which to use. Some comments to consider are included below. +\li In general, a variable length string dataset is more complex than a fixed length string. If you don't +specifically need a variable length type, then just use the fixed length string. +\li A variable length dataset consists of pointers to heaps in different locations in the file. For this +reason, a variable length dataset cannot be compressed. (Basically, the pointers get compressed and +not the actual data!) If compression is needed, then do not use variable length types. +\li If you need to create an array of of different length strings, you can either use fixed length strings +along with compression, or use a variable length string. + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand + +*/ diff --git a/doxygen/dox/ViewTools2.dox b/doxygen/dox/ViewTools2.dox new file mode 100644 index 0000000..4d8788a --- /dev/null +++ b/doxygen/dox/ViewTools2.dox @@ -0,0 +1,786 @@ +/** @page ViewToolsEdit Command-line Tools For Editing HDF5 Files +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand +
+ +\section secViewToolsEditTOC Contents +
    +
  • \ref secViewToolsEditRemove
    • +
  • \ref secViewToolsEditChange
    • +
  • \ref secViewToolsEditApply
    • +
  • \ref secViewToolsEditCopy
    • +
  • \ref secViewToolsEditAdd
    • +
+ +\section secViewToolsEditRemove Remove Inaccessible Objects and Unused Space in a File +HDF5 files may accumulate unused space when they are read and rewritten to or if objects are deleted within +them. With many edits and deletions this unused space can add up to a sizable amount. + +The h5repack tool can be used to remove unused space in an HDF5 +file. If no options other than the input and output HDF5 files are specified on the +h5repack command line, it will write the file to the new +file, getting rid of the unused space: +\code +h5repack +\endcode + +\section secViewToolsEditChange Change a Dataset's Storage Layout +The h5repack utility can be used to change a dataset's storage +layout. By default, the storage layout of a dataset is defined at creation time and it cannot be changed. +However, with h5repack you can write an HDF5 file to a new file and change the layout for objects in the new file. + +The -l option in h5repack +is used to change the layout for an object. The string following the -l +option defines the layout type and parameters for specified objects (or all objects): +\code +h5repack -l [list of objects:]= +\endcode + +If no object is specified, then everything in the input file will be written to the output file with the specified +layout type and parameters. If objects are specified then everything in the input file will be written to the +output file as is, except for those specified objects. They will be written to the output file with the given +layout type and parameters. + +Following is a description of the dataset layouts and the h5repack +options to use to change a dataset: + + + + + + + + + + + + + + + + + + + +
Storage Layouth5repack OptionDescription
Contiguous +CONTI +Data is stored physically together +
Chunked +CHUNK=DIM[xDIM...xDIM] +Data is stored in DIM[xDIM...xDIM] chunks +
Compact +COMPA +Data is stored in the header of the object (less I/O) +
+ +If you type h5repack -h on the command line, you will see +a detailed usage statement with examples of modifying the layout. + +In the following example, the dataset /dset in the file +dset.h5 is contiguous, as shown by the h5dump -pH command. +The h5repack utility writes dset.h5 to a new file, dsetrpk.h5, +where the dataset dset is chunked. This can be seen by examining +the resulting dsetrpk.h5 file with h5dump, as shown: +\code +$ h5dump -pH dset.h5 +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + STORAGE_LAYOUT { + CONTIGUOUS + SIZE 96 + OFFSET 1400 + } + FILTERS { + NONE + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 0 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_LATE + } + } +} +} + +$ h5repack -l dset:CHUNK=4x6 dset.h5 dsetrpk.h5 + +$ h5dump -pH dsetrpk.h5 +HDF5 "dsetrpk.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + STORAGE_LAYOUT { + CHUNKED ( 4, 6 ) + SIZE 96 + } + FILTERS { + NONE + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 0 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_INCR + } + } +} +} +\endcode + +There can be many reasons that the storage layout needs to be changed for a dataset. For example, +there may be a performance issue with a dataset due to a small chunk size. + +\section secViewToolsEditApply Apply Compression Filter to a Dataset +The h5repack utility can be used to compress or +remove compression from a dataset in a file. By default, compression cannot be added to or removed +from a dataset once it has been created. However, with h5repack +you can write a file to a new file and specify a compression filter to apply to a dataset or datasets in the new file. + +To apply a filter to an object in an HDF5 file, specify the -f option, +where the string following the -f option defines the filter and +its parameters (if there are any) to apply to a given object or objects: +\code +h5repack -f [list of objects:]= +\endcode + +If no objects are specified then everything in the input file will be written to the output file with +the filter and parameters specified. If objects are specified, then everything in the input file will +be written to the output file as is, except for the specified objects. They will be written to the +output file with the filter and parameters specified. + +If you type h5repack --help on the command line, +you will see a detailed usage statement with examples of modifying a filter. There are actually +numerous filters that you can apply to a dataset: + + +Options + + + + + + + + + + + + + + + + + + + + + + + + + + +
Filter
GZIP compression (levels 1-9) +GZIP=<deflation level> +
SZIP compression +SZIP= +
Shuffle filter +SHUF +
Checksum filter +FLET +
NBIT compression +NBIT +
HDF5 Scale/Offset filter +SOFF= +
User defined filter +UD= +
Remove ALL filters +NONE +
+ +Be aware that a dataset must be chunked to apply compression to it. If the dataset is not already chunked, +then h5repack will apply chunking to it. Both chunking +and compression cannot be applied to a dataset at the same time with h5repack. + +In the following example, +\li h5dump lists the properties for the objects in dset.h5. Note that the dataset dset is contiguous. +\li h5repack writes dset.h5 into a new file dsetrpk.h5, applying GZIP Level 5 compression to the dataset /dset in dsetrpk.h5. +\li h5dump lists the properties for the new dsetrpk.h5 file. Note that /dset is both compressed and chunked. + +Example +\code +$ h5dump -pH dset.h5 +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 12, 18 ) / ( 12, 18 ) } + STORAGE_LAYOUT { + CONTIGUOUS + SIZE 864 + OFFSET 1400 + } + FILTERS { + NONE + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 0 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_LATE + } + } +} +} + +$ h5repack -f dset:GZIP=5 dset.h5 dsetrpk.h5 + +$ h5dump -pH dsetrpk.h5 +HDF5 "dsetrpk.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 12, 18 ) / ( 12, 18 ) } + STORAGE_LAYOUT { + CHUNKED ( 12, 18 ) + SIZE 160 (5.400:1 COMPRESSION) + } + FILTERS { + COMPRESSION DEFLATE { LEVEL 5 } + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 0 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_INCR + } + } +} +} +\endcode + +\section secViewToolsEditCopy Copy Objects to Another File +The h5copy utility can be used to copy an object or +objects from one HDF5 file to another or to a different location in the same file. It uses the +#H5Ocopy and #H5Lcopy APIs in HDF5. + +Following are some of the options that can be used with h5copy. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
h5copy OptionsDescription
-i, --input +Input file name +
-o, --output +Output file name +
-s, --source +Source object name +
-d, --destination +Destination object name +
-p, --parents +Make parent groups as needed +
-v, --verbose +Verbose mode +
-f, --flag +Flag type +
+ +For a complete list of options and information on using h5copy, type: +\code +h5copy --help +\endcode + +In the example below, the dataset /MyGroup/Group_A/dset2 +in groups.h5 gets copied to the root +("/") group of a new file, +newgroup.h5, with the name +dset3: +\code +$h5dump -H groups.h5 +HDF5 "groups.h5" { +GROUP "/" { + GROUP "MyGroup" { + GROUP "Group_A" { + DATASET "dset2" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 2, 10 ) / ( 2, 10 ) } + } + } + GROUP "Group_B" { + } + DATASET "dset1" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) } + } + } +} +} + +$ h5copy -i groups.h5 -o newgroup.h5 -s /MyGroup/Group_A/dset2 -d /dset3 + +$ h5dump -H newgroup.h5 +HDF5 "newgroup.h5" { +GROUP "/" { + DATASET "dset3" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 2, 10 ) / ( 2, 10 ) } + } +} +} +\endcode + +There are also h5copy flags that can be specified +with the -f option. In the example below, the +-f shallow option specifies to copy only the +immediate members of the group /MyGroup from +the groups.h5 file mentioned above to a new +file mygrouponly.h5: +\code +h5copy -v -i groups.h5 -o mygrouponly.h5 -s /MyGroup -d /MyGroup -f shallow +\endcode + +The output of the above command is shown below. The verbose option -v +describes the action that was taken, as shown in the highlighted text. +\code +Copying file and object to file and object +Using shallow flag + +$ h5dump -H mygrouponly.h5 +HDF5 "mygrouponly.h5" { +GROUP "/" { + GROUP "MyGroup" { + GROUP "Group_A" { + } + GROUP "Group_B" { + } + DATASET "dset1" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) } + } + } +} +} +\endcode + +\section secViewToolsEditAdd Add or Remove User Block from File +The user block is a space in an HDF5 file that is not interpreted by the HDF5 library. It is a property +list that can be added when creating a file. See the #H5Pset_userblock API in the \ref RM for more +information regarding this property. + +Once created in a file, the user block cannot be removed. However, you can use the +h5jam and h5unjam +utilities to add or remove a user block from a file into a new file. + +These two utilities work similarly, except that h5jam +adds a user block to a file and h5unjam removes the user +block. You can also overwrite or delete a user block in a file. + +Specify the -h option to see a complete list of options +that can be used with h5jam and +h5unjam. For example: +\code + h5jam -h + h5unjam -h +\endcode + +Below are the basic options for adding or removing a user block with h5jam +and h5unjam: + + + + + + + + + + + + + + + + + +
h5copy OptionsDescription
-i +Input File +
-o +Output File +
-u +File to add or remove from user block +
+ +Let's say you wanted to add the program that creates an HDF5 file to its user block. As an example, you +can take the h5_crtgrpar.c program from the +\ref LBExamples +and add it to the file it creates, groups.h5. This can +be done with h5jam, as follows: +\code +h5jam -i groups.h5 -u h5_crtgrpar.c -o groupsub.h5 +\endcode + +You can actually view the file with more groupsub.h5 +to see that the h5_crtgrpar.c file is indeed included. + +To remove the user block that was just added, type: +\code +h5unjam -i groupsub.h5 -u h5_crtgrparNEW.c -o groups-noub.h5 +\endcode + +This writes the user block in the file groupsub.h5 +into h5_crtgrparNEW.c. The new HDF5 file, +groups-noub.h5, will not contain a user block. + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand + +*/ + +/** @page ViewToolsConvert Command-line Tools For Converting HDF5 Files +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand +
+ +\section secViewToolsConvertTOC Contents +
    +
  • \ref secViewToolsConvertASCII
    • +
  • \ref secViewToolsConvertBinary
    • +
  • \ref secViewToolsConvertExport
    • +
+ +\section secViewToolsConvertASCII Output HDF5 Dataset into an ASCII File (to Import into Excel and Other Applications) +The h5dump utility can be used to convert an HDF5 dataset +into an ASCII file, which can then be imported into Excel and other applications. The following options are used: + + + + + + + + + + + + + + + + + + + + +
OptionsDescription
-d D, --dataset=D +Display dataset D +
-o F, --output=F +Output raw data into file F +
-y, --noindex +Suppress printing of array indices with the data +
-w N, --width=N +Set N number of columns of output. A value of 0 +sets the number to 65535 (the maximum) +
+ +As an example, h5_crtdat.c from the \ref LBDsetCreate +HDF5 Tutorial topic, creates the file dset.h5 with +a dataset /dset that is a 4 x 6 integer array. The +following is displayed when viewing dset.h5 with +h5dump: +\code +$ h5dump dset.h5 +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + (0,0): 1, 2, 3, 4, 5, 6, + (1,0): 7, 8, 9, 10, 11, 12, + (2,0): 13, 14, 15, 16, 17, 18, + (3,0): 19, 20, 21, 22, 23, 24 + } + } +} +} +\endcode + +The following command will output the values of the /dset +dataset to the ASCII file dset.asci: +\code +h5dump -d /dset -o dset.asci -y -w 50 dset.h5 +\endcode + +In particular, note that: +\li The default behavior of h5dump is to print indices, +and the -y option suppresses this. +\li The -w 50 option tells +h5dump to allow 50 columns for outputting the data. The +value specified must be large enough to accommodate the dimension size of the dataset multiplied by the +number of positions and spaces needed to print each value. If the value is not large enough, the output +will wrap to the next line, and the data will not display as expected in Excel or other applications. To +ensure that the output does not wrap to the next line, you can also specify 0 (zero) for the +-w option. + +In addition to creating the ASCII file dset.asci, the +above command outputs the metadata of the specified dataset: +\code +HDF5 "dset.h5" { +DATASET "/dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + } +} +} +\endcode + +The dset.asci file will contain the values for the dataset: +\code + 1, 2, 3, 4, 5, 6, + 7, 8, 9, 10, 11, 12, + 13, 14, 15, 16, 17, 18, + 19, 20, 21, 22, 23, 24 +\endcode + +\section secViewToolsConvertBinary Output HDF5 Dataset into Binary File +The h5dump utility can be used to convert an +HDF5 dataset to a binary file with the following options: + + + + + + + + + + + + + + + + +
OptionsDescription
-d D, --dataset=D +Display dataset D +
-o F, --output=F +Output raw data into file F +
-b B, --binary=B +Binary file output of form B. +Valid values are: LE, BE, NATIVE, FILE +
+ +As an example, h5_crtdat.c from the +\ref LBDsetCreate HDF5 Tutorial topic, creates the file dset.h5 with a dataset +/dset that is a 4 x 6 integer array. The +following is displayed when viewing dset.h5 +with h5dump: +\code +$ h5dump -d /dset/ dset.h5 +HDF5 "dset.h5" { +DATASET "/dset/" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + (0,0): 1, 2, 3, 4, 5, 6, + (1,0): 7, 8, 9, 10, 11, 12, + (2,0): 13, 14, 15, 16, 17, 18, + (3,0): 19, 20, 21, 22, 23, 24 + } +} +} +\endcode + +As specified by the -d and +-o options, the following +h5dump command will output the values of the dataset +/dset to a file called +dset.bin. The -b +option specifies that the output will be binary in Little Endian format (LE). + +\code +h5dump -d /dset -b LE -o dset.bin dset.h5 +\endcode + +This command outputs the metadata for the dataset, as well as creating the binary file +dset.bin: +\code +HDF5 "dset.h5" { +DATASET "/dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + } +} +} +\endcode + +If you look at the resulting dset.bin file with +a binary editor, you will see that it contains the dataset's values. For example (on Linux) you will see: +\code +$ od -t d dset.bin +0000000 1 2 3 4 +0000020 5 6 7 8 +0000040 9 10 11 12 +0000060 13 14 15 16 +0000100 17 18 19 20 +0000120 21 22 23 24 +0000140 +\endcode + +\section secViewToolsConvertExport Export from h5dump and Import into HDF5 +The h5import utility can use the output of +h5dump as input to create a dataset or file. + +The h5dump utility must first create two files: +\li A DDL file, which will be used as an h5import configuration file +\li A raw data file containing the data to be imported + +The DDL file must be generated with the h5dump -p option, to generate properties. + +The raw data file that can be imported into HDF5 using this method may contain either numeric or string data with the following restrictions: +\li Numeric data requires the use of the h5dump -b option to produce a binary data file. +\li String data must be written with the h5dump -y and +--width=1 options, generating a single column of strings without indices. + +Two examples follow: the first imports a dataset with a numeric datatype. Note that numeric data requires +the use of the h5dump -b option to produce a binary data +file. The example program (h5_crtdat.c) that creates this +file is included with the \ref IntroHDF5 tutorial and can be obtained from the \ref LBExamples page: +\code +h5dump -p -d "/dset" --ddl=dsetbin.dmp -o dset.bin -b dset.h5 +h5import dset.bin -c dsetbin.dmp -o new-dset.h5 +\endcode + +The output before and after running these commands is shown below: +\code +$ h5dump dset.h5 +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + (0,0): 1, 2, 3, 4, 5, 6, + (1,0): 7, 8, 9, 10, 11, 12, + (2,0): 13, 14, 15, 16, 17, 18, + (3,0): 19, 20, 21, 22, 23, 24 + } + } +} +} +$ h5dump -p -d "/dset" --ddl=dsetbin.dmp -o dset.bin -b dset.h5 + +$ h5import dset.bin -c dsetbin.dmp -o new-dset.h5 + +$ h5dump new-dset.h5 +HDF5 "new-dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + (0,0): 1, 2, 3, 4, 5, 6, + (1,0): 7, 8, 9, 10, 11, 12, + (2,0): 13, 14, 15, 16, 17, 18, + (3,0): 19, 20, 21, 22, 23, 24 + } + } +} +} +\endcode + +The second example imports string data. The example program that creates this file can be downloaded +from the Examples by API page. + +Note that string data requires use of the h5dump -y +option to exclude indexes and the h5dump --width=1 +option to generate a single column of strings. The -o +option outputs the data into an ASCII file. +\code +h5dump -p -d "/DS1" -O vlstring.dmp -o vlstring.ascii -y --width=1 h5ex_t_vlstring.h5 +h5import vlstring.ascii -c vlstring.dmp -o new-vlstring.h5 +\endcode + +The output before and after running these commands is shown below: +\code +$ h5dump h5ex_t_vlstring.h5 +HDF5 "h5ex_t_vlstring.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_STRING { + STRSIZE H5T_VARIABLE; + STRPAD H5T_STR_SPACEPAD; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SIMPLE { ( 4 ) / ( 4 ) } + DATA { + (0): "Parting", "is such", "sweet", "sorrow." + } + } +} +} + +$ h5dump -p -d "/DS1" -O vlstring.dmp -o vlstring.ascii -y --width=1 h5ex_t_vlstring.h5 + +$ h5import vlstring.ascii -c vlstring.dmp -o new-vlstring.h5 + +$ h5dump new-vlstring.h5 +HDF5 "new-vlstring.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_STRING { + STRSIZE H5T_VARIABLE; + STRPAD H5T_STR_NULLTERM; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SIMPLE { ( 4 ) / ( 4 ) } + DATA { + (0): "Parting", "is such", "sweet", "sorrow." + } + } +} +\endcode + +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand + +*/ diff --git a/doxygen/dox/ViewToolsJPSS.dox b/doxygen/dox/ViewToolsJPSS.dox new file mode 100644 index 0000000..9c15395 --- /dev/null +++ b/doxygen/dox/ViewToolsJPSS.dox @@ -0,0 +1,763 @@ +/** @page ViewToolsJPSS Use Case: Examining a JPSS NPP File With HDF5 Tools +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand +
+ +\section secViewToolsJPSSTOC Contents +
    +
  • \ref secViewToolsJPSSDeter
    • +
  • \ref secViewToolsJPSSView
    • +
  • \ref secViewToolsJPSSExam
    • +
+ +This tutorial illustrates how to use the HDF5 tools to examine NPP files from the JPSS project. The following files are discussed: +\code +SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 (gzipped file) +SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 (gzipped file) +\endcode + +\section secViewToolsJPSSDeter Determining File Contents +The first thing you may want to do is determine what is in your file. You can use the command-line tools or HDFView to do this: +\li @ref subsecViewToolsJPSSDeter_h5dump +\li @ref subsecViewToolsJPSSDeter_h5ls +\li @ref subsecViewToolsJPSSDeter_HDFView + +JPSS NPP files all contain two root level groups: + + + + + + + + + + + + +
GroupDescription
/All_Data +Contains the raw data and optional geo-location information. +
/Data_Products +Contains a dataset ending in Aggr with +references to objects in the /All_Data group. +Contains granules (datasets with a name ending in Gran_#) +with references to selected regions in datasets under /All_Data. +
+ +\subsection subsecViewToolsJPSSDeter_h5dump h5dump +With h5dump you can see a list of the objects +in the file using the -n option: +\code +h5dump -n +\endcode + +For example: +\code +$ h5dump -n SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 +HDF5 "SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5" { +FILE_CONTENTS { + group / + group /All_Data + group /All_Data/VIIRS-M9-SDR_All + dataset /All_Data/VIIRS-M9-SDR_All/ModeGran + dataset /All_Data/VIIRS-M9-SDR_All/ModeScan + dataset /All_Data/VIIRS-M9-SDR_All/NumberOfBadChecksums + dataset /All_Data/VIIRS-M9-SDR_All/NumberOfDiscardedPkts + dataset /All_Data/VIIRS-M9-SDR_All/NumberOfMissingPkts + dataset /All_Data/VIIRS-M9-SDR_All/NumberOfScans + dataset /All_Data/VIIRS-M9-SDR_All/PadByte1 + dataset /All_Data/VIIRS-M9-SDR_All/QF1_VIIRSMBANDSDR + dataset /All_Data/VIIRS-M9-SDR_All/QF2_SCAN_SDR + dataset /All_Data/VIIRS-M9-SDR_All/QF3_SCAN_RDR + dataset /All_Data/VIIRS-M9-SDR_All/QF4_SCAN_SDR + dataset /All_Data/VIIRS-M9-SDR_All/QF5_GRAN_BADDETECTOR + dataset /All_Data/VIIRS-M9-SDR_All/Radiance + dataset /All_Data/VIIRS-M9-SDR_All/RadianceFactors + dataset /All_Data/VIIRS-M9-SDR_All/Reflectance + dataset /All_Data/VIIRS-M9-SDR_All/ReflectanceFactors + group /Data_Products + group /Data_Products/VIIRS-M9-SDR + dataset /Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Aggr + dataset /Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0 + dataset /Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_1 + dataset /Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_2 + dataset /Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_3 + } +} +\endcode + +In the output above you can see that there are four granules (ending in +Gran_#) in the +/Data_Products/VIIRS-M9-SDR/ group. + +\subsection subsecViewToolsJPSSDeter_h5ls h5ls +With h5ls you can see a list of the objects in the +file using the -lr +options. The h5ls utility also shows shape and size +(dataspace) information about datasets. +\code +h5ls -lr +\endcode + +For example: +\code +$ h5ls -lr SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 +/ Group +/All_Data Group +/All_Data/VIIRS-M9-SDR_All Group +/All_Data/VIIRS-M9-SDR_All/ModeGran Dataset {4/Inf} +/All_Data/VIIRS-M9-SDR_All/ModeScan Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/NumberOfBadChecksums Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/NumberOfDiscardedPkts Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/NumberOfMissingPkts Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/NumberOfScans Dataset {4/Inf} +/All_Data/VIIRS-M9-SDR_All/PadByte1 Dataset {12/Inf} +/All_Data/VIIRS-M9-SDR_All/QF1_VIIRSMBANDSDR Dataset {3072/Inf, 3200/Inf} +/All_Data/VIIRS-M9-SDR_All/QF2_SCAN_SDR Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/QF3_SCAN_RDR Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/QF4_SCAN_SDR Dataset {3072/Inf} +/All_Data/VIIRS-M9-SDR_All/QF5_GRAN_BADDETECTOR Dataset {64/Inf} +/All_Data/VIIRS-M9-SDR_All/Radiance Dataset {3072/Inf, 3200/Inf} +/All_Data/VIIRS-M9-SDR_All/RadianceFactors Dataset {8/Inf} +/All_Data/VIIRS-M9-SDR_All/Reflectance Dataset {3072/Inf, 3200/Inf} +/All_Data/VIIRS-M9-SDR_All/ReflectanceFactors Dataset {8/Inf} +/Data_Products Group +/Data_Products/VIIRS-M9-SDR Group +/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Aggr Dataset {16/Inf} +/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0 Dataset {16/Inf} +/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_1 Dataset {16/Inf} +/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_2 Dataset {16/Inf} +/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_3 Dataset {16/Inf} +\endcode +Note that the Inf indicates that those datasets are appendable or unlimited in size. + +\subsection subsecViewToolsJPSSDeter_HDFView HDFView +If you open the file in HDFView, it will display the file and the root level groups within +it in the TreeView on the left. An HDF5 file is a folder with a "5" in the middle, followed +by the file name. There are two folders (groups) within the JPSS file +(All_Data/ and Data Products/), +which you can select to see their contents: + + + + +
+\image html hdfview-tree.png +
+ +If you click twice with the left-mouse button on a folder or group in the TreeView, the contents +of the folder will be listed. If you click twice on an object such as a dataset, a window with +the object's values will be displayed. + +Underneath the VIIRS-M1-SDR folder are what HDF5 +calls datasets. The scarlet letter "A" attached +to the group and datasets under Data_Products/ +indicates that there are attributes associated with them. + +\section secViewToolsJPSSView Viewing the User Block +All JPSS files contain a user block in XML with information about the file. The user block is an +optional space allocated at the beginning of an HDF5 file that is not interpreted by the HDF5 +library. Its size is a multiple of 512. + +Since the user block in JPSS files is stored in ASCII and it is stored at the beginning of an +HDF5 file, you could use a text editor or viewer to examine it. However, there are HDF5 utilities +that can help with this: + + + + + + + + + + + + +
UtilityDescription
h5unjam +Extracts a user block from an HDF5 file +
h5dump +The -B (--superblock) option displays the size of the user block in an HDF5 file +
+ +\subsection subsecViewToolsJPSSView_h5unjam h5unjam +The \ref secViewToolsEditAdd tutorial topic discusses the use of the +h5jam and h5unjam +utilities for adding or removing a user block from a file. An input HDF5 file +(-i), output HDF5 file +(-o), and user block text file +(-u) can be specified with these tools. You can use the +h5unjam tool to extract and view the user block in a JPSS file: +\code +h5unjam -i -o -u +\endcode + +For example this command will extract the user block into the file UB.xml: +\code +$ h5unjam -i SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 + -o svm09-noUB.h5 -u UB.xml +\endcode + +The input HDF5 file remains unchanged. The output HDF5 file will not contain the user block. +The UB.xml file contains the user block +which can be viewed with a browser. + +\subsection subsecViewToolsJPSSView_h5dump h5dump +The h5dump utility has the -B (--superblock) option for displaying the superblock in an HDF5 file. +The superblock contains information about the file such as the file signature, file consistency flags, +the number of bytes to store addresses and size of an object, as well as the size of the user block: +\code +h5dump -B (--superblock) +\endcode + +Below is an example (Unix): +\code +$ h5dump -B -H SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 | more +HDF5 "SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5" { +SUPER_BLOCK { + SUPERBLOCK_VERSION 0 + FREELIST_VERSION 0 + SYMBOLTABLE_VERSION 0 + OBJECTHEADER_VERSION 0 + OFFSET_SIZE 8 + LENGTH_SIZE 8 + BTREE_RANK 16 + BTREE_LEAF 4 + ISTORE_K 32 + USER_BLOCK { + USERBLOCK_SIZE 1024 + } +} +\endcode + +Once you have the size of the user block, you can extract it from the file using system commands. +For example, on Unix platforms you can use the head command-line tool: +\code +head -c >& USERBLOCK.xml +\endcode + +There are Unix tools for Windows that may work, such as CoreUtils for Windows. + +\section secViewToolsJPSSExam Examining a Granule +
    +
  • @ref subsecViewToolsJPSSExam_h5dump
    +
      +
    • @ref subsubsecViewToolsJPSSExam_h5dumpRegRef
      • +
    • @ref subsubsecViewToolsJPSSExam_h5dumpQuality
      • +
    • @ref subsubsecViewToolsJPSSExam_h5dumpProps
      • +
    • +
  • @ref subsecViewToolsJPSSExamr_HDFView
    • +
+ +\subsection subsecViewToolsJPSSExam_h5dump h5dump +There are several options that you may first want to use when examining a granule with h5dump: + + + + + + + + + + + + + + + + + + + + +
OptionDescription
-H, --header +Prints header (metadata) information only +
-d D, --dataset=D +Specifies the granule dataset +
-A 0, --onlyattr=0 +Suppresses attributes +
-p, --properties +Show properties of datasets +(See Properties) +
+ +You would specify the dataset (-d D) and the +-H options to view the metadata associated with +a specific granule. There are many attributes associated with a granule and +-A 0 can be used to suppress those. + +For example: +\code +h5dump -H -A 0 -d "/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0" + SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 +\endcode + +This command displays: +\code + HDF5 "SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5" { + DATASET "/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } + } + } +\endcode + +To see the actual contents of the granule remove the -H option: +\code +h5dump -A 0 -d "/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0" + SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 +\endcode + +The above command displays: +\code +HDF5 "SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5" { +DATASET "/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } + DATA { + DATASET /All_Data/VIIRS-M9-SDR_All/Radiance {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M9-SDR_All/Reflectance {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M9-SDR_All/ModeScan {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/ModeGran {(0)-(0)}, + DATASET /All_Data/VIIRS-M9-SDR_All/PadByte1 {(0)-(2)}, + DATASET /All_Data/VIIRS-M9-SDR_All/NumberOfScans {(0)-(0)}, + DATASET /All_Data/VIIRS-M9-SDR_All/NumberOfMissingPkts {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/NumberOfBadChecksums {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/NumberOfDiscardedPkts {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/QF1_VIIRSMBANDSDR {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M9-SDR_All/QF2_SCAN_SDR {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/QF3_SCAN_RDR {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/QF4_SCAN_SDR {(0)-(767)}, + DATASET /All_Data/VIIRS-M9-SDR_All/QF5_GRAN_BADDETECTOR {(0)-(15)}, + DATASET /All_Data/VIIRS-M9-SDR_All/RadianceFactors {(0)-(1)}, + DATASET /All_Data/VIIRS-M9-SDR_All/ReflectanceFactors {(0)-(1)} + } +} +} +\endcode + +As you can see in the output above, the datatype for this dataset is: +\code +DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } +\endcode + +This indicates that it is a dataset specifically for storing references to regions (or subsets) +in other datasets. The dataset contains 16 such references, and more can be added to it, as +indicated by the dataspace (in other words it is unlimited): +\code +DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } +\endcode + +\subsubsection subsubsecViewToolsJPSSExam_h5dumpRegRef Viewing a Region Reference +What if we wanted to look at the NumberOfScans data for a specific granule in a file? + +First, we may be interested in determining whether the scans were done at night or in the day. If a scan was at night, there will be no data. + +The attribute N_Day_Night_Flag is used to determine when the scan was done. If you don't know where this attribute is located, you can use the -N option to search for it in the file. If you were to run this command on the SVM09 file used above, you would see that the N_Day_Night_Flag attribute has a value of Night for the four granules in the file. Indeed, if you actually examine the NumberOfScans data, you will see that only fill values are written. + +For that reason we will examine the NumberOfScans data for the SVMO1 file below, as it was obtained during the day: +\code +h5dump -N N_Day_Night_Flag SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +\endcode + +It displays: +\code +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +ATTRIBUTE "N_Day_Night_Flag" { + DATATYPE H5T_STRING { + STRSIZE 4; + STRPAD H5T_STR_NULLTERM; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SIMPLE { ( 1, 1 ) / ( 1, 1 ) } + DATA { + (0,0): "Day" + } +} +} +\endcode + +There is just one granule in this SVM01 file, as shown below: +\code +$ h5dump -n SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +FILE_CONTENTS { + group / + group /All_Data + group /All_Data/VIIRS-M1-SDR_All + dataset /All_Data/VIIRS-M1-SDR_All/ModeGran + dataset /All_Data/VIIRS-M1-SDR_All/ModeScan + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfBadChecksums + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfDiscardedPkts + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfMissingPkts + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfScans + dataset /All_Data/VIIRS-M1-SDR_All/PadByte1 + dataset /All_Data/VIIRS-M1-SDR_All/QF1_VIIRSMBANDSDR + dataset /All_Data/VIIRS-M1-SDR_All/QF2_SCAN_SDR + dataset /All_Data/VIIRS-M1-SDR_All/QF3_SCAN_RDR + dataset /All_Data/VIIRS-M1-SDR_All/QF4_SCAN_SDR + dataset /All_Data/VIIRS-M1-SDR_All/QF5_GRAN_BADDETECTOR + dataset /All_Data/VIIRS-M1-SDR_All/Radiance + dataset /All_Data/VIIRS-M1-SDR_All/RadianceFactors + dataset /All_Data/VIIRS-M1-SDR_All/Reflectance + dataset /All_Data/VIIRS-M1-SDR_All/ReflectanceFactors + group /Data_Products + group /Data_Products/VIIRS-M1-SDR + dataset /Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Aggr + dataset /Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0 + } +} +\endcode + +Now examine the references in the VIIRS-M1-SDR_Gran_0 granule +\code +$ h5dump -A 0 -d "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" + SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +DATASET "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } + DATA { + DATASET /All_Data/VIIRS-M1-SDR_All/Radiance {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M1-SDR_All/Reflectance {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M1-SDR_All/ModeScan {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/ModeGran {(0)-(0)}, + DATASET /All_Data/VIIRS-M1-SDR_All/PadByte1 {(0)-(2)}, + DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfScans {(0)-(0)}, + DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfMissingPkts {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfBadChecksums {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfDiscardedPkts {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/QF1_VIIRSMBANDSDR {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M1-SDR_All/QF2_SCAN_SDR {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/QF3_SCAN_RDR {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/QF4_SCAN_SDR {(0)-(767)}, + DATASET /All_Data/VIIRS-M1-SDR_All/QF5_GRAN_BADDETECTOR {(0)-(15)}, + DATASET /All_Data/VIIRS-M1-SDR_All/RadianceFactors {(0)-(1)}, + DATASET /All_Data/VIIRS-M1-SDR_All/ReflectanceFactors {(0)-(1)} + } +} +} +\endcode + +In the output above, you can see that the NumberOfScans +reference is the sixth reference in the granule counting from the top. + +The list of references shown above is a 0-based index to the dataset. Therefore, to specify +NumberOfScans, enter a start offset of +5 for the -s +option (the sixth reference minus 1). To see the region reference data, use the -R option. + +This command will display the data in the NumberOfScans region reference: +\code +h5dump -A 0 -d "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" -s 5 -R + SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +\endcode + +It displays the number of scans (48): +\code +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +DATASET "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } + SUBSET { + START ( 5 ); + STRIDE ( 1 ); + COUNT ( 1 ); + BLOCK ( 1 ); + DATA { + (5): DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfScans { + (5): REGION_TYPE BLOCK (0)-(0) + (5): DATATYPE H5T_STD_I32BE + (5): DATASPACE SIMPLE { ( 1 ) / ( H5S_UNLIMITED ) } + (5): DATA { + (0): 48 + (5): } + (5): } + } + } +} +} +\endcode + +The -s option may be familiar as one of the options +that was described in the \ref secViewToolsViewSub tutorial topic. The other subsetting options are not included, +indicating that the default values are used. + +If you leave off the -R option, you will see the subset selection, but not the data: +\code +$ h5dump -A 0 -d "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" -s 5 + SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +DATASET "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } + SUBSET { + START ( 5 ); + STRIDE ( 1 ); + COUNT ( 1 ); + BLOCK ( 1 ); + DATA { + DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfScans {(0)-(0)} + } + } +} +} +\endcode + +\subsubsection subsubsecViewToolsJPSSExam_h5dumpQuality Viewing a Quality Flag +The quality flags in an NPP file can be viewed with h5dump using the -M +option. Quality flags are packed into each integer value in a quality flag dataset. Quality flag datasets in NPP +files begin with the letters QF. + +In the following NPP file, there are five Quality Flag datasets +(/All_Data/VIIRS-M1-SDR_All/QF*): +\code +$ h5dump -n SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +FILE_CONTENTS { + group / + group /All_Data + group /All_Data/VIIRS-M1-SDR_All + dataset /All_Data/VIIRS-M1-SDR_All/ModeGran + dataset /All_Data/VIIRS-M1-SDR_All/ModeScan + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfBadChecksums + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfDiscardedPkts + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfMissingPkts + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfScans + dataset /All_Data/VIIRS-M1-SDR_All/PadByte1 + dataset /All_Data/VIIRS-M1-SDR_All/QF1_VIIRSMBANDSDR + dataset /All_Data/VIIRS-M1-SDR_All/QF2_SCAN_SDR + dataset /All_Data/VIIRS-M1-SDR_All/QF3_SCAN_RDR + dataset /All_Data/VIIRS-M1-SDR_All/QF4_SCAN_SDR + dataset /All_Data/VIIRS-M1-SDR_All/QF5_GRAN_BADDETECTOR + dataset /All_Data/VIIRS-M1-SDR_All/Radiance + dataset /All_Data/VIIRS-M1-SDR_All/RadianceFactors + dataset /All_Data/VIIRS-M1-SDR_All/Reflectance + dataset /All_Data/VIIRS-M1-SDR_All/ReflectanceFactors + group /Data_Products + group /Data_Products/VIIRS-M1-SDR + dataset /Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Aggr + dataset /Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0 + } +} +\endcode + +The flags in this particular dataset happen to be stored in every two bits of each quality flag dataset +element, and the values range from 0 to 2. In other words, to see the quality flag values for this +dataset, these bits would be examined: 0 and 1, 2 and 3, 4 and 5, or 6 and 7 (This information was +obtained from the Product Profile XML File.) + +For example, bits 0 and 1 in the VQF1_VIIRSMBANDSDR dataset specify the flag that +"Indicates calibration quality due to bad space view offsets, OBC view offsets, etc or use of a +previous calibration view". It has 3 values: Good (0), Poor (1), or No Calibration (2). + +The -M option is used to specify the quality +flag bit offset (O) and length (L): +\code +h5dump -d DATASET -M O,L FILE +\endcode + +To view the first quality flag (0-1) in a 5 x 6 subset of the QF1_VIIRSMBANDSDR dataset, specify: +\code +h5dump -d "/All_Data/VIIRS-M1-SDR_All/QF1_VIIRSMBANDSDR[0,0;;5,6;]" + -M 0,2 SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +\endcode + +This outputs: +\code +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +DATASET "/All_Data/VIIRS-M1-SDR_All/QF1_VIIRSMBANDSDR" { + DATATYPE H5T_STD_U8BE + DATASPACE SIMPLE { ( 768, 3200 ) / ( H5S_UNLIMITED, H5S_UNLIMITED ) } + PACKED_BITS OFFSET=0 LENGTH=2 + SUBSET { + START ( 0, 0 ); + STRIDE ( 1, 1 ); + COUNT ( 5, 6 ); + BLOCK ( 1, 1 ); + DATA { + (0,0): 2, 2, 2, 2, 2, 2, + (1,0): 2, 2, 2, 2, 2, 2, + (2,0): 0, 0, 0, 0, 0, 0, + (3,0): 0, 0, 0, 0, 0, 0, + (4,0): 0, 0, 0, 0, 0, 0 + } + } +} +} +\endcode + +To view more than one quality flag at a time simply add the bit offset and length values to +-M, separated by commas. For example, this +-M option specifies bits 0-1 and 2-3: +\code +h5dump -d DATASET -M 0,2,2,2 FILE +\endcode + +\subsubsection subsubsecViewToolsJPSSExam_h5dumpProps Properties +To view properties of a specific dataset with h5dump +use the -p option along with the +-d option. Depending on the number of attributes +and the amount of data, the -A 0 and +-H options can also be specified to suppress +printing of attributes and data values: +\code +h5dump -p -H -A 0 -d DATASET +\endcode + +The -p option shows any compression filters +associated with a dataset, as well as layout and fill value information. This option can be helpful +in diagnosing performance and other issues. + +As an example, examine the /All_Data/VIIRS-M1-SDR_All/Radiance +dataset in the SVM01 file: +\code +$ h5dump -p -H -A 0 -d "/All_Data/VIIRS-M1-SDR_All/Radiance" + SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +DATASET "/All_Data/VIIRS-M1-SDR_All/Radiance" { + DATATYPE H5T_STD_U16BE + DATASPACE SIMPLE { ( 768, 3200 ) / ( H5S_UNLIMITED, H5S_UNLIMITED ) } + STORAGE_LAYOUT { + CHUNKED ( 768, 3200 ) + SIZE 4915200 + } + FILTERS { + NONE + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 65529 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_INCR + } +} +} +\endcode + +We can see that the chunk size for this dataset is 768 x 3200, and the storage size is 4915200. + +What if the chunk size were smaller? + +The dataset was modified to have a chunk size of 1 x 10, using the +h5repack utility, as shown below. +\code +$ h5repack -l /All_Data/VIIRS-M1-SDR_All/Radiance:CHUNK=1x10 + SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 SVM01repack.h5 + +$ h5dump -p -H -A 0 -d "/All_Data/VIIRS-M1-SDR_All/Radiance" SVM01repack.h5 +HDF5 "SVM01repack.h5" { +DATASET "/All_Data/VIIRS-M1-SDR_All/Radiance" { + DATATYPE H5T_STD_U16BE + DATASPACE SIMPLE { ( 768, 3200 ) / ( H5S_UNLIMITED, H5S_UNLIMITED ) } + STORAGE_LAYOUT { + CHUNKED ( 1, 10 ) + SIZE 4915200 + } + FILTERS { + NONE + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 65529 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_INCR + } +} +} +\endcode + +In this case, the storage size of the dataset is the same, but the size of the file almost doubled!: +\code +$ ls -1sh +total 35M +12M SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +23M SVM01repack.h5 +\endcode + +In general, the smaller the chunk size, the more chunks that HDF5 has to keep track of, which increases +the size of the file and can affect performance. + +\subsection subsecViewToolsJPSSExamr_HDFView HDFView +As mentioned previously, the structure of an HDF5 file is displayed in the TreeView on the left side of the HDFView screen, +and you can click on objects and have metadata information displayed on the right side. + +To discover more about the granule /Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0 +in the SVM01 file shown below in the TreeView, position +the mouse over the granule and click to select. Properties for the object is displayed on the right side of the HDFView screen. +You can see Datatype and Dataspace information on the General Object Info +tab, any Attributes associated with the granulewill be on the +Object Attribute Info tab. In the +General Object Info, you can see that the dataset is a +Region Reference dataset, and that there are sixteen Region References in this dataset: + + + + +
+\image html hdfview-prop.png +
+ +To examine the data in the granule, click twice on it with the left mouse button in the TreeView, +and it will open in a new window.: + + + + +
+\image html hdfview-regref.png +
+ +If you click twice with the left mouse button on the fifth Region Reference +/All_Data/VIIRS-M1-SDR_All/NumberOfScans a window +will pop up with the value(s) of the reference: + + + + +
+\image html hdfview-regref2.png +
+ +You can also set a user option to automatically show the value(s) in a Region Reference. Under the +Tools pull-down menu, select +User Options and then select +HDF Settings and then select +Show RegRef Values in the +Data section (see the middle of the image below): + + + + +
+\image html hdfview-regrefval.png +
+ +Then you will automatically see the values of the Region Reference when you open it and select an entry: + + + + +
+\image html hdfview-regref1.png +
+ +You can view and set quality flags by clicking the right mouse button over a quality flags dataset under +All_Data and selecting +Open As from the pop-up menu. In the middle of +the window that pops up, you will see where you can specify Bitmask options. + + + + +
+\image html hdfview-qf.png +
+ +
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand + +*/ diff --git a/doxygen/examples/fortran_menu.md b/doxygen/examples/fortran_menu.md index 335a21a..8ef4ead 100644 --- a/doxygen/examples/fortran_menu.md +++ b/doxygen/examples/fortran_menu.md @@ -1,61 +1,73 @@ Fortran Library -- H5A "Attributes (H5A)" +- @ref FH5A "Attributes (H5A)"
HDF5 attribute is a small metadata object describing the nature and/or intended usage of a primary data object. -- H5D "Datasets (H5D)" +- @ref FH5D "Datasets (H5D)"
Manage HDF5 datasets, including the transfer of data between memory and disk and the description of dataset properties. -- H5S "Dataspaces (H5S)" +- @ref FH5S "Dataspaces (H5S)"
HDF5 dataspaces describe the shape of datasets in memory or in HDF5 files. -- H5T "Datatypes (H5T)" +- @ref FH5T "Datatypes (H5T)"
HDF5 datatypes describe the element type of HDF5 datasets and attributes. -- H5E "Error Handling (H5E)" +- @ref FH5E "Error Handling (H5E)"
HDF5 library error reporting. -- H5F "Files (H5F)" +- @ref FH5F "Files (H5F)"
Manage HDF5 files. -- H5Z "Filters (H5Z)" +- @ref FH5Z "Filters (H5Z)"
Manage HDF5 user-defined filters -- H5G "Groups (H5G)" +- @ref FH5G "Groups (H5G)"
Manage HDF5 groups. -- H5I "Identifiers (H5I)" +- @ref FH5I "Identifiers (H5I)"
Manage identifiers defined by the HDF5 library. -- H5 "Library General (H5)" +- @ref FH5 "Library General (H5)"
Manage the life cycle of HDF5 library instances. -- H5L "Links (H5L)" +- @ref FH5L "Links (H5L)"
Manage HDF5 links and link types. -- H5O "Objects (H5O)" +- @ref FH5O "Objects (H5O)"
Manage HDF5 objects (groups, datasets, datatype objects). -- H5P "Property Lists (H5P)" +- @ref FH5P "Property Lists (H5P)"
HDF5 property lists are the main vehicle to configure the behavior of HDF5 API functions. -- H5PL "Dynamically-loaded Plugins (H5PL)" +- @ref FH5R "References (H5R)"
-Manage the loading behavior of HDF5 plugins. +Manage HDF5 references (HDF5 objects, attributes, and selections on datasets a.k.a. dataset regions). -- H5R "References (H5R)" +- @ref FH5LT "High Level Lite (H5LT)"
-Manage HDF5 references (HDF5 objects, attributes, and selections on datasets a.k.a. dataset regions). +Functions to simplify creating and manipulating datasets, attributes and other features + +- @ref FH5IM "High Level Image (H5IM)" +
+Creating and manipulating HDF5 datasets intended to be interpreted as images + +- @ref FH5TB "High Level Table (H5TB)" +
+Creating and manipulating HDF5 datasets intended to be interpreted as tables + +- @ref FH5DS "High Level Dimension Scale (H5DS)" +
+Creating and manipulating HDF5 datasets that are associated with the dimension of another HDF5 dataset diff --git a/doxygen/examples/high_level_menu.md b/doxygen/examples/high_level_menu.md index 9e6f696..d209bf4 100644 --- a/doxygen/examples/high_level_menu.md +++ b/doxygen/examples/high_level_menu.md @@ -3,27 +3,27 @@ The high-level HDF5 library includes several sets of convenience and standard-use APIs to facilitate common HDF5 operations. -- @ref H5LT "Lite (H5LT, H5LD)" +- @ref H5LT
Functions to simplify creating and manipulating datasets, attributes and other features -- @ref H5IM "Image (H5IM)" +- @ref H5IM
Creating and manipulating HDF5 datasets intended to be interpreted as images -- @ref H5TB "Table (H5TB)" +- @ref H5TB
Creating and manipulating HDF5 datasets intended to be interpreted as tables -- @ref H5PT "Packet Table (H5PT)" +- @ref H5PT
Creating and manipulating HDF5 datasets to support append- and read-only operations on table data -- @ref H5DS "Dimension Scale (H5DS)" +- @ref H5DS
Creating and manipulating HDF5 datasets that are associated with the dimension of another HDF5 dataset -- @ref H5DO "Optimizations (H5DO)" +- @ref H5DO
Bypassing default HDF5 behavior in order to optimize for specific use cases diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml index 20e0123..f7c47bf 100644 --- a/doxygen/hdf5doxy_layout.xml +++ b/doxygen/hdf5doxy_layout.xml @@ -3,7 +3,7 @@ - + diff --git a/doxygen/img/DataGroup.png b/doxygen/img/DataGroup.png new file mode 100644 index 0000000..4edeba3 Binary files /dev/null and b/doxygen/img/DataGroup.png differ diff --git a/doxygen/img/LBDsetSubRWProg.png b/doxygen/img/LBDsetSubRWProg.png new file mode 100644 index 0000000..4627740 Binary files /dev/null and b/doxygen/img/LBDsetSubRWProg.png differ diff --git a/doxygen/img/StormDataset.png b/doxygen/img/StormDataset.png new file mode 100644 index 0000000..da44335 Binary files /dev/null and b/doxygen/img/StormDataset.png differ diff --git a/doxygen/img/cmpnddtype.png b/doxygen/img/cmpnddtype.png new file mode 100644 index 0000000..53b4afd Binary files /dev/null and b/doxygen/img/cmpnddtype.png differ diff --git a/doxygen/img/crtatt.png b/doxygen/img/crtatt.png new file mode 100644 index 0000000..93ac36c Binary files /dev/null and b/doxygen/img/crtatt.png differ diff --git a/doxygen/img/crtdset.png b/doxygen/img/crtdset.png new file mode 100644 index 0000000..9cc3085 Binary files /dev/null and b/doxygen/img/crtdset.png differ diff --git a/doxygen/img/crtf-pic.png b/doxygen/img/crtf-pic.png new file mode 100644 index 0000000..f7c49b8 Binary files /dev/null and b/doxygen/img/crtf-pic.png differ diff --git a/doxygen/img/crtgrp.png b/doxygen/img/crtgrp.png new file mode 100644 index 0000000..506bc68 Binary files /dev/null and b/doxygen/img/crtgrp.png differ diff --git a/doxygen/img/dataset.png b/doxygen/img/dataset.png new file mode 100644 index 0000000..1524417 Binary files /dev/null and b/doxygen/img/dataset.png differ diff --git a/doxygen/img/datasetwdata.png b/doxygen/img/datasetwdata.png new file mode 100644 index 0000000..5f03827 Binary files /dev/null and b/doxygen/img/datasetwdata.png differ diff --git a/doxygen/img/dataspace.png b/doxygen/img/dataspace.png new file mode 100644 index 0000000..95e0b7d Binary files /dev/null and b/doxygen/img/dataspace.png differ diff --git a/doxygen/img/dataspace1.png b/doxygen/img/dataspace1.png new file mode 100644 index 0000000..f21a5f5 Binary files /dev/null and b/doxygen/img/dataspace1.png differ diff --git a/doxygen/img/datatype.png b/doxygen/img/datatype.png new file mode 100644 index 0000000..6ea5732 Binary files /dev/null and b/doxygen/img/datatype.png differ diff --git a/doxygen/img/fileobj.png b/doxygen/img/fileobj.png new file mode 100644 index 0000000..ae5212d Binary files /dev/null and b/doxygen/img/fileobj.png differ diff --git a/doxygen/img/group.png b/doxygen/img/group.png new file mode 100644 index 0000000..7fec7fc Binary files /dev/null and b/doxygen/img/group.png differ diff --git a/doxygen/img/hdfview-anthrstrm-img.png b/doxygen/img/hdfview-anthrstrm-img.png new file mode 100644 index 0000000..add4e48 Binary files /dev/null and b/doxygen/img/hdfview-anthrstrm-img.png differ diff --git a/doxygen/img/hdfview-anthrstrm-sprdsht.png b/doxygen/img/hdfview-anthrstrm-sprdsht.png new file mode 100644 index 0000000..4584fd5 Binary files /dev/null and b/doxygen/img/hdfview-anthrstrm-sprdsht.png differ diff --git a/doxygen/img/hdfview-anthrstrm.png b/doxygen/img/hdfview-anthrstrm.png new file mode 100644 index 0000000..afc2de3 Binary files /dev/null and b/doxygen/img/hdfview-anthrstrm.png differ diff --git a/doxygen/img/hdfview-imgicon.png b/doxygen/img/hdfview-imgicon.png new file mode 100644 index 0000000..f189080 Binary files /dev/null and b/doxygen/img/hdfview-imgicon.png differ diff --git a/doxygen/img/hdfview-imgprop.png b/doxygen/img/hdfview-imgprop.png new file mode 100644 index 0000000..717727b Binary files /dev/null and b/doxygen/img/hdfview-imgprop.png differ diff --git a/doxygen/img/hdfview-imgsubset.png b/doxygen/img/hdfview-imgsubset.png new file mode 100644 index 0000000..19cec57 Binary files /dev/null and b/doxygen/img/hdfview-imgsubset.png differ diff --git a/doxygen/img/hdfview-newcmpd.png b/doxygen/img/hdfview-newcmpd.png new file mode 100644 index 0000000..b07b5f8 Binary files /dev/null and b/doxygen/img/hdfview-newcmpd.png differ diff --git a/doxygen/img/hdfview-newimgsubset.png b/doxygen/img/hdfview-newimgsubset.png new file mode 100644 index 0000000..fd16b23 Binary files /dev/null and b/doxygen/img/hdfview-newimgsubset.png differ diff --git a/doxygen/img/hdfview-prop.png b/doxygen/img/hdfview-prop.png new file mode 100644 index 0000000..16c0904 Binary files /dev/null and b/doxygen/img/hdfview-prop.png differ diff --git a/doxygen/img/hdfview-qf.png b/doxygen/img/hdfview-qf.png new file mode 100644 index 0000000..edc371f Binary files /dev/null and b/doxygen/img/hdfview-qf.png differ diff --git a/doxygen/img/hdfview-regref.png b/doxygen/img/hdfview-regref.png new file mode 100644 index 0000000..7f2b02a Binary files /dev/null and b/doxygen/img/hdfview-regref.png differ diff --git a/doxygen/img/hdfview-regref1.png b/doxygen/img/hdfview-regref1.png new file mode 100644 index 0000000..f754931 Binary files /dev/null and b/doxygen/img/hdfview-regref1.png differ diff --git a/doxygen/img/hdfview-regref2.png b/doxygen/img/hdfview-regref2.png new file mode 100644 index 0000000..5a73c01 Binary files /dev/null and b/doxygen/img/hdfview-regref2.png differ diff --git a/doxygen/img/hdfview-regrefval.png b/doxygen/img/hdfview-regrefval.png new file mode 100644 index 0000000..e0a666b Binary files /dev/null and b/doxygen/img/hdfview-regrefval.png differ diff --git a/doxygen/img/hdfview-table.png b/doxygen/img/hdfview-table.png new file mode 100644 index 0000000..69301bc Binary files /dev/null and b/doxygen/img/hdfview-table.png differ diff --git a/doxygen/img/hdfview-tree.png b/doxygen/img/hdfview-tree.png new file mode 100644 index 0000000..8ba2621 Binary files /dev/null and b/doxygen/img/hdfview-tree.png differ diff --git a/doxygen/img/imgLBDsetCreate.gif b/doxygen/img/imgLBDsetCreate.gif new file mode 100644 index 0000000..67585ef Binary files /dev/null and b/doxygen/img/imgLBDsetCreate.gif differ diff --git a/doxygen/img/imgLBDsetSubRW11.png b/doxygen/img/imgLBDsetSubRW11.png new file mode 100644 index 0000000..8b1df86 Binary files /dev/null and b/doxygen/img/imgLBDsetSubRW11.png differ diff --git a/doxygen/img/imgLBDsetSubRW12.png b/doxygen/img/imgLBDsetSubRW12.png new file mode 100644 index 0000000..976966a Binary files /dev/null and b/doxygen/img/imgLBDsetSubRW12.png differ diff --git a/doxygen/img/imgLBDsetSubRW31.png b/doxygen/img/imgLBDsetSubRW31.png new file mode 100644 index 0000000..31d5098 Binary files /dev/null and b/doxygen/img/imgLBDsetSubRW31.png differ diff --git a/doxygen/img/imgLBDsetSubRW32.png b/doxygen/img/imgLBDsetSubRW32.png new file mode 100644 index 0000000..f7d82fd Binary files /dev/null and b/doxygen/img/imgLBDsetSubRW32.png differ diff --git a/doxygen/img/imgLBDsetSubRW33.png b/doxygen/img/imgLBDsetSubRW33.png new file mode 100644 index 0000000..69a368b Binary files /dev/null and b/doxygen/img/imgLBDsetSubRW33.png differ diff --git a/doxygen/img/imgLBFile.gif b/doxygen/img/imgLBFile.gif new file mode 100644 index 0000000..b79c6d6 Binary files /dev/null and b/doxygen/img/imgLBFile.gif differ diff --git a/doxygen/img/imggrpcreate.gif b/doxygen/img/imggrpcreate.gif new file mode 100644 index 0000000..ac1dcf9 Binary files /dev/null and b/doxygen/img/imggrpcreate.gif differ diff --git a/doxygen/img/imggrpdsets.gif b/doxygen/img/imggrpdsets.gif new file mode 100644 index 0000000..3383dc6 Binary files /dev/null and b/doxygen/img/imggrpdsets.gif differ diff --git a/doxygen/img/imggrps.gif b/doxygen/img/imggrps.gif new file mode 100644 index 0000000..d48dbab Binary files /dev/null and b/doxygen/img/imggrps.gif differ diff --git a/doxygen/img/newgroupimage.png b/doxygen/img/newgroupimage.png new file mode 100644 index 0000000..7bc4c90 Binary files /dev/null and b/doxygen/img/newgroupimage.png differ diff --git a/doxygen/img/noattrs.png b/doxygen/img/noattrs.png new file mode 100644 index 0000000..13abcc5 Binary files /dev/null and b/doxygen/img/noattrs.png differ diff --git a/doxygen/img/properties.png b/doxygen/img/properties.png new file mode 100644 index 0000000..083dc14 Binary files /dev/null and b/doxygen/img/properties.png differ diff --git a/doxygen/img/scarletletter.png b/doxygen/img/scarletletter.png new file mode 100644 index 0000000..7c5d2e6 Binary files /dev/null and b/doxygen/img/scarletletter.png differ diff --git a/doxygen/img/showasimage.png b/doxygen/img/showasimage.png new file mode 100644 index 0000000..8377292 Binary files /dev/null and b/doxygen/img/showasimage.png differ diff --git a/doxygen/img/storm.png b/doxygen/img/storm.png new file mode 100644 index 0000000..769b037 Binary files /dev/null and b/doxygen/img/storm.png differ diff --git a/doxygen/img/tutr-lochk.png b/doxygen/img/tutr-lochk.png new file mode 100644 index 0000000..297cd6d Binary files /dev/null and b/doxygen/img/tutr-lochk.png differ diff --git a/doxygen/img/tutr-lochks.png b/doxygen/img/tutr-lochks.png new file mode 100644 index 0000000..477fc1d Binary files /dev/null and b/doxygen/img/tutr-lochks.png differ diff --git a/doxygen/img/tutr-locons.png b/doxygen/img/tutr-locons.png new file mode 100644 index 0000000..bea5be4 Binary files /dev/null and b/doxygen/img/tutr-locons.png differ diff --git a/doxygen/img/vol_architecture.png b/doxygen/img/vol_architecture.png new file mode 100755 index 0000000..10e5596 Binary files /dev/null and b/doxygen/img/vol_architecture.png differ diff --git a/fortran/src/H5Aff.F90 b/fortran/src/H5Aff.F90 index 53f0a39..e167b7f 100644 --- a/fortran/src/H5Aff.F90 +++ b/fortran/src/H5Aff.F90 @@ -1,13 +1,13 @@ -!****h* ROBODoc/H5A -! -! NAME -! MODULE H5A -! -! PURPOSE -! This file contains Fortran interfaces for H5A functions. It includes -! all the functions that are independent on whether the Fortran 2003 functions -! are enabled or disabled. -! +!> @defgroup FH5A Fortran Attribute (H5A) Interface +!! +!! @see H5A, C-API +!! +!! @see @ref H5A_UG, User Guide +!! + +!> @ingroup FH5A +!! +!! @brief This module contains Fortran interfaces for H5A functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -66,7 +66,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** #include @@ -79,6 +78,7 @@ MODULE H5A PRIVATE h5awrite_char_scalar, h5awrite_ptr PRIVATE h5aread_char_scalar, h5aread_ptr +#ifndef H5_DOXYGEN_FORTRAN INTERFACE h5awrite_f MODULE PROCEDURE h5awrite_char_scalar ! This is the preferred way to call h5awrite @@ -118,56 +118,36 @@ MODULE H5A TYPE(C_PTR), VALUE :: buf END FUNCTION h5aread_f_c END INTERFACE +#endif CONTAINS -! -!****s* H5A/h5acreate_f -! -! NAME -! h5acreate_f -! -! PURPOSE -! Creates a dataset as an attribute of a group, dataset, or named datatype -! -! INPUTS -! loc_id - identifier of an object (group, dataset, -! or named datatype) attribute is attached to -! name - attribute name -! type_id - attribute datatype identifier -! space_id - attribute dataspace identifier -! -! OUTPUTS -! attr_id - attribute identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! acpl_id - Attribute creation property list identifier -! appl_id - Attribute access property list identifier -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces are added for -! called C functions (it is needed for Windows -! port). February 27, 2001 -! -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Creates a dataset as an attribute of a group, dataset, or named datatype +!! +!! \param loc_id Identifier of an object (group, dataset, or named datatype) attribute is attached to +!! \param name Attribute name +!! \param type_id Attribute datatype identifier +!! \param space_id Attribute dataspace identifier +!! \param attr_id Attribute identifier +!! \param hdferr \fortran_error +!! \param acpl_id Attribute creation property list identifier +!! \param aapl_id Attribute access property list identifier +!! SUBROUTINE h5acreate_f(loc_id, name, type_id, space_id, attr_id, & hdferr, acpl_id, aapl_id ) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Object identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Attribute name - INTEGER(HID_T), INTENT(IN) :: type_id ! Attribute datatype identifier - INTEGER(HID_T), INTENT(IN) :: space_id ! Attribute dataspace identifier - INTEGER(HID_T), INTENT(OUT) :: attr_id ! Attribute identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure -!***** - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: acpl_id ! Attribute creation property list identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: aapl_id ! Attribute access property list identifier + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER(HID_T), INTENT(IN) :: space_id + INTEGER(HID_T), INTENT(OUT) :: attr_id + INTEGER, INTENT(OUT) :: hdferr + + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: acpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: aapl_id INTEGER(HID_T) :: acpl_id_default INTEGER(HID_T) :: aapl_id_default @@ -200,40 +180,24 @@ CONTAINS END SUBROUTINE h5acreate_f -! -!****s* H5A/h5aopen_name_f -! -! NAME -! h5aopen_name_f -! -! PURPOSE -! Opens an attribute specified by name. -! -! INPUTS -! obj_id - identifier of a group, dataset, or named -! datatype attribute to be attached to -! name - attribute name -! OUTPUTS -! attr_id - attribute identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces are added for -! called C functions (it is needed for Windows -! port). February 27, 2001 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Opens an attribute specified by name. +!! +!! \param obj_id Identifier of a group, dataset, or named +!! datatype attribute to be attached to +!! \param name Attribute name +!! \param attr_id Attribute identifier +!! \param hdferr \fortran_error +!! SUBROUTINE H5Aopen_name_f(obj_id, name, attr_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Attribute name - INTEGER(HID_T), INTENT(OUT) :: attr_id ! Attribute identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(HID_T), INTENT(OUT) :: attr_id + INTEGER, INTENT(OUT) :: hdferr + CHARACTER(LEN=LEN_TRIM(name)+1,KIND=C_CHAR) :: c_name ! H5Aopen_name is deprecated @@ -254,41 +218,22 @@ CONTAINS IF(attr_id.LT.0) hdferr = -1 END SUBROUTINE H5Aopen_name_f -! -!****s* H5A/H5Aopen_idx_f -! -! NAME -! H5Aopen_idx_f -! -! PURPOSE -! Opens the attribute specified by its index. -! -! INPUTS -! obj_id - identifier of a group, dataset, or named -! datatype an attribute to be attached to -! index - index of the attribute to open (zero-based) -! OUTPUTS -! attr_id - attribute identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces are added for -! called C functions (it is needed for Windows -! port). February 27, 2001 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Opens the attribute specified by its index. +!! +!! \param obj_id Identifier of a group, dataset, or named datatype an attribute to be attached to +!! \param index Index of the attribute to open (zero-based) +!! \param attr_id Attribute identifier +!! \param hdferr \fortran_error +!! SUBROUTINE H5Aopen_idx_f(obj_id, index, attr_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - INTEGER, INTENT(IN) :: index ! Attribute index - INTEGER(HID_T), INTENT(OUT) :: attr_id ! Attribute identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** -! H5Aopen_idx is deprecated in favor of the function H5Aopen_by_idx. + INTEGER(HID_T), INTENT(IN) :: obj_id + INTEGER, INTENT(IN) :: index + INTEGER(HID_T), INTENT(OUT) :: attr_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER(HID_T) FUNCTION H5Aopen_by_idx(obj_id, index) BIND(C,NAME='H5Aopen_by_idx') IMPORT :: HID_T @@ -304,39 +249,20 @@ CONTAINS IF(attr_id.LT.0) hdferr = -1 END SUBROUTINE H5Aopen_idx_f -! -!****s* H5A/H5Aget_space_f -! -! NAME -! H5Aget_space_f -! -! PURPOSE -! Gets a copy of the dataspace for an attribute. -! -! INPUTS -! attr_id - attribute identifier -! -! OUTPUTS -! space_id - attribite dataspace identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces are added for -! called C functions (it is needed for Windows -! port). February 27, 2001 -! -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Gets a copy of the dataspace for an attribute. +!! +!! \param attr_id Attribute identifier +!! \param space_id Attribite dataspace identifier +!! \param hdferr \fortran_error +!! SUBROUTINE H5Aget_space_f(attr_id, space_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - INTEGER(HID_T), INTENT(OUT) :: space_id ! Attribute dataspace identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(HID_T), INTENT(OUT) :: space_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER(HID_T) FUNCTION H5Aget_space(attr_id) BIND(C,NAME='H5Aget_space') IMPORT :: HID_T @@ -351,37 +277,20 @@ CONTAINS IF(space_id.LT.0) hdferr = -1 END SUBROUTINE H5Aget_space_f -! -!****s* H5A/H5Aget_type_f -! -! NAME -! H5Aget_type_f -! -! PURPOSE -! Gets an attribute datatype. -! -! INPUTS -! attr_id - attribute identifier -! OUTPUTS -! type_id - attribute datatype identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces are added for -! called C functions (it is needed for Windows -! port). February 27, 2001 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Gets an attribute datatype. +!! +!! \param attr_id Attribute identifier +!! \param type_id Attribute datatype identifier +!! \param hdferr \fortran_error +!! SUBROUTINE H5Aget_type_f(attr_id, type_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - INTEGER(HID_T), INTENT(OUT) :: type_id ! Attribute datatype identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(HID_T), INTENT(OUT) :: type_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER(HID_T) FUNCTION H5Aget_type(attr_id) BIND(C,NAME='H5Aget_type') IMPORT :: HID_T @@ -396,41 +305,22 @@ CONTAINS IF(type_id.LT.0) hdferr = -1 END SUBROUTINE H5Aget_type_f -! -!****s* H5A/H5Aget_name_f -! -! NAME -! H5Aget_name_f -! -! PURPOSE -! Gets an attribute name. -! -! INPUTS -! attr_id - attribute identifier -! size - size of a buffer to read name in -! OUTPUTS -! buf - buffer to read name in -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces are added for -! called C functions (it is needed for Windows -! port). February 27, 2001 -! -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Gets an attribute name. +!! +!! \param attr_id Attribute identifier +!! \param size Size of a buffer to read name in +!! \param buf Buffer to read name in +!! \param hdferr \fortran_error +!! SUBROUTINE h5aget_name_f(attr_id, size, buf, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - INTEGER(SIZE_T), INTENT(IN) :: size ! Buffer size - CHARACTER(LEN=*), INTENT(INOUT) :: buf ! Buffer to hold attribute name - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! name length is successful, -1 if fail -!***** + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(SIZE_T), INTENT(IN) :: size + CHARACTER(LEN=*), INTENT(INOUT) :: buf + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5aget_name_c(attr_id, size, buf) & BIND(C,NAME='h5aget_name_c') @@ -444,73 +334,48 @@ CONTAINS hdferr = h5aget_name_c(attr_id, size, buf) END SUBROUTINE h5aget_name_f -! -!****s* H5A/H5Aget_name_by_idx_f -! -! NAME -! H5Aget_name_by_idx_f -! -! PURPOSE -! Gets an attribute name, by attribute index position. -! -! INPUTS -! loc_id - Location of object to which attribute is attached -! obj_name - Name of object to which attribute is attached, relative to location -! idx_type - Type of index; Possible values are: -! H5_INDEX_UNKNOWN_F = -1 - Unknown index type -! H5_INDEX_NAME_F - Index on names -! H5_INDEX_CRT_ORDER_F - Index on creation order -! H5_INDEX_N_F - Number of indices defined -! -! order - Order in which to iterate over index; Possible values are: -! H5_ITER_UNKNOWN_F - Unknown order -! H5_ITER_INC_F - Increasing order -! H5_ITER_DEC_F - Decreasing order -! H5_ITER_NATIVE_F - No particular order, whatever is fastest -! H5_ITER_N_F - Number of iteration orders -! order - Index traversal order -! n - Attribute’s position in index -! -! OUTPUTS -! name - Attribute name -! hdferr - Returns 0 if successful and -1 if fails -! -! OPTIONAL PARAMETERS -! lapl_id - Link access property list -! size - Size, in bytes, of attribute name -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Gets an attribute name, by attribute index position. +!! +!! \param loc_id Location of object to which attribute is attached +!! \param obj_name Name of object to which attribute is attached, relative to location +!! \param idx_type Type of index; Possible values are: +!! \li H5_INDEX_UNKNOWN_F = -1 - Unknown index type +!! \li H5_INDEX_NAME_F - Index on names +!! \li H5_INDEX_CRT_ORDER_F - Index on creation order +!! \li H5_INDEX_N_F - Number of indices defined +!! +!! \param order Index traversal order in which to iterate over index; Possible values are: +!! \li H5_ITER_UNKNOWN_F - Unknown order +!! \li H5_ITER_INC_F - Increasing order +!! \li H5_ITER_DEC_F - Decreasing order +!! \li H5_ITER_NATIVE_F - No particular order, whatever is fastest +!! \li H5_ITER_N_F - Number of iteration orders +!! \param n Attribute’s position in index +!! \param name Attribute name +!! \param hdferr \fortran_error +!! +!! \param size Size, in bytes, of attribute name +!! \param lapl_id Link access property list +!! SUBROUTINE h5aget_name_by_idx_f(loc_id, obj_name, idx_type, order, & n, name, hdferr, size, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifier for object to which attribute is attached - CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Name of object, relative to location, - ! from which attribute is to be removed *TEST* check NULL - INTEGER, INTENT(IN) :: idx_type ! Type of index; Possible values are: - ! H5_INDEX_UNKNOWN_F - Unknown index type - ! H5_INDEX_NAME_F - Index on names - ! H5_INDEX_CRT_ORDER_F - Index on creation order - ! H5_INDEX_N_F - Number of indices defined - - INTEGER, INTENT(IN) :: order ! Order in which to iterate over index; Possible values are: - ! H5_ITER_UNKNOWN_F - Unknown order - ! H5_ITER_INC_F - Increasing order - ! H5_ITER_DEC_F - Decreasing order + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: obj_name + INTEGER, INTENT(IN) :: idx_type + ! H5_INDEX_N_F - Number of indices defined + + INTEGER, INTENT(IN) :: order ! H5_ITER_NATIVE_F - No particular order, whatever is fastest - ! H5_ITER_N_F - Number of iteration orders - INTEGER(HSIZE_T), INTENT(IN) :: n ! Attribute’s position in index - CHARACTER(LEN=*), INTENT(OUT) :: name ! Attribute name - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! Returns attribute name size, - ! -1 if fail - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list - INTEGER(SIZE_T), OPTIONAL, INTENT(OUT) :: size ! Indicates the size, in the number of characters, - ! of the attribute -!***** + ! H5_ITER_N_F - Number of iteration orders + INTEGER(HSIZE_T), INTENT(IN) :: n + CHARACTER(LEN=*), INTENT(OUT) :: name + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id + INTEGER(SIZE_T), OPTIONAL, INTENT(OUT) :: size INTEGER(HID_T) :: lapl_id_default INTEGER(SIZE_T) :: obj_namelen INTEGER(SIZE_T) :: size_default @@ -546,38 +411,20 @@ CONTAINS END SUBROUTINE h5aget_name_by_idx_f -! -!****s* H5A/H5Aget_num_attrs_f -! -! NAME -! H5Aget_num_attrs_f -! -! PURPOSE -! Determines the number of attributes attached to an object. -! -! INPUTS -! obj_id - object (group, dataset, or named datatype) -! identifier -! OUTPUTS -! attr_num - number of attributes attached to the object -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces are added for -! called C functions (it is needed for Windows -! port). February 27, 2001 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Determines the number of attributes attached to an object. +!! +!! \param obj_id Object (group, dataset, or named datatype) identifier +!! \param attr_num Number of attributes attached to the object +!! \param hdferr \fortran_error +!! SUBROUTINE h5aget_num_attrs_f(obj_id, attr_num, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - INTEGER, INTENT(OUT) :: attr_num ! Number of attributes of the object - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + INTEGER, INTENT(OUT) :: attr_num + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5aget_num_attrs_c(obj_id, attr_num) BIND(C,name='h5aget_num_attrs_c') @@ -590,38 +437,21 @@ CONTAINS hdferr = h5aget_num_attrs_c(obj_id, attr_num) END SUBROUTINE h5aget_num_attrs_f -! -!****s* H5A/H5Adelete_f -! -! NAME -! H5Adelete_f -! -! PURPOSE -! Deletes an attribute of an object (group, dataset or -! named datatype) -! -! INPUTS -! obj_id - object identifier -! name - attribute name -! OUTPUTS -! -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces are added for -! called C functions (it is needed for Windows -! port). February 27, 2001 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Deletes an attribute of an object (group, dataset or named datatype) +!! +!! \param obj_id Object identifier +!! \param name Attribute name +!! +!! \param hdferr \fortran_error +!! SUBROUTINE H5Adelete_f(obj_id, name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Attribute name - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(OUT) :: hdferr INTEGER(SIZE_T) :: namelen INTERFACE @@ -638,36 +468,18 @@ CONTAINS hdferr = H5Adelete_c(obj_id, name, namelen) END SUBROUTINE H5Adelete_f -! -!****s* H5A/H5Aclose_f -! -! NAME -! H5Aclose_f -! -! PURPOSE -! Closes the specified attribute. -! -! INPUTS -! attr_id - attribute identifier -! OUTPUTS -! -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces are added for -! called C functions (it is needed for Windows -! port). February 27, 2001 -! SOURCE - +!> +!! \ingroup FH5A +!! +!! \brief Closes the specified attribute. +!! +!! \param attr_id Attribute identifier +!! \param hdferr \fortran_error +!! SUBROUTINE H5Aclose_f(attr_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION H5Aclose(attr_id) BIND(C, NAME='H5Aclose') @@ -679,31 +491,20 @@ CONTAINS hdferr = INT(H5Aclose(attr_id)) END SUBROUTINE H5Aclose_f -! -!****s* H5A/H5Aget_storage_size_f -! -! NAME -! H5Aget_storage_size_f -! -! PURPOSE -! Returns the amount of storage required for an attribute. -! -! INPUTS -! attr_id - attribute identifier -! OUTPUTS -! size - attribute storage size -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Returns the amount of storage required for an attribute. +!! +!! \param attr_id Attribute identifier +!! \param size Attribute storage size +!! \param hdferr \fortran_error +!! SUBROUTINE H5Aget_storage_size_f(attr_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - INTEGER(HSIZE_T), INTENT(OUT) :: size ! Attribute storage requirement - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(HSIZE_T), INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER(HSIZE_T) FUNCTION H5Aget_storage_size(attr_id) BIND(C,NAME='H5Aget_storage_size') @@ -719,33 +520,20 @@ CONTAINS END SUBROUTINE H5Aget_storage_size_f -! -!****s* H5A/H5Aget_create_plist_f -! -! NAME -! H5Aget_create_plist_f -! -! PURPOSE -! Gets an attribute creation property list identifier -! -! INPUTS -! attr_id - Identifier of the attribute -! OUTPUTS -! creation_prop_id - Identifier for the attribute’s creation property -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Gets an attribute creation property list identifier +!! +!! \param attr_id Identifier of the attribute +!! \param creation_prop_id Identifier for the attribute’s creation property +!! \param hdferr \fortran_error +!! SUBROUTINE H5Aget_create_plist_f(attr_id, creation_prop_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Identifier of the attribute - INTEGER(HID_T), INTENT(OUT) :: creation_prop_id ! Identifier for the attribute’s creation property - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(HID_T), INTENT(OUT) :: creation_prop_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER(HID_T) FUNCTION H5Aget_create_plist(attr_id) BIND(C,NAME='H5Aget_create_plist') IMPORT :: HID_T @@ -760,44 +548,28 @@ CONTAINS END SUBROUTINE H5Aget_create_plist_f -! -!****s* H5A/H5Arename_by_name_f -! -! NAME -! H5Arename_by_name_f -! -! PURPOSE -! Renames an attribute -! -! INPUTS -! loc_id - Location or object identifier; may be dataset or group -! obj_name - Name of object, relative to location, -! whose attribute is to be renamed -! old_attr_name - Prior attribute name -! new_attr_name - New attribute name -! lapl_id - Link access property list identifier -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Renames an attribute +!! +!! \param loc_id Location or object identifier; may be dataset or group +!! \param obj_name Name of object, relative to location, whose attribute is to be renamed +!! \param old_attr_name Prior attribute name +!! \param new_attr_name New attribute name +!! \param lapl_id Link access property list identifier +!! \param hdferr \fortran_error +!! SUBROUTINE H5Arename_by_name_f(loc_id, obj_name, old_attr_name, new_attr_name, & hdferr, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Object identifier - CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Name of object, relative to location, - ! whose attribute is to be renamed - CHARACTER(LEN=*), INTENT(IN) :: old_attr_name ! Prior attribute name - CHARACTER(LEN=*), INTENT(IN) :: new_attr_name ! New attribute name - - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list identifier -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: obj_name + CHARACTER(LEN=*), INTENT(IN) :: old_attr_name + CHARACTER(LEN=*), INTENT(IN) :: new_attr_name + + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(HID_T) :: lapl_id_default INTEGER(SIZE_T) :: obj_namelen INTEGER(SIZE_T) :: old_attr_namelen @@ -835,41 +607,25 @@ CONTAINS END SUBROUTINE H5Arename_by_name_f -! -!****s* H5A/H5Aopen_f -! -! NAME -! H5Aopen_f -! -! PURPOSE -! Opens an attribute for an object specified by object -! identifier and attribute name -! -! INPUTS -! obj_id - Identifier for object to which attribute is attached -! attr_name - Name of attribute to open -! OUTPUTS -! attr_id - attribute identifier - -! OPTIONAL PARAMETERS -! aapl_id - Attribute access property list -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Opens an attribute for an object specified by object +!! identifier and attribute name +!! +!! \param obj_id Identifier for object to which attribute is attached +!! \param attr_name Name of attribute to open +!! \param attr_id Attribute identifier +!! \param hdferr \fortran_error +!! \param aapl_id Attribute access property list +!! SUBROUTINE H5Aopen_f(obj_id, attr_name, attr_id, hdferr, aapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - CHARACTER(LEN=*), INTENT(IN) :: attr_name ! Attribute name - INTEGER(HID_T), INTENT(OUT) :: attr_id ! Attribute identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! Success: 0 - ! Failure: -1 - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: aapl_id ! Attribute access property list -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + CHARACTER(LEN=*), INTENT(IN) :: attr_name + INTEGER(HID_T), INTENT(OUT) :: attr_id + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: aapl_id INTEGER(HID_T) :: aapl_id_default INTEGER(SIZE_T) :: attr_namelen @@ -896,64 +652,39 @@ CONTAINS END SUBROUTINE H5Aopen_f -! -!****s* H5A/H5Adelete_by_idx_f -! -! NAME -! H5Adelete_by_idx_f -! -! PURPOSE -! Deletes an attribute from an object according to index order -! -! INPUTS -! loc_id - Location or object identifier; may be dataset or group -! obj_name - Name of object, relative to location, from which attribute is to be removed -! idx_type - Type of index; Possible values are: -! H5_INDEX_UNKNOWN_F = -1 - Unknown index type -! H5_INDEX_NAME_F - Index on names -! H5_INDEX_CRT_ORDER_F - Index on creation order -! H5_INDEX_N_F - Number of indices defined -! -! order - Order in which to iterate over index; Possible values are: -! H5_ITER_UNKNOWN_F - Unknown order -! H5_ITER_INC_F - Increasing order -! H5_ITER_DEC_F - Decreasing order -! H5_ITER_NATIVE_F - No particular order, whatever is fastest -! H5_ITER_N_F - Number of iteration orders -! -! n - Offset within index -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lapl_id - Link access property list -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Deletes an attribute from an object according to index order +!! +!! \param loc_id Location or object identifier; may be dataset or group +!! \param obj_name Name of object, relative to location, from which attribute is to be removed +!! \param idx_type Type of index; Possible values are: +!! \li H5_INDEX_UNKNOWN_F = -1 - Unknown index type +!! \li H5_INDEX_NAME_F - Index on names +!! \li H5_INDEX_CRT_ORDER_F - Index on creation order +!! \li H5_INDEX_N_F - Number of indices defined +!! +!! \param order Order in which to iterate over index; Possible values are: +!! \li H5_ITER_UNKNOWN_F - Unknown order +!! \li H5_ITER_INC_F - Increasing order +!! \li H5_ITER_DEC_F - Decreasing order +!! \li H5_ITER_NATIVE_F - No particular order, whatever is fastest +!! \li H5_ITER_N_F - Number of iteration orders +!! +!! \param n Offset within index +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list +!! SUBROUTINE H5Adelete_by_idx_f(loc_id, obj_name, idx_type, order, n, hdferr, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifier for object to which attribute is attached - CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Name of object, relative to location, - ! from which attribute is to be removed - INTEGER, INTENT(IN) :: idx_type ! Type of index; Possible values are: - ! H5_INDEX_UNKNOWN_F - Unknown index type - ! H5_INDEX_NAME_F - Index on names - ! H5_INDEX_CRT_ORDER_F - Index on creation order - ! H5_INDEX_N_F - Number of indices defined - - INTEGER, INTENT(IN) :: order ! Order in which to iterate over index; Possible values are: - ! H5_ITER_UNKNOWN_F - Unknown order - ! H5_ITER_INC_F - Increasing order - ! H5_ITER_DEC_F - Decreasing order - ! H5_ITER_NATIVE_F - No particular order, whatever is fastest - ! H5_ITER_N_F - Number of iteration orders - INTEGER(HSIZE_T), INTENT(IN) :: n ! Offset within index - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: obj_name + INTEGER, INTENT(IN) :: idx_type + INTEGER, INTENT(IN) :: order + INTEGER(HSIZE_T), INTENT(IN) :: n + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(SIZE_T) :: obj_namelen INTEGER(HID_T) :: lapl_id_default @@ -981,38 +712,24 @@ CONTAINS END SUBROUTINE H5Adelete_by_idx_f -! -!****s* H5A/H5Adelete_by_name_f -! -! NAME -! H5Adelete_by_name_f -! -! PURPOSE -! Removes an attribute from a specified location -! -! INPUTS -! loc_id - Identifier for object to which attribute is attached -! obj_name - Name of attribute to open -! attr_name - Attribute access property list -! lapl_id - Link access property list -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Removes an attribute from a specified location +!! +!! \param loc_id Identifier for object to which attribute is attached +!! \param obj_name Name of attribute to open +!! \param attr_name Attribute access property list +!! \param lapl_id Link access property list +!! \param hdferr \fortran_error +!! SUBROUTINE H5Adelete_by_name_f(loc_id, obj_name, attr_name, hdferr, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifier for object to which attribute is attached - CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Name of object, relative to location, - ! from which attribute is to be removed - CHARACTER(LEN=*), INTENT(IN) :: attr_name ! Name of attribute to delete - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: obj_name + CHARACTER(LEN=*), INTENT(IN) :: attr_name + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(SIZE_T) :: attr_namelen INTEGER(SIZE_T) :: obj_namelen @@ -1042,55 +759,44 @@ CONTAINS END SUBROUTINE H5Adelete_by_name_f -! -!****s* H5A/H5Aopen_by_idx_f -! -! NAME -! H5Aopen_by_idx_f -! -! PURPOSE -! Opens an existing attribute that is attached to an object specified by location and name -! -! INPUTS -! loc_id - Location of object to which attribute is attached -! obj_name - Name of object to which attribute is attached, relative to location -! idx_type - Type of index -! order - Index traversal order -! n - Attribute’s position in index -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! aapl_id - Attribute access property list -! lapl_id - Link access property list -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Opens an existing attribute that is attached to an object specified by location and name. +!! +!! \param loc_id Location of object to which attribute is attached. +!! \param obj_name Name of object to which attribute is attached, relative to location. +!! \param idx_type Type of index; Possible values are: +!! \li H5_INDEX_UNKNOWN_F = -1 - Unknown index type +!! \li H5_INDEX_NAME_F - Index on names +!! \li H5_INDEX_CRT_ORDER_F - Index on creation order +!! \li H5_INDEX_N_F - Number of indices defined +!! +!! \param order Order in which to iterate over index; Possible values are: +!! \li H5_ITER_UNKNOWN_F - Unknown order +!! \li H5_ITER_INC_F - Increasing order +!! \li H5_ITER_DEC_F - Decreasing order +!! \li H5_ITER_NATIVE_F - No particular order, whatever is fastest +!! \li H5_ITER_N_F - Number of iteration orders +!! \param n Attribute’s position in index. +!! \param attr_id Attribute identifier. +!! \param hdferr \fortran_error +!! \param aapl_id Attribute access property list. +!! \param lapl_id Link access property list. +!! SUBROUTINE H5Aopen_by_idx_f(loc_id, obj_name, idx_type, order, n, attr_id, hdferr, aapl_id, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Object identifier - CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Name of object to which attribute is attached - INTEGER, INTENT(IN) :: idx_type ! Type of index; Possible values are: - ! H5_INDEX_UNKNOWN_F - Unknown index type - ! H5_INDEX_NAME_F - Index on names - ! H5_INDEX_CRT_ORDER_F - Index on creation order - ! H5_INDEX_N_F - Number of indices defined - INTEGER, INTENT(IN) :: order ! Order in which to iterate over index; Possible values are: - ! H5_ITER_UNKNOWN_F - Unknown order - ! H5_ITER_INC_F - Increasing order - ! H5_ITER_DEC_F - Decreasing order - ! H5_ITER_NATIVE_F - No particular order, whatever is fastest + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: obj_name + INTEGER, INTENT(IN) :: idx_type + INTEGER, INTENT(IN) :: order - INTEGER(HSIZE_T), INTENT(IN) :: n ! Attribute’s position in index + INTEGER(HSIZE_T), INTENT(IN) :: n - INTEGER(HID_T), INTENT(OUT) :: attr_id ! Attribute identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: aapl_id ! Attribute access property list - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list -!***** + INTEGER(HID_T), INTENT(OUT) :: attr_id + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: aapl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(SIZE_T) :: obj_namelen INTEGER(HID_T) :: aapl_id_default INTEGER(HID_T) :: lapl_id_default @@ -1108,7 +814,7 @@ CONTAINS INTEGER(HID_T) :: aapl_id_default INTEGER(HID_T) :: lapl_id_default INTEGER(SIZE_T) :: obj_namelen - INTEGER(HID_T), INTENT(OUT) :: attr_id ! Attribute identifier + INTEGER(HID_T), INTENT(OUT) :: attr_id END FUNCTION H5Aopen_by_idx_c END INTERFACE @@ -1124,41 +830,27 @@ CONTAINS END SUBROUTINE H5Aopen_by_idx_f -! -!****s* H5A/H5Aget_info_f -! -! NAME -! H5Aget_info_f -! -! PURPOSE -! Retrieves attribute information, by attribute identifier -! -! INPUTS -! attr_id - attribute identifier -! -! OUTPUTS -! NOTE: In C it is defined as a structure: H5A_info_t -! -! corder_valid - indicates whether the creation order data is valid for this attribute -! corder - is a positive integer containing the creation order of the attribute -! cset - indicates the character set used for the attribute’s name -! data_size - indicates the size, in the number of characters, of the attribute -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Retrieves attribute information, by attribute identifier. +!! +!! \param attr_id Attribute identifier. +!! NOTE: In C it is defined as a structure: H5A_info_t. +!! \param f_corder_valid Indicates whether the creation order data is valid for this attribute. +!! \param corder Is a positive integer containing the creation order of the attribute. +!! \param cset Indicates the character set used for the attribute’s name. +!! \param data_size Indicates the size, in the number of characters, of the attribute. +!! \param hdferr \fortran_error +!! SUBROUTINE H5Aget_info_f(attr_id, f_corder_valid, corder, cset, data_size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - - LOGICAL, INTENT(OUT) :: f_corder_valid ! Indicates whether the creation order data is valid for this attribute - INTEGER, INTENT(OUT) :: corder ! Is a positive integer containing the creation order of the attribute - INTEGER, INTENT(OUT) :: cset ! Indicates the character set used for the attribute’s name - INTEGER(HSIZE_T), INTENT(OUT) :: data_size ! Indicates the size, in the number of characters, of the attribute - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: attr_id + LOGICAL, INTENT(OUT) :: f_corder_valid + INTEGER, INTENT(OUT) :: corder + INTEGER, INTENT(OUT) :: cset + INTEGER(HSIZE_T), INTENT(OUT) :: data_size + INTEGER, INTENT(OUT) :: hdferr INTEGER :: corder_valid INTERFACE @@ -1182,63 +874,42 @@ CONTAINS END SUBROUTINE H5Aget_info_f -! -!****s* H5A/H5Aget_info_by_idx_f -! -! NAME -! H5Aget_info_by_idx_f -! -! PURPOSE -! Retrieves attribute information, by attribute index position -! -! INPUTS -! loc_id - Location of object to which attribute is attached -! obj_name - Name of object to which attribute is attached, relative to location -! idx_type - Type of index -! order - Index traversal order -! n - Attribute’s position in index -! -! OUTPUTS NOTE: In C it is defined as a structure: H5A_info_t -! corder_valid - indicates whether the creation order data is valid for this attribute -! corder - is a positive integer containing the creation order of the attribute -! cset - indicates the character set used for the attribute’s name -! data_size - indicates the size, in the number of characters, of the attribute -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lapl_id - Link access property list -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Retrieves attribute information, by attribute index position +!! +!! \param loc_id Location of object to which attribute is attached +!! \param obj_name Name of object to which attribute is attached, relative to location +!! \param idx_type Type of index +!! \param order Index traversal order +!! \param n Attribute’s position in index +!! \param f_corder_valid Indicates whether the creation order data is valid for this attribute +!! \param corder Is a positive integer containing the creation order of the attribute +!! \param cset Indicates the character set used for the attribute’s name +!! \param data_size Indicates the size, in the number of characters, of the attribute +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list +!! SUBROUTINE H5Aget_info_by_idx_f(loc_id, obj_name, idx_type, order, n, & f_corder_valid, corder, cset, data_size, hdferr, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Object identifier - CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Name of object to which attribute is attached - INTEGER, INTENT(IN) :: idx_type ! Type of index; Possible values are: - ! H5_INDEX_UNKNOWN_F - Unknown index type - ! H5_INDEX_NAME_F - Index on names - ! H5_INDEX_CRT_ORDER_F - Index on creation order - ! H5_INDEX_N_F - Number of indices defined - INTEGER, INTENT(IN) :: order ! Order in which to iterate over index; Possible values are: - ! H5_ITER_UNKNOWN_F - Unknown order - ! H5_ITER_INC_F - Increasing order - ! H5_ITER_DEC_F - Decreasing order + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: obj_name + INTEGER, INTENT(IN) :: idx_type + ! H5_INDEX_N_F - Number of indices defined + INTEGER, INTENT(IN) :: order ! H5_ITER_NATIVE_F - No particular order, whatever is fastest - INTEGER(HSIZE_T), INTENT(IN) :: n ! Attribute’s position in index + INTEGER(HSIZE_T), INTENT(IN) :: n - LOGICAL, INTENT(OUT) :: f_corder_valid ! Indicates whether the creation order data is valid for this attribute - INTEGER, INTENT(OUT) :: corder ! Is a positive integer containing the creation order of the attribute - INTEGER, INTENT(OUT) :: cset ! Indicates the character set used for the attribute’s name - INTEGER(HSIZE_T), INTENT(OUT) :: data_size ! Indicates the size, in the number of characters, of the attribute - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list -!***** + LOGICAL, INTENT(OUT) :: f_corder_valid + INTEGER, INTENT(OUT) :: corder + INTEGER, INTENT(OUT) :: cset + INTEGER(HSIZE_T), INTENT(OUT) :: data_size + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER :: corder_valid INTEGER(SIZE_T) :: obj_namelen INTEGER(HID_T) :: lapl_id_default @@ -1276,50 +947,35 @@ CONTAINS END SUBROUTINE H5Aget_info_by_idx_f -! -!****s* H5A/H5Aget_info_by_name_f -! -! NAME -! H5Aget_info_by_name_f -! -! PURPOSE -! Retrieves attribute information, by attribute name -! -! INPUTS -! loc_id - Location of object to which attribute is attached -! obj_name - Name of object to which attribute is attached, relative to location -! attr_name - Attribute name -! -! OUTPUTS NOTE: In C it is defined as a structure: H5A_info_t -! corder_valid - indicates whether the creation order data is valid for this attribute -! corder - is a positive integer containing the creation order of the attribute -! cset - indicates the character set used for the attribute’s name -! data_size - indicates the size, in the number of characters, of the attribute -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lapl_id - Link access property list -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Retrieves attribute information, by attribute name +!! +!! \param loc_id Location of object to which attribute is attached +!! \param obj_name Name of object to which attribute is attached, relative to location +!! \param attr_name Attribute name +!! \param f_corder_valid Indicates whether the creation order data is valid for this attribute +!! \param corder Is a positive integer containing the creation order of the attribute +!! \param cset Indicates the character set used for the attribute’s name +!! \param data_size Indicates the size, in the number of characters, of the attribute +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list +!! SUBROUTINE H5Aget_info_by_name_f(loc_id, obj_name, attr_name, & f_corder_valid, corder, cset, data_size, hdferr, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Object identifier - CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Name of object to which attribute is attached - CHARACTER(LEN=*), INTENT(IN) :: attr_name ! Attribute name - - - LOGICAL, INTENT(OUT) :: f_corder_valid ! Indicates whether the creation order data is valid for this attribute - INTEGER, INTENT(OUT) :: corder ! Is a positive integer containing the creation order of the attribute - INTEGER, INTENT(OUT) :: cset ! Indicates the character set used for the attribute’s name - INTEGER(HSIZE_T), INTENT(OUT) :: data_size ! Indicates the size, in the number of characters, of the attribute - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: obj_name + CHARACTER(LEN=*), INTENT(IN) :: attr_name + + + LOGICAL, INTENT(OUT) :: f_corder_valid + INTEGER, INTENT(OUT) :: corder + INTEGER, INTENT(OUT) :: cset + INTEGER(HSIZE_T), INTENT(OUT) :: data_size + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER :: corder_valid INTEGER(SIZE_T) :: obj_namelen INTEGER(SIZE_T) :: attr_namelen @@ -1359,34 +1015,22 @@ CONTAINS END SUBROUTINE H5Aget_info_by_name_f -! -!****s* H5A/H5Acreate_by_name_f -! -! NAME -! H5Acreate_by_name_f -! -! PURPOSE -! Creates an attribute attached to a specified object -! -! INPUTS -! loc_id - Location or object identifier; may be dataset or group -! obj_name - Name, relative to loc_id, of object that attribute is to be attached to -! attr_name - Attribute name -! type_id - Attribute datatype identifier -! space_id - Attribute dataspace identifier -! -! OUTPUTS -! attr - an attribute identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! acpl_id - Attribute creation property list identifier (Currently not used.) -! aapl_id - Attribute access property list identifier (Currently not used.) -! lapl_id - Link access property list -! -! AUTHOR -! M. Scot Breitenfeld -! February, 2008 -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Creates an attribute attached to a specified object +!! +!! \param loc_id Location or object identifier; may be dataset or group +!! \param obj_name Name, relative to loc_id, of object that attribute is to be attached to +!! \param attr_name Attribute name +!! \param type_id Attribute datatype identifier +!! \param space_id Attribute dataspace identifier +!! \param attr An attribute identifier +!! \param hdferr \fortran_error +!! \param acpl_id Attribute creation property list identifier (Currently not used.) +!! \param aapl_id Attribute access property list identifier (Currently not used.) +!! \param lapl_id Link access property list +!! SUBROUTINE H5Acreate_by_name_f(loc_id, obj_name, attr_name, type_id, space_id, attr, hdferr, & acpl_id, aapl_id, lapl_id) IMPLICIT NONE @@ -1401,7 +1045,6 @@ CONTAINS INTEGER(HID_T), INTENT(IN), OPTIONAL :: acpl_id INTEGER(HID_T), INTENT(IN), OPTIONAL :: aapl_id INTEGER(HID_T), INTENT(IN), OPTIONAL :: lapl_id -!***** INTEGER(SIZE_T) :: obj_namelen INTEGER(SIZE_T) :: attr_namelen @@ -1446,36 +1089,22 @@ CONTAINS type_id, space_id, acpl_id_default, aapl_id_default, lapl_id_default, attr) END SUBROUTINE H5Acreate_by_name_f -! -!****s* H5A/H5Aexists_f -! -! NAME -! H5Aexists_f -! -! PURPOSE -! Determines whether an attribute with a given name exists on an object -! -! INPUTS -! obj_id - Object identifier -! attr_name - Attribute name -! -! OUTPUTS -! attr_exists - attribute exists status -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! February, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Determines whether an attribute with a given name exists on an object +!! +!! \param obj_id Object identifier +!! \param attr_name Attribute name +!! \param attr_exists Attribute exists status +!! \param hdferr \fortran_error +!! SUBROUTINE H5Aexists_f(obj_id, attr_name, attr_exists, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - CHARACTER(LEN=*), INTENT(IN) :: attr_name ! Attribute name - LOGICAL, INTENT(OUT) :: attr_exists ! .TRUE. if exists, .FALSE. otherwise - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + CHARACTER(LEN=*), INTENT(IN) :: attr_name + LOGICAL, INTENT(OUT) :: attr_exists + INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T) :: attr_exists_c INTEGER(SIZE_T) :: attr_namelen @@ -1500,42 +1129,26 @@ CONTAINS END SUBROUTINE H5Aexists_f -! -!****s* H5A/H5Aexists_by_name_f -! -! NAME -! H5Aexists_by_name_f -! -! PURPOSE -! Determines whether an attribute with a given name exists on an object -! -! INPUTS -! loc_id - Location identifier -! obj_name - Object name either relative to loc_id, absolute from the file’s root group, or '.' (a dot) -! attr_name - Attribute name -! -! OUTPUTS -! attr_exists - attribute exists status -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lapl_id - Link access property list identifier -! -! AUTHOR -! M. Scot Breitenfeld -! February, 2008 -! -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Determines whether an attribute with a given name exists on an object +!! +!! \param loc_id Location identifier +!! \param obj_name Object name either relative to loc_id, absolute from the file’s root group, or '. '(a dot) +!! \param attr_name Attribute name +!! \param attr_exists Attribute exists status +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list identifier +!! SUBROUTINE H5Aexists_by_name_f(loc_id, obj_name, attr_name, attr_exists, hdferr, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Location identifier - CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Object name either relative to loc_id, - ! absolute from the file’s root group, or '.' - CHARACTER(LEN=*), INTENT(IN) :: attr_name ! Attribute name - LOGICAL, INTENT(OUT) :: attr_exists ! .TRUE. if exists, .FALSE. otherwise - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list identifier -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: obj_name + CHARACTER(LEN=*), INTENT(IN) :: attr_name + LOGICAL, INTENT(OUT) :: attr_exists + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER :: attr_exists_c INTEGER(SIZE_T) :: obj_namelen INTEGER(SIZE_T) :: attr_namelen @@ -1570,44 +1183,28 @@ CONTAINS IF(attr_exists_c.GT.0) attr_exists = .TRUE. END SUBROUTINE H5Aexists_by_name_f -! -!****s* H5A/H5Aopen_by_name_f -! -! NAME -! H5Aopen_by_name_f -! -! PURPOSE -! Opens an attribute for an object by object name and attribute name. -! -! INPUTS -! loc_id - Location from which to find object to which attribute is attached -! obj_name - Object name either relative to loc_id, absolute from the file’s root group, or '.' (a dot) -! attr_name - Attribute name -! -! OUTPUTS -! attr_id - attribute identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! aapl_id - Attribute access property list (Currently unused; should be passed in as H5P_DEFAULT.) -! lapl_id - Link access property list identifier -! -! AUTHOR -! M. Scot Breitenfeld -! February, 2008 -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Opens an attribute for an object by object name and attribute name. +!! +!! \param loc_id Location from which to find object to which attribute is attached +!! \param obj_name Object name either relative to loc_id, absolute from the file’s root group, or '.' (a dot) +!! \param attr_name Attribute name +!! \param attr_id Attribute identifier +!! \param hdferr \fortran_error +!! \param aapl_id Attribute access property list (Currently unused; should be passed in as H5P_DEFAULT.) +!! \param lapl_id Link access property list identifier +!! SUBROUTINE H5Aopen_by_name_f(loc_id, obj_name, attr_name, attr_id, hdferr, aapl_id, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Location identifier - CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Object name either relative to loc_id, - ! absolute from the file’s root group, or '.' - CHARACTER(LEN=*), INTENT(IN) :: attr_name ! Attribute name - INTEGER(HID_T), INTENT(OUT) :: attr_id ! Attribute identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: aapl_id ! Attribute access property list - ! (Currently unused; should be passed in as H5P_DEFAULT_F) - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list identifier -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: obj_name + CHARACTER(LEN=*), INTENT(IN) :: attr_name + INTEGER(HID_T), INTENT(OUT) :: attr_id + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: aapl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(HID_T) :: aapl_id_default INTEGER(HID_T) :: lapl_id_default @@ -1644,41 +1241,22 @@ CONTAINS END SUBROUTINE H5Aopen_by_name_f -! -!****s* H5A/H5Arename_f -! -! NAME -! H5Arename_f -! -! PURPOSE -! Renames an attribute -! -! INPUTS -! loc_id - Location or object identifier; may be dataset or group -! old_attr_name - Prior attribute name -! new_attr_name - New attribute name -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! HISTORY -! N/A -! -! - -! SOURCE +!> +!! \ingroup FH5A +!! +!! \brief Renames an attribute +!! +!! \param loc_id Location or object identifier; may be dataset or group +!! \param old_attr_name Prior attribute name +!! \param new_attr_name New attribute name +!! \param hdferr \fortran_error +!! SUBROUTINE H5Arename_f(loc_id, old_attr_name, new_attr_name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Object identifier - CHARACTER(LEN=*), INTENT(IN) :: old_attr_name ! Prior attribute name - CHARACTER(LEN=*), INTENT(IN) :: new_attr_name ! New attribute name - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: old_attr_name + CHARACTER(LEN=*), INTENT(IN) :: new_attr_name + INTEGER, INTENT(OUT) :: hdferr INTEGER(SIZE_T) :: old_attr_namelen INTEGER(SIZE_T) :: new_attr_namelen @@ -1704,14 +1282,99 @@ CONTAINS END SUBROUTINE H5Arename_f +#ifdef H5_DOXYGEN_FORTRAN + + +!> +!! \ingroup FH5A +!! +!! \brief Writes data to an attribute. +!! +!! \note \fortran_approved +!! +!! \param attr_id Identifier of an attribute to write. +!! \param memtype_id Identifier of the attribute datatype (in memory). +!! \param buf Data to be written. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5awrite_f(attr_id, memtype_id, buf, hdferr) + INTEGER(HID_T) , INTENT(IN) :: attr_id + INTEGER(HID_T) , INTENT(IN) :: memtype_id + TYPE(C_PTR) , INTENT(IN) :: buf + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5awrite_f + +!> +!! \ingroup FH5A +!! +!! \brief Writes data to an attribute. +!! +!! \note \fortran_obsolete +!! +!! \param attr_id Identifier of an attribute to write. +!! \param memtype_id Identifier of the attribute datatype (in memory). +!! \param buf Data buffer; may be a scalar or an array. +!! \param dims Array to hold corresponding dimension sizes of data buffer buf; +!! dim(k) has value of the k-th dimension of buffer buf; values are ignored if buf is a scalar. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5awrite_f(attr_id, memtype_id, buf, dims, hdferr) + INTEGER(HID_T) , INTENT(IN) :: attr_id + INTEGER(HID_T) , INTENT(IN) :: memtype_id + TYPE(TYPE) , INTENT(IN) :: buf + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5awrite_f +!> +!! \ingroup FH5A +!! +!! \brief Reads an attribute. +!! +!! \note \fortran_approved +!! +!! \param attr_id Identifier of an attribute to read. +!! \param memtype_id Identifier of the attribute datatype (in memory). +!! \param buf Buffer for data to be read. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5aread_f(attr_id, memtype_id, buf, hdferr) + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(HID_T), INTENT(IN) :: memtype_id + TYPE(C_PTR) , INTENT(INOUT) :: buf + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5aread_f + +!> +!! \ingroup FH5A +!! +!! \brief Reads an attribute. +!! +!! \note \fortran_obsolete +!! +!! \param attr_id Identifier of an attribute to read. +!! \param memtype_id Identifier of the attribute datatype (in memory). +!! \param buf Buffer for data to be read. +!! \param dims Array to hold corresponding dimension sizes of data buffer buf; +!! dim(k) has value of the k-th dimension of buffer buf; values are ignored if buf is a scalar. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5aread_f(attr_id, memtype_id, buf, dims, hdferr) + INTEGER(HID_T) , INTENT(IN) :: attr_id + INTEGER(HID_T) , INTENT(IN) :: memtype_id + TYPE(TYPE) , INTENT(INOUT) :: buf + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5aread_f + +#else + SUBROUTINE H5Awrite_char_scalar(attr_id, memtype_id, buf, dims, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - INTEGER(HID_T), INTENT(IN) :: memtype_id ! Attribute datatype - ! identifier (in memory) - INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims ! Array to story buf dimension sizes - CHARACTER(LEN=*), INTENT(IN) :: buf ! Attribute data - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(HID_T), INTENT(IN) :: memtype_id + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims + CHARACTER(LEN=*), INTENT(IN) :: buf + INTEGER, INTENT(OUT) :: hdferr CALL H5Awrite_char_scalar_fix(attr_id, memtype_id, buf, LEN(buf), dims, hdferr) @@ -1719,13 +1382,12 @@ CONTAINS SUBROUTINE H5Awrite_char_scalar_fix(attr_id, memtype_id, buf, buf_len, dims, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - INTEGER(HID_T), INTENT(IN) :: memtype_id ! Attribute datatype - ! identifier (in memory) - INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims ! Array to story buf dimension sizes + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(HID_T), INTENT(IN) :: memtype_id + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims INTEGER, INTENT(IN) :: buf_len - CHARACTER(LEN=buf_len), INTENT(IN), TARGET :: buf ! Attribute data - INTEGER, INTENT(OUT) :: hdferr ! Error code + CHARACTER(LEN=buf_len), INTENT(IN), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1:1)) @@ -1734,51 +1396,12 @@ CONTAINS END SUBROUTINE H5Awrite_char_scalar_fix - -!****s* H5A (F03)/H5Awrite_f_F03 -! -! NAME -! H5Awrite_f_F03 -! -! PURPOSE -! Writes an attribute. -! -! Inputs: -! attr_id - Attribute identifier -! memtype_id - Attribute datatype identifier (in memory) -! buf - Data buffer; may be a scalar or an array -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces are added for -! called C functions (it is needed for Windows -! port). February 27, 2001 -! -! NOTES -! This function is overloaded to write INTEGER, -! REAL, REAL(KIND=C_DOUBLE) and CHARACTER buffers -! up to 7 dimensions. -! -! Fortran2003 Interface: -!! SUBROUTINE H5Awrite_f(attr_id, memtype_id, buf, hdferr) -!! INTEGER(HID_T) , INTENT(IN) :: attr_id -!! INTEGER(HID_T) , INTENT(IN) :: memtype_id -!! TYPE(C_PTR) , INTENT(IN) :: buf -!! INTEGER , INTENT(OUT) :: hdferr -!***** - SUBROUTINE H5Awrite_ptr(attr_id, mem_type_id, buf, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id TYPE(C_PTR), INTENT(IN), TARGET :: buf - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER, INTENT(OUT) :: hdferr hdferr = H5Awrite_f_c(attr_id, mem_type_id, buf) @@ -1786,12 +1409,11 @@ CONTAINS SUBROUTINE H5Aread_char_scalar(attr_id, memtype_id, buf, dims, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - INTEGER(HID_T), INTENT(IN) :: memtype_id ! Attribute datatype - ! identifier (in memory) - INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims ! Array to story buf dimension sizes - CHARACTER(LEN=*), INTENT(INOUT) :: buf ! Attribute data - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(HID_T), INTENT(IN) :: memtype_id + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims + CHARACTER(LEN=*), INTENT(INOUT) :: buf + INTEGER, INTENT(OUT) :: hdferr CALL H5Aread_char_scalar_fix(attr_id, memtype_id, buf, LEN(buf), hdferr) @@ -1799,12 +1421,11 @@ CONTAINS SUBROUTINE H5Aread_char_scalar_fix(attr_id, memtype_id, buf, buf_len, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - INTEGER(HID_T), INTENT(IN) :: memtype_id ! Attribute datatype - ! identifier (in memory) + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(HID_T), INTENT(IN) :: memtype_id INTEGER, INTENT(IN) :: buf_len - CHARACTER(LEN=buf_len), INTENT(INOUT), TARGET :: buf ! Attribute data - INTEGER, INTENT(OUT) :: hdferr ! Error code + CHARACTER(LEN=buf_len), INTENT(INOUT), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1:1)) @@ -1813,62 +1434,19 @@ CONTAINS END SUBROUTINE H5Aread_char_scalar_fix -!****s* H5A (F03)/H5Aread_f_F03 -! -! NAME -! H5Aread_f_F03 -! -! PURPOSE -! Reads an attribute. -! -! Inputs: -! attr_id - Attribute identifier -! memtype_id - Attribute datatype identifier (in memory) -! -! Outputs: -! buf - Data buffer; may be a scalar or an array -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces are added for -! called C functions (it is needed for Windows -! port). February 27, 2001 -! -! dims parameter was added to make code portable; -! Aprile 4, 2001 -! -! Changed buf intent to INOUT to be consistent -! with how the C functions handles it. The pg -! compiler will return 0 if a buf value is not set. -! February, 2008 -! -! NOTES -! This function is overloaded to write INTEGER, -! REAL, REAL(KIND=C_DOUBLE) and CHARACTER buffers -! up to 7 dimensions. -! Fortran2003 Interface: -!! SUBROUTINE H5Aread_f(attr_id, memtype_id, buf, hdferr) -!! INTEGER(HID_T) , INTENT(IN) :: attr_id -!! INTEGER(HID_T) , INTENT(IN) :: memtype_id -!! TYPE(C_PTR) , INTENT(INOUT) :: buf -!! INTEGER , INTENT(OUT) :: hdferr -!***** - SUBROUTINE H5Aread_ptr(attr_id, mem_type_id, buf, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: attr_id ! Attribute identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier + INTEGER(HID_T), INTENT(IN) :: attr_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id TYPE(C_PTR), INTENT(INOUT), TARGET :: buf - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER, INTENT(OUT) :: hdferr hdferr = H5Aread_f_c(attr_id, mem_type_id, buf) END SUBROUTINE H5Aread_ptr +#endif + END MODULE H5A diff --git a/fortran/src/H5Dff.F90 b/fortran/src/H5Dff.F90 index 216b005..35a959e 100644 --- a/fortran/src/H5Dff.F90 +++ b/fortran/src/H5Dff.F90 @@ -1,13 +1,13 @@ -!****h* ROBODoc/H5D -! -! NAME -! MODULE H5D -! -! FILE -! fortran/src/H5Dff.F90 -! -! PURPOSE -! This file contains Fortran interfaces for H5D functions. +!> @defgroup FH5D Fortran Datasets (H5D) Interface +!! +!! @see H5D, C-API +!! +!! @see @ref H5D_UG, User Guide +!! + +!> @ingroup FH5D +!! +!! @brief This module contains Fortran interfaces for H5D functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -36,7 +36,7 @@ ! (i.e. real , dimension(*) :: ... ) etc... ! ! (3) Could not place the USE, INTRINSIC :: ISO_C_BINDING in the module header because it may -! conflict with the USE, INTRINSIC :: ISO_C_BINDING included in the user's program. Moved +! conflict with the USE, INTRINSIC :: ISO_C_BINDING included in the user's program. Moved ! the statement instead to each subroutine. ! ! @@ -56,7 +56,7 @@ ! (b) an allocated allocatable variable that has the TARGET attribute, or ! (c) an associated pointer. ! -! - When X is a character, for interoperability the standard is: +! - When X is a character, for interoperability the standard is: ! ! 15.2.1 Interoperability of intrinsic types ! @@ -81,7 +81,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** #include @@ -103,17 +102,7 @@ MODULE H5D MODULE PROCEDURE h5dset_extent_f END INTERFACE - INTERFACE h5dread_vl_f - MODULE PROCEDURE h5dread_vl_integer - MODULE PROCEDURE h5dread_vl_real - MODULE PROCEDURE h5dread_vl_string - END INTERFACE - - INTERFACE h5dwrite_vl_f - MODULE PROCEDURE h5dwrite_vl_integer - MODULE PROCEDURE h5dwrite_vl_real - MODULE PROCEDURE h5dwrite_vl_string - END INTERFACE +#ifndef H5_DOXYGEN_FORTRAN INTERFACE h5dwrite_f MODULE PROCEDURE h5dwrite_reference_obj @@ -131,7 +120,18 @@ MODULE H5D ! This is the preferred way to call h5dread ! by passing an address MODULE PROCEDURE h5dread_ptr + END INTERFACE + + INTERFACE h5dread_vl_f + MODULE PROCEDURE h5dread_vl_integer + MODULE PROCEDURE h5dread_vl_real + MODULE PROCEDURE h5dread_vl_string + END INTERFACE + INTERFACE h5dwrite_vl_f + MODULE PROCEDURE h5dwrite_vl_integer + MODULE PROCEDURE h5dwrite_vl_real + MODULE PROCEDURE h5dwrite_vl_string END INTERFACE @@ -195,64 +195,43 @@ MODULE H5D IMPORT :: HID_T IMPLICIT NONE TYPE(C_PTR), VALUE :: f_ptr_fill_value - INTEGER(HID_T) :: fill_type_id ! Fill value datatype identifier - INTEGER(HID_T), INTENT(IN) :: space_id ! Memory dataspace selection identifier + INTEGER(HID_T) :: fill_type_id + INTEGER(HID_T), INTENT(IN) :: space_id TYPE(C_PTR), VALUE :: f_ptr_buf INTEGER(HID_T) :: mem_type_id END FUNCTION h5dfill_c END INTERFACE +#endif CONTAINS -! -!****s* H5D/h5dcreate_f -! -! NAME -! h5dcreate_f -! -! PURPOSE -! Creates a dataset at the specified location -! -! INPUTS -! loc_id - file or group identifier -! name - dataset name -! type_id - dataset datatype identifier -! space_id - dataset dataspace identifier -! OUTPUTS -! dset_id - dataset identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! creation_prp - Dataset creation property list -! lcpl_id - Link creation property list -! dapl_id - Dataset access property list -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! -! - Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! - Added version's 1.8 new optional parameters -! February, 2008 -! -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Creates a dataset at the specified location. +!! +!! \param loc_id File or group identifier +!! \param name Dataset name +!! \param type_id Dataset datatype identifier +!! \param space_id Dataset dataspace identifier +!! \param dset_id Dataset identifier +!! \param hdferr \fortran_error +!! \param dcpl_id Dataset creation property list +!! \param lcpl_id Link creation property list +!! \param dapl_id Dataset access property list +!! SUBROUTINE h5dcreate_f(loc_id, name, type_id, space_id, dset_id, & hdferr, dcpl_id, lcpl_id, dapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the dataset - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier - INTEGER(HID_T), INTENT(IN) :: space_id ! Dataspace identifier - INTEGER(HID_T), INTENT(OUT) :: dset_id ! Dataset identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: dcpl_id ! Dataset creation property list - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id ! Link creation property list - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: dapl_id ! Dataset access property list + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER(HID_T), INTENT(IN) :: space_id + INTEGER(HID_T), INTENT(OUT) :: dset_id + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: dcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: dapl_id INTEGER(HID_T) :: lcpl_id_default INTEGER(HID_T) :: dcpl_id_default @@ -295,45 +274,24 @@ CONTAINS END SUBROUTINE h5dcreate_f -! -!****s* H5D/h5dopen_f -! -! NAME -! h5dopen_f -! -! PURPOSE -! Opens an existing dataset. -! -! INPUTS -! loc_id - file or group identifier -! name - dataset name -! OUTPUTS -! dset_id - dataset identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! dapl_id - Dataset access property list -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! -Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! -Added 1.8 (optional) parameter dapl_id -! February, 2008, M. Scot Breitenfeld -! -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Opens an existing dataset. +!! +!! \param loc_id File or group identifier +!! \param name Dataset name +!! \param dset_id Dataset identifier +!! \param hdferr \fortran_error +!! \param dapl_id Dataset access property list +!! SUBROUTINE h5dopen_f(loc_id, name, dset_id, hdferr, dapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the dataset - INTEGER(HID_T), INTENT(OUT) :: dset_id ! Dataset identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: dapl_id ! Dataset access property list -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(HID_T), INTENT(OUT) :: dset_id + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: dapl_id INTEGER :: namelen ! Name length INTEGER(HID_T) :: dapl_id_default @@ -360,35 +318,18 @@ CONTAINS END SUBROUTINE h5dopen_f -! -!****s* H5D/h5dclose_f -! -! NAME -! h5dclose_f -! -! PURPOSE -! Closes a dataset. -! -! INPUTS -! dset_id - dataset identifier -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Closes a dataset. +!! +!! \param dset_id Dataset identifier +!! \param hdferr \fortran_error +!! SUBROUTINE h5dclose_f(dset_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5dclose_c(dset_id) & BIND(C,NAME='h5dclose_c') @@ -402,40 +343,21 @@ CONTAINS END SUBROUTINE h5dclose_f -! -!****s* H5D/h5dget_type_f -! -! NAME -! h5dget_type_f -! -! PURPOSE -! Returns an identifier for a copy of the datatype for a -! dataset. -! -! INPUTS -! dataset_id - dataset identifier -! OUTPUTS -! datatype_id - dataspace identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! NOTES -! -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Returns an identifier for a copy of the datatype for a +!! dataset. +!! +!! \param dataset_id Dataset identifier +!! \param datatype_id Dataspace identifier +!! \param hdferr \fortran_error +!! SUBROUTINE h5dget_type_f(dataset_id, datatype_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dataset_id ! Dataset identifier - INTEGER(HID_T), INTENT(OUT) :: datatype_id ! Datatype identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: dataset_id + INTEGER(HID_T), INTENT(OUT) :: datatype_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5dget_type_c(dataset_id, datatype_id) & BIND(C,NAME='h5dget_type_c') @@ -449,44 +371,20 @@ CONTAINS hdferr = h5dget_type_c (dataset_id, datatype_id) END SUBROUTINE h5dget_type_f -! -!****s* H5D/h5dset_extent -! -! NAME -! h5dset_extent (instead of obsolete name: h5dextend_f) -! -! PURPOSE -! Extends a dataset with unlimited dimension. -! -! INPUTS -! dataset_id - dataset identifier -! size - array containing the new magnitude of -! each dimension -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! Changed name from the now obsolete h5dextend_f -! to h5dset_extent_f. Provided interface to old name -! for backward compatibility. -MSB- March 14, 2008 -! -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Extends a dataset with unlimited dimension. +!! +!! \param dataset_id Dataset identifier +!! \param size Array containing the new magnitude of each dimension +!! \param hdferr \fortran_error +!! SUBROUTINE h5dset_extent_f(dataset_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dataset_id ! Dataset identifier + INTEGER(HID_T), INTENT(IN) :: dataset_id INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: size - ! Array containing - ! dimensions' sizes - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5dset_extent_c(dataset_id, size) & BIND(C,NAME='h5dset_extent_c') @@ -500,37 +398,20 @@ CONTAINS hdferr = H5Dset_extent_c(dataset_id, size) END SUBROUTINE h5dset_extent_f -!****s* H5D/h5dget_create_plist_f -! -! NAME -! h5dget_create_plist_f -! -! PURPOSE -! Returns an identifier for a copy of the dataset creation -! property list for a dataset. -! -! INPUTS -! dataset_id - dataset identifier -! OUTPUTS -! plist_id - creation property list identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Returns an identifier for a copy of the dataset creation property list for a dataset. +!! +!! \param dataset_id Dataset identifier +!! \param plist_id Creation property list identifier +!! \param hdferr \fortran_error +!! SUBROUTINE h5dget_create_plist_f(dataset_id, plist_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dataset_id ! Dataset identifier - INTEGER(HID_T), INTENT(OUT) :: plist_id ! Dataset creation - ! property list identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: dataset_id + INTEGER(HID_T), INTENT(OUT) :: plist_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5dget_create_plist_c(dataset_id, plist_id) & BIND(C,NAME='h5dget_create_plist_c') @@ -543,32 +424,20 @@ CONTAINS hdferr = h5dget_create_plist_c(dataset_id, plist_id) END SUBROUTINE h5dget_create_plist_f -! -!****s* H5D/h5dget_storage_size_f -! -! NAME -! h5dget_storage_size_f -! -! PURPOSE -! Returns the amount of storage requires by a dataset -! -! INPUTS -! dataset_id - dataset identifier -! OUTPUTS -! size - datastorage size -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! October 15, 2002 -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Returns the amount of storage requires by a dataset +!! +!! \param dataset_id Dataset identifier +!! \param size Datastorage size +!! \param hdferr \fortran_error +!! SUBROUTINE h5dget_storage_size_f(dataset_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dataset_id ! Dataset identifier - INTEGER(HSIZE_T), INTENT(OUT) :: size ! Amount of storage - ! allocated for dataset - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: dataset_id + INTEGER(HSIZE_T), INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5dget_storage_size_c(dataset_id, size) & BIND(C,NAME='h5dget_storage_size_c') @@ -581,38 +450,24 @@ CONTAINS hdferr = h5dget_storage_size_c(dataset_id, size) END SUBROUTINE h5dget_storage_size_f -! -!****s* H5D/h5dvlen_get_max_len_f -! -! NAME -! h5dvlen_get_max_len_f -! -! PURPOSE -! Returns maximum length of the VL array elements -! -! INPUTS -! dataset_id - dataset identifier -! type_id - datatype identifier -! space_id - dataspace identifier -! OUTPUTS -! size - buffer size -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! NONE -! -! AUTHOR -! Elena Pourmal -! October 15, 2002 -! -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Returns maximum length of the VL array elements +!! +!! \param dataset_id Dataset identifier +!! \param type_id Datatype identifier +!! \param space_id Dataspace identifier +!! \param len Buffer size +!! \param hdferr \fortran_error +!! SUBROUTINE h5dvlen_get_max_len_f(dataset_id, type_id, space_id, len, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dataset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier - INTEGER(HID_T), INTENT(IN) :: space_id ! Dataspace identifier - INTEGER(SIZE_T), INTENT(OUT) :: len ! Maximum length of the element - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: dataset_id + INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER(HID_T), INTENT(IN) :: space_id + INTEGER(SIZE_T), INTENT(OUT) :: len + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5dvlen_get_max_len_c(dataset_id, type_id, space_id, len) & BIND(C,NAME='h5dvlen_get_max_len_c') @@ -627,36 +482,24 @@ CONTAINS hdferr = h5dvlen_get_max_len_c(dataset_id, type_id, space_id, len) END SUBROUTINE h5dvlen_get_max_len_f -! -!****s* H5D/h5dget_space_status_f -! -! NAME -! h5dget_space_status_f -! -! PURPOSE -! Returns the status of data space allocation. -! -! INPUTS -! dset_id - dataset identifier -! OUTPUTS -! flag - status; may have one of the following values: -! H5D_SPACE_STS_ERROR_F -! H5D_SPACE_STS_NOT_ALLOCATED_F -! H5D_SPACE_STS_PART_ALLOCATED_F -! H5D_SPACE_STS_ALLOCATED_F -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! March 12, 2003 -! -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Returns the status of data space allocation. +!! +!! \param dset_id Dataset identifier +!! \param flag Status; may have one of the following values: +!! \li H5D_SPACE_STS_ERROR_F +!! \li H5D_SPACE_STS_NOT_ALLOCATED_F +!! \li H5D_SPACE_STS_PART_ALLOCATED_F +!! \li H5D_SPACE_STS_ALLOCATED_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5dget_space_status_f(dset_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataspace identifier - INTEGER, INTENT(OUT) :: flag ! Memory buffer to fill in - INTEGER, INTENT(OUT) :: hdferr ! Error code - !***** + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER, INTENT(OUT) :: flag + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5dget_space_status_c(dset_id, flag) & BIND(C,NAME='h5dget_space_status_c') @@ -669,41 +512,28 @@ CONTAINS hdferr = h5dget_space_status_c(dset_id, flag) END SUBROUTINE h5dget_space_status_f -! -!****s* H5D/h5dcreate_anon_f -! -! NAME -! h5dcreate_anon_f -! -! PURPOSE -! Creates a dataset in a file without linking it into the file structure -! -! INPUTS -! loc_id - Identifier of the file or group within which to create the dataset. -! type_id - Identifier of the datatype to use when creating the dataset. -! space_id - Identifier of the dataspace to use when creating the dataset. -! OUTPUTS -! dset_id - dataset identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! dcpl_id - Dataset creation property list identifier. -! dapl_id - Dataset access property list identifier. -! -! AUTHOR -! M. Scot Breitenfeld -! February 11, 2008 -! -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Creates a dataset in a file without linking it into the file structure +!! +!! \param loc_id Identifier of the file or group within which to create the dataset. +!! \param type_id Identifier of the datatype to use when creating the dataset. +!! \param space_id Identifier of the dataspace to use when creating the dataset. +!! \param dset_id Dataset identifier. +!! \param hdferr \fortran_error +!! \param dcpl_id Dataset creation property list identifier. +!! \param dapl_id Dataset access property list identifier. +!! SUBROUTINE h5dcreate_anon_f(loc_id, type_id, space_id, dset_id, hdferr, dcpl_id, dapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier. - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier. - INTEGER(HID_T), INTENT(IN) :: space_id ! Dataspace identifier. - INTEGER(HID_T), INTENT(OUT) :: dset_id ! Dataset identifier. - INTEGER, INTENT(OUT) :: hdferr ! Error code. - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: dcpl_id ! Dataset creation property list identifier. - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: dapl_id ! Dataset access property list identifier. -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER(HID_T), INTENT(IN) :: space_id + INTEGER(HID_T), INTENT(OUT) :: dset_id + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: dcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: dapl_id INTEGER(HID_T) :: dcpl_id_default INTEGER(HID_T) :: dapl_id_default @@ -734,21 +564,83 @@ CONTAINS END SUBROUTINE h5dcreate_anon_f +#if H5_DOXYGEN_FORTRAN + !> + !! \ingroup FH5D + !! + !! \brief Reads variable-length data. F2003 API h5dread_f should be used instead. + !! + !! \param dset_id Dataset identifier. + !! \param mem_type_id Memory datatype identifier. + !! \param buf Data buffer; may be a scalar or an array, TYPE(TYPE) must be one of the following: + !! \li INTEGER + !! \li REAL + !! \li CHARACTER + !! \param dims Array to hold corresponding dimension sizes of data buffer buf, dim(k) has value of the k-th + !! dimension of buffer buf. Values are ignored if buf is a scalar. + !! \param len Array to store length of each element. + !! \param hdferr \fortran_error + !! \param mem_space_id Memory dataspace identifier, default value is H5S_ALL_F. + !! \param file_space_id File dataspace identifier, default value is H5S_ALL_F. + !! \param xfer_prp Transfer property list identifier, default value is H5P_DEFAULT_F. + !! + SUBROUTINE h5dread_vl_f(dset_id, mem_type_id, buf, dims, len, hdferr, mem_space_id, file_space_id, xfer_prp) + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + TYPE(TYPE), INTENT(INOUT), DIMENSION(dims(1),dims(2)) :: buf + + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims + INTEGER(SIZE_T), INTENT(INOUT), DIMENSION(*) :: len + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp + END SUBROUTINE h5dread_vl_f + !> + !! \ingroup FH5D + !! + !! \brief Writes variable-length data. F2003 API h5dwritef should be used instead. + !! + !! \param dset_id Dataset identifier. + !! \param mem_type_id Memory datatype identifier. + !! \param buf Data buffer; may be a scalar or an array, TYPE(TYPE) must be one of the following: + !! \li INTEGER + !! \li REAL + !! \li CHARACTER + !! \param dims Array to hold corresponding dimension sizes of data buffer buf, dim(k) has value of the k-th + !! dimension of buffer buf. Values are ignored if buf is a scalar. + !! \param len Array to store length of each element. + !! \param hdferr \fortran_error + !! \param mem_space_id Memory dataspace identifier, default value is H5S_ALL_F. + !! \param file_space_id File dataspace identifier, default value is H5S_ALL_F. + !! \param xfer_prp Transfer property list identifier, default value is H5P_DEFAULT_F. + !! + SUBROUTINE h5dwrite_vl_f(dset_id, mem_type_id, buf, dims, len, hdferr, mem_space_id, file_space_id, xfer_prp) + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + TYPE(TYPE), INTENT(IN),DIMENSION(dims(1),dims(2)) :: buf + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims + INTEGER(SIZE_T), INTENT(IN), DIMENSION(*) :: len + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp + END SUBROUTINE h5dwrite_vl_f + +#else SUBROUTINE h5dwrite_vl_integer(dset_id, mem_type_id, buf, dims, len, & hdferr, & mem_space_id, file_space_id, xfer_prp) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier - INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims ! MAX len x num_elem - INTEGER(SIZE_T), INTENT(IN), DIMENSION(*) :: len ! Array to store - ! the length of each - ! element - INTEGER, INTENT(IN), DIMENSION(dims(1),dims(2)), TARGET :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims + INTEGER(SIZE_T), INTENT(IN), DIMENSION(*) :: len + INTEGER, INTENT(IN), DIMENSION(dims(1),dims(2)), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default INTEGER(HID_T) :: file_space_id_default @@ -790,19 +682,15 @@ CONTAINS hdferr, & mem_space_id, file_space_id, xfer_prp) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier - INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims ! MAX len x num_elem - INTEGER(SIZE_T), INTENT(INOUT), DIMENSION(*) :: len ! Array to store - ! the length of each - ! element - INTEGER, INTENT(INOUT), & - DIMENSION(dims(1),dims(2)), TARGET :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! -1 if failed, 0 otherwise - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims + INTEGER(SIZE_T), INTENT(INOUT), DIMENSION(*) :: len + INTEGER, INTENT(INOUT), DIMENSION(dims(1),dims(2)), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default INTEGER(HID_T) :: file_space_id_default @@ -847,18 +735,16 @@ CONTAINS hdferr, & mem_space_id, file_space_id, xfer_prp) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier - INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims ! MAX len x num_elem - INTEGER(SIZE_T), INTENT(IN), DIMENSION(*) :: len ! Array to store - ! the length of each - ! element + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims + INTEGER(SIZE_T), INTENT(IN), DIMENSION(*) :: len REAL, INTENT(IN), & DIMENSION(dims(1),dims(2)) :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default @@ -903,17 +789,16 @@ CONTAINS hdferr, & mem_space_id, file_space_id, xfer_prp) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier - INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims ! MAX len x num_elem - INTEGER(SIZE_T), INTENT(INOUT), DIMENSION(*) :: len ! Array to store the length of each element + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims + INTEGER(SIZE_T), INTENT(INOUT), DIMENSION(*) :: len REAL, INTENT(INOUT), & DIMENSION(dims(1),dims(2)) :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! -1 if failed, 0 otherwise - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default @@ -961,15 +846,15 @@ CONTAINS mem_space_id, file_space_id, xfer_prp) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_CHAR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier - INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims ! Number of strings - INTEGER(SIZE_T), INTENT(IN), DIMENSION(*) :: str_len ! Array to store the length of each element - CHARACTER(LEN=*), INTENT(IN), DIMENSION(dims(2)) :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims + INTEGER(SIZE_T), INTENT(IN), DIMENSION(*) :: str_len + CHARACTER(LEN=*), INTENT(IN), DIMENSION(dims(2)) :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default @@ -1014,18 +899,16 @@ CONTAINS SUBROUTINE h5dread_vl_string(dset_id, mem_type_id, buf, dims, str_len, & hdferr, mem_space_id, file_space_id, xfer_prp) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier - INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims ! number of strings - INTEGER(SIZE_T), INTENT(OUT), DIMENSION(*) :: str_len ! Array to store - ! the length of each - ! element + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(2) :: dims + INTEGER(SIZE_T), INTENT(OUT), DIMENSION(*) :: str_len CHARACTER(LEN=*), INTENT(OUT), & DIMENSION(dims(2)) :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default @@ -1064,33 +947,22 @@ CONTAINS buf, dims, str_len) RETURN END SUBROUTINE h5dread_vl_string +#endif -! -!****s* H5D/h5dget_offset_f -! -! NAME -! h5dget_offset_f -! -! PURPOSE -! Returns dataset address in file. -! -! INPUTS -! dataset_id - Dataset identifier. -! OUTPUTS -! offset - The offset in bytes. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! April 16, 2015 -! -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Returns dataset address in file. +!! +!! \param dset_id Dataset identifier. +!! \param offset The offset in bytes. +!! \param hdferr \fortran_error +!! SUBROUTINE h5dget_offset_f(dset_id, offset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dset_id INTEGER(HADDR_T), INTENT(OUT) :: offset INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER(HADDR_T) FUNCTION h5dget_offset(dset_id) BIND(C,NAME='H5Dget_offset') IMPORT :: HID_T, HADDR_T @@ -1105,38 +977,21 @@ CONTAINS END SUBROUTINE h5dget_offset_f -! -!****s* H5D/h5dget_space_f -! -! NAME -! h5dget_space_f -! -! PURPOSE -! Returns an identifier for a copy of the dataspace for a -! dataset. -! -! INPUTS -! dataset_id - dataset identifier -! OUTPUTS -! dataspace_id - dataspace identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Returns an identifier for a copy of the dataspace for a +!! dataset. +!! +!! \param dataset_id Dataset identifier. +!! \param dataspace_id Dataspace identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5dget_space_f(dataset_id, dataspace_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dataset_id ! Dataset identifier - INTEGER(HID_T), INTENT(OUT) :: dataspace_id ! Dataspace identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: dataset_id + INTEGER(HID_T), INTENT(OUT) :: dataspace_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5dget_space_c(dataset_id, dataspace_id) BIND(C,NAME='h5dget_space_c') IMPORT :: HID_T @@ -1149,32 +1004,20 @@ CONTAINS hdferr = h5dget_space_c(dataset_id, dataspace_id) END SUBROUTINE h5dget_space_f -!****s* H5D/h5dget_access_plist_f -! -! NAME -! h5dget_access_plist_f -! -! PURPOSE -! Returns a copy of the dataset creation property list. -! -! INPUTS -! dset_id - Dataset identifier -! -! OUTPUTS -! plist_id - Dataset access property list identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! April 13, 2009 -! -! SOURCE +!> +!! \ingroup FH5D +!! +!! \brief Returns a copy of the dataset creation property list. +!! +!! \param dset_id Dataset identifier. +!! \param plist_id Dataset access property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5dget_access_plist_f(dset_id, plist_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dset_id INTEGER(HID_T), INTENT(OUT) :: plist_id INTEGER , INTENT(OUT) :: hdferr - !***** INTERFACE INTEGER FUNCTION h5dget_access_plist_c(dset_id, plist_id) BIND(C,NAME='h5dget_access_plist_c') IMPORT :: HID_T @@ -1188,19 +1031,191 @@ CONTAINS END SUBROUTINE h5dget_access_plist_f +!> +!! \ingroup FH5D +!! +!! \brief Reclaims VL datatype memory buffers. +!! +!! \param type_id Identifier of the datatype. +!! \param space_id Identifier of the dataspace. +!! \param plist_id Identifier of the property list used to create the buffer. +!! \param buf Pointer to the buffer to be reclaimed. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5dvlen_reclaim_f(type_id, space_id, plist_id, buf, hdferr) + IMPLICIT NONE + INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER(HID_T), INTENT(IN) :: space_id + INTEGER(HID_T), INTENT(IN) :: plist_id + TYPE(C_PTR) , INTENT(INOUT) :: buf + INTEGER , INTENT(OUT) :: hdferr + + INTERFACE + INTEGER FUNCTION h5dvlen_reclaim_c(type_id, space_id, plist_id, buf) BIND(C, NAME='h5dvlen_reclaim_c') + IMPORT :: C_PTR + IMPORT :: HID_T + IMPLICIT NONE + INTEGER(HID_T) :: type_id + INTEGER(HID_T) :: space_id + INTEGER(HID_T) :: plist_id + TYPE(C_PTR), VALUE :: buf + END FUNCTION h5dvlen_reclaim_c + END INTERFACE + + hdferr = H5Dvlen_reclaim_c(type_id, space_id, plist_id, buf) + + END SUBROUTINE H5Dvlen_reclaim_f + +#ifdef H5_DOXYGEN_FORTRAN +!> +!! \ingroup FH5D +!! +!! \brief Writes raw data from a dataset into a buffer. +!! +!! \note \fortran_approved +!! +!! \param dset_id Identifier of the dataset to write to. +!! \param mem_type_id Identifier of the memory datatype. +!! \param buf Buffer with data to be written to the file. +!! \param hdferr \fortran_error +!! \param mem_space_id Identifier of the memory dataspace. +!! \param file_space_id Identifier of the dataset's dataspace in the file. +!! \param xfer_prp Identifier of a transfer property list for this I/O operation. +!! + SUBROUTINE h5dwrite_f(dset_id, mem_type_id, buf, hdferr, mem_space_id, file_space_id, xfer_prp) + USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR + IMPLICIT NONE + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + TYPE(C_PTR), INTENT(IN) :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp + END SUBROUTINE h5dwrite +!> +!! \ingroup FH5D +!! +!! \brief Reads raw data from a dataset into a buffer (Passes Pointer). +!! +!! \note \fortran_approved +!! +!! \param dset_id Identifier of the dataset read from. +!! \param mem_type_id Identifier of the memory datatype. +!! \param buf Buffer to receive data read from file. +!! \param hdferr \fortran_error +!! \param mem_space_id Identifier of the memory dataspace. +!! \param file_space_id Identifier of dataset's dataspace in the file. (Default: H5S_ALL_F) +!! \param xfer_prp Identifier of a transfer property list for this I/O operation. +!! + SUBROUTINE h5dread_f(dset_id, mem_type_id, buf, hdferr, mem_space_id, file_space_id, xfer_prp) + USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR + IMPLICIT NONE + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + TYPE(C_PTR), INTENT(INOUT) :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp + END SUBROUTINE h5dread_f + +!> +!! \ingroup FH5D +!! +!! \brief There is no direct Fortran90 counterpart for the C function H5Dwrite. Instead, that +!! functionality is provided by two Fortran90 subroutines: +!! \li h5dwrite_f Purpose: Writes data other than variable-length data. +!! \li h5dwrite_vl_f Purpose: Writes variable-length data. +!! +!! \note \fortran_obsolete +!! +!! \param dset_id Identifier of the dataset to write to. +!! \param mem_type_id Identifier of the memory datatype. +!! \param buf Data buffer; may be a scalar or an array. +!! \param dims Array to hold corresponding dimension sizes of data buffer buf; dim(k) has value. +!! of the k-th dimension of buffer buf; values are ignored if buf is a scalar. +!! \param hdferr \fortran_error +!! \param mem_space_id Identifier of the memory dataspace. Default value is H5S_ALL_F. +!! \param file_space_id Identifier of the dataset's dataspace in the file. Default value is H5S_ALL_F. +!! \param xfer_prp Identifier of a transfer property list for this I/O operation. Default value is H5P_DEFAULT_F. +!! + SUBROUTINE h5dwrite_f___F90_VERSION(dset_id, mem_type_id, buf, dims, hdferr, mem_space_id, file_space_id, xfer_prp) + IMPLICIT NONE + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + TYPE(TYPE), INTENT(IN) :: buf + DIMENSION(*), INTEGER(HSIZE_T), INTENT(IN) :: dims + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp + END SUBROUTINE h5dwrite_f___F90_VERSION + +!> +!! \ingroup FH5D +!! +!! \brief There is no direct Fortran90 counterpart for the C function H5Dread. Instead, that functionality +!! is provided by two Fortran90 subroutines: +!! \li h5dread_f Purpose: Reads data other than variable-length data, uses DIMENSION argument and buf is not a pointer. +!! \li h5dread_vl_f Purpose: Reads variable-length data. +!! +!! \note \fortran_obsolete +!! +!! \param dset_id Identifier of the dataset read from. +!! \param mem_type_id Identifier of the memory datatype. +!! \param buf Buffer to receive data read from file, may be a scalar or an array. +!! \param dims Array to hold corresponding dimension sizes of data buffer buf. dim(k) has value of the k-th. +!! dimension of buffer buf. Values are ignored if buf is a scalar. +!! \param hdferr \fortran_error +!! \param mem_space_id Identifier of the memory dataspace. (Default: H5S_ALL_F) +!! \param file_space_id Identifier of dataset's dataspace in the file. (Default: H5S_ALL_F) +!! \param xfer_prp Identifier of a transfer property list for this I/O operation. (Default: H5P_DEFAULT_F) +!! + SUBROUTINE h5dread_f___F90_VERSION(dset_id, mem_type_id, buf, dims, hdferr, mem_space_id, file_space_id, xfer_prp) + IMPLICIT NONE + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims + TYPE(TYPE), INTENT(INOUT) :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp + END SUBROUTINE h5dread_f___F90_VERSION + +!> +!! \ingroup FH5D +!! +!! \brief Fills dataspace elements with a fill value in a memory buffer. +!! Only INTEGER, CHARACTER, REAL and DOUBLE PRECISION datatypes of the fillvalues and buffers are supported. +!! Buffer and fillvalue are assumed to have the same datatype. Only one-dimesional buffers are supported. +!! +!! \param fill_value Fill value. +!! \param space_id Identifier of the memory datatype. +!! \param buf Buffer to receive data read from file. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5dfill_f(fill_value, space_id, buf, hdferr) + TYPE(TYPE), INTENT(IN) :: fill_value + INTEGER(HID_T), INTENT(IN) :: space_id + TYPE(TYPE), INTENT(OUT), DIMENSION(*) :: buf + INTEGER, INTENT(OUT) :: hdferr + END SUBROUTINE h5dfill_f + +#else SUBROUTINE h5dwrite_reference_obj(dset_id, mem_type_id, buf, dims, hdferr, & mem_space_id, file_space_id, xfer_prp) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier - INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: dims ! size of the buffer buf - TYPE(hobj_ref_t_f), DIMENSION(dims(1)), INTENT(IN), TARGET :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: dims + TYPE(hobj_ref_t_f), DIMENSION(dims(1)), INTENT(IN), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default @@ -1225,14 +1240,14 @@ CONTAINS mem_space_id, file_space_id, xfer_prp) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier - INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: dims ! size of the buffer buf - TYPE(hdset_reg_ref_t_f), DIMENSION(dims(1)), INTENT(IN), TARGET :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id + INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: dims + TYPE(hdset_reg_ref_t_f), DIMENSION(dims(1)), INTENT(IN), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default @@ -1287,14 +1302,14 @@ CONTAINS mem_space_id, file_space_id, xfer_prp) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims - CHARACTER(*), INTENT(IN), TARGET :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + CHARACTER(*), INTENT(IN), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp CALL h5dwrite_char_scalar_fix(dset_id, mem_type_id, buf, LEN(buf), dims, hdferr, & mem_space_id, file_space_id, xfer_prp) @@ -1305,15 +1320,15 @@ CONTAINS mem_space_id, file_space_id, xfer_prp) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims INTEGER, INTENT(IN) :: buf_len - CHARACTER(LEN=buf_len), INTENT(IN), TARGET :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + CHARACTER(LEN=buf_len), INTENT(IN), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default INTEGER(HID_T) :: file_space_id_default @@ -1338,15 +1353,15 @@ CONTAINS mem_space_id, file_space_id, xfer_prp) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims TYPE(hobj_ref_t_f), INTENT(INOUT) , & DIMENSION(dims(1)), TARGET :: buf - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default @@ -1370,15 +1385,15 @@ CONTAINS SUBROUTINE h5dread_reference_dsetreg(dset_id, mem_type_id, buf, dims, hdferr, & mem_space_id, file_space_id, xfer_prp) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims TYPE(hdset_reg_ref_t_f), INTENT(INOUT), & DIMENSION(dims(1)), TARGET :: buf - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default INTEGER(HID_T) :: file_space_id_default @@ -1433,14 +1448,15 @@ CONTAINS mem_space_id, file_space_id, xfer_prp) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id INTEGER(HSIZE_T), INTENT(IN), DIMENSION(*) :: dims - CHARACTER(LEN=*), INTENT(INOUT) :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + + CHARACTER(LEN=*), INTENT(INOUT) :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default @@ -1463,14 +1479,14 @@ CONTAINS mem_space_id, file_space_id, xfer_prp) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id INTEGER, INTENT(IN) :: buf_len - CHARACTER(LEN=buf_len), INTENT(INOUT), TARGET :: buf ! Data buffer - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + CHARACTER(LEN=buf_len), INTENT(INOUT), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp TYPE(C_PTR) :: f_ptr @@ -1481,53 +1497,17 @@ CONTAINS END SUBROUTINE h5dread_char_scalar_fix -!****s* H5D (F03)/h5dwrite_f_F03 -! -! NAME -! h5dwrite_f_F03 -! -! PURPOSE -! Writes raw data from a dataset into a buffer. -! -! Inputs: -! dset_id - Identifier of the dataset to write to. -! mem_type_id - Identifier of the memory datatype. -! buf - Buffer with data to be written to the file. -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! Optional parameters: -! mem_space_id - Identifier of the memory dataspace. -! file_space_id - Identifier of the dataset's dataspace in the file. -! xfer_prp - Identifier of a transfer property list for this I/O operation. -! -! AUTHOR -! M. Scot Breitenfeld -! September 17, 2011 -! -! Fortran2003 Interface: -!! SUBROUTINE h5dwrite_f(dset_id, mem_type_id, buf, hdferr, & -!! mem_space_id, file_space_id, xfer_prp) -!! INTEGER(HID_T), INTENT(IN) :: dset_id -!! INTEGER(HID_T), INTENT(IN) :: mem_type_id -!! TYPE(C_PTR) , INTENT(IN) :: buf -!! INTEGER , INTENT(OUT) :: hdferr -!! INTEGER(HID_T), INTENT(IN) , OPTIONAL :: mem_space_id -!! INTEGER(HID_T), INTENT(IN) , OPTIONAL :: file_space_id -!! INTEGER(HID_T), INTENT(IN) , OPTIONAL :: xfer_prp -!***** SUBROUTINE h5dwrite_ptr(dset_id, mem_type_id, buf, hdferr, & mem_space_id, file_space_id, xfer_prp) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id TYPE(C_PTR), INTENT(IN) :: buf - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default @@ -1546,53 +1526,17 @@ CONTAINS END SUBROUTINE h5dwrite_ptr -!****s* H5D (F03)/h5dread_f_F03 -! -! NAME -! h5dread_f_F03 -! -! PURPOSE -! Reads raw data from a dataset into a buffer. -! -! Inputs: -! dset_id - Identifier of the dataset read from. -! mem_type_id - Identifier of the memory datatype. -! -! Outputs: -! buf - Buffer to receive data read from file. -! hdferr - Returns 0 if successful and -1 if fails -! -! Optional parameters: -! mem_space_id - Identifier of the memory dataspace. -! file_space_id - Identifier of the dataset's dataspace in the file. -! xfer_prp - Identifier of a transfer property list for this I/O operation. -! -! AUTHOR -! M. Scot Breitenfeld -! September 17, 2011 -! -! Fortran2003 Interface: -!! SUBROUTINE h5dread_f(dset_id, mem_type_id, buf, hdferr, & -!! mem_space_id, file_space_id, xfer_prp) -!! INTEGER(HID_T), INTENT(IN) :: dset_id -!! INTEGER(HID_T), INTENT(IN) :: mem_type_id -!! TYPE(C_PTR) , INTENT(INOUT) :: buf -!! INTEGER , INTENT(OUT) :: hdferr -!! INTEGER(HID_T), INTENT(IN) , OPTIONAL :: mem_space_id -!! INTEGER(HID_T), INTENT(IN) , OPTIONAL :: file_space_id -!! INTEGER(HID_T), INTENT(IN) , OPTIONAL :: xfer_prp -!***** SUBROUTINE h5dread_ptr(dset_id, mem_type_id, buf, hdferr, & mem_space_id, file_space_id, xfer_prp) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - INTEGER(HID_T), INTENT(IN) :: mem_type_id ! Memory datatype identifier + INTEGER(HID_T), INTENT(IN) :: dset_id + INTEGER(HID_T), INTENT(IN) :: mem_type_id TYPE(C_PTR), INTENT(INOUT) :: buf - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id ! Memory dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id ! File dataspace identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp ! Transfer property list identifier + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: mem_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: file_space_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: xfer_prp INTEGER(HID_T) :: xfer_prp_default INTEGER(HID_T) :: mem_space_id_default @@ -1611,31 +1555,6 @@ CONTAINS END SUBROUTINE h5dread_ptr -! -! NAME -! h5dfill_integer -! -! PURPOSE -! Fills dataspace elements with a fill value in a memory buffer. -! Only INTEGER, CHARACTER, REAL and DOUBLE PRECISION datatypes -! of the fillvalues and buffers are supported. Buffer and fillvalue -! are assumed to have the same datatype. -! Only one-dimesional buffers are supported. -! -! Inputs: -! fill_value - fill value -! space_id - memory space selection identifier -! buf - memory buffer containing the selection to be filled -! Outputs: -! hdferr: - error code -! Success: 0 -! Failure: -1 -! AUTHOR -! Elena Pourmal -! March 12, 2003 -! -! - SUBROUTINE h5dfill_integer(fill_value, space_id, buf, hdferr) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE @@ -1661,37 +1580,13 @@ CONTAINS END SUBROUTINE h5dfill_integer -! -! NAME -! h5dfill_c_float -! -! PURPOSE -! Fills dataspace elements with a fill value in a memory buffer. -! Only INTEGER, CHARACTER, REAL and DOUBLE PRECISION datatypes -! of the fillvalues and buffers are supported. Buffer and fillvalue -! are assumed to have the same datatype. -! Only one-dimesional buffers are supported. -! -! Inputs: -! fill_value - fill value -! space_id - memory space selection identifier -! buf - memory buffer containing the selection to be filled -! Outputs: -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! March 12, 2003 -! SUBROUTINE h5dfill_c_float(fill_valuer, space_id, buf, hdferr) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - REAL(KIND=C_FLOAT), INTENT(IN), TARGET :: fill_valuer ! Fill value - INTEGER(HID_T), INTENT(IN) :: space_id ! Memory dataspace selection identifier - REAL(KIND=C_FLOAT), INTENT(IN), DIMENSION(*), TARGET :: buf ! Memory buffer to fill in - INTEGER, INTENT(OUT) :: hdferr ! Error code + REAL(KIND=C_FLOAT), INTENT(IN), TARGET :: fill_valuer + INTEGER(HID_T), INTENT(IN) :: space_id + REAL(KIND=C_FLOAT), INTENT(OUT), DIMENSION(*), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T) :: fill_type_id ! Fill value datatype identifier INTEGER(HID_T) :: mem_type_id ! Buffer dadtype identifier @@ -1710,35 +1605,12 @@ CONTAINS END SUBROUTINE h5dfill_c_float - !---------------------------------------------------------------------- - ! Name: h5dfill_c_double - ! - ! Purpose: Fills dataspace elements with a fill value in a memory buffer. - ! Only INTEGER, CHARACTER, REAL and DOUBLE PRECISION datatypes - ! of the fillvalues and buffers are supported. Buffer and fillvalue - ! are assumed to have the same datatype. - ! Only one-dimesional buffers are supported. - ! - ! Inputs: - ! fill_value - fill value - ! space_id - memory space selection identifier - ! buf - memory buffer containing the selection to be filled - ! Outputs: - ! hdferr: - error code - ! Success: 0 - ! Failure: -1 - ! - ! Programmer: Elena Pourmal - ! March 12, 2003 - ! - !---------------------------------------------------------------------- - SUBROUTINE h5dfill_c_double(fill_value, space_id, buf, hdferr) IMPLICIT NONE - REAL(KIND=C_DOUBLE), INTENT(IN), TARGET :: fill_value ! Fill value - INTEGER(HID_T), INTENT(IN) :: space_id ! Memory dataspace selection identifier - REAL(KIND=C_DOUBLE), INTENT(IN), DIMENSION(*), TARGET :: buf ! Memory buffer to fill in - INTEGER, INTENT(OUT) :: hdferr ! Error code + REAL(KIND=C_DOUBLE), INTENT(IN), TARGET :: fill_value + INTEGER(HID_T), INTENT(IN) :: space_id + REAL(KIND=C_DOUBLE), INTENT(OUT), DIMENSION(*), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T) :: fill_type_id ! Fill value datatype identifier INTEGER(HID_T) :: mem_type_id ! Buffer dadtype identifier @@ -1760,10 +1632,10 @@ CONTAINS #if H5_FORTRAN_C_LONG_DOUBLE_IS_UNIQUE!=0 SUBROUTINE h5dfill_c_long_double(fill_value, space_id, buf, hdferr) IMPLICIT NONE - REAL(KIND=C_LONG_DOUBLE), INTENT(IN), TARGET :: fill_value ! Fill value - INTEGER(HID_T), INTENT(IN) :: space_id ! Memory dataspace selection identifier - REAL(KIND=C_LONG_DOUBLE), INTENT(IN), DIMENSION(*), TARGET :: buf ! Memory buffer to fill in - INTEGER, INTENT(OUT) :: hdferr ! Error code + REAL(KIND=C_LONG_DOUBLE), INTENT(IN), TARGET :: fill_value + INTEGER(HID_T), INTENT(IN) :: space_id + REAL(KIND=C_LONG_DOUBLE), INTENT(OUT), DIMENSION(*), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T) :: fill_type_id ! Fill value datatype identifier INTEGER(HID_T) :: mem_type_id ! Buffer dadtype identifier @@ -1782,36 +1654,14 @@ CONTAINS END SUBROUTINE h5dfill_c_long_double #endif -! -! NAME -! h5dfill_char -! -! PURPOSE -! Fills dataspace elements with a fill value in a memory buffer. -! Only INTEGER, CHARACTER, REAL and DOUBLE PRECISION datatypes -! of the fillvalues and buffers are supported. Buffer and fillvalue -! are assumed to have the same datatype. -! Only one-dimesional buffers are supported. -! -! Inputs: -! fill_value - fill value -! space_id - memory space selection identifier -! buf - memory buffer containing the selection to be filled -! Outputs: -! hdferr: - error code -! Success: 0 -! Failure: -1 -! AUTHOR -! Elena Pourmal -! March 12, 2003 -! + SUBROUTINE h5dfill_char(fill_value, space_id, buf, hdferr) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - CHARACTER, INTENT(IN), TARGET :: fill_value ! Fill value - INTEGER(HID_T), INTENT(IN) :: space_id ! Memory dataspace selection identifier - CHARACTER, INTENT(IN), DIMENSION(*), TARGET :: buf ! Memory buffer to fill in - INTEGER, INTENT(OUT) :: hdferr ! Error code + CHARACTER, INTENT(IN), TARGET :: fill_value + INTEGER(HID_T), INTENT(IN) :: space_id + CHARACTER, INTENT(OUT), DIMENSION(*), TARGET :: buf + INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T) :: fill_type_id ! Fill value datatype identifier INTEGER(HID_T) :: mem_type_id ! Buffer dadtype identifier @@ -1826,54 +1676,8 @@ CONTAINS f_ptr_buf, mem_type_id) END SUBROUTINE h5dfill_char -! -!****s* H5D (F03)/h5dvlen_reclaim_f -! NAME -! h5dvlen_reclaim_f -! -! PURPOSE -! Reclaims VL datatype memory buffers. -! -! Inputs: -! -! type_id - Identifier of the datatype. -! space_id - Identifier of the dataspace. -! plist_id - Identifier of the property list used to create the buffer. -! buf - Pointer to the buffer to be reclaimed. -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! January 11, 2011 -! -! Fortran2003 Interface: - SUBROUTINE h5dvlen_reclaim_f(type_id, space_id, plist_id, buf, hdferr) - IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: type_id - INTEGER(HID_T), INTENT(IN) :: space_id - INTEGER(HID_T), INTENT(IN) :: plist_id - TYPE(C_PTR) , INTENT(INOUT) :: buf - INTEGER , INTENT(OUT) :: hdferr -!***** - - INTERFACE - INTEGER FUNCTION h5dvlen_reclaim_c(type_id, space_id, plist_id, buf) BIND(C, NAME='h5dvlen_reclaim_c') - IMPORT :: C_PTR - IMPORT :: HID_T - IMPLICIT NONE - INTEGER(HID_T) :: type_id - INTEGER(HID_T) :: space_id - INTEGER(HID_T) :: plist_id - TYPE(C_PTR), VALUE :: buf - END FUNCTION h5dvlen_reclaim_c - END INTERFACE - - hdferr = H5Dvlen_reclaim_c(type_id, space_id, plist_id, buf) - - END SUBROUTINE H5Dvlen_reclaim_f +#endif END MODULE H5D diff --git a/fortran/src/H5Eff.F90 b/fortran/src/H5Eff.F90 index d0e7c41..0d7a873 100644 --- a/fortran/src/H5Eff.F90 +++ b/fortran/src/H5Eff.F90 @@ -1,13 +1,13 @@ -!****h* ROBODoc/H5E -! -! NAME -! MODULE H5E -! -! FILE -! fortran/src/H5Eff.F90 -! -! PURPOSE -! This Module contains Fortran interfaces for H5E functions. +!> @defgroup FH5E Fortran Error (H5E) Interface +!! +!! @see H5E, C-API +!! +!! @see @ref H5E_UG, User Guide +!! + +!> @ingroup FH5E +!! +!! @brief This module contains Fortran interfaces for H5E functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -35,52 +35,29 @@ ! to the Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** MODULE H5E USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR, C_FUNPTR, C_CHAR USE H5GLOBAL - !Turn on automatic printing of errors - INTEGER, PARAMETER :: PRINTON = 1 - - !Turn off automatic printing of errors - INTEGER, PARAMETER :: PRINTOFF = 0 + INTEGER, PARAMETER :: PRINTON = 1 !< Turn on automatic printing of errors + INTEGER, PARAMETER :: PRINTOFF = 0 !< Turn off automatic printing of errors CONTAINS -!****s* H5E/h5eclear_f -! -! NAME -! h5eclear_f -! -! PURPOSE -! Clears the error stack for the current thread. -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! estack_id - Error Stack id -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). April 6, 2001 -! -! Added optional error stack identifier in order to bring -! the function in line with the h5eclear2 routine. -! MSB, July 9, 2009 -! -! SOURCE +!> +!! \ingroup FH5E +!! +!! \brief Clears the error stack for the current thread. +!! +!! \param hdferr \fortran_error +!! \param estack_id Error Stack id +!! SUBROUTINE h5eclear_f(hdferr, estack_id) IMPLICIT NONE - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T), OPTIONAL, INTENT(IN) :: estack_id -!***** INTEGER(HID_T) :: estack_id_default INTERFACE @@ -97,33 +74,17 @@ CONTAINS hdferr = h5eclear_c(estack_id_default) END SUBROUTINE h5eclear_f -!****s* H5E/h5eprint_f -! -! NAME -! h5eprint_f -! -! PURPOSE -! Prints the error stack in a default manner. -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! OPTIONAL PARAMETERS -! name - name of the file that contains print output -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). April 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5E +!! +!! \brief Prints the error stack in a default manner. +!! +!! \param hdferr \fortran_error +!! \param name Name of the file that contains print output +!! SUBROUTINE h5eprint_f(hdferr, name) CHARACTER(LEN=*), OPTIONAL, INTENT(IN) :: name INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: namelen INTERFACE @@ -147,41 +108,21 @@ CONTAINS hdferr = h5eprint_c2() ENDIF END SUBROUTINE h5eprint_f -!****s* H5E/h5eget_major_f -! -! NAME -! h5eget_major_f -! -! PURPOSE -! Returns a character string describing an error specified -! by a major error number. -! -! INPUTS -! error_no - major error number -! -! OUTPUTS -! name - character string describing the error -! namelen - number of characters in the name buffer -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). April 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5E +!! +!! \brief Returns a character string describing an error specified by a major error number. +!! +!! \param error_no Major error number. +!! \param name Character string describing the error. +!! \param namelen Number of characters in the name buffer. +!! \param hdferr \fortran_error +!! SUBROUTINE h5eget_major_f(error_no, name, namelen, hdferr) - INTEGER, INTENT(IN) :: error_no ! Major error number - CHARACTER(LEN=*), INTENT(OUT) :: name ! Character string describing - ! the error. - INTEGER(SIZE_T), INTENT(IN) :: namelen ! Anticipated number of characters - ! in name. - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER, INTENT(IN) :: error_no + CHARACTER(LEN=*), INTENT(OUT) :: name + INTEGER(SIZE_T), INTENT(IN) :: namelen + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5eget_major_c(error_no, name, namelen) BIND(C,NAME='h5eget_major_c') IMPORT :: C_CHAR @@ -195,38 +136,19 @@ CONTAINS hdferr = h5eget_major_c(error_no, name, namelen) END SUBROUTINE h5eget_major_f -!****s* H5E/h5eget_minor_f -! -! NAME -! h5eget_minor_f -! -! PURPOSE -! Returns a character string describing an error specified -! by a minor error number. -! -! INPUTS -! error_no - minor error number -! -! OUTPUTS -! name - character string describing the error -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). April 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5E +!! +!! \brief Returns a character string describing an error specified by a minor error number. +!! +!! \param error_no Minor error number. +!! \param name Character string describing the error. +!! \param hdferr \fortran_error +!! SUBROUTINE h5eget_minor_f(error_no, name, hdferr) - INTEGER, INTENT(IN) :: error_no ! Major error number - CHARACTER(LEN=*), INTENT(OUT) :: name ! Character string describing - ! the error - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER, INTENT(IN) :: error_no + CHARACTER(LEN=*), INTENT(OUT) :: name + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5eget_minor_c(error_no, name) BIND(C,NAME='h5eget_minor_c') IMPORT :: C_CHAR @@ -238,31 +160,19 @@ CONTAINS hdferr = h5eget_minor_c(error_no, name) END SUBROUTINE h5eget_minor_f -!****s* H5E/h5eset_auto_f -! -! NAME -! h5eset_auto_f -! -! PURPOSE -! Returns settings for automatic error stack traversal function and its data. -! -! Inputs: -! printflag - Flag to turn automatic error printing on or off; -! possible values are: -! printon (1) -! printoff(0) -! estack_id - Error stack identifier. -! func - Function to be called upon an error condition. -! client_data - Data passed to the error function -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! July 10, 2009 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5E +!! +!! \brief Returns settings for automatic error stack traversal function and its data. +!! +!! \param printflag Flag to turn automatic error printing on or off; possible values are: +!! \li printon (1) +!! \li printoff(0) +!! \param estack_id Error stack identifier. +!! \param func Function to be called upon an error condition. +!! \param client_data Data passed to the error function. +!! \param hdferr \fortran_error +!! SUBROUTINE h5eset_auto_f(printflag, hdferr, estack_id, func, client_data) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR, C_FUNPTR INTEGER , INTENT(IN) :: printflag @@ -270,7 +180,6 @@ CONTAINS INTEGER(HID_T), INTENT(IN) , OPTIONAL :: estack_id TYPE(C_FUNPTR), INTENT(IN) , OPTIONAL :: func TYPE(C_PTR) , INTENT(IN) , OPTIONAL :: client_data -!***** INTEGER(HID_T) :: estack_id_default TYPE(C_FUNPTR) :: func_default TYPE(C_PTR) :: client_data_default diff --git a/fortran/src/H5Fff.F90 b/fortran/src/H5Fff.F90 index ecb40b7..817dab0 100644 --- a/fortran/src/H5Fff.F90 +++ b/fortran/src/H5Fff.F90 @@ -1,13 +1,13 @@ -!****h* ROBODoc/H5F -! -! NAME -! MODULE H5F -! -! FILE -! H5Fff.F90 -! -! PURPOSE -! This file contains Fortran interfaces for H5F functions. +!> @defgroup FH5F Fortran File (H5F) Interface +!! +!! @see H5F, C-API +!! +!! @see @ref H5F_UG, User Guide +!! + +!> @ingroup FH5F +!! +!! @brief This module contains Fortran interfaces for H5F functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -35,7 +35,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** MODULE H5F USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR, C_CHAR, C_NULL_PTR @@ -45,6 +44,7 @@ MODULE H5F ! Number of objects opened in H5open_f INTEGER(SIZE_T) :: H5OPEN_NUM_OBJ +#ifndef H5_DOXYGEN_FORTRAN INTERFACE INTEGER(C_INT) FUNCTION h5fis_accessible(name, & access_prp_default) BIND(C,NAME='H5Fis_accessible') @@ -56,53 +56,32 @@ MODULE H5F INTEGER(HID_T), INTENT(IN), VALUE :: access_prp_default END FUNCTION h5fis_accessible END INTERFACE +#endif CONTAINS -!****s* H5F/h5fcreate_f -! -! NAME -! h5fcreate_f -! -! PURPOSE -! Creates HDF5 files. -! -! INPUTS -! name - name of the file to create -! access_flags - File access flags. Allowable values are: -! H5F_ACC_TRUNC_F -! H5F_ACC_EXCL_F -! OUTPUTS -! file_id - file identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! OPTIONAL PARAMETERS -! creation_prp - file creation property list identifier -! access_prp - file access property list identifier -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Creates HDF5 files. +!! +!! \param name Name of the file to create. +!! \param access_flags File access flags. Allowable values are: +!! \li H5F_ACC_TRUNC_F +!! \li H5F_ACC_EXCL_F +!! \param file_id File identifier. +!! \param hdferr \fortran_error +!! \param creation_prp File creation property list identifier. +!! \param access_prp File access property list identifier. +!! SUBROUTINE h5fcreate_f(name, access_flags, file_id, hdferr, & creation_prp, access_prp) IMPLICIT NONE - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the file - INTEGER, INTENT(IN) :: access_flags ! File access flags - INTEGER(HID_T), INTENT(OUT) :: file_id ! File identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(IN) :: access_flags + INTEGER(HID_T), INTENT(OUT) :: file_id + INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T), OPTIONAL, INTENT(IN) :: creation_prp - ! File creation property - ! list identifier INTEGER(HID_T), OPTIONAL, INTENT(IN) :: access_prp - ! File access property list - ! identifier -!***** INTEGER(HID_T) :: creation_prp_default INTEGER(HID_T) :: access_prp_default INTEGER :: namelen ! Length of the name character string @@ -131,57 +110,23 @@ CONTAINS creation_prp_default, access_prp_default, file_id) END SUBROUTINE h5fcreate_f -!****s* H5F/h5fflush_f -! -! NAME -! h5fflush_f -! -! PURPOSE -! Flushes all buffers associated WITH a file to disk -! -! INPUTS -! object_id - identifier of object used to identify the file. -! scope - specifies the scope of the flushing action. -! Possible values are: -! H5F_SCOPE_GLOBAL_F -! H5F_SCOPE_LOCAL_F -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! OPTIONAL PARAMETERS -! creation_prp - file creation property list identifier -! access_prp - file access property list identifier -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Flushes all buffers associated with a file to disk +!! +!! \param object_id Identifier of object used to identify the file. +!! \param scope Specifies the scope of the flushing action. Possible values are: +!! \li H5F_SCOPE_GLOBAL_F +!! \li H5F_SCOPE_LOCAL_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5fflush_f(object_id, scope, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: object_id !identifier for any object - !associate with a file, - !including the file itself, - !a dataset, a group, an - !attribute, or a named - !data type - - INTEGER, INTENT(IN) :: scope !scope of the flushing - !action, possible values - !are: H5F_SCOPE_GLOBAL_F - ! which flushes the entire - !virtual file, - !and H5F_SCOPE_LOCAL_F - !which flushes only the - !specified file. - - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: object_id + INTEGER, INTENT(IN) :: scope + INTEGER, INTENT(OUT) :: hdferr + INTERFACE INTEGER FUNCTION h5fflush_c(object_id, scope) BIND(C,NAME='h5fflush_c') IMPORT :: HID_T @@ -194,47 +139,24 @@ CONTAINS hdferr = h5fflush_c(object_id, scope) END SUBROUTINE h5fflush_f -!****s* H5F/h5fmount_f -! -! NAME -! h5fmount_f -! -! PURPOSE -! Mounts a file. -! -! INPUTS -! loc_id - the identifier for of file or group in -! which name is defined -! name - the name of the group onto which the file -! specified by child_id is to be mounted. -! child_id - the identifier of the file to be mounted. -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! access_prp - the identifier of the property list to be used -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Mounts a file. +!! +!! \param loc_id The identifier for of file or group in which name is defined. +!! \param name The name of the group onto which the file specified by child_id is to be mounted. +!! \param child_id The identifier of the file to be mounted. +!! \param hdferr \fortran_error +!! \param access_prp The identifier of the property list to be used. +!! SUBROUTINE h5fmount_f(loc_id, name, child_id, hdferr, access_prp) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifier for file or group - ! in which dsetname is defined - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group - INTEGER(HID_T), INTENT(IN) :: child_id ! File identifier for the - ! file to be mounted - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(HID_T), INTENT(IN) :: child_id + INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T), OPTIONAL, INTENT(IN) :: access_prp - ! File access property list - ! identifier -!***** INTEGER(HID_T) :: access_prp_default INTEGER :: namelen ! Length of the name character string @@ -259,38 +181,20 @@ CONTAINS END SUBROUTINE h5fmount_f -!****s* H5F/h5funmount_f -! -! NAME -! h5funmount_f -! -! PURPOSE -! Unmounts a file. -! -! INPUTS -! loc_id - the identifier for of file or group in -! which name is defined -! name - the name of the mount point -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Unmounts a file. +!! +!! \param loc_id The identifier for of file or group in which name is defined. +!! \param name The name of the mount point. +!! \param hdferr \fortran_error +!! SUBROUTINE h5funmount_f(loc_id, name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifier for file or group - ! at which the specified file - ! is to be unmounted - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the mount point - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(OUT) :: hdferr INTEGER :: namelen ! Length of the name character string INTERFACE @@ -308,45 +212,26 @@ CONTAINS hdferr = h5funmount_c(loc_id, name, namelen) END SUBROUTINE h5funmount_f -!****s* H5F/h5fopen_f -! -! NAME -! h5fopen_f -! -! PURPOSE -! Opens HDF5 file. -! -! INPUTS -! name - name of the file to acecss -! access_flags - File access flags. Allowable values are: -! H5F_ACC_RDWR_F -! H5F_ACC_RDONLY_F -! OUTPUTS -! file_id - file identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! access_prp - file access property list identifier -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Opens HDF5 file. +!! +!! \param name Name of the file to acecss. +!! \param access_flags File access flags. Allowable values are: +!! \li H5F_ACC_RDWR_F +!! \li H5F_ACC_RDONLY_F +!! \param file_id File identifier. +!! \param hdferr \fortran_error +!! \param access_prp File access property list identifier. +!! SUBROUTINE h5fopen_f(name, access_flags, file_id, hdferr, access_prp) IMPLICIT NONE - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the file - INTEGER, INTENT(IN) :: access_flags ! File access flags - INTEGER(HID_T), INTENT(OUT) :: file_id ! File identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(IN) :: access_flags + INTEGER(HID_T), INTENT(OUT) :: file_id + INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T), OPTIONAL, INTENT(IN) :: access_prp - ! File access property list - ! identifier -!***** INTEGER(HID_T) :: access_prp_default INTEGER :: namelen ! Length of the name character string @@ -370,36 +255,20 @@ CONTAINS hdferr = h5fopen_c(name, namelen, access_flags, & access_prp_default, file_id) END SUBROUTINE h5fopen_f -!****s* H5F/h5freopen_f -! -! NAME -! h5freopen_f -! -! PURPOSE -! Reopens HDF5 file. -! -! INPUTS -! file_id - identifier of a file for which an -! additional identifier is required -! OUTPUTS -! ret_file_id - new file identifier -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Reopens HDF5 file. +!! +!! \param file_id Identifier of a file for which an additional identifier is required. +!! \param ret_file_id New file identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5freopen_f(file_id, ret_file_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier - INTEGER(HID_T), INTENT(OUT) :: ret_file_id ! New File identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: file_id + INTEGER(HID_T), INTENT(OUT) :: ret_file_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5freopen_c(file_id, ret_file_id) BIND(C,NAME='h5freopen_c') IMPORT :: HID_T @@ -412,37 +281,20 @@ CONTAINS hdferr = h5freopen_c(file_id, ret_file_id) END SUBROUTINE h5freopen_f -!****s* H5F/h5fget_create_plist_f -! -! NAME -! h5fget_create_plist_f -! -! PURPOSE -! Returns a file creation property list identifier. -! -! INPUTS -! file_id - identifier of a file to creation property list of -! OUTPUTS -! prop_id - creation property list identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Returns a file creation property list identifier. +!! +!! \param file_id Identifier of a file to creation property list of. +!! \param prop_id Creation property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5fget_create_plist_f(file_id, prop_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier - INTEGER(HID_T), INTENT(OUT) :: prop_id ! File creation property - ! list identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: file_id + INTEGER(HID_T), INTENT(OUT) :: prop_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5fget_create_plist_c(file_id, prop_id) BIND(C,NAME='h5fget_create_plist_c') IMPORT :: HID_T @@ -455,36 +307,20 @@ CONTAINS hdferr = h5fget_create_plist_c(file_id, prop_id) END SUBROUTINE h5fget_create_plist_f -!****s* H5F/h5fget_access_plist_f -! -! NAME -! h5fget_access_plist_f -! -! PURPOSE -! Returns a file access property list identifier. -! -! INPUTS -! file_id - identifier of a file to creation property list of -! OUTPUTS -! access_id - access property list identifier -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Returns a file access property list identifier. +!! +!! \param file_id Identifier of a file to creation property list of. +!! \param access_id Access property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5fget_access_plist_f(file_id, access_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier - INTEGER(HID_T), INTENT(OUT) :: access_id ! File access property - ! list identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: file_id + INTEGER(HID_T), INTENT(OUT) :: access_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5fget_access_plist_c(file_id, access_id) BIND(C,NAME='h5fget_access_plist_c') IMPORT :: HID_T @@ -498,41 +334,23 @@ CONTAINS END SUBROUTINE h5fget_access_plist_f -!****s* H5F/h5fis_accessible_f -! -! NAME -! h5fis_accessible_f -! -! PURPOSE -! Determines whether a file can be accessed as HDF5. -! -! INPUTS -! name - name of the file to check -! OUTPUTS -! status - indicates if file is and HDF5 file -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! access_prp - file access property list identifier -! AUTHOR -! Dana Robinson -! September 2018 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Determines whether a file can be accessed as HDF5. +!! +!! \param name Name of the file to check. +!! \param status Indicates if file is and HDF5 file. +!! \param hdferr \fortran_error +!! \param access_prp File access property list identifier. +!! SUBROUTINE h5fis_accessible_f(name, status, hdferr, access_prp) IMPLICIT NONE - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the file - LOGICAL, INTENT(OUT) :: status ! Indicates if file - ! is an HDF5 file - INTEGER, INTENT(OUT) :: hdferr ! Error code + CHARACTER(LEN=*), INTENT(IN) :: name + LOGICAL, INTENT(OUT) :: status + INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T), OPTIONAL, INTENT(IN) :: access_prp - ! File access property list - ! identifier -!***** + INTEGER(HID_T) :: access_prp_default CHARACTER(LEN=LEN_TRIM(name)+1,KIND=C_CHAR) :: c_name INTEGER(C_INT) :: flag ! "TRUE/FALSE/ERROR" flag from C routine @@ -555,42 +373,20 @@ CONTAINS ! XXX (VOL_MERGE): This function should probably be marked as ! deprecated since H5Fis_hdf5() is deprecated. -!****s* H5F/h5fis_hdf5_f -! -! NAME -! h5fis_hdf5_f -! -! PURPOSE -! Determines whether a file is in the HDF5 format. -! -! INPUTS -! name - name of the file to check -! OUTPUTS -! status - indicates if file is and HDF5 file -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! NOTES -! The underlying HDF5 C API call (H5Fis_hdf5) has been deprecated -! in favor of the VOL-capable H5Fis_accessible(). New code should -! use h5fis_accessible_f() instead of this function in case this -! function is deprecated in the future. -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Determines whether a file is in the HDF5 format. +!! +!! \param name Name of the file to check. +!! \param status Indicates if file is and HDF5 file. +!! \param hdferr \fortran_error +!! SUBROUTINE h5fis_hdf5_f(name, status, hdferr) IMPLICIT NONE - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the file - LOGICAL, INTENT(OUT) :: status ! Indicates if file - ! is an HDF5 file - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + CHARACTER(LEN=*), INTENT(IN) :: name + LOGICAL, INTENT(OUT) :: status + INTEGER, INTENT(OUT) :: hdferr CHARACTER(LEN=LEN_TRIM(name)+1,KIND=C_CHAR) :: c_name INTEGER(C_INT) :: flag ! "TRUE/FALSE/ERROR" flag from C routine ! to define status value. @@ -607,33 +403,18 @@ CONTAINS END SUBROUTINE h5fis_hdf5_f -!****s* H5F/h5fclose_f -! -! NAME -! h5fclose_f -! -! PURPOSE -! Closes HDF5 file. -! -! INPUTS -! file_id - file identifier -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Closes HDF5 file. +!! +!! \param file_id File identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5fclose_f(file_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: file_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5fclose_c(file_id) BIND(C,NAME='h5fclose_c') IMPORT :: HID_T @@ -646,41 +427,27 @@ CONTAINS END SUBROUTINE h5fclose_f -!****s* H5F/h5fget_obj_count_f -! -! NAME -! h5fget_obj_count_f -! -! PURPOSE -! Gets number of the objects open within a file -! -! INPUTS -! file_id - file identifier -! obj_type - type of the object; possible values are: -! H5F_OBJ_FILE_F -! H5F_OBJ_DATASET_F -! H5F_OBJ_GROUP_F -! H5F_OBJ_DATATYPE_F -! H5F_OBJ_ALL_F -! OUTPUTS -! obj_count - number of open objects -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! September 30, 2002 -! -! HISTORY -! Changed the type of obj_count to INTEGER(SIZE_T) -! September 25, 2008 EIP -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Gets number of the objects open within a file +!! +!! \param file_id File identifier. +!! \param obj_type Type of the object; possible values are: +!! \li H5F_OBJ_FILE_F +!! \li H5F_OBJ_DATASET_F +!! \li H5F_OBJ_GROUP_F +!! \li H5F_OBJ_DATATYPE_F +!! \li H5F_OBJ_ALL_F +!! \param obj_count Number of open objects. +!! \param hdferr \fortran_error +!! SUBROUTINE h5fget_obj_count_f(file_id, obj_type, obj_count, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: file_id INTEGER, INTENT(IN) :: obj_type INTEGER(SIZE_T), INTENT(OUT) :: obj_count INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5fget_obj_count_c(file_id, obj_type, obj_count) BIND(C,NAME='h5fget_obj_count_c') IMPORT :: HID_T, SIZE_T @@ -700,50 +467,32 @@ CONTAINS END SUBROUTINE h5fget_obj_count_f -!****s* H5F/h5fget_obj_ids_f -! -! NAME -! h5fget_obj_ids_f -! -! PURPOSE -! Get list of open objects identifiers within a file -! -! INPUTS -! file_id - file identifier -! obj_type - type of the object; possible values are: -! H5F_OBJ_FILE_F -! H5F_OBJ_DATASET_F -! H5F_OBJ_GROUP_F -! H5F_OBJ_DATATYPE_F -! H5F_OBJ_ALL_F -! OUTPUTS -! obj_ids - array of open object identifiers -! hdferr - Returns 0 if successful and -1 if fails -! -! OPTIONAL PARAMETERS -! num_objs - number of open objects -! -! AUTHOR -! Elena Pourmal -! September 30, 2002 -! -! HISTORY -! Added optional parameter num_objs for number of open objects -! of the specified type and changed type of max_obj to -! INTEGER(SIZE_T) -! September 25, 2008 EIP -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Get list of open objects identifiers within a file +!! +!! \param file_id File identifier. +!! \param obj_type Type of the object; possible values are: +!! \li H5F_OBJ_FILE_F +!! \li H5F_OBJ_DATASET_F +!! \li H5F_OBJ_GROUP_F +!! \li H5F_OBJ_DATATYPE_F +!! \li H5F_OBJ_ALL_F +!! \param max_objs Maximum # of objects to retrieve. +!! \param obj_ids Array of open object identifiers. +!! \param hdferr \fortran_error +!! \param num_objs Number of open objects. +!! SUBROUTINE h5fget_obj_ids_f(file_id, obj_type, max_objs, obj_ids, hdferr, num_objs) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier - INTEGER, INTENT(IN) :: obj_type ! Object type - INTEGER(SIZE_T), INTENT(IN) :: max_objs ! Maximum # of objects to retrieve + INTEGER(HID_T), INTENT(IN) :: file_id + INTEGER, INTENT(IN) :: obj_type + INTEGER(SIZE_T), INTENT(IN) :: max_objs INTEGER(HID_T), DIMENSION(*), INTENT(INOUT) :: obj_ids - ! Array of open objects iidentifiers - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(SIZE_T), INTENT(OUT), OPTIONAL :: num_objs ! number of open objects -!***** + INTEGER, INTENT(OUT) :: hdferr + INTEGER(SIZE_T), INTENT(OUT), OPTIONAL :: num_objs + INTEGER(SIZE_T) :: c_num_objs ! Number of open objects of the specified type INTERFACE @@ -763,32 +512,20 @@ CONTAINS IF (PRESENT(num_objs)) num_objs= c_num_objs END SUBROUTINE h5fget_obj_ids_f -!****s* H5F/h5fget_freespace_f -! -! NAME -! h5fget_freespace_f -! -! PURPOSE -! Get amount of free space within a file -! -! INPUTS -! file_id - file identifier -! OUTPUTS -! free_space - amount of free space in file -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Quincey Koziol -! October 7, 2003 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Get amount of free space within a file. +!! +!! \param file_id File identifier. +!! \param free_space Amount of free space in file. +!! \param hdferr \fortran_error +!! SUBROUTINE h5fget_freespace_f(file_id, free_space, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier + INTEGER(HID_T), INTENT(IN) :: file_id INTEGER(HSSIZE_T), INTENT(OUT) :: free_space - ! amount of free space in file - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5fget_freespace_c(file_id, free_space) & BIND(C,NAME='h5fget_freespace_c') @@ -802,34 +539,22 @@ CONTAINS hdferr = h5fget_freespace_c(file_id, free_space) END SUBROUTINE h5fget_freespace_f -!****s* H5F/h5fget_name_f -! -! NAME -! h5fget_name_f -! -! PURPOSE -! Gets the name of the file from the object identifier -! -! INPUTS -! obj_id - object identifier -! OUTPUTS -! buf - buffer to store the read name -! size - actual size of the name -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! July 6, 2004 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Gets the name of the file from the object identifier. +!! +!! \param obj_id Object identifier. +!! \param buf Buffer to store the read name. +!! \param size Actual size of the name. +!! \param hdferr \fortran_error +!! SUBROUTINE h5fget_name_f(obj_id, buf, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier + INTEGER(HID_T), INTENT(IN) :: obj_id CHARACTER(LEN=*), INTENT(OUT) :: buf - ! Buffer to hold file name - INTEGER(SIZE_T), INTENT(OUT) :: size ! Size of the file name - INTEGER, INTENT(OUT) :: hdferr ! Error code: 0 on success, - ! -1 if fail -!***** + INTEGER(SIZE_T), INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTEGER(SIZE_T) :: buflen INTERFACE @@ -847,32 +572,20 @@ CONTAINS buflen = LEN(buf) hdferr = h5fget_name_c(obj_id, size, buf, buflen) END SUBROUTINE h5fget_name_f -!****s* H5F/h5fget_filesize_f -! -! NAME -! h5fget_filesize_f -! -! PURPOSE -! Retrieves the file size of the HDF5 file. -! -! INPUTS -! file_id - file identifier -! OUTPUTS -! size - file size -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! July 7, 2004 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Retrieves the file size of the HDF5 file. +!! +!! \param file_id File identifier. +!! \param size File size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5fget_filesize_f(file_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: file_id ! file identifier - INTEGER(HSIZE_T), INTENT(OUT) :: size ! Size of the file - INTEGER, INTENT(OUT) :: hdferr ! Error code: 0 on success, - ! -1 if fail -!***** + INTEGER(HID_T), INTENT(IN) :: file_id + INTEGER(HSIZE_T), INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5fget_filesize_c(file_id, size) & BIND(C,NAME='h5fget_filesize_c') @@ -885,36 +598,24 @@ CONTAINS hdferr = h5fget_filesize_c(file_id, size) END SUBROUTINE h5fget_filesize_f -!****s* H5F/h5fget_fileno_f -! -! NAME -! h5fget_fileno_f -! -! PURPOSE -! Retrieves the file number of the HDF5 file. -! -! INPUTS -! file_id - file identifier -! OUTPUTS -! fileno - file number -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Quincey Koziol -! April 13, 2019 -! -! SOURCE +!> +!! \ingroup FH5F +!! +!! \brief Retrieves the file number of the HDF5 file. +!! +!! \param file_id File identifier. +!! \param fileno File number. +!! \param hdferr \fortran_error +!! SUBROUTINE h5fget_fileno_f(file_id, fileno, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: file_id ! file identifier - INTEGER, INTENT(OUT) :: fileno ! File number - INTEGER, INTENT(OUT) :: hdferr ! Error code: 0 on success, - ! -1 if fail -!***** + INTEGER(HID_T), INTENT(IN) :: file_id + INTEGER, INTENT(OUT) :: fileno + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5fget_fileno_c(file_id, fileno) & BIND(C,NAME='h5fget_fileno_c') - IMPORT :: HID_T, HSIZE_T + IMPORT :: HID_T IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: file_id INTEGER, INTENT(OUT) :: fileno @@ -923,31 +624,17 @@ CONTAINS hdferr = h5fget_fileno_c(file_id, fileno) END SUBROUTINE h5fget_fileno_f -!****s* H5F (F03)/h5fget_file_image_f_F03 -! -! NAME -! h5fget_file_image_f -! -! PURPOSE -! Retrieves a copy of the image of an existing, open file. -! -! INPUTS -! file_id - Target file identifier. -! buf_ptr - Pointer to the buffer into which the image of the HDF5 file is to be copied. -! buf_len - Size of the supplied buffer. -! -! OUTPUTS -! hdferr - error code: -! 0 on success and -1 on failure -! OPTIONAL PARAMETERS -! buf_size - Returns the size in bytes of the buffer required to store the file image, -! no data will be copied. -! -! AUTHOR -! M. Scot Breitenfeld -! November 26, 2012 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5F +!! +!! \brief Retrieves a copy of the image of an existing, open file. +!! +!! \param file_id Target file identifier. +!! \param buf_ptr Pointer to the buffer into which the image of the HDF5 file is to be copied. +!! \param buf_len Size of the supplied buffer. +!! \param hdferr \fortran_error +!! \param buf_size Returns the size in bytes of the buffer required to store the file image, no data will be copied. +!! SUBROUTINE h5fget_file_image_f(file_id, buf_ptr, buf_len, hdferr, buf_size) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: file_id @@ -955,7 +642,6 @@ CONTAINS INTEGER(SIZE_T), INTENT(IN) :: buf_len INTEGER , INTENT(OUT) :: hdferr INTEGER(SIZE_T), INTENT(OUT) , OPTIONAL :: buf_size -!***** INTEGER(SIZE_T) :: buf_size_default @@ -983,34 +669,21 @@ CONTAINS END SUBROUTINE h5fget_file_image_f -!****s* H5F (F03)/h5fget_dset_no_attrs_hint_f_F03 -! -! NAME -! h5fget_dset_no_attrs_hint_f -! -! PURPOSE -! Gets the value of the "minimize dataset headers" value which creates -! smaller dataset object headers when its set and no attributes are present. -! -! INPUTS -! file_id - Target file identifier. -! -! OUTPUTS -! minimize - Value of the setting. -! hdferr - error code: -! 0 on success and -1 on failure -! -! AUTHOR -! Dana Robinson -! January 2019 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5F +!! +!! \brief Gets the value of the "minimize dataset headers" value which creates +!! smaller dataset object headers when its set and no attributes are present. +!! +!! \param file_id Target file identifier. +!! \param minimize Value of the setting. +!! \param hdferr \fortran_error +!! SUBROUTINE h5fget_dset_no_attrs_hint_f(file_id, minimize, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: file_id LOGICAL , INTENT(OUT) :: minimize INTEGER , INTENT(OUT) :: hdferr -!***** LOGICAL(C_BOOL) :: c_minimize INTERFACE @@ -1029,34 +702,21 @@ CONTAINS END SUBROUTINE h5fget_dset_no_attrs_hint_f -!****s* H5F (F03)/h5fset_dset_no_attrs_hint_f_F03 -! -! NAME -! h5fset_dset_no_attrs_hint_f -! -! PURPOSE -! Sets the value of the "minimize dataset headers" value which creates -! smaller dataset object headers when its set and no attributes are present. -! -! INPUTS -! file_id - Target file identifier. -! minimize - Value of the setting. -! -! OUTPUTS -! hdferr - error code: -! 0 on success and -1 on failure -! -! AUTHOR -! Dana Robinson -! January 2019 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5F +!! +!! \brief Sets the value of the "minimize dataset headers" value which creates +!! smaller dataset object headers when its set and no attributes are present. +!! +!! \param file_id Target file identifier. +!! \param minimize Value of the setting. +!! \param hdferr \fortran_error +!! SUBROUTINE h5fset_dset_no_attrs_hint_f(file_id, minimize, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: file_id LOGICAL , INTENT(IN) :: minimize INTEGER , INTENT(OUT) :: hdferr -!***** LOGICAL(C_BOOL) :: c_minimize INTERFACE diff --git a/fortran/src/H5Gff.F90 b/fortran/src/H5Gff.F90 index bfca595..10055bc 100644 --- a/fortran/src/H5Gff.F90 +++ b/fortran/src/H5Gff.F90 @@ -1,13 +1,13 @@ -!****h* ROBODoc/H5G -! -! NAME -! MODULE H5G -! -! FILE -! fortran/src/H5Gff.F90 -! -! PURPOSE -! This file contains Fortran interfaces for H5G functions. +!> @defgroup FH5G Fortran Group (H5G) Interface +!! +!! @see H5G, C-API +!! +!! @see @ref H5G_UG, User Guide +!! + +!> @ingroup FH5G +!! +!! @brief This module contains Fortran interfaces for H5G functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -35,7 +35,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** MODULE H5G USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_CHAR @@ -43,63 +42,36 @@ MODULE H5G CONTAINS -!****s* H5G/h5gcreate_f -! -! NAME -! h5gcreate_f -! -! PURPOSE -! Creates a new group. -! -! INPUTS -! loc_id - location identifier -! name - group name at the specified location -! OUTPUTS -! grp_id - group identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! size_hint - a parameter indicating the number of bytes to -! reserve for the names that will appear in the group -! lcpl_id - Property list for link creation -! gcpl_id - Property list for group creation -! gapl_id - Property list for group access -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! Added additional optional parameters in 1.8 -! MSB - February 27, 2008 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Creates a new group. +!! +!! \param loc_id Location identifier. +!! \param name Group name at the specified location. +!! \param grp_id Group identifier. +!! \param hdferr \fortran_error +!! \param size_hint A parameter indicating the number of bytes to reserve for the names that will appear in the group. +!! Set to OBJECT_NAMELEN_DEFAULT_F if using any of the optional parameters lcpl_id, gcpl_id, +!! and/or gapl_id when not using keywords in specifying the optional parameters. +!! \param lcpl_id Property list for link creation. +!! \param gcpl_id Property list for group creation. +!! \param gapl_id Property list for group access. +!! SUBROUTINE h5gcreate_f(loc_id, name, grp_id, hdferr, size_hint, lcpl_id, gcpl_id, gapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group - INTEGER(HID_T), INTENT(OUT) :: grp_id ! Group identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(HID_T), INTENT(OUT) :: grp_id + INTEGER, INTENT(OUT) :: hdferr INTEGER(SIZE_T), OPTIONAL, INTENT(IN) :: size_hint - ! Parameter indicating - ! the number of bytes - ! to reserve for the - ! names that will appear - ! in the group. Set to OBJECT_NAMELEN_DEFAULT_F - ! if using any of the optional - ! parameters lcpl_id, gcpl_id, and/or gapl_id when not - ! using keywords in specifying the optional parameters - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id ! Property list for link creation - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gcpl_id ! Property list for group creation - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id ! Property list for group access -!***** + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id + INTEGER(HID_T) :: lcpl_id_default INTEGER(HID_T) :: gcpl_id_default INTEGER(HID_T) :: gapl_id_default - INTEGER :: namelen ! Length of the name character string INTEGER(SIZE_T) :: size_hint_default @@ -136,139 +108,24 @@ CONTAINS END SUBROUTINE h5gcreate_f -!!$! -!!$!****s* H5G/ -!!$! -!!$! NAME -!!$! h5gcreate2_f -!!$! -!!$! PURPOSE -!!$! Creates a new group. -!!$! -!!$! INPUTS -!!$! loc_id - location identifier -!!$! name - group name at the specified location -!!$! OUTPUTS -!!$! grp_id - group identifier -!!$! hdferr: - error code -!!$! Success: 0 -!!$! Failure: -1 -!!$! OPTIONAL PARAMETERS -!!$! -!!$! lcpl_id - Property list for link creation -!!$! gcpl_id - Property list for group creation -!!$! gapl_id - Property list for group access -!!$! -!!$! AUTHOR M. Scot Breitenfeld -!!$! February 27, 2008 -!!$! -!!$! HISTORY -!!$! -!!$! NOTES Needed to switch the first 2 arguments to avoid conflect -!!$! with h5gcreate1_f -!!$! -!!$ -!!$ SUBROUTINE h5gcreate2_f(name, loc_id, grp_id, hdferr, & -!!$ lcpl_id, gcpl_id, gapl_id) -!!$ IMPLICIT NONE -!!$ CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: name ! Name of the group -!!$ INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier -!!$ INTEGER, INTENT(OUT) :: hdferr ! Error code -!!$ INTEGER(HID_T), INTENT(OUT) :: grp_id ! Group identifier -!!$ -!!$ INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id ! Property list for link creation -!!$ INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gcpl_id ! Property list for group creation -!!$ INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id ! Property list for group access -!!$ -!!$ INTEGER(HID_T) :: lcpl_id_default -!!$ INTEGER(HID_T) :: gcpl_id_default -!!$ INTEGER(HID_T) :: gapl_id_default -!!$ -!!$ INTEGER(SIZE_T) :: OBJECT_NAME -! LEN_DEFAULT ! Dummy argument to pass to c call -!!$ INTEGER :: namelen ! Length of the name character string -!!$ -!!$! MS FORTRAN needs explicit interface for C functions called here. -!!$! -!!$ INTERFACE -!!$ INTEGER FUNCTION h5gcreate_c(loc_id, name, namelen, & -!!$ OBJECT_NAME -! LEN_DEFAULT, grp_id, lcpl_id_default, gcpl_id_default, gapl_id_default) -!!$ USE H5GLOBAL -!!$ !DEC$IF DEFINED(HDF5F90_WINDOWS) -!!$ !DEC$ATTRIBUTES C,reference,decorate,alias:'H5GCREATE_C'::h5gcreate_c -!!$ !DEC$ENDIF -!!$ !DEC$ATTRIBUTES reference :: name -!!$ INTEGER(HID_T), INTENT(IN) :: loc_id -!!$ CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: name -!!$ INTEGER :: namelen -!!$ INTEGER(SIZE_T) :: OBJECT_NAME -! LEN_DEFAULT -!!$ INTEGER(HID_T) :: lcpl_id_default -!!$ INTEGER(HID_T) :: gcpl_id_default -!!$ INTEGER(HID_T) :: gapl_id_default -!!$ INTEGER(HID_T), INTENT(OUT) :: grp_id -!!$ END FUNCTION h5gcreate_c -!!$ END INTERFACE -!!$ -!!$ namelen = LEN(name) -!!$ OBJECT_NAME -! LEN_DEFAULT = OBJECT_NAME -! LEN_DEFAULT_F -!!$ -!!$ lcpl_id_default = H5P_DEFAULT_F -!!$ IF(PRESENT(lcpl_id)) lcpl_id_default = lcpl_id -!!$ gcpl_id_default = H5P_DEFAULT_F -!!$ IF(PRESENT(gcpl_id)) gcpl_id_default = gcpl_id -!!$ gapl_id_default = H5P_DEFAULT_F -!!$ IF(PRESENT(gapl_id)) gapl_id_default = gapl_id -!!$ -!!$ -!!$ hdferr = h5gcreate_c(loc_id, name, namelen, OBJECT_NAME -! LEN_DEFAULT, grp_id, & -!!$ lcpl_id_default, gcpl_id_default, gapl_id_default) -!!$ -!!$ END SUBROUTINE h5gcreate2_f - -! -!****s* H5G/h5gopen_f -! -! NAME -! h5gopen_f -! -! PURPOSE -! Opens an existing group. -! -! INPUTS -! loc_id - location identifier -! name - name of the group to open -! OUTPUTS -! grp_id - group identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! gapl_id - Group access property list identifier -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! Added 1.8 (optional) parameter gapl_id -! February, 2008 M. Scot Breitenfeld -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Opens an existing group. +!! +!! \param loc_id Location identifier. +!! \param name Name of the group to open. +!! \param grp_id Group identifier. +!! \param hdferr \fortran_error +!! \param gapl_id Group access property list identifier. +!! SUBROUTINE h5gopen_f(loc_id, name, grp_id, hdferr, gapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group - INTEGER(HID_T), INTENT(OUT) :: grp_id ! File identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id ! Group access property list identifier -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(HID_T), INTENT(OUT) :: grp_id + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id INTEGER(HID_T) :: gapl_id_default INTEGER :: namelen ! Length of the name character string @@ -292,34 +149,18 @@ CONTAINS hdferr = h5gopen_c(loc_id, name, namelen, gapl_id_default, grp_id) END SUBROUTINE h5gopen_f -! -!****s* H5G/h5gclose_f -! -! NAME -! h5gclose_f -! -! PURPOSE -! Closes the specified group. -! -! INPUTS -! grp_id - group identifier -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Closes the specified group. +!! +!! \param grp_id Group identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5gclose_f(grp_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: grp_id ! Group identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: grp_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5gclose_c(grp_id) BIND(C,NAME='h5gclose_c') IMPORT :: HID_T @@ -330,44 +171,28 @@ CONTAINS hdferr = h5gclose_c(grp_id) END SUBROUTINE h5gclose_f -! -!****s* H5G/h5gget_obj_info_idx_f -! -! NAME -! h5gget_obj_info_idx_f -! -! PURPOSE -! Returns name and type of the group member identified by -! its index. -! -! INPUTS -! loc_id - location identifier -! name - name of the group at the specified location -! idx - object index (zero-based) -! OUTPUTS -! obj_name - object name -! obj_type - object type -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Returns name and type of the group member identified by its index. +!! +!! \param loc_id Location identifier. +!! \param name Name of the group at the specified location. +!! \param idx Object index (zero-based). +!! \param obj_name Object name. +!! \param obj_type Object type. +!! \param hdferr \fortran_error +!! SUBROUTINE h5gget_obj_info_idx_f(loc_id, name, idx, & obj_name, obj_type, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group - INTEGER, INTENT(IN) :: idx ! Index of member object - CHARACTER(LEN=*), INTENT(OUT) :: obj_name ! Name of the object - INTEGER, INTENT(OUT) :: obj_type ! Object type - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(IN) :: idx + CHARACTER(LEN=*), INTENT(OUT) :: obj_name + INTEGER, INTENT(OUT) :: obj_type + INTEGER, INTENT(OUT) :: hdferr + INTEGER :: namelen ! Length of the name character string INTEGER :: obj_namelen ! Length of the obj_name character string @@ -393,103 +218,63 @@ CONTAINS obj_name, obj_namelen, obj_type) END SUBROUTINE h5gget_obj_info_idx_f -! -!****s* H5G/h5gn_members_f -! -! NAME -! h5gn_members_f -! -! PURPOSE -! Returns the number of group members. -! -! INPUTS -! loc_id - location identifier -! name - name of the group at the specified location -! OUTPUTS -! nmembers - number of group members -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Returns the number of group members. +!! +!! \param loc_id Location identifier. +!! \param name Name of the group at the specified location. +!! \param nmembers Number of group members. +!! \param hdferr \fortran_error +!! SUBROUTINE h5gn_members_f(loc_id, name, nmembers, hdferr) - IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the group - INTEGER, INTENT(OUT) :: nmembers ! Number of members in the - ! group - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** - INTEGER :: namelen ! Length of the name character string - - INTERFACE - INTEGER FUNCTION h5gn_members_c(loc_id, name, namelen, nmembers) & - BIND(C,NAME='h5gn_members_c') - IMPORT :: C_CHAR - IMPORT :: HID_T - INTEGER(HID_T), INTENT(IN) :: loc_id - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: name - INTEGER :: namelen - INTEGER, INTENT(OUT) :: nmembers - END FUNCTION h5gn_members_c - END INTERFACE - - namelen = LEN(name) - hdferr = h5gn_members_c(loc_id, name, namelen, nmembers) - - END SUBROUTINE h5gn_members_f -! -!****s* H5G/h5glink_f -! -! NAME -! h5glink_f -! -! PURPOSE -! Creates a link of the specified type from new_name -! to current_name. -! -! INPUTS -! loc_id - location identifier -! link_type - link type; possible values are: -! H5G_LINK_HARD_F (0) -! H5G_LINK_SOFT_F (1) -! current_name - name of the existing object if link is a -! hard link. Can be anything for the soft link -! new_name - new name for the object -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! SOURCE + IMPLICIT NONE + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(OUT) :: nmembers + INTEGER, INTENT(OUT) :: hdferr + + INTEGER :: namelen ! Length of the name character string + + INTERFACE + INTEGER FUNCTION h5gn_members_c(loc_id, name, namelen, nmembers) & + BIND(C,NAME='h5gn_members_c') + IMPORT :: C_CHAR + IMPORT :: HID_T + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: name + INTEGER :: namelen + INTEGER, INTENT(OUT) :: nmembers + END FUNCTION h5gn_members_c + END INTERFACE + + namelen = LEN(name) + hdferr = h5gn_members_c(loc_id, name, namelen, nmembers) + + END SUBROUTINE h5gn_members_f +!> +!! \ingroup FH5G +!! +!! \brief Creates a link of the specified type from new_name to current_name. +!! +!! \param loc_id Location identifier. +!! \param link_type Link type; possible values are: +!! \li H5G_LINK_HARD_F +!! \li H5G_LINK_SOFT_F +!! \param current_name Name of the existing object if link is a hard link. Can be anything for the soft link. +!! \param new_name New name for the object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5glink_f(loc_id, link_type, current_name, & new_name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - INTEGER, INTENT(IN) :: link_type ! link type - ! Possible values are: - ! H5G_LINK_HARD_F (0) or - ! H5G_LINK_SOFT_F (1) + INTEGER(HID_T), INTENT(IN) :: loc_id + INTEGER, INTENT(IN) :: link_type CHARACTER(LEN=*), INTENT(IN) :: current_name - ! Current name of an object - CHARACTER(LEN=*), INTENT(IN) :: new_name ! New name of an object - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + CHARACTER(LEN=*), INTENT(IN) :: new_name + INTEGER, INTENT(OUT) :: hdferr INTEGER :: current_namelen ! Length of the current_name string INTEGER :: new_namelen ! Length of the new_name string @@ -515,49 +300,32 @@ CONTAINS current_namelen, new_name, new_namelen) END SUBROUTINE h5glink_f -! -!****s* H5G/h5glink2_f -! -! NAME -! h5glink2_f -! -! PURPOSE -! Creates a link of the specified type from new_name -! to current_name. current_name and new_name are interpreted -! relative to current and new location identifiers. -! -! INPUTS -! cur_loc_id - location identifier -! cur_name - name of the existing object if link is a -! hard link. Can be anything for the soft link. -! link_type - link type; possible values are: -! H5G_LINK_HARD_F (0) -! H5G_LINK_SOFT_F (1) -! new_loc_id - new location identifier -! new_name - new name for the object -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! September 25, 2002 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Creates a link of the specified type from new_name +!! to current_name. current_name and new_name are interpreted +!! relative to current and new location identifiers. +!! +!! \param cur_loc_id Location identifier. +!! \param cur_name Name of the existing object if link is a hard link. Can be anything for the soft link. +!! \param link_type Link type; possible values are: +!! \li H5G_LINK_HARD_F +!! \li H5G_LINK_SOFT_F +!! \param new_loc_id New location identifier. +!! \param new_name New name for the object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5glink2_f(cur_loc_id, cur_name, link_type, new_loc_id, & new_name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: cur_loc_id ! File or group identifier + INTEGER(HID_T), INTENT(IN) :: cur_loc_id CHARACTER(LEN=*), INTENT(IN) :: cur_name - ! Current name of an object - INTEGER, INTENT(IN) :: link_type ! link type - ! Possible values are: - ! H5G_LINK_HARD_F (0) or - ! H5G_LINK_SOFT_F (1) + INTEGER, INTENT(IN) :: link_type - INTEGER(HID_T), INTENT(IN) :: new_loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: new_name ! New name of an object - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: new_loc_id + CHARACTER(LEN=*), INTENT(IN) :: new_name + INTEGER, INTENT(OUT) :: hdferr INTEGER :: cur_namelen ! Length of the current_name string INTEGER :: new_namelen ! Length of the new_name string @@ -584,39 +352,21 @@ CONTAINS new_loc_id, new_name, new_namelen) END SUBROUTINE h5glink2_f -! -!****s* H5G/h5gunlink_f -! -! NAME -! h5gunlink_f -! -! PURPOSE -! Removes the specified name from the group graph and -! decrements the link count for the object to which name -! points -! -! INPUTS -! loc_id - location identifier -! name - name of the object to unlink -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Removes the specified name from the group graph and +!! decrements the link count for the object to which name points +!! +!! \param loc_id Location identifier. +!! \param name Name of the object to unlink. +!! \param hdferr \fortran_error +!! SUBROUTINE h5gunlink_f(loc_id, name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of an object - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(OUT) :: hdferr INTEGER :: namelen ! Length of the name character string INTERFACE @@ -633,39 +383,22 @@ CONTAINS hdferr = h5gunlink_c(loc_id, name, namelen) END SUBROUTINE h5gunlink_f -! -!****s* H5G/h5gmove_f -! -! NAME -! h5gmove_f -! -! PURPOSE -! Renames an object within an HDF5 file. -! -! INPUTS -! loc_id - location identifier -! name - object's name at specified location -! new_name - object's new name -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Renames an object within an HDF5 file. +!! +!! \param loc_id Location identifier. +!! \param name Object's name at specified location. +!! \param new_name Object's new name. +!! \param hdferr \fortran_error +!! SUBROUTINE h5gmove_f(loc_id, name, new_name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Current name of an object - CHARACTER(LEN=*), INTENT(IN) :: new_name ! New name of an object - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + CHARACTER(LEN=*), INTENT(IN) :: new_name + INTEGER, INTENT(OUT) :: hdferr INTEGER :: namelen ! Length of the current_name string INTEGER :: new_namelen ! Length of the new_name string @@ -685,35 +418,24 @@ CONTAINS new_namelen = LEN(new_name) hdferr = h5gmove_c(loc_id, name, namelen, new_name, new_namelen) END SUBROUTINE h5gmove_f -! -!****s* H5G/h5gmove2_f -! -! NAME -! h5gmove2_f -! -! PURPOSE -! Renames an object within an HDF5 file. -! -! INPUTS -! src_loc_id - original location identifier -! src_name - object's name at specified original location -! dst_loc_id - original location identifier -! dst_name - object's new name -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! September 25, 2002 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Renames an object within an HDF5 file. +!! +!! \param src_loc_id Original location identifier. +!! \param src_name Object's name at specified original location. +!! \param dst_loc_id Original location identifier. +!! \param dst_name Object's new name. +!! \param hdferr \fortran_error +!! SUBROUTINE h5gmove2_f(src_loc_id, src_name, dst_loc_id, dst_name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: src_loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: src_name ! Original name of an object - INTEGER(HID_T), INTENT(IN) :: dst_loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: dst_name ! New name of an object - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: src_loc_id + CHARACTER(LEN=*), INTENT(IN) :: src_name + INTEGER(HID_T), INTENT(IN) :: dst_loc_id + CHARACTER(LEN=*), INTENT(IN) :: dst_name + INTEGER, INTENT(OUT) :: hdferr INTEGER :: src_namelen ! Length of the current_name string INTEGER :: dst_namelen ! Length of the new_name string @@ -735,47 +457,24 @@ CONTAINS dst_namelen = LEN(dst_name) hdferr = h5gmove2_c(src_loc_id, src_name, src_namelen, dst_loc_id, dst_name, dst_namelen) END SUBROUTINE h5gmove2_f -! -!****s* H5G/h5gget_linkval_f -! -! NAME -! h5gget_linkval_f -! -! PURPOSE -! Returns the name of the object that the symbolic link -! points to. -! -! INPUTS -! loc_id - location identifier -! name - symbolic link to the object whose name -! is to be returned. -! size - maximum number of characters to be returned -! OUTPUTS -! buffer - a buffer to hold the name of the object -! being sought -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Returns the name of the object that the symbolic link points to. +!! +!! \param loc_id Location identifier. +!! \param name Symbolic link to the object whose name is to be returned. +!! \param size Maximum number of characters to be returned. +!! \param buffer A buffer to hold the name of the object being sought. +!! \param hdferr \fortran_error +!! SUBROUTINE h5gget_linkval_f(loc_id, name, size, buffer, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Current name of an object - INTEGER(SIZE_T), INTENT(IN) :: size ! Maximum number of buffer + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T), INTENT(IN) :: size CHARACTER(LEN=size), INTENT(OUT) :: buffer - ! Buffer to hold a name of - ! the object symbolic link - ! points to - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER, INTENT(OUT) :: hdferr INTEGER :: namelen ! Length of the current_name string INTERFACE @@ -794,39 +493,22 @@ CONTAINS hdferr = h5gget_linkval_c(loc_id, name, namelen, size, buffer) END SUBROUTINE h5gget_linkval_f -! -!****s* H5G/h5gset_comment_f -! -! NAME -! h5gset_comment_f -! -! PURPOSE -! Sets comment for specified object. -! -! INPUTS -! loc_id - location identifier -! name - name of the object -! comment - comment to set for the object -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Sets comment for specified object. +!! +!! \param loc_id Location identifier. +!! \param name Name of the object. +!! \param comment Comment to set for the object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5gset_comment_f(loc_id, name, comment, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Current name of an object - CHARACTER(LEN=*), INTENT(IN) :: comment ! New name of an object - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + CHARACTER(LEN=*), INTENT(IN) :: comment + INTEGER, INTENT(OUT) :: hdferr INTEGER :: namelen ! Length of the current_name string INTEGER :: commentlen ! Length of the comment string @@ -847,42 +529,24 @@ CONTAINS commentlen = LEN(comment) hdferr = h5gset_comment_c(loc_id, name, namelen, comment, commentlen) END SUBROUTINE h5gset_comment_f -! -!****s* H5G/h5gget_comment_f -! -! NAME -! h5gget_comment_f -! -! PURPOSE -! Retrieves comment for specified object. -! -! INPUTS -! loc_id - location identifier -! name - name of the object at specified location -! size - size of the buffer required to hold comment -! OUTPUTS -! buffer - buffer to hold object's comment -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Retrieves comment for specified object. +!! +!! \param loc_id Location identifier. +!! \param name Name of the object at specified location. +!! \param size Size of the buffer required to hold comment. +!! \param buffer Buffer to hold object's comment. +!! \param hdferr \fortran_error +!! SUBROUTINE h5gget_comment_f(loc_id, name, size, buffer, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Current name of an object - INTEGER(SIZE_T), INTENT(IN) :: size ! Maximum number of buffer + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T), INTENT(IN) :: size CHARACTER(LEN=size), INTENT(OUT) :: buffer - ! Buffer to hold a comment - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER, INTENT(OUT) :: hdferr INTEGER :: namelen ! Length of the current_name string INTERFACE @@ -901,37 +565,24 @@ CONTAINS hdferr = h5gget_comment_c(loc_id, name, namelen, size, buffer) END SUBROUTINE h5gget_comment_f -! -!****s* H5G/H5Gcreate_anon_f -! -! NAME -! H5Gcreate_anon_f -! -! PURPOSE -! Creates a new empty group without linking it into the file structure. -! -! INPUTS -! loc_id - Location identifier -! OUTPUTS -! grp_id - group identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! gcpl_id - Group creation property list identifier -! gapl_id - Group access property list identifier -! -! AUTHOR -! M. Scot Breitenfeld -! February 15, 2008 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Creates a new empty group without linking it into the file structure. +!! +!! \param loc_id Location identifier. +!! \param grp_id Group identifier. +!! \param hdferr \fortran_error +!! \param gcpl_id Group creation property list identifier. +!! \param gapl_id Group access property list identifier. +!! SUBROUTINE h5Gcreate_anon_f(loc_id, grp_id, hdferr, gcpl_id, gapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - INTEGER(HID_T), INTENT(OUT) :: grp_id ! Group identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gcpl_id ! Property list for group creation - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id ! Property list for group access -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + INTEGER(HID_T), INTENT(OUT) :: grp_id + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id INTEGER(HID_T) :: gcpl_id_default INTEGER(HID_T) :: gapl_id_default @@ -939,10 +590,10 @@ CONTAINS INTEGER FUNCTION h5gcreate_anon_c(loc_id, gcpl_id_default, gapl_id_default, grp_id) & BIND(C,NAME='h5gcreate_anon_c') IMPORT :: HID_T - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - INTEGER(HID_T), INTENT(IN) :: gcpl_id_default ! Property list for group creation - INTEGER(HID_T), INTENT(IN) :: gapl_id_default ! Property list for group access - INTEGER(HID_T), INTENT(OUT) :: grp_id ! Group identifier + INTEGER(HID_T), INTENT(IN) :: loc_id + INTEGER(HID_T), INTENT(IN) :: gcpl_id_default + INTEGER(HID_T), INTENT(IN) :: gapl_id_default + INTEGER(HID_T), INTENT(OUT) :: grp_id END FUNCTION h5gcreate_anon_c END INTERFACE @@ -955,31 +606,20 @@ CONTAINS hdferr = h5gcreate_anon_c(loc_id, gcpl_id_default, gapl_id_default, grp_id) END SUBROUTINE h5Gcreate_anon_f -! -!****s* H5G/H5Gget_create_plist_f -! -! NAME -! H5Gget_create_plist_f -! -! PURPOSE -! Gets a group creation property list identifier. -! -! INPUTS -! grp_id - group identifier -! OUTPUTS -! gcpl_id - Group creation property list identifier -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! M. Scot Breitenfeld -! February 15, 2008 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Gets a group creation property list identifier. +!! +!! \param grp_id Group identifier. +!! \param gcpl_id Group creation property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5gget_create_plist_f(grp_id, gcpl_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: grp_id ! Group identifier - INTEGER(HID_T), INTENT(OUT) :: gcpl_id ! Property list for group creation - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: grp_id + INTEGER(HID_T), INTENT(OUT) :: gcpl_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5gget_create_plist_c(grp_id, gcpl_id ) BIND(C,NAME='h5gget_create_plist_c') IMPORT :: HID_T @@ -992,57 +632,30 @@ CONTAINS END SUBROUTINE h5gget_create_plist_f -! -!****s* H5G/h5gget_info_f -! -! NAME -! h5gget_info_f -! -! PURPOSE -! Retrieves information about a group -! -! INPUTS -! group_id - Group identifier -! -! OUTPUTS -! storage_type - Type of storage for links in group -! H5G_STORAGE_TYPE_COMPACT: Compact storage -! H5G_STORAGE_TYPE_DENSE: Indexed storage -! H5G_STORAGE_TYPE_SYMBOL_TABLE: Symbol tables, the original HDF5 structure -! nlinks - Number of links in group -! max_corder - Current maximum creation order value for group -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! mounted - Whether group has a file mounted on it -! -! AUTHOR -! M. Scot Breitenfeld -! February 15, 2008 -! -! NOTES -! In C the output is defined as a structure: H5G_info_t -! -! HISTORY -! -! - Added 'mounted' parameter -! M. Scot Breitenfeld -! July 16, 2008 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Retrieves information about a group +!! +!! \param group_id Group identifier. +!! \param storage_type Type of storage for links in group: +!! \li H5G_STORAGE_TYPE_COMPACT_F: Compact storage +!! \li H5G_STORAGE_TYPE_DENS_FE: Indexed storage +!! \li H5G_STORAGE_TYPE_SYMBOL_TABLE_F: Symbol tables, the original HDF5 structure +!! \param nlinks Number of links in group. +!! \param max_corder Current maximum creation order value for group. +!! \param hdferr \fortran_error +!! \param mounted Whether group has a file mounted on it. +!! SUBROUTINE h5gget_info_f(group_id, storage_type, nlinks, max_corder, hdferr, mounted) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: group_id ! Group identifier - - INTEGER, INTENT(OUT) :: storage_type ! Type of storage for links in group: - ! H5G_STORAGE_TYPE_COMPACT_F: Compact storage - ! H5G_STORAGE_TYPE_DENSE_F: Indexed storage - ! H5G_STORAGE_TYPE_SYMBOL_TABLE_F: Symbol tables, the original HDF5 structure - INTEGER, INTENT(OUT) :: nlinks ! Number of links in group - INTEGER, INTENT(OUT) :: max_corder ! Current maximum creation order value for group - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - LOGICAL, INTENT(OUT), OPTIONAL :: mounted ! Whether group has a file mounted on it -!***** + INTEGER(HID_T), INTENT(IN) :: group_id + + INTEGER, INTENT(OUT) :: storage_type + INTEGER, INTENT(OUT) :: nlinks + INTEGER, INTENT(OUT) :: max_corder + INTEGER, INTENT(OUT) :: hdferr + LOGICAL, INTENT(OUT), OPTIONAL :: mounted INTEGER :: mounted_c INTERFACE @@ -1068,67 +681,41 @@ CONTAINS ENDIF END SUBROUTINE h5gget_info_f -! -!****s* H5G/h5gget_info_by_idx_f -! -! NAME -! h5gget_info_by_idx_f -! -! PURPOSE -! Retrieves information about a group, according to the group’s position within an index. -! -! INPUTS -! loc_id - File or group identifier -! group_name - Name of group containing group for which information is to be retrieved -! index_type - Index type -! order - Order of the count in the index -! n - Position in the index of the group for which information is retrieved -! -! OUTPUTS -! storage_type - Type of storage for links in group -! H5G_STORAGE_TYPE_COMPACT: Compact storage -! H5G_STORAGE_TYPE_DENSE: Indexed storage -! H5G_STORAGE_TYPE_SYMBOL_TABLE: Symbol tables, the original HDF5 structure -! nlinks - Number of links in group -! max_corder - Current maximum creation order value for group -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lapl_id - Link access property list -! mounted - Whether group has a file mounted on it -! -! NOTES -! In C the output is defined as a structure: H5G_info_t -! -! AUTHOR -! M. Scot Breitenfeld -! February 18, 2008 -! -! HISTORY -! Added 'mounted' parameter -! M. Scot Breitenfeld -! July 16, 2008 -! -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Retrieves information about a group, according to the group’s position within an index. +!! +!! \param loc_id File or group identifier. +!! \param group_name Name of group containing group for which information is to be retrieved. +!! \param index_type Index type. +!! \param order Order of the count in the index. +!! \param n Position in the index of the group for which information is retrieved. +!! \param storage_type Type of storage for links in group: +!! \li H5G_STORAGE_TYPE_COMPACT_F: Compact storage +!! \li H5G_STORAGE_TYPE_DENSE_F: Indexed storage +!! \li H5G_STORAGE_TYPE_SYMBOL_TABLE_F: Symbol tables, the original HDF5 structure +!! \param nlinks Number of links in group. +!! \param max_corder Current maximum creation order value for group. +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list. +!! \param mounted Whether group has a file mounted on it. +!! SUBROUTINE h5gget_info_by_idx_f(loc_id, group_name, index_type, order, n, & storage_type, nlinks, max_corder, hdferr, lapl_id, mounted) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: group_name ! Name of group containing group for which information is to be retrieved - INTEGER, INTENT(IN) :: index_type ! Index type - INTEGER, INTENT(IN) :: order ! Order of the count in the index - INTEGER(HSIZE_T), INTENT(IN) :: n ! Position in the index of the group for which information is retrieved - - INTEGER, INTENT(OUT) :: storage_type ! Type of storage for links in group: - ! H5G_STORAGE_TYPE_COMPACT_F: Compact storage - ! H5G_STORAGE_TYPE_DENSE_F: Indexed storage - ! H5G_STORAGE_TYPE_SYMBOL_TABLE_F: Symbol tables, the original HDF5 structure - INTEGER, INTENT(OUT) :: nlinks ! Number of links in group - INTEGER, INTENT(OUT) :: max_corder ! Current maximum creation order value for group - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list - LOGICAL, INTENT(OUT), OPTIONAL :: mounted ! Whether group has a file mounted on it -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: group_name + INTEGER, INTENT(IN) :: index_type + INTEGER, INTENT(IN) :: order + INTEGER(HSIZE_T), INTENT(IN) :: n + + INTEGER, INTENT(OUT) :: storage_type + INTEGER, INTENT(OUT) :: nlinks + INTEGER, INTENT(OUT) :: max_corder + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id + LOGICAL, INTENT(OUT), OPTIONAL :: mounted INTEGER :: mounted_c INTEGER(HID_T) :: lapl_id_default INTEGER(SIZE_T) :: group_name_len ! length of group name @@ -1172,61 +759,35 @@ CONTAINS ENDIF END SUBROUTINE h5gget_info_by_idx_f -! -!****s* H5G/h5gget_info_by_name_f -! -! NAME -! h5gget_info_by_name_f -! -! PURPOSE -! Retrieves information about a group. -! -! INPUTS -! loc_id - File or group identifier -! group_name - Name of group containing group for which information is to be retrieved -! -! OUTPUTS -! -! storage_type - Type of storage for links in group -! H5G_STORAGE_TYPE_COMPACT: Compact storage -! H5G_STORAGE_TYPE_DENSE: Indexed storage -! H5G_STORAGE_TYPE_SYMBOL_TABLE: Symbol tables, the original HDF5 structure -! nlinks - Number of links in group -! max_corder - Current maximum creation order value for group -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lapl_id - Link access property list -! mounted - Whether group has a file mounted on it -! -! NOTES -! In C the output is defined as a structure: H5G_info_t -! -! AUTHOR -! M. Scot Breitenfeld -! February 18, 2008 -! -! HISTORY -! Added 'mounted' parameter -! M. Scot Breitenfeld -! July 16, 2008 -! SOURCE +!> +!! \ingroup FH5G +!! +!! \brief Retrieves information about a group. +!! +!! \param loc_id File or group identifier. +!! \param group_name Name of group containing group for which information is to be retrieved. +!! \param storage_type Type of storage for links in group: +!! \li H5G_STORAGE_TYPE_COMPACT_F: Compact storage +!! \li H5G_STORAGE_TYPE_DENSE_F: Indexed storage +!! \li H5G_STORAGE_TYPE_SYMBOL_TABLE_F: Symbol tables, the original HDF5 structure +!! \param nlinks Number of links in group. +!! \param max_corder Current maximum creation order value for group. +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list. +!! \param mounted Whether group has a file mounted on it. +!! SUBROUTINE h5gget_info_by_name_f(loc_id, group_name, & storage_type, nlinks, max_corder, hdferr, lapl_id, mounted) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier - CHARACTER(LEN=*), INTENT(IN) :: group_name ! Name of group containing group for which information is to be retrieved - - INTEGER, INTENT(OUT) :: storage_type ! Type of storage for links in group: - ! H5G_STORAGE_TYPE_COMPACT_F: Compact storage - ! H5G_STORAGE_TYPE_DENSE_F: Indexed storage - ! H5G_STORAGE_TYPE_SYMBOL_TABLE_F: Symbol tables, the original HDF5 structure - INTEGER, INTENT(OUT) :: nlinks ! Number of links in group - INTEGER, INTENT(OUT) :: max_corder ! Current maximum creation order value for group - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list - LOGICAL, INTENT(OUT), OPTIONAL :: mounted ! Whether group has a file mounted on it -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: group_name + + INTEGER, INTENT(OUT) :: storage_type + INTEGER, INTENT(OUT) :: nlinks + INTEGER, INTENT(OUT) :: max_corder + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id + LOGICAL, INTENT(OUT), OPTIONAL :: mounted INTEGER :: mounted_c INTEGER(HID_T) :: lapl_id_default INTEGER(SIZE_T) :: group_name_len ! length of group name diff --git a/fortran/src/H5Iff.F90 b/fortran/src/H5Iff.F90 index cda26ed..b67d807 100644 --- a/fortran/src/H5Iff.F90 +++ b/fortran/src/H5Iff.F90 @@ -1,13 +1,13 @@ -!****h* ROBODoc/H5I -! -! NAME -! MODULE H5I -! -! FILE -! fortran/src/H5Iff.F90 -! -! PURPOSE -! This file contains Fortran interfaces for H5I functions. +!> @defgroup FH5I Fortran Identifier (H5I) Interface +!! +!! @see H5I, C-API +!! +!! @see @ref H5I_UG, User Guide +!! + +!> @ingroup FH5I +!! +!! @brief This module contains Fortran interfaces for H5I functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -35,7 +35,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** MODULE H5I @@ -44,53 +43,27 @@ MODULE H5I CONTAINS -!****s* H5I/h5iget_type_f -! -! NAME -! h5iget_type_f -! -! PURPOSE -! Retrieves the type of an object. -! -! INPUTS -! obj_id - object identifier -! OUTPUTS -! type - type of the object, possible values: -! H5I_FILE_F -! H5I_GROUP_F -! H5I_DATATYPE_F -! H5I_DATASPACE_F -! H5I_DATASET_F -! H5I_ATTR_F -! H5I_BADID_F -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 5, 2001 -! -! SOURCE +!> +!! \ingroup FH5I +!! +!! \brief Retrieves the type of an object. +!! +!! \param obj_id Object identifier. +!! \param type Type of the object, possible values: +!! \li H5I_FILE_F +!! \li H5I_GROUP_F +!! \li H5I_DATATYPE_F +!! \li H5I_DATASPACE_F +!! \li H5I_DATASET_F +!! \li H5I_ATTR_F +!! \li H5I_BADID_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5iget_type_f(obj_id, TYPE, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - INTEGER, INTENT(OUT) :: TYPE ! type of an object. - ! possible values are: - ! H5I_FILE_F - ! H5I_GROUP_F - ! H5I_DATATYPE_F - ! H5I_DATASPACE_F - ! H5I_DATASET_F - ! H5I_ATTR_F - ! H5I_BADID_F - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + INTEGER, INTENT(OUT) :: TYPE + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5iget_type_c(obj_id, TYPE) BIND(C, NAME='h5iget_type_c') IMPORT :: HID_T @@ -102,39 +75,24 @@ CONTAINS hdferr = h5iget_type_c(obj_id, TYPE) END SUBROUTINE h5iget_type_f -!****s* H5I/h5iget_name_f -! -! NAME -! h5iget_name_f -! -! PURPOSE -! Gets a name of an object specified by its identifier. -! -! INPUTS -! obj_id - attribute identifier -! buf_size - size of a buffer to read name in -! OUTPUTS -! buf - buffer to read name in, name will be truncated if -! buffer is not big enough -! name_size - name size -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! March 12, 2003 -! SOURCE +!> +!! \ingroup FH5I +!! +!! \brief Gets a name of an object specified by its identifier. +!! +!! \param obj_id Attribute identifier. +!! \param buf_size Size of a buffer to read name in. +!! \param buf Buffer to read name in, name will be truncated if buffer is not big enough. +!! \param name_size Name size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5iget_name_f(obj_id, buf, buf_size, name_size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - INTEGER(SIZE_T), INTENT(IN) :: buf_size ! Buffer size - CHARACTER(LEN=*), INTENT(OUT) :: buf ! Buffer to hold object name - INTEGER(SIZE_T), INTENT(OUT) :: name_size ! Actual name size - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 if successful, - ! -1 if fail -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + INTEGER(SIZE_T), INTENT(IN) :: buf_size + CHARACTER(LEN=*), INTENT(OUT) :: buf + INTEGER(SIZE_T), INTENT(OUT) :: name_size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5iget_name_c(obj_id, buf, buf_size, name_size) BIND(C, NAME='h5iget_name_c') IMPORT :: C_CHAR @@ -150,32 +108,20 @@ CONTAINS hdferr = h5iget_name_c(obj_id, buf, buf_size, name_size) END SUBROUTINE h5iget_name_f -!****s* H5I/h5iinc_ref_f -! -! NAME -! h5iinc_ref_f -! -! PURPOSE -! Increments the reference count of an ID -! -! INPUTS -! obj_id - object identifier -! OUTPUTS -! ref_count - Current reference count of the ID -! hdferr: - error code -! Success: 0 -! Failure: -1 -! AUTHOR -! Quincey Koziol -! December 9, 2003 -! -! SOURCE +!> +!! \ingroup FH5I +!! +!! \brief Increments the reference count of an ID. +!! +!! \param obj_id Object identifier. +!! \param ref_count Current reference count of the ID. +!! \param hdferr \fortran_error +!! SUBROUTINE h5iinc_ref_f(obj_id, ref_count, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - INTEGER, INTENT(OUT) :: ref_count ! Current reference count of ID - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + INTEGER, INTENT(OUT) :: ref_count + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5iinc_ref_c(obj_id, ref_count) BIND(C, NAME='h5iinc_ref_c') IMPORT :: HID_T @@ -187,32 +133,20 @@ CONTAINS hdferr = h5iinc_ref_c(obj_id, ref_count) END SUBROUTINE h5iinc_ref_f -!****s* H5I/h5idec_ref_f -! -! NAME -! h5idec_ref_f -! -! PURPOSE -! Decrements the reference count of an ID -! -! INPUTS -! obj_id - Object identifier -! OUTPUTS -! ref_count - Current reference count of the ID -! hdferr: - Error code -! Success: 0 -! Failure: -1 -! AUTHOR -! Quincey Koziol -! December 9, 2003 -! -! SOURCE +!> +!! \ingroup FH5I +!! +!! \brief Decrements the reference count of an ID. +!! +!! \param obj_id Object identifier. +!! \param ref_count Current reference count of the ID. +!! \param hdferr \fortran_error +!! SUBROUTINE h5idec_ref_f(obj_id, ref_count, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - INTEGER, INTENT(OUT) :: ref_count ! Current reference count of ID - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + INTEGER, INTENT(OUT) :: ref_count + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5idec_ref_c(obj_id, ref_count) BIND(C, NAME='h5idec_ref_c') IMPORT :: HID_T @@ -224,32 +158,20 @@ CONTAINS hdferr = h5idec_ref_c(obj_id, ref_count) END SUBROUTINE h5idec_ref_f -!****s* H5I/h5iget_ref_f -! NAME -! h5iget_ref_f -! -! PURPOSE -! Retrieves the reference count of an ID -! -! INPUTS -! obj_id - object identifier -! -! OUTPUTS -! ref_count - Current reference count of the ID -! hdferr: - error code -! Success: 0 -! Failure: -1 -! AUTHOR -! Quincey Koziol -! December 9, 2003 -! -! SOURCE +!> +!! \ingroup FH5I +!! +!! \brief Retrieves the reference count of an ID. +!! +!! \param obj_id Object identifier. +!! \param ref_count Current reference count of the ID. +!! \param hdferr \fortran_error +!! SUBROUTINE h5iget_ref_f(obj_id, ref_count, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - INTEGER, INTENT(OUT) :: ref_count ! Current reference count of ID - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + INTEGER, INTENT(OUT) :: ref_count + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5iget_ref_c(obj_id, ref_count) BIND(C, NAME='h5iget_ref_c') IMPORT :: HID_T @@ -260,32 +182,20 @@ CONTAINS END INTERFACE hdferr = h5iget_ref_c(obj_id, ref_count) END SUBROUTINE h5iget_ref_f -! -!****s* H5I/h5iget_file_id_f -! NAME -! h5iget_file_id_f -! -! PURPOSE -! Obtains file identifier from the object identifier -! -! INPUTS -! obj_id - object identifier -! OUTPUTS -! file_id - file identifier -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 23, 2004 -! SOURCE +!> +!! \ingroup FH5I +!! +!! \brief Obtains file identifier from the object identifier. +!! +!! \param obj_id Object identifier. +!! \param file_id File identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5iget_file_id_f(obj_id, file_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier - INTEGER(HID_T), INTENT(OUT) :: file_id ! File identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + INTEGER(HID_T), INTENT(OUT) :: file_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5iget_file_id_c(obj_id, file_id) BIND(C, NAME='h5iget_file_id_c') IMPORT :: HID_T @@ -296,39 +206,27 @@ CONTAINS END INTERFACE hdferr = h5iget_file_id_c(obj_id, file_id) END SUBROUTINE h5iget_file_id_f -! -!****s* H5I/h5iis_valid_f -! NAME -! h5iget_file_id_f -! -! PURPOSE -! Check if an ID is valid without producing an error message -! -! INPUTS -! id - identifier -! OUTPUTS -! valid - status of id as a valid identifier -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! April 13, 2009 -! SOURCE +!> +!! \ingroup FH5I +!! +!! \brief Check if an ID is valid without producing an error message. +!! +!! \param id Identifier. +!! \param valid Status of id as a valid identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5iis_valid_f(id, valid, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: id ! Identifier - LOGICAL, INTENT(OUT) :: valid ! Status of id as a valid identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: id + LOGICAL, INTENT(OUT) :: valid + INTEGER, INTENT(OUT) :: hdferr INTEGER :: c_valid ! 0 = .false, 1 = .true. INTERFACE INTEGER FUNCTION h5iis_valid_c(id, c_valid) BIND(C, NAME='h5iis_valid_c') IMPORT :: HID_T IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: id ! Identifier + INTEGER(HID_T), INTENT(IN) :: id INTEGER :: c_valid END FUNCTION h5iis_valid_c END INTERFACE diff --git a/fortran/src/H5Lff.F90 b/fortran/src/H5Lff.F90 index 50d08a8..2b4e569 100644 --- a/fortran/src/H5Lff.F90 +++ b/fortran/src/H5Lff.F90 @@ -1,10 +1,13 @@ -!****h* ROBODoc/H5L -! -! NAME -! MODULE H5L -! -! PURPOSE -! This file contains Fortran interfaces for H5L functions. +!> @defgroup FH5L Fortran Link (H5L) Interface +!! +!! @see H5L, C-API +!! +!! @see @ref H5L_UG, User Guide +!! + +!> @ingroup FH5L +!! +!! @brief This module contains Fortran interfaces for H5L functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -32,7 +35,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** MODULE H5L @@ -41,77 +43,54 @@ MODULE H5L IMPLICIT NONE -!****t* H5L (F03)/h5l_info_t -! -! Fortran2003 Derived Type: -! TYPE, bind(c) :: union_t - TYPE(H5O_TOKEN_T_F) :: token - INTEGER(size_t) :: val_size + TYPE(H5O_TOKEN_T_F) :: token !< Type for object tokens + INTEGER(size_t) :: val_size !< Size of a soft link or user-defined link value END TYPE union_t +! +! @brief Fortran2003 Derived Type for h5l_info_t +! TYPE, bind(c) :: h5l_info_t - INTEGER(c_int) :: type ! H5L_type_t type -! LOGICAL(c_bool) :: corder_valid ! hbool_t corder_valid - INTEGER(c_int64_t) :: corder ! int64_t corder; - INTEGER(c_int) :: cset ! H5T_cset_t cset; + INTEGER(c_int) :: type !< Specifies the link class. Valid values include the following: + !< \li H5L_TYPE_HARD_F Hard link + !< \li H5L_TYPE_SOFT_F Soft link + !< \li H5L_TYPE_EXTERNAL_F External link + !< \li H5L_TYPE_ERROR_F Invalid link type id + ! LOGICAL(c_bool) :: corder_valid ! hbool_t corder_valid + INTEGER(c_int64_t) :: corder !< Creation order + INTEGER(c_int) :: cset !< Character set of link name is encoded. Valid values include the following: + !< \li H5T_CSET_ASCII US ASCII + !< \li H5T_CSET_UTF8 UTF-8 Unicode encoding TYPE(union_t) :: u END TYPE h5l_info_t -!***** - -!type specifies the link class. Valid values include the following: -! H5L_TYPE_HARD Hard link -! H5L_TYPE_SOFT Soft link -! H5L_TYPE_EXTERNAL External link -! H5L_TYPE_ERROR Error -!cset specifies the character set in which the link name is encoded. Valid values include the following: -! H5T_CSET_ASCII US ASCII -! H5T_CSET_UTF8 UTF-8 Unicode encoding - CONTAINS -! -!****s* H5L/h5lcopy_f -! -! NAME -! h5lcopy_f -! -! PURPOSE -! Copies a link from one location to another. -! -! INPUTS -! src_loc_id - Location identifier of the source link -! src_name - Name of the link to be copied -! dest_loc_id - Location identifier specifying the destination of the copy -! dest_name - Name to be assigned to the NEW copy -! loc_id - Identifier of the file or group containing the object -! name - Name of the link to delete -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lcpl_id - Link creation property list identifier -! lapl_id - Link access property list identifier -! -! AUTHOR -! M. Scot Breitenfeld -! February 27, 2008 -! -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Copies a link from one location to another. +!! +!! \param src_loc_id Location identifier. The identifier may be that of a file, group, dataset, or named datatype. +!! \param src_name Name of the link to be copied. +!! \param dest_loc_id Location identifier. The identifier may be that of a file, group, dataset, or named datatype. +!! \param dest_name Name to be assigned to the new copy. +!! \param hdferr \fortran_error +!! \param lcpl_id Link creation property list identifier. +!! \param lapl_id Link access property list identifier. +!! SUBROUTINE h5lcopy_f(src_loc_id, src_name, dest_loc_id, dest_name, hdferr, & lcpl_id, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: src_loc_id ! Location identifier of the source link - CHARACTER(LEN=*), INTENT(IN) :: src_name ! Name of the link to be copied - INTEGER(HID_T), INTENT(IN) :: dest_loc_id ! Location identifier specifying the destination of the copy - CHARACTER(LEN=*), INTENT(IN) :: dest_name ! Name to be assigned to the NEW copy - - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id ! Link creation property list identifier - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list identifier -!***** + INTEGER(HID_T), INTENT(IN) :: src_loc_id + CHARACTER(LEN=*), INTENT(IN) :: src_name + INTEGER(HID_T), INTENT(IN) :: dest_loc_id + CHARACTER(LEN=*), INTENT(IN) :: dest_name + + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(HID_T) :: lcpl_id_default INTEGER(HID_T) :: lapl_id_default @@ -150,37 +129,22 @@ CONTAINS END SUBROUTINE h5lcopy_f -! -!****s* H5L/h5ldelete_f -! -! NAME -! h5ldelete_f -! -! PURPOSE -! Removes a link from a group. -! -! INPUTS -! loc_id - Identifier of the file or group containing the object -! name - Name of the link to delete -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lapl_id - Link access property list identifier -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Removes a link from a group. +!! +!! \param loc_id Identifier of the file or group containing the object. +!! \param name Name of the link to delete. +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list identifier. +!! SUBROUTINE h5ldelete_f(loc_id, name, hdferr, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifier of the file or group containing the object - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the link to delete - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list identifier -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(HID_T) :: lapl_id_default INTEGER(SIZE_T) :: namelen @@ -205,41 +169,26 @@ CONTAINS END SUBROUTINE h5ldelete_f -! -!****s* H5L/H5Lcreate_soft_f -! -! NAME -! H5Lcreate_soft_f -! -! PURPOSE -! Creates a soft link to an object. -! -! INPUTS -! target_path - Path to the target object, which is not required to exist. -! link_loc_id - The file or group identifier for the new link. -! link_name - The name of the new link. -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lcpl_id - Link creation property list identifier. -! lapl_id - Link access property list identifier. -! -! AUTHOR -! M. Scot Breitenfeld -! February 20, 2008 -! -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Creates a soft link to an object. +!! +!! \param target_path Path to the target object, which is not required to exist. +!! \param link_loc_id The file or group identifier for the new link. +!! \param link_name The name of the new link. +!! \param hdferr \fortran_error +!! \param lcpl_id Link creation property list identifier. +!! \param lapl_id Link access property list identifier. +!! SUBROUTINE h5lcreate_soft_f(target_path, link_loc_id, link_name, hdferr, lcpl_id, lapl_id) IMPLICIT NONE - CHARACTER(LEN=*), INTENT(IN) :: target_path ! Path to the target object, which is not required to exist. - INTEGER(HID_T), INTENT(IN) :: link_loc_id ! The file or group identifier for the new link. - CHARACTER(LEN=*), INTENT(IN) :: link_name ! The name of the new link. - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id ! Link creation property list identifier. - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list identifier. -!***** + CHARACTER(LEN=*), INTENT(IN) :: target_path + INTEGER(HID_T), INTENT(IN) :: link_loc_id + CHARACTER(LEN=*), INTENT(IN) :: link_name + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(HID_T) :: lcpl_id_default INTEGER(HID_T) :: lapl_id_default INTEGER(SIZE_T) :: target_path_len @@ -278,46 +227,30 @@ CONTAINS END SUBROUTINE h5lcreate_soft_f -! -!****s* H5L/H5Lcreate_hard_f -! -! NAME -! H5Lcreate_hard_f -! -! PURPOSE -! Creates a hard link to an object. -! -! INPUTS -! -! obj_loc_id - The file or group identifier for the target object. -! obj_name - Name of the target object, which must already exist. -! link_loc_id - The file or group identifier for the new link. -! link_name - The name of the new link. -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lcpl_id - Link creation property list identifier. -! lapl_id - Link access property list identifier. -! -! AUTHOR -! M. Scot Breitenfeld -! February 27, 2008 -! -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Creates a hard link to an object. +!! +!! \param obj_loc_id The file or group identifier for the target object. +!! \param obj_name Name of the target object, which must already exist. +!! \param link_loc_id The file or group identifier for the new link. +!! \param link_name The name of the new link. +!! \param hdferr \fortran_error +!! \param lcpl_id Link creation property list identifier. +!! \param lapl_id Link access property list identifier. +!! SUBROUTINE h5lcreate_hard_f(obj_loc_id, obj_name, link_loc_id, link_name, hdferr, lcpl_id, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_loc_id ! The file or group identifier for the target object. - CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Name of the target object, which must already exist. - INTEGER(HID_T), INTENT(IN) :: link_loc_id ! The file or group identifier for the new link. - CHARACTER(LEN=*), INTENT(IN) :: link_name ! The name of the new link. + INTEGER(HID_T), INTENT(IN) :: obj_loc_id + CHARACTER(LEN=*), INTENT(IN) :: obj_name + INTEGER(HID_T), INTENT(IN) :: link_loc_id + CHARACTER(LEN=*), INTENT(IN) :: link_name - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure + INTEGER, INTENT(OUT) :: hdferr - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id ! Link creation property list identifier. - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list identifier. -!***** + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(HID_T) :: lcpl_id_default INTEGER(HID_T) :: lapl_id_default @@ -353,48 +286,32 @@ CONTAINS END SUBROUTINE h5lcreate_hard_f -! -!****s* H5L/H5Lcreate_external_f -! -! NAME -! H5Lcreate_external_f -! -! PURPOSE -! Creates a soft link to an object in a different file. -! -! INPUTS -! -! file_name - Name of the file containing the target object. Neither the file nor the target object is -! required to exist. May be the file the link is being created in. -! obj_name - Path within the target file to the target object. -! link_loc_id - The file or group identifier for the new link. -! link_name - The name of the new link. -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lcpl_id - Link creation property list identifier. -! lapl_id - Link access property list identifier. -! -! AUTHOR -! M. Scot Breitenfeld -! February 27, 2008 -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Creates a soft link to an object in a different file. +!! +!! \param file_name Name of the file containing the target object. Neither the file nor the target object is +!! required to exist. May be the file the link is being created in. +!! \param obj_name Path within the target file to the target object. +!! \param link_loc_id The file or group identifier for the new link. +!! \param link_name The name of the new link. +!! \param hdferr \fortran_error +!! \param lcpl_id Link creation property list identifier. +!! \param lapl_id Link access property list identifier. +!! SUBROUTINE h5lcreate_external_f(file_name, obj_name, link_loc_id, link_name, hdferr, lcpl_id, lapl_id) IMPLICIT NONE - CHARACTER(LEN=*), INTENT(IN) :: file_name ! Name of the file containing the target object. Neither - ! the file nor the target object is required to exist. - ! May be the file the link is being created in. - CHARACTER(LEN=*), INTENT(IN) :: obj_name ! Name of the target object, which must already exist. - INTEGER(HID_T), INTENT(IN) :: link_loc_id ! The file or group identifier for the new link. - CHARACTER(LEN=*), INTENT(IN) :: link_name ! The name of the new link. - - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id ! Link creation property list identifier. - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list identifier. -!***** + CHARACTER(LEN=*), INTENT(IN) :: file_name + CHARACTER(LEN=*), INTENT(IN) :: obj_name + INTEGER(HID_T), INTENT(IN) :: link_loc_id + CHARACTER(LEN=*), INTENT(IN) :: link_name + + INTEGER, INTENT(OUT) :: hdferr + + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id + INTEGER(HID_T) :: lcpl_id_default INTEGER(HID_T) :: lapl_id_default @@ -433,61 +350,37 @@ CONTAINS END SUBROUTINE h5lcreate_external_f -! -!****s* H5L/h5ldelete_by_idx_f -! -! NAME -! h5ldelete_by_idx_f -! -! PURPOSE -! Removes the nth link in a group. -! INPUTS -! loc_id - File or group identifier specifying location of subject group -! group_name - Name of subject group -! index_field - Type of index; Possible values are: -! H5_INDEX_UNKNOWN_F = -1 - Unknown index type -! H5_INDEX_NAME_F - Index on names -! H5_INDEX_CRT_ORDER_F - Index on creation order -! H5_INDEX_N_F - Number of indices defined -! -! order - Order within field or index; Possible values are: -! H5_ITER_UNKNOWN_F - Unknown order -! H5_ITER_INC_F - Increasing order -! H5_ITER_DEC_F - Decreasing order -! H5_ITER_NATIVE_F - No particular order, whatever is fastest -! H5_ITER_N_F - Number of iteration orders -! -! n - Link for which to retrieve information -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lapl_id - Link access property list -! -! AUTHOR -! M. Scot Breitenfeld -! February 29, 2008 -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Removes the nth link in a group. +!! +!! \param loc_id File or group identifier specifying location of subject group. +!! \param group_name Name of subject group. +!! \param index_field Type of index; Possible values are: +!! \li H5_INDEX_UNKNOWN_F = -1 - Unknown index type +!! \li H5_INDEX_NAME_F - Index on names +!! \li H5_INDEX_CRT_ORDER_F - Index on creation order +!! \li H5_INDEX_N_F - Number of indices defined +!! \param order Order within field or index; Possible values are: +!! \li H5_ITER_UNKNOWN_F - Unknown order +!! \li H5_ITER_INC_F - Increasing order +!! \li H5_ITER_DEC_F - Decreasing order +!! \li H5_ITER_NATIVE_F - No particular order, whatever is fastest +!! \li H5_ITER_N_F - Number of iteration orders +!! \param n Link for which to retrieve information. +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list. +!! SUBROUTINE h5ldelete_by_idx_f(loc_id, group_name, index_field, order, n, hdferr, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifier for object to which attribute is attached - CHARACTER(LEN=*), INTENT(IN) :: group_name ! Name of object, relative to location, - ! from which attribute is to be removed - INTEGER, INTENT(IN) :: index_field ! Type of index; Possible values are: - ! H5_INDEX_UNKNOWN_F - Unknown index type - ! H5_INDEX_NAME_F - Index on names - ! H5_INDEX_CRT_ORDER_F - Index on creation order - ! H5_INDEX_N_F - Number of indices defined - INTEGER, INTENT(IN) :: order ! Order in which to iterate over index; Possible values are: - ! H5_ITER_UNKNOWN_F - Unknown order - ! H5_ITER_INC_F - Increasing order - ! H5_ITER_DEC_F - Decreasing order - ! H5_ITER_NATIVE_F - No particular order, whatever is fastest - ! H5_ITER_N_F - Number of iteration orders - INTEGER(HSIZE_T), INTENT(IN) :: n ! Offset within index - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: group_name + INTEGER, INTENT(IN) :: index_field + INTEGER, INTENT(IN) :: order + INTEGER(HSIZE_T), INTENT(IN) :: n + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(HID_T) :: lapl_id_default INTEGER(SIZE_T) :: group_namelen @@ -515,40 +408,24 @@ CONTAINS END SUBROUTINE h5ldelete_by_idx_f -! -!****s* H5L/H5Lexists_f -! -! NAME -! H5Lexists_f -! -! PURPOSE -! Check if a link with a particular name exists in a group. -! -! INPUTS -! loc_id - Identifier of the file or group to query. -! name - Link name to check -! -! OUTPUTS -! link_exists - link exists status (.TRUE.,.FALSE.) -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lapl_id - Link access property list identifier. -! -! AUTHOR -! M. Scot Breitenfeld -! February 29, 2008 -! -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Check if a link with a particular name exists in a group. +!! +!! \param loc_id Identifier of the file or group to query. +!! \param name Link name to check. +!! \param link_exists Link exists status (.TRUE.,.FALSE.). +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list identifier. +!! SUBROUTINE h5lexists_f(loc_id, name, link_exists, hdferr, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Identifier of the file or group to query. - CHARACTER(LEN=*), INTENT(IN) :: name ! Link name to check. - LOGICAL, INTENT(OUT) :: link_exists ! .TRUE. if exists, .FALSE. otherwise - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + LOGICAL, INTENT(OUT) :: link_exists + INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id - ! Link access property list identifier. -!***** INTEGER :: link_exists_c INTEGER(HID_T) :: lapl_id_default INTEGER(SIZE_T) :: namelen @@ -580,74 +457,44 @@ CONTAINS END SUBROUTINE h5lexists_f -! -!****s* H5L/h5lget_info_f -! -! NAME -! h5lget_info_f -! -! PURPOSE -! Returns information about a link. -! -! INPUTS -! link_loc_id - File or group identifier. -! link_name - Name of the link for which information is being sought -! -! OUTPUTS -! NOTE: In C these are contained in the structure H5L_info_t -! -! cset - indicates the character set used for link’s name. -! corder - specifies the link’s creation order position. -! corder_valid - indicates whether the value in corder is valid. -! link_type - specifies the link class: -! H5L_TYPE_HARD_F - Hard link -! H5L_TYPE_SOFT_F - Soft link -! H5L_TYPE_EXTERNAL_F - External link -! H5L_TYPE_ERROR_ F - Error -! token - If the link is a hard link, token specifies the object token that the link points to -! val_size - If the link is a symbolic link, val_size will be the length of the link value, e.g., -! the length of the name of the pointed-to object with a null terminator. -! hdferr - Returns 0 if successful and -1 if fails -! -! OPTIONAL PARAMETERS -! lapl_id - Link access property list -! -! AUTHOR -! M. Scot Breitenfeld -! February 29, 2008 -! -! HISTORY -! Changed the link_type names to match those in C (bug 1720) from, -! H5L_LINK_HARD_F, H5L_LINK_SOFT_F,H5L_LINK_EXTERNAL_F,H5L_LINK_ERROR_F -! to -! H5L_TYPE_HARD_F, H5L_TYPE_SOFT_F,H5L_TYPE_EXTERNAL_F,H5L_TYPE_ERROR_F -! MSB January 8, 2010. -! -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Returns information about a link. +!! +!! \param link_loc_id File or group identifier. +!! \param link_name Name of the link for which information is being sought. +!! NOTE: In C these are contained in the structure H5L_info_t +!! \param cset Indicates the character set used for link’s name. +!! \param corder Specifies the link’s creation order position. +!! \param f_corder_valid Indicates whether the value in corder is valid. +!! \param link_type Specifies the link class: +!! \li H5L_TYPE_HARD_F - Hard link +!! \li H5L_TYPE_SOFT_F - Soft link +!! \li H5L_TYPE_EXTERNAL_F - External link +!! \li H5L_TYPE_ERROR_ F - Error +!! \param token If the link is a hard link, token specifies the object token that the link points to. +!! \param val_size If the link is a symbolic link, val_size will be the length of the link value, e.g., +!! the length of the name of the pointed-to object with a null terminator. +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list. +!! SUBROUTINE h5lget_info_f(link_loc_id, link_name, & cset, corder, f_corder_valid, link_type, token, val_size, & hdferr, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: link_loc_id ! File or group identifier. - CHARACTER(LEN=*), INTENT(IN) :: link_name ! Name of the link for which information is being sought - -! OUTPUTS NOTE: In C these are contained in the structure H5L_info_t - INTEGER, INTENT(OUT) :: cset ! Indicates the character set used for the link’s name. - INTEGER, INTENT(OUT) :: corder ! Specifies the link’s creation order position. - LOGICAL, INTENT(OUT) :: f_corder_valid ! Indicates whether the value in corder is valid. - INTEGER, INTENT(OUT) :: link_type ! Specifies the link class: - ! H5L_TYPE_HARD_F - Hard link - ! H5L_TYPE_SOFT_F - Soft link - ! H5L_TYPE_EXTERNAL_F - External link - ! H5L_TYPE_ERROR _F - Error - TYPE(H5O_TOKEN_T_F), INTENT(OUT), TARGET :: token ! If the link is a hard link, token specifies the object token that the link points to - INTEGER(SIZE_T), INTENT(OUT) :: val_size ! If the link is a symbolic link, val_size will be the length of the link value, e.g., - ! the length of the name of the pointed-to object with a null terminator. - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list -!***** + INTEGER(HID_T), INTENT(IN) :: link_loc_id + CHARACTER(LEN=*), INTENT(IN) :: link_name + + INTEGER, INTENT(OUT) :: cset + INTEGER, INTENT(OUT) :: corder + LOGICAL, INTENT(OUT) :: f_corder_valid + INTEGER, INTENT(OUT) :: link_type + TYPE(H5O_TOKEN_T_F), INTENT(OUT), TARGET :: token + INTEGER(SIZE_T), INTENT(OUT) :: val_size + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(SIZE_T) :: link_namelen INTEGER(HID_T) :: lapl_id_default INTEGER :: corder_valid @@ -685,78 +532,57 @@ CONTAINS END SUBROUTINE h5lget_info_f -! -!****s* H5L/h5lget_info_by_idx_f -! -! NAME -! h5lget_info_by_idx_f -! -! PURPOSE -! Retrieves metadata for a link in a group, according to the order within a field or index. -! -! INPUTS -! loc_id - File or group identifier specifying location of subject group -! group_name - Name of subject group -! index_field - Index or field which determines the order -! order - Order within field or index -! n - Link for which to retrieve information -! -! OUTPUTS -! NOTE: In C these are defined as a structure: H5L_info_t -! corder_valid - Indicates whether the creation order data is valid for this attribute -! corder - Is a positive integer containing the creation order of the attribute -! cset - Indicates the character set used for the attribute’s name -! token - If the link is a hard link, token specifies the object token that the link points to -! val_size - If the link is a symbolic link, val_size will be the length of the link value, e.g., -! the length of the name of the pointed-to object with a null terminator. -! hdferr - Returns 0 if successful and -1 if fails -! -! OPTIONAL PARAMETERS -! lapl_id - Link access property list -! -! AUTHOR -! M. Scot Breitenfeld -! February 29, 2008 -! -! HISTORY -! Changed the link_type names to match those in C (bug 1720) from, -! H5L_LINK_HARD_F, H5L_LINK_SOFT_F,H5L_LINK_EXTERNAL_F,H5L_LINK_ERROR_F -! to -! H5L_TYPE_HARD_F, H5L_TYPE_SOFT_F,H5L_TYPE_EXTERNAL_F,H5L_TYPE_ERROR_F -! MSB January 8, 2010. -! -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Retrieves metadata for a link in a group, according to the order within a field or index. +!! +!! \param loc_id File or group identifier specifying location of subject group. +!! \param group_name Name of subject group. +!! \param index_field Index or field which determines the order: +!! \li H5_INDEX_UNKNOWN_F = -1 - Unknown index type +!! \li H5_INDEX_NAME_F - Index on names +!! \li H5_INDEX_CRT_ORDER_F - Index on creation order +!! \li H5_INDEX_N_F - Number of indices defined +!! \param order Order within field or index: +!! \li H5_ITER_UNKNOWN_F - Unknown order +!! \li H5_ITER_INC_F - Increasing order +!! \li H5_ITER_DEC_F - Decreasing order +!! \li H5_ITER_NATIVE_F - No particular order, whatever is fastest +!! \li H5_ITER_N_F - Number of iteration orders +!! \param n Link for which to retrieve information. +!! NOTE: In C these are defined as a structure: H5L_info_t +!! \param link_type Specifies the link class: +!! \li H5L_TYPE_HARD_F - Hard link +!! \li H5L_TYPE_SOFT_F - Soft link +!! \li H5L_TYPE_EXTERNAL_F - External link +!! \li H5L_TYPE_ERROR _F - Error +!! \param f_corder_valid Indicates whether the creation order data is valid for this attribute. +!! \param corder Is a positive integer containing the creation order of the attribute. +!! \param cset Indicates the character set used for the attribute’s name. +!! \param token If the link is a hard link, token specifies the object token that the link points to. +!! \param val_size If the link is a symbolic link, val_size will be the length of the link value, e.g., +!! the length of the name of the pointed-to object with a null terminator. +!! \param hdferr \fortran_error +!! +!! \param lapl_id Link access property list. +!! SUBROUTINE h5lget_info_by_idx_f(loc_id, group_name, index_field, order, n, & link_type, f_corder_valid, corder, cset, token, val_size, hdferr, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier specifying location of subject group - CHARACTER(LEN=*), INTENT(IN) :: group_name ! Name of subject group - INTEGER, INTENT(IN) :: index_field ! Index or field which determines the order - ! H5_INDEX_UNKNOWN_F - Unknown index type - ! H5_INDEX_NAME_F - Index on names - ! H5_INDEX_CRT_ORDER_F - Index on creation order - ! H5_INDEX_N_F - Number of indices defined - INTEGER, INTENT(IN) :: order ! Order in which to iterate over index; Possible values are: - ! H5_ITER_UNKNOWN_F - Unknown order - ! H5_ITER_INC_F - Increasing order - ! H5_ITER_DEC_F - Decreasing order - ! H5_ITER_NATIVE_F - No particular order, whatever is fastest - INTEGER(HSIZE_T), INTENT(IN) :: n ! Attribute’s position in index - INTEGER, INTENT(OUT) :: link_type ! Specifies the link class: - ! H5L_TYPE_HARD_F - Hard link - ! H5L_TYPE_SOFT_F - Soft link - ! H5L_TYPE_EXTERNAL_F - External link - ! H5L_TYPE_ERROR _F - Error - LOGICAL, INTENT(OUT) :: f_corder_valid ! Indicates whether the creation order data is valid for this attribute - INTEGER, INTENT(OUT) :: corder ! Is a positive integer containing the creation order of the attribute - INTEGER, INTENT(OUT) :: cset ! Indicates the character set used for the attribute’s name - TYPE(H5O_TOKEN_T_F), INTENT(OUT), TARGET :: token ! If the link is a hard link, token specifies the object token that the link points to - INTEGER(SIZE_T), INTENT(OUT) :: val_size ! If the link is a symbolic link, val_size will be the length of the link value, e.g., - ! the length of the name of the pointed-to object with a null terminator. - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: group_name + INTEGER, INTENT(IN) :: index_field + INTEGER, INTENT(IN) :: order + INTEGER(HSIZE_T), INTENT(IN) :: n + INTEGER, INTENT(OUT) :: link_type + LOGICAL, INTENT(OUT) :: f_corder_valid + INTEGER, INTENT(OUT) :: corder + INTEGER, INTENT(OUT) :: cset + TYPE(H5O_TOKEN_T_F), INTENT(OUT), TARGET :: token + INTEGER(SIZE_T), INTENT(OUT) :: val_size + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER :: corder_valid INTEGER(SIZE_T) :: group_namelen INTEGER(HID_T) :: lapl_id_default @@ -799,42 +625,24 @@ CONTAINS END SUBROUTINE h5lget_info_by_idx_f -! -!****s* H5L/h5lis_registered_f -! -! NAME -! h5lis_registered_f -! -! PURPOSE -! Determines whether a class of user-defined links is registered. -! -! INPUTS -! link_cls_id - User-defined link class identifier -! -! OUTPUTS -! registered - .TRUE. - if the link class has been registered -! .FALSE. - if it is unregistered -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! February 29, 2008 -! -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Determines whether a class of user-defined links is registered. +!! +!! \param link_cls_id User-defined link class identifier. +!! \param registered .TRUE. if the link class has been registered. +!! \param hdferr \fortran_error +!! SUBROUTINE h5lis_registered_f(link_cls_id, registered, hdferr) IMPLICIT NONE - INTEGER, INTENT(IN) :: link_cls_id ! User-defined link class identifier - LOGICAL, INTENT(OUT) :: registered ! .TRUE. - if the link class has been registered and - ! .FALSE. - if it is unregistered - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure -!***** + INTEGER, INTENT(IN) :: link_cls_id + LOGICAL, INTENT(OUT) :: registered + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5lis_registered_c(link_cls_id) BIND(C,NAME='h5lis_registered_c') IMPLICIT NONE - INTEGER, INTENT(IN) :: link_cls_id ! User-defined link class identifier + INTEGER, INTENT(IN) :: link_cls_id END FUNCTION h5lis_registered_c END INTERFACE @@ -848,47 +656,28 @@ CONTAINS END SUBROUTINE h5lis_registered_f -! -!****s* H5L/h5lmove_f -! -! NAME -! h5lmove_f -! -! PURPOSE -! Renames a link within an HDF5 file. -! -! INPUTS -! src_loc_id - Original file or group identifier. -! src_name - Original link name. -! dest_loc_id - Destination file or group identifier. -! dest_name - NEW link name. -! -! OUTPUTS -! hdferr - Error code: -! 0 on success and -1 on failure -! -! OPTIONAL PARAMETERS -! lcpl_id - Link creation property list identifier to be associated WITH the NEW link. -! lapl_id - Link access property list identifier to be associated WITH the NEW link. -! -! AUTHOR -! M. Scot Breitenfeld -! March 3, 2008 -! -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Renames a link within an HDF5 file. +!! +!! \param src_loc_id Original file or group identifier. +!! \param src_name Original link name. +!! \param dest_loc_id Destination file or group identifier. +!! \param dest_name NEW link name. +!! \param hdferr \fortran_error +!! \param lcpl_id Link creation property list identifier to be associated WITH the NEW link. +!! \param lapl_id Link access property list identifier to be associated WITH the NEW link. +!! SUBROUTINE h5lmove_f(src_loc_id, src_name, dest_loc_id, dest_name, hdferr, lcpl_id, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: src_loc_id ! Original file or group identifier. - CHARACTER(LEN=*), INTENT(IN) :: src_name ! Original link name. - INTEGER(HID_T), INTENT(IN) :: dest_loc_id ! Destination file or group identifier. - CHARACTER(LEN=*), INTENT(IN) :: dest_name ! NEW link name. - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id ! Link creation property list identifier - ! to be associated WITH the NEW link. - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list identifier - ! to be associated WITH the NEW link. -!***** + INTEGER(HID_T), INTENT(IN) :: src_loc_id + CHARACTER(LEN=*), INTENT(IN) :: src_name + INTEGER(HID_T), INTENT(IN) :: dest_loc_id + CHARACTER(LEN=*), INTENT(IN) :: dest_name + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(SIZE_T) :: src_namelen INTEGER(SIZE_T) :: dest_namelen @@ -928,59 +717,44 @@ CONTAINS END SUBROUTINE h5lmove_f -! -!****s* H5L/h5lget_name_by_idx_f -! -! NAME -! h5lget_name_by_idx_f -! -! PURPOSE -! Retrieves name of the nth link in a group, according to the order within a specified field or index. -! -! INPUTS -! loc_id - File or group identifier specifying location of subject group -! group_name - Name of subject group -! index_field - Index or field which determines the order -! order - Order within field or index -! n - Link for which to retrieve information -! -! OUTPUTS -! name - Buffer in which link value is returned -! hdferr - Returns 0 if successful and -1 if fails -! -! OPTIONAL PARAMETERS -! lapl_id - List access property list identifier. -! size - Maximum number of characters of link value to be returned. -! -! AUTHOR -! M. Scot Breitenfeld -! March 10, 2008 -! -! SOURCE +!> +!! \ingroup FH5L +!! +!! \brief Retrieves name of the nth link in a group, according to the order within a specified field or index. +!! +!! \param loc_id File or group identifier specifying location of subject group. +!! \param group_name Name of subject group. +!! \param index_field Index or field which determines the order: +!! \li H5_INDEX_UNKNOWN_F = -1 - Unknown index type +!! \li H5_INDEX_NAME_F - Index on names +!! \li H5_INDEX_CRT_ORDER_F - Index on creation order +!! \li H5_INDEX_N_F - Number of indices defined +!! \param order Order within field or index: +!! \li H5_ITER_UNKNOWN_F - Unknown order +!! \li H5_ITER_INC_F - Increasing order +!! \li H5_ITER_DEC_F - Decreasing order +!! \li H5_ITER_NATIVE_F - No particular order, whatever is fastest +!! \li H5_ITER_N_F - Number of iteration orders +!! \param n Link for which to retrieve information. +!! \param name Buffer in which link value is returned. +!! \param hdferr \fortran_error +!! \param lapl_id List access property list identifier. +!! \param size Maximum number of characters of link value to be returned. +!! SUBROUTINE h5lget_name_by_idx_f(loc_id, group_name, index_field, order, n, & name, hdferr, size, lapl_id) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier specifying location of subject group - CHARACTER(LEN=*), INTENT(IN) :: group_name ! Name of subject group - INTEGER, INTENT(IN) :: index_field ! Index or field which determines the order - ! H5_INDEX_UNKNOWN_F - Unknown index type - ! H5_INDEX_NAME_F - Index on names - ! H5_INDEX_CRT_ORDER_F - Index on creation order - ! H5_INDEX_N_F - Number of indices defined - INTEGER, INTENT(IN) :: order ! Order in which to iterate over index; Possible values are: - ! H5_ITER_UNKNOWN_F - Unknown order - ! H5_ITER_INC_F - Increasing order - ! H5_ITER_DEC_F - Decreasing order - ! H5_ITER_NATIVE_F - No particular order, whatever is fastest - INTEGER(HSIZE_T), INTENT(IN) :: n ! Attribute’s position in index - CHARACTER(LEN=*), INTENT(OUT) :: name ! Buffer in which link value is returned - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: group_name + INTEGER, INTENT(IN) :: index_field + INTEGER, INTENT(IN) :: order + INTEGER(HSIZE_T), INTENT(IN) :: n + CHARACTER(LEN=*), INTENT(OUT) :: name + INTEGER, INTENT(OUT) :: hdferr INTEGER(SIZE_T) :: group_namelen - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id INTEGER(HID_T) :: lapl_id_default - INTEGER(SIZE_T), OPTIONAL, INTENT(OUT) :: size ! Indicates the size, in the number of characters, of the link + INTEGER(SIZE_T), OPTIONAL, INTENT(OUT) :: size INTEGER(SIZE_T) :: size_default INTERFACE @@ -1020,90 +794,23 @@ CONTAINS ! HAS PROBLEM WITH void pointer in C !!$! -!!$!****s* H5L/ -!!$! -!!$! NAME -!!$! h5lget_val_by_idx_f -!!$! -!!$! PURPOSE -!!$! Returns the link value of a link, according to the order of -!!$! an index. For symbolic links, this is the path to which the -!!$! link points, including the null terminator. For user-defined -!!$! links, it is the link buffer. -!!$! INPUTS -!!$! loc_id - File or group identifier specifying location of subject group -!!$! group_name - Name of subject group -!!$! index_field - Index or field which determines the order -!!$! order - Order within field or index -!!$! n - Link for which to retrieve information -!!$! size - Maximum number of characters of link value to be returned. -!!$! -!!$! OUTPUTS NOTE: In C these are defined as a structure: H5L_info_t -!!$! corder_valid - indicates whether the creation order data is valid for this attribute -!!$! corder - is a positive integer containing the creation order of the attribute -!!$! cset - indicates the character set used for the attribute’s name -!!$! data_size - indicates the size, in the number of characters, of the attribute -!!$! hdferr - error code -!!$! Success: 0 -!!$! Failure: -1 -!!$! OPTIONAL PARAMETERS -!!$! lapl_id - List access property list identifier. -!!$! -!!$! AUTHOR -!!$! M. Scot Breitenfeld -!!$! March 3, 2008 -!!$! -!!$! HISTORY N/A -!!$! -!!$! -!!$! SOURCE +!> !!$ SUBROUTINE h5lget_val_by_idx_f(loc_id, group_name, index_field, order, n, & !!$ f_corder_valid, corder, cset, data_size, hdferr, lapl_id) !!$ IMPLICIT NONE -!!$ INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier specifying location of subject group -!!$ CHARACTER(LEN=*), INTENT(IN) :: group_name ! Name of subject group -!!$ INTEGER, INTENT(IN) :: index_field ! Index or field which determines the order -!!$ ! H5_INDEX_UNKNOWN_F - Unknown index type -!!$ ! H5_INDEX_NAME_F - Index on names -!!$ ! H5_INDEX_CRT_ORDER_F - Index on creation order -!!$ ! H5_INDEX_N_F - Number of indices defined -!!$ INTEGER, INTENT(IN) :: order ! Order in which to iterate over index; Possible values are: -!!$ ! H5_ITER_UNKNOWN_F - Unknown order -!!$ ! H5_ITER_INC_F - Increasing order -!!$ ! H5_ITER_DEC_F - Decreasing order + +!!$ ! H5_INDEX_N_F - Number of indices defined + !!$ ! H5_ITER_NATIVE_F - No particular order, whatever is fastest -!!$ INTEGER(HSIZE_T), INTENT(IN) :: n ! Attribute’s position in index -!!$ LOGICAL, INTENT(OUT) :: f_corder_valid ! Indicates whether the creation order data is valid for this attribute -!!$ INTEGER, INTENT(OUT) :: corder ! Is a positive integer containing the creation order of the attribute -!!$ INTEGER, INTENT(OUT) :: cset ! Indicates the character set used for the attribute’s name -!!$ INTEGER(HSIZE_T), INTENT(OUT) :: data_size ! Indicates the size, in the number of characters, of the attribute -!!$ INTEGER, INTENT(OUT) :: hdferr ! Error code: -!!$ ! 0 on success and -1 on failure -!!$ INTEGER :: corder_valid -!!$ INTEGER(SIZE_T) :: group_namelen -!!$ INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list -!!$ INTEGER(HID_T) :: lapl_id_default -!!$ -!!$ INTERFACE + + !!$ INTEGER FUNCTION h5lget_val_by_idx_c(loc_id, group_name, group_namelen, index_field, order, n, & !!$ corder_valid, corder, cset, data_size, lapl_id_default) !!$ USE H5GLOBAL !!$ !DEC$IF DEFINED(HDF5F90_WINDOWS) !!$ !DEC$ATTRIBUTES C,reference,decorate,alias:'H5LGET_VAL_BY_IDX_C'::h5lget_val_by_idx_c !!$ !DEC$ENDIF -!!$ INTEGER(HID_T), INTENT(IN) :: loc_id -!!$ CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: group_name -!!$ INTEGER(SIZE_T) :: group_namelen -!!$ INTEGER, INTENT(IN) :: index_field -!!$ INTEGER, INTENT(IN) :: order -!!$ INTEGER(HSIZE_T), INTENT(IN) :: n -!!$ INTEGER :: corder_valid -!!$ INTEGER, INTENT(OUT) :: corder -!!$ INTEGER, INTENT(OUT) :: cset -!!$ INTEGER(HSIZE_T), INTENT(OUT) :: data_size -!!$ INTEGER(HID_T) :: lapl_id_default -!!$ END FUNCTION h5lget_val_by_idx_c -!!$ END INTERFACE + !!$ !!$ group_namelen = LEN(group_name) !!$ @@ -1119,45 +826,11 @@ CONTAINS !!$ END SUBROUTINE h5lget_val_by_idx_f !!$! -!!$!****s* H5L/h5lget_val_f -!!$! -!!$! NAME -!!$! h5lget_val_f -!!$! -!!$! PURPOSE -!!$! Returns the value of a symbolic link. -!!$! -!!$! INPUTS -!!$! link_loc_id - File or group identifier. -!!$! link_name - Link whose value is to be returned. -!!$! size - Maximum number of characters of link value to be returned. -!!$! -!!$! OUTPUTS -!!$! linkval_buff - The buffer to hold the returned link value. -!!$! hdferr - error code -!!$! Success: 0 -!!$! Failure: -1 -!!$! OPTIONAL PARAMETERS -!!$! lapl_id - List access property list identifier. -!!$! -!!$! AUTHOR -!!$! M. Scot Breitenfeld -!!$! March 3, 2008 -!!$! SOURCE +!> !!$ SUBROUTINE h5lget_val_f(link_loc_id, link_name, size, linkval_buff, & !!$ hdferr, lapl_id) !!$ IMPLICIT NONE -!!$ INTEGER(HID_T), INTENT(IN) :: link_loc_id ! File or group identifier. -!!$ CHARACTER(LEN=*), INTENT(IN) :: link_name ! Link whose value is to be returned. -!!$ INTEGER(SIZE_T), INTENT(IN) :: size ! Maximum number of characters of link value to be returned. -!!$ -!!$ CHARACTER(LEN=size), INTENT(OUT) :: linkval_buff ! The buffer to hold the returned link value. -!!$ INTEGER, INTENT(OUT) :: hdferr ! Error code: -!!$ ! 0 on success and -1 on failure -!!$ INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id ! Link access property list -!!$ -!!$ INTEGER :: link_namelen -!!$ INTEGER(HID_T) :: lapl_id_default + !!$ INTEGER :: corder_valid !!$ !!$ INTEGER :: link_namelen @@ -1172,15 +845,7 @@ CONTAINS !!$ !DEC$IF DEFINED(HDF5F90_WINDOWS) !!$ !DEC$ATTRIBUTES C,reference,decorate,alias:'H5LGET_VAL_C'::h5lget_val_c !!$ !DEC$ENDIF -!!$ INTEGER(HID_T), INTENT(IN) :: link_loc_id ! File or group identifier. -!!$ CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: link_name ! Link whose value is to be returned. -!!$ INTEGER :: link_namelen -!!$ INTEGER(SIZE_T), INTENT(IN) :: size ! Maximum number of characters of link value to be returned. -!!$ -!!$ CHARACTER(LEN=size), INTENT(OUT) :: linkval_buff ! The buffer to hold the returned link value. -!!$ -!!$ INTEGER :: link_namelen -!!$ INTEGER(HID_T) :: lapl_id_default + !!$ !!$ END FUNCTION h5lget_val_c !!$ END INTERFACE @@ -1196,56 +861,11 @@ CONTAINS !!$ END SUBROUTINE h5lget_val_f !!$! -!!$!****s* H5L/H5Lregistered_f -!!$! -!!$! NAME -!!$! H5Lregistered_f -!!$! -!!$! PURPOSE -!!$! Registers user-defined link class or changes behavior of existing class. -!!$! -!!$! INPUTS NOTE: In C the following represents struct H5L_class_t: -!!$! version - Version number of this struct -!!$! class_id - Link class identifier -!!$! comment - Comment for debugging -!!$! create_func - Callback during link creation -!!$! move_func - Callback after moving link -!!$! copy_func - Callback after copying link -!!$! trav_func - The main traversal function -!!$! del_func - Callback for link deletion -!!$! query_func - Callback for queries -!!$! -!!$! OUTPUTS -!!$! hdferr - Error code -!!$! Success: 0 -!!$! Failure: -1 -!!$! OPTIONAL PARAMETERS -!!$! None -!!$! -!!$! AUTHOR -!!$! M. Scot Breitenfeld -!!$! February 29, 2008 -!!$! -!!$! HISTORY N/A -!!$! -!!$! -!!$! SOURCE +!> !!$ SUBROUTINE H5Lregistered_f(version, class_id, comment, create_func, & !!$ move_func, copy_func, trav_func, del_func, query_func, hdferr) !!$ IMPLICIT NONE -!!$ INTEGER, INTENT(IN) :: version ! Version number of this struct -!!$ INTEGER, INTENT(IN) :: class_id ! Link class identifier -!!$ CHARACTER(LEN=*), INTENT(IN) :: comment ! Comment for debugging -!!$ CHARACTER(LEN=*), INTENT(IN) :: create_func ! Callback during link creation -!!$ CHARACTER(LEN=*), INTENT(IN) :: move_func ! Callback after moving link -!!$ CHARACTER(LEN=*), INTENT(IN) :: copy_func ! Callback after copying link -!!$ CHARACTER(LEN=*), INTENT(IN) :: trav_func ! The main traversal function -!!$ CHARACTER(LEN=*), INTENT(IN) :: del_func ! Callback for link deletion -!!$ CHARACTER(LEN=*), INTENT(IN) :: query_func ! Callback for queries -!!$ INTEGER, INTENT(OUT) :: hdferr ! Error code: -!!$ ! 0 on success and -1 on failure -!!$ INTEGER :: comment_len -!!$ INTEGER :: create_func_len + !!$ INTEGER :: move_func_len !!$ INTEGER :: copy_func_len !!$ INTEGER :: trav_func_len @@ -1264,19 +884,7 @@ CONTAINS !!$ !DEC$IF DEFINED(HDF5F90_WINDOWS) !!$ !DEC$ATTRIBUTES C,reference,decorate,alias:'H5LREGISTERED_C'::H5Lregistered_c !!$ !DEC$ENDIF -!!$ INTEGER, INTENT(IN) :: version ! Version number of this struct -!!$ INTEGER, INTENT(IN) :: class_id ! Link class identifier -!!$ CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: comment ! Comment for debugging -!!$ CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: create_func ! Callback during link creation -!!$ CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: move_func ! Callback after moving link -!!$ CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: copy_func ! Callback after copying link -!!$ CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: trav_func ! The main traversal function -!!$ CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: del_func ! Callback for link deletion -!!$ CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: query_func ! Callback for queries -!!$ INTEGER, INTENT(OUT) :: hdferr ! Error code: -!!$ ! 0 on success and -1 on failure -!!$ INTEGER :: comment_len -!!$ INTEGER :: create_func_len + !!$ INTEGER :: move_func_len !!$ INTEGER :: copy_func_len !!$ INTEGER :: trav_func_len @@ -1304,44 +912,30 @@ CONTAINS !!$ !!$ END SUBROUTINE H5Lregistered_f -!****s* H5L (F03)/h5literate_f -! -! NAME -! h5literate_f -! -! PURPOSE -! Iterates through links in a group. -! -! Inputs: -! group_id - Identifier specifying subject group -! index_type - Type of index which determines the order: -! H5_INDEX_NAME_F - Alphanumeric index on name -! H5_INDEX_CRT_ORDER_F - Index on creation order -! order - Order within index: -! H5_ITER_INC_F - Increasing order -! H5_ITER_DEC_F - Decreasing order -! H5_ITER_NATIVE_F - Fastest available order -! idx - IN: Iteration position at which to start -! op - Callback function passing data regarding the link to the calling application -! op_data - User-defined pointer to data required by the application for its processing of the link -! -! Outputs: -! idx - OUT: Position at which an interrupted iteration may be restarted -! return_value - Success: The return value of the first operator that -! returns non-zero, or zero if all members were -! processed with no operator returning non-zero. -! -! Failure: Negative if something goes wrong within the -! library, or the negative value returned by one -! of the operators. -! -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! July 8, 2008 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5L +!! +!! \brief Iterates through links in a group. +!! +!! \param group_id Identifier specifying subject group. +!! \param index_type Type of index which determines the order: +!! \li H5_INDEX_NAME_F - Alphanumeric index on name +!! \li H5_INDEX_CRT_ORDER_F - Index on creation order +!! \param order Order within index: +!! \li H5_ITER_INC_F - Increasing order +!! \li H5_ITER_DEC_F - Decreasing order +!! \li H5_ITER_NATIVE_F - Fastest available order +!! \param idx Iteration position at which to start, or
+!! Position at which an interrupted iteration may be restarted +!! \param op Callback function passing data regarding the link to the calling application. +!! \param op_data User-defined pointer to data required by the application for its processing of the link. +!! \param return_value Return context: +!! \li Success: The return value of the first operator that +!! returns non-zero, or zero if all members were processed with no operator returning non-zero. +!! \li Failure: Negative if something goes wrong within the +!! library, or the negative value returned by one of the operators. +!! \param hdferr \fortran_error +!! SUBROUTINE h5literate_f(group_id, index_type, order, idx, op, op_data, return_value, hdferr) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR, C_FUNPTR IMPLICIT NONE @@ -1353,7 +947,6 @@ CONTAINS TYPE(C_PTR) , INTENT(IN) :: op_data INTEGER , INTENT(OUT) :: return_value INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5literate_c(group_id, index_type, order, idx, op, op_data) & BIND(C, NAME='h5literate_c') @@ -1379,48 +972,32 @@ CONTAINS END SUBROUTINE h5literate_f -!****s* H5L (F03)/h5literate_by_name_f -! -! NAME -! h5literate_by_name_f -! -! PURPOSE -! Iterates through links in a group. -! -! Inputs: -! loc_id - File or group identifier specifying location of subject group -! group_name - Name of subject group -! index_type - Type of index which determines the order: -! H5_INDEX_NAME_F - Alphanumeric index on name -! H5_INDEX_CRT_ORDER_F - Index on creation order -! order - Order within index: -! H5_ITER_INC_F - Increasing order -! H5_ITER_DEC_F - Decreasing order -! H5_ITER_NATIVE_F - Fastest available order -! idx - IN: Iteration position at which to start -! op - Callback function passing data regarding the link to the calling application -! op_data - User-defined pointer to data required by the application for its processing of the link -! -! Outputs: -! idx - OUT: Position at which an interrupted iteration may be restarted -! return_value - Success: The return value of the first operator that -! returns non-zero, or zero if all members were -! processed with no operator returning non-zero. -! -! Failure: Negative if something goes wrong within the -! library, or the negative value returned by one -! of the operators. -! -! hdferr - Returns 0 if successful and -1 if fails -! -! Optional parameters: -! lapl_id - Link access property list -! -! AUTHOR -! M. Scot Breitenfeld -! August 18, 2008 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5L +!! +!! \brief Iterates through links in a group. +!! +!! \param loc_id File or group identifier specifying location of subject group. +!! \param group_name Name of subject group. +!! \param index_type Type of index which determines the order: +!! \li H5_INDEX_NAME_F - Alphanumeric index on name +!! \li H5_INDEX_CRT_ORDER_F - Index on creation order +!! \param order Order within index: +!! \li H5_ITER_INC_F - Increasing order +!! \li H5_ITER_DEC_F - Decreasing order +!! \li H5_ITER_NATIVE_F - Fastest available order +!! \param idx Iteration position at which to start, or
+!! Position at which an interrupted iteration may be restarted +!! \param op Callback function passing data regarding the link to the calling application. +!! \param op_data User-defined pointer to data required by the application for its processing of the link. +!! \param return_value Return context: +!! \li Success: The return value of the first operator that returns non-zero, or zero if +!! all members were processed with no operator returning non-zero. +!! \li Failure: Negative if something goes wrong within the +!! library, or the negative value returned by one of the operators. +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list +!! SUBROUTINE h5literate_by_name_f(loc_id, group_name, index_type, order, & idx, op, op_data, return_value, hdferr, lapl_id) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR, C_FUNPTR @@ -1435,7 +1012,6 @@ CONTAINS INTEGER , INTENT(OUT) :: return_value INTEGER , INTENT(OUT) :: hdferr INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lapl_id -!***** INTEGER(HID_T) :: lapl_id_default INTEGER(SIZE_T) :: namelen diff --git a/fortran/src/H5Off.F90 b/fortran/src/H5Off.F90 index b5261d9..388e30e 100644 --- a/fortran/src/H5Off.F90 +++ b/fortran/src/H5Off.F90 @@ -1,14 +1,13 @@ -!****h* ROBODoc/H5O -! -! NAME -! MODULE H5O -! -! FILE -! fortran/src/H5Off.F90 -! -! PURPOSE -! This file contains Fortran interfaces for H5O functions. -! +!> @defgroup FH5O Fortran Object (H5O) Interface +!! +!! @see H5O, C-API +!! +!! @see @ref H5O_UG, User Guide +!! + +!> @ingroup FH5O +!! +!! @brief This module contains Fortran interfaces for H5O functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -36,7 +35,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** MODULE H5O @@ -44,127 +42,115 @@ MODULE H5O USE H5GLOBAL IMPLICIT NONE -!****t* H5O (F03)/h5o_info_t -! -! Fortran2003 Derived Type: -! +!> @brief h5o_info_t derived type. The time values are an integer array as specified in the Fortran intrinsic DATE_AND_TIME(VALUES). TYPE, BIND(C) :: h5o_info_t - INTEGER(C_LONG) :: fileno ! File number that object is located in - TYPE(H5O_TOKEN_T_F) :: token ! Token for object in file - INTEGER(C_INT) :: type ! Basic object type (group, dataset, etc.) - INTEGER :: rc ! Reference count of object - - INTEGER, DIMENSION(8) :: atime ! Access time ! -- NOTE -- - INTEGER, DIMENSION(8) :: mtime ! Modification time ! Returns an integer array - INTEGER, DIMENSION(8) :: ctime ! Change time ! as specified in the Fortran - INTEGER, DIMENSION(8) :: btime ! Birth time ! intrinsic DATE_AND_TIME(VALUES) - - INTEGER(hsize_t) :: num_attrs ! # of attributes attached to object + INTEGER(C_LONG) :: fileno !< File number that object is located in + TYPE(H5O_TOKEN_T_F) :: token !< Token for object in file + INTEGER(C_INT) :: type !< Basic object type (group, dataset, etc.) + INTEGER :: rc !< Reference count of object + ! -- NOTE -- + ! Returns an integer array + ! as specified in the Fortran + ! intrinsic DATE_AND_TIME(VALUES) + INTEGER, DIMENSION(8) :: atime !< Access time + INTEGER, DIMENSION(8) :: mtime !< Modification time + INTEGER, DIMENSION(8) :: ctime !< Change time + INTEGER, DIMENSION(8) :: btime !< Birth time + + INTEGER(hsize_t) :: num_attrs !< Number of attributes attached to object END TYPE h5o_info_t -! C interoperable structure for h5o_info_t. The Fortran derived type returns the time -! values as an integer array as specified in the Fortran intrinsic DATE_AND_TIME(VALUES). -! Whereas, this derived type does not. +!> @brief C interoperable structure for h5o_info_t. The Fortran derived type returns the time +!! values as an integer array as specified in the Fortran intrinsic DATE_AND_TIME(VALUES). +!! Whereas, this derived type does not. TYPE, BIND(C) :: c_h5o_info_t - INTEGER(C_LONG) :: fileno ! File number that object is located in - TYPE(H5O_TOKEN_T_F) :: token ! Token for object in file - INTEGER(C_INT) :: type ! Basic object type (group, dataset, etc.) - INTEGER(C_INT) :: rc ! Reference count of object + INTEGER(C_LONG) :: fileno !< File number that object is located in + TYPE(H5O_TOKEN_T_F) :: token !< Token for object in file + INTEGER(C_INT) :: type !< Basic object type (group, dataset, etc.) + INTEGER(C_INT) :: rc !< Reference count of object - INTEGER(KIND=TIME_T) :: atime ! Access time - INTEGER(KIND=TIME_T) :: mtime ! Modify time - INTEGER(KIND=TIME_T) :: ctime ! Create time - INTEGER(KIND=TIME_T) :: btime ! Birth time + INTEGER(KIND=TIME_T) :: atime !< Access time + INTEGER(KIND=TIME_T) :: mtime !< Modify time + INTEGER(KIND=TIME_T) :: ctime !< Create time + INTEGER(KIND=TIME_T) :: btime !< Birth time - INTEGER(hsize_t) :: num_attrs ! # of attributes attached to object + INTEGER(hsize_t) :: num_attrs !< Number of attributes attached to object END TYPE c_h5o_info_t -!****t* H5O (F03)/h5o_native_info_t -! -! Fortran2003 Derived Type: -! +!> @brief space_t derived type TYPE, BIND(C) :: space_t - INTEGER(hsize_t) :: total ! Total space for storing object header in file - INTEGER(hsize_t) :: meta ! Space within header for object header metadata information - INTEGER(hsize_t) :: mesg ! Space within header for actual message information - INTEGER(hsize_t) :: free ! Free space within object header + INTEGER(hsize_t) :: total !< Total space for storing object header in file + INTEGER(hsize_t) :: meta !< Space within header for object header metadata information + INTEGER(hsize_t) :: mesg !< Space within header for actual message information + INTEGER(hsize_t) :: free !< Free space within object header END TYPE space_t +!> @brief mesg_t derived type TYPE, BIND(C) :: mesg_t - INTEGER(c_int64_t) :: present ! Flags to indicate presence of message type in header - INTEGER(c_int64_t) :: shared ! Flags to indicate message type is shared in header + INTEGER(c_int64_t) :: present !< Flags to indicate presence of message type in header + INTEGER(c_int64_t) :: shared !< Flags to indicate message type is shared in header END TYPE mesg_t +!> @brief hdr_t derived type TYPE, BIND(C) :: hdr_t - INTEGER :: version ! Version number of header format in file - INTEGER :: nmesgs ! Number of object header messages - INTEGER :: nchunks ! Number of object header chunks - INTEGER :: flags ! Object header status flags + INTEGER :: version !< Version number of header format in file + INTEGER :: nmesgs !< Number of object header messages + INTEGER :: nchunks !< Number of object header chunks + INTEGER :: flags !< Object header status flags TYPE(space_t) :: space TYPE(mesg_t) :: mesg END TYPE hdr_t +!> @brief c_hdr_t derived type TYPE, BIND(C) :: c_hdr_t - INTEGER(C_INT) :: version ! Version number of header format in file - INTEGER(C_INT) :: nmesgs ! Number of object header messages - INTEGER(C_INT) :: nchunks ! Number of object header chunks - INTEGER(C_INT) :: flags ! Object header status flags + INTEGER(C_INT) :: version !< Version number of header format in file + INTEGER(C_INT) :: nmesgs !< Number of object header messages + INTEGER(C_INT) :: nchunks !< Number of object header chunks + INTEGER(C_INT) :: flags !< Object header status flags TYPE(space_t) :: space TYPE(mesg_t) :: mesg END TYPE c_hdr_t - ! Extra metadata storage for obj & attributes +!> @brief Extra metadata storage for obj & attributes TYPE, BIND(C) :: H5_ih_info_t - INTEGER(hsize_t) :: index_size ! btree and/or list - INTEGER(hsize_t) :: heap_size + INTEGER(hsize_t) :: index_size !< btree and/or list + INTEGER(hsize_t) :: heap_size !< heap END TYPE H5_ih_info_t +!> @brief meta_size_t derived type TYPE, BIND(C) :: meta_size_t - TYPE(H5_ih_info_t) :: obj ! v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets - TYPE(H5_ih_info_t) :: attr ! v2 B-tree & heap for attributes + TYPE(H5_ih_info_t) :: obj !< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets + TYPE(H5_ih_info_t) :: attr !< v2 B-tree & heap for attributes ENDTYPE meta_size_t +!> @brief h5o_native_info_t derived type TYPE, BIND(C) :: h5o_native_info_t TYPE(hdr_t) :: hdr TYPE(meta_size_t) :: meta_size END TYPE h5o_native_info_t -! C interoperable structure for h5o_native_info_t. +! @brief C interoperable structure for h5o_native_info_t. TYPE, BIND(C) :: c_h5o_native_info_t TYPE(c_hdr_t) :: hdr TYPE(meta_size_t) :: meta_size END TYPE c_h5o_native_info_t -!***** CONTAINS -!****s* H5O/h5olink_f -! -! NAME -! h5olink_f -! -! PURPOSE -! Creates a hard link to an object in an HDF5 file. -! -! Inputs: -! object_id - Object to be linked. -! new_loc_id - File or group identifier specifying location at which object is to be linked. -! new_link_name - Name of link to be created, relative to new_loc_id. -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails. -! -! Optional parameters: -! lcpl_id - Link creation property list identifier. -! lapl_id - Link access property list identifier. -! -! AUTHOR -! M. Scot Breitenfeld -! April 21, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Creates a hard link to an object in an HDF5 file. +!! +!! \param object_id Object to be linked. +!! \param new_loc_id File or group identifier specifying location at which object is to be linked. +!! \param new_link_name Name of link to be created, relative to new_loc_id. +!! \param hdferr \fortran_error +!! \param lcpl_id Link creation property list identifier. +!! \param lapl_id Link access property list identifier. +!! SUBROUTINE h5olink_f(object_id, new_loc_id, new_link_name, hdferr, lcpl_id, lapl_id) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: object_id @@ -173,7 +159,6 @@ CONTAINS INTEGER , INTENT(OUT) :: hdferr INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lcpl_id INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lapl_id -!***** INTEGER(HID_T) :: lapl_id_default INTEGER(HID_T) :: lcpl_id_default @@ -206,30 +191,17 @@ CONTAINS END SUBROUTINE h5olink_f -!****s* H5O/h5oopen_f -! -! NAME -! h5oopen_f -! -! PURPOSE -! Opens an object in an HDF5 file by location identifier and path name. -! -! Inputs: -! loc_id - File or group identifier. -! name - Path to the object, relative to loc_id. -! -! Outputs: -! obj_id - Object identifier for the opened object. -! hdferr - Returns 0 if successful and -1 if fails. -! -! Optional parameters: -! lapl_id - Access property list identifier for the link pointing to the object. -! -! AUTHOR -! M. Scot Breitenfeld -! April 18, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Opens an object in an HDF5 file by location identifier and path name. +!! +!! \param loc_id File or group identifier. +!! \param name Path to the object, relative to loc_id. +!! \param obj_id Object identifier for the opened object. +!! \param hdferr \fortran_error +!! \param lapl_id Access property list identifier for the link pointing to the object. +!! SUBROUTINE h5oopen_f(loc_id, name, obj_id, hdferr, lapl_id) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: loc_id @@ -237,7 +209,6 @@ CONTAINS INTEGER(HID_T) , INTENT(OUT) :: obj_id INTEGER , INTENT(OUT) :: hdferr INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lapl_id -!***** INTEGER(HID_T) :: lapl_id_default INTEGER(SIZE_T) :: namelen @@ -262,31 +233,18 @@ CONTAINS hdferr = h5oopen_c(loc_id, name, namelen, lapl_id_default, obj_id) END SUBROUTINE h5oopen_f -! -!****s* H5O/h5oclose_f -! -! NAME -! h5oclose_f -! -! PURPOSE -! Closes an object in an HDF5 file. -! -! Inputs: -! object_id - Object identifier. -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! December 17, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Closes an object in an HDF5 file. +!! +!! \param object_id Object identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5oclose_f(object_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: object_id INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5oclose_c(object_id) BIND(C,NAME='h5oclose_c') IMPORT :: HID_T @@ -298,34 +256,22 @@ CONTAINS hdferr = h5oclose_c(object_id) END SUBROUTINE h5oclose_f -! -!****s* H5O/h5oopen_by_token_f -! NAME -! h5oopen_by_token_f -! -! PURPOSE -! Opens an object using its token within an HDF5 file. -! -! Inputs: -! loc_id - File or group identifier. -! token - Object’s token in the file. -! -! Outputs: -! obj_id - Object identifier for the opened object. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! September 14, 2009 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Opens an object using its token within an HDF5 file. +!! +!! \param loc_id File or group identifier. +!! \param token Object’s token in the file. +!! \param obj_id Object identifier for the opened object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5oopen_by_token_f(loc_id, token, obj_id, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: loc_id TYPE(H5O_TOKEN_T_F), INTENT(IN) :: token INTEGER(HID_T) , INTENT(OUT) :: obj_id INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5oopen_by_token_c(loc_id, token, obj_id) BIND(C,NAME='h5oopen_by_token_c') IMPORT :: HID_T, H5O_TOKEN_T_F @@ -339,32 +285,20 @@ CONTAINS hdferr = h5oopen_by_token_c(loc_id, token, obj_id) END SUBROUTINE h5oopen_by_token_f -! -!****s* H5O/h5ocopy_f -! NAME -! h5ocopy_f -! -! PURPOSE -! Copies an object in an HDF5 file. -! -! Inputs: -! src_loc_id - Object identifier indicating the location of the source object to be copied. -! src_name - Name of the source object to be copied. -! dst_loc_id - Location identifier specifying the destination. -! dst_name - Name to be assigned to the new copy. -! -! Optional parameters: -! ocpypl_id - Object copy property list. -! lcpl_id - Link creation property list for the new hard link. -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! March 14, 2012 -! -! Fortran90 Interface: + +!> +!! \ingroup FH5O +!! +!! \brief Copies an object in an HDF5 file. +!! +!! \param src_loc_id Object identifier indicating the location of the source object to be copied. +!! \param src_name Name of the source object to be copied. +!! \param dst_loc_id Location identifier specifying the destination. +!! \param dst_name Name to be assigned to the new copy. +!! \param ocpypl_id Object copy property list. +!! \param lcpl_id Link creation property list for the new hard link. +!! \param hdferr \fortran_error +!! SUBROUTINE h5ocopy_f(src_loc_id, src_name, dst_loc_id, dst_name, hdferr, ocpypl_id, lcpl_id) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: src_loc_id @@ -374,7 +308,6 @@ CONTAINS INTEGER , INTENT(OUT) :: hdferr INTEGER(HID_T) , INTENT(IN), OPTIONAL :: ocpypl_id INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lcpl_id -!***** INTEGER(SIZE_T) :: src_name_len, dst_name_len INTEGER(HID_T) :: ocpypl_id_default, lcpl_id_default @@ -410,29 +343,18 @@ CONTAINS END SUBROUTINE h5ocopy_f -!****s* H5O/h5odecr_refcount_f -! NAME -! h5odecr_refcount_f -! -! PURPOSE -! Decrements an object reference count. -! -! Inputs: -! object_id - Object identifier. -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! May 11, 2012 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Decrements an object reference count. +!! +!! \param object_id Object identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5odecr_refcount_f(object_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: object_id INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5odecr_refcount_c(object_id) BIND(C,NAME='h5odecr_refcount_c') @@ -446,30 +368,19 @@ CONTAINS END SUBROUTINE h5odecr_refcount_f -!****s* H5O/h5oexists_by_name_f -! NAME -! h5oexists_by_name_f -! -! PURPOSE -! Determines whether a link resolves to an actual object. -! -! Inputs: -! loc_id - Identifier of the file or group to query. -! name - The name of the link to check. -! -! -! Optional parameters: -! lapl_id - Link access property list identifier. -! -! Outputs: -! link_exists - Existing link resolves to an object. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! May 11, 2012 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Determines whether a link resolves to an actual object. +!! +!! \param loc_id IdeIdentifier of the file or group to query. +!! \param name TheThe name of the link to check. +!! +!! +!! \param lapl_id Link access property list identifier. +!! \param link_exists Existing link resolves to an object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5oexists_by_name_f(loc_id, name, link_exists, hdferr, lapl_id) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: loc_id @@ -477,7 +388,6 @@ CONTAINS LOGICAL , INTENT(OUT) :: link_exists INTEGER , INTENT(OUT) :: hdferr INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lapl_id -!***** INTEGER(size_t) :: namelen INTEGER :: status @@ -516,35 +426,22 @@ CONTAINS END SUBROUTINE h5oexists_by_name_f -!****s* H5O/h5oget_comment_f -! NAME -! h5oget_comment_f -! -! PURPOSE -! Retrieves comment for specified object. -! -! Inputs: -! obj_id - Identifier for the target object. -! -! Optional parameters: -! bufsize - Size of the comment buffer. -! -! Outputs: -! comment - The comment. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! May 11, 2012 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Retrieves comment for specified object. +!! +!! \param obj_id Identifier for the target object. +!! \param bufsize Size of the comment buffer. +!! \param comment The comment. +!! \param hdferr \fortran_error +!! SUBROUTINE h5oget_comment_f(obj_id, comment, hdferr, bufsize) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: obj_id CHARACTER(LEN=*) , INTENT(OUT) :: comment INTEGER , INTENT(OUT) :: hdferr INTEGER(HSSIZE_T), INTENT(OUT), OPTIONAL :: bufsize -!***** INTEGER(SIZE_T) :: commentsize_default INTEGER(HSSIZE_T) :: bufsize_default @@ -570,30 +467,18 @@ CONTAINS END SUBROUTINE h5oget_comment_f -!****s* H5O/h5oget_comment_by_name_f -! NAME -! h5oget_comment_by_name_f -! -! PURPOSE -! Retrieves comment for specified object. -! -! Inputs: -! loc_id - Identifier of a file, group, dataset, or named datatype. -! name - Name of the object whose comment is to be retrieved, -! specified as a path relative to loc_id. -! -! Optional parameters: -! bufsize - Size of the comment buffer. -! -! Outputs: -! comment - The comment. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! July 6, 2012 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Retrieves comment for specified object. +!! +!! \param loc_id Identifier of a file, group, dataset, or named datatype. +!! \param name Name of the object whose comment is to be retrieved, specified as a path relative to loc_id. +!! \param comment The comment. +!! \param hdferr \fortran_error +!! \param bufsize Size of the comment buffer. +!! \param lapl_id File access property list identifier. +!! SUBROUTINE h5oget_comment_by_name_f(loc_id, name, comment, hdferr, bufsize, lapl_id) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: loc_id @@ -602,7 +487,6 @@ CONTAINS INTEGER , INTENT(OUT) :: hdferr INTEGER(SIZE_T) , INTENT(OUT), OPTIONAL :: bufsize INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: lapl_id -!***** INTEGER(SIZE_T) :: commentsize_default INTEGER(SIZE_T) :: name_size @@ -637,29 +521,18 @@ CONTAINS END SUBROUTINE h5oget_comment_by_name_f -!****s* H5O/h5oincr_refcount_f -! NAME -! h5oincr_refcount_f -! -! PURPOSE -! Increments an object reference count. -! -! Inputs: -! obj_id - Object identifier. -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! May 15, 2012 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Increments an object reference count. +!! +!! \param obj_id Object identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5oincr_refcount_f(obj_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: obj_id INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5oincr_refcount_c(obj_id) BIND(C,NAME='h5oincr_refcount_c') @@ -673,33 +546,21 @@ CONTAINS END SUBROUTINE h5oincr_refcount_f -!****s* H5O/h5oopen_by_idx_f -! -! NAME -! h5oopen_by_idx_f -! -! PURPOSE -! Open the nth object in a group. -! -! Inputs: -! loc_id - A file or group identifier. -! group_name - Name of group, relative to loc_id, in which object is located. -! index_type - Type of index by which objects are ordered. -! order - Order of iteration within index, NOTE: zero-based. -! n - Object to open. -! -! Outputs: -! obj_id - An object identifier for the opened object. -! hdferr - Returns 0 if successful and -1 if fails. -! -! Optional parameters: -! lapl_id - Link access property list. -! -! AUTHOR -! M. Scot Breitenfeld -! May 17, 2012 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Open the nth object in a group. +!! +!! \param loc_id A file or group identifier. +!! \param group_name Name of group, relative to loc_id, in which object is located. +!! \param index_type Type of index by which objects are ordered. +!! \param order Order of iteration within index, NOTE: zero-based. +!! \param n Object to open. +!! \param obj_id An object identifier for the opened object. +!! \param hdferr \fortran_error +!! +!! \param lapl_id Link access property list. +!! SUBROUTINE h5oopen_by_idx_f(loc_id, group_name, index_type, order, n, obj_id, & hdferr, lapl_id) IMPLICIT NONE @@ -711,7 +572,6 @@ CONTAINS INTEGER(HID_T) , INTENT(OUT) :: obj_id INTEGER , INTENT(OUT) :: hdferr INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: lapl_id -!***** INTEGER(SIZE_T) :: group_namelen INTEGER(HID_T) :: lapl_id_default @@ -742,31 +602,20 @@ CONTAINS END SUBROUTINE H5Oopen_by_idx_f -!****s* H5O/h5oset_comment_f -! NAME -! h5oset_comment_f -! -! PURPOSE -! Sets comment for specified object. -! -! Inputs: -! obj_id - Identifier of the target object. -! comment - The new comment. -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! May 15, 2012 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Sets comment for specified object. +!! +!! \param obj_id Identifier of the target object. +!! \param comment The new comment. +!! \param hdferr \fortran_error +!! SUBROUTINE h5oset_comment_f(obj_id, comment, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: obj_id CHARACTER(LEN=*), INTENT(IN) :: comment INTEGER , INTENT(OUT) :: hdferr -!***** INTEGER(SIZE_T) :: commentlen INTERFACE @@ -787,30 +636,17 @@ CONTAINS END SUBROUTINE h5oset_comment_f -!****s* H5O/h5oset_comment_by_name_f -! NAME -! h5oset_comment_by_name_f -! -! PURPOSE -! Sets comment for specified object. -! -! Inputs: -! loc_id - Identifier of a file, group, dataset, or named datatype. -! name - Name of the object whose comment is to be set or reset, -! specified as a path relative to loc_id. -! comment - The new comment. -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails. -! -! Optional parameters: -! lapl_id - Link access property list identifier. -! -! AUTHOR -! M. Scot Breitenfeld -! May 15, 2012 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Sets comment for specified object. +!! +!! \param loc_id Identifier of a file, group, dataset, or named datatype. +!! \param name Name of the object whose comment is to be set or reset, specified as a path relative to loc_id. +!! \param comment The new comment. +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list identifier. +!! SUBROUTINE h5oset_comment_by_name_f(loc_id, name, comment, hdferr, lapl_id) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: loc_id @@ -818,7 +654,6 @@ CONTAINS CHARACTER(LEN=*), INTENT(IN) :: comment INTEGER , INTENT(OUT) :: hdferr INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lapl_id -!***** INTEGER(SIZE_T) :: commentlen INTEGER(SIZE_T) :: namelen INTEGER(HID_T) :: lapl_id_default @@ -848,39 +683,26 @@ CONTAINS END SUBROUTINE h5oset_comment_by_name_f -!****s* H5O (F03)/h5ovisit_f_F03 -! -! NAME -! h5ovisit_f -! -! PURPOSE -! Recursively visits all objects starting from a specified object. -! -! Inputs: -! object_id - Identifier of the object at which the recursive iteration begins. -! index_type - Type of index; valid values include: -! H5_INDEX_NAME_F -! H5_INDEX_CRT_ORDER_F -! order - Order in which index is traversed; valid values include: -! H5_ITER_DEC_F -! H5_ITER_INC_F -! H5_ITER_NATIVE_F -! op - Callback function passing data regarding the group to the calling application -! op_data - User-defined pointer to data required by the application for its processing of the group -! -! Outputs: -! return_value - returns the return value of the first operator that returns a positive value, or -! zero if all members were processed with no operator returning non-zero. -! hdferr - Returns 0 if successful and -1 if fails -! -! Optional parameters: -! fields - Flags specifying the fields to include in object_info. -! -! AUTHOR -! M. Scot Breitenfeld -! November 19, 2008 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Recursively visits all objects starting from a specified object. +!! +!! \param object_id Identifier of the object at which the recursive iteration begins. +!! \param index_type Type of index; valid values include: +!! \li H5_INDEX_NAME_F +!! \li H5_INDEX_CRT_ORDER_F +!! \param order Order in which index is traversed; valid values include: +!! \li H5_ITER_DEC_F +!! \li H5_ITER_INC_F +!! \li H5_ITER_NATIVE_F +!! \param op Callback function passing data regarding the group to the calling application. +!! \param op_data User-defined pointer to data required by the application for its processing of the group. +!! \param return_value Returns the return value of the first operator that returns a positive value, or +!! zero if all members were processed with no operator returning non-zero. +!! \param hdferr \fortran_error +!! \param fields Flags specifying the fields to include in object_info. +!! SUBROUTINE h5ovisit_f(object_id, index_type, order, op, op_data, return_value, hdferr, fields) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: object_id @@ -892,7 +714,6 @@ CONTAINS INTEGER, INTENT(OUT) :: return_value INTEGER, INTENT(OUT) :: hdferr INTEGER, INTENT(IN), OPTIONAL :: fields -!***** INTEGER :: fields_c INTERFACE @@ -923,32 +744,18 @@ CONTAINS END SUBROUTINE h5ovisit_f -!****s* H5O (F03)/h5oget_info_by_name_f_F03 -! -! NAME -! h5oget_info_by_name_f -! -! PURPOSE -! Retrieves the metadata for an object, identifying the object by location and relative name. -! -! Inputs: -! loc_id - File or group identifier specifying location of group -! in which object is located. -! name - Name of group, relative to loc_id. -! -! Outputs: -! object_info - Buffer in which to return object information. -! hdferr - Returns 0 if successful and -1 if fails. -! -! Optional parameters: -! lapl_id - Link access property list. -! fields - Flags specifying the fields to include in object_info. -! -! AUTHOR -! M. Scot Breitenfeld -! December 1, 2008 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Retrieves the metadata for an object, identifying the object by location and relative name. +!! +!! \param loc_id File or group identifier specifying location of group in which object is located. +!! \param name Name of group, relative to loc_id. +!! \param object_info Buffer in which to return object information. +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list. +!! \param fields Flags specifying the fields to include in object_info. +!! SUBROUTINE h5oget_info_by_name_f(loc_id, name, object_info, hdferr, lapl_id, fields) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: loc_id @@ -957,7 +764,7 @@ CONTAINS INTEGER , INTENT(OUT) :: hdferr INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: lapl_id INTEGER , INTENT(IN) , OPTIONAL :: fields -!***** + INTEGER(SIZE_T) :: namelen INTEGER(HID_T) :: lapl_id_default TYPE(C_PTR) :: ptr @@ -992,29 +799,16 @@ CONTAINS END SUBROUTINE H5Oget_info_by_name_f -!****s* H5O (F03)/h5oget_info_f_F03 -! -! NAME -! h5oget_info_f -! -! PURPOSE -! Retrieves the metadata for an object specified by an identifier. -! -! Inputs: -! object_id - Identifier for target object. -! -! Outputs: -! object_info - Buffer in which to return object information. -! hdferr - Returns 0 if successful and -1 if fails. -! -! Optional parameters: -! fields - Flags specifying the fields to include in object_info. -! -! AUTHOR -! M. Scot Breitenfeld -! May 11, 2012 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Retrieves the metadata for an object specified by an identifier. +!! +!! \param object_id Identifier for target object. +!! \param object_info Buffer in which to return object information. +!! \param hdferr \fortran_error +!! \param fields Flags specifying the fields to include in object_info. +!! SUBROUTINE h5oget_info_f(object_id, object_info, hdferr, fields) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR @@ -1023,7 +817,6 @@ CONTAINS TYPE(h5o_info_t), INTENT(OUT), TARGET :: object_info INTEGER , INTENT(OUT) :: hdferr INTEGER , INTENT(IN), OPTIONAL :: fields -!***** TYPE(C_PTR) :: ptr INTEGER :: fields_c @@ -1047,35 +840,23 @@ CONTAINS END SUBROUTINE H5Oget_info_f -!****s* H5O (F03)/h5oget_info_by_idx_f_F03 -! -! NAME -! h5oget_info_by_idx_f -! -! PURPOSE -! Retrieves the metadata for an object, identifying the object by an index position. -! -! Inputs: -! loc_id - File or group identifier specifying location of group -! in which object is located. -! group_name - Name of group in which object is located. -! index_field - Index or field that determines the order. -! order - Order within field or index. -! n - Object for which information is to be returned -! -! Outputs: -! object_info - Buffer in which to return object information. -! hdferr - Returns 0 if successful and -1 if fails. -! -! Optional parameters: -! lapl_id - Link access property list. (Not currently used.) -! fields - Flags specifying the fields to include in object_info. -! -! AUTHOR -! M. Scot Breitenfeld -! May 11, 2012 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Retrieves the metadata for an object, identifying the object by an index position. +!! +!! \param loc_id File or group identifier specifying location of group in which object is located. +!! \param group_name Name of group in which object is located. +!! \param index_field Index or field that determines the order. +!! \param order Order within field or index. +!! \param n Object for which information is to be returned. +!! \param object_info Buffer in which to return object information. +!! \param hdferr \fortran_error +!! +!! \param lapl_id Link access property list. (Not currently used.). +!! \param fields Flags specifying the fields to include in object_info. +!! +!! Fortran2003 Interface: SUBROUTINE h5oget_info_by_idx_f(loc_id, group_name, index_field, order, n, & object_info, hdferr, lapl_id, fields) @@ -1090,7 +871,6 @@ CONTAINS INTEGER , INTENT(OUT) :: hdferr INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: lapl_id INTEGER , INTENT(IN) , OPTIONAL :: fields -!***** INTEGER(SIZE_T) :: namelen INTEGER(HID_T) :: lapl_id_default TYPE(C_PTR) :: ptr @@ -1127,41 +907,28 @@ CONTAINS END SUBROUTINE H5Oget_info_by_idx_f -!****s* H5O (F03)/h5ovisit_by_name_f_F03 -! -! NAME -! h5ovisit_by_name_f -! -! PURPOSE -! Recursively visits all objects starting from a specified object. -! -! Inputs: -! loc_id - Identifier of a file or group. -! object_name - Name of the object, generally relative to loc_id, that will serve as root of the iteration -! index_type - Type of index; valid values include: -! H5_INDEX_NAME_F -! H5_INDEX_CRT_ORDER_F -! order - Order in which index is traversed; valid values include: -! H5_ITER_DEC_F -! H5_ITER_INC_F -! H5_ITER_NATIVE_F -! op - Callback function passing data regarding the group to the calling application -! op_data - User-defined pointer to data required by the application for its processing of the group -! -! Outputs: -! return_value - Returns the return value of the first operator that returns a positive value, or -! zero if all members were processed with no operator returning non-zero. -! hdferr - Returns 0 if successful and -1 if fails -! -! Optional parameters: -! lapl_id - Link access property list identifier. -! fields - Flags specifying the fields to include in object_info. -! -! AUTHOR -! M. Scot Breitenfeld -! November 19, 2008 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Recursively visits all objects starting from a specified object. +!! +!! \param loc_id Identifier of a file or group. +!! \param object_name Name of the object, generally relative to loc_id, that will serve as root of the iteration. +!! \param index_type Type of index; valid values include: +!! \li H5_INDEX_NAME_F +!! \li H5_INDEX_CRT_ORDER_F +!! \param order Order in which index is traversed; valid values include: +!! \li H5_ITER_DEC_F +!! \li H5_ITER_INC_F +!! \li H5_ITER_NATIVE_F +!! \param op Callback function passing data regarding the group to the calling application. +!! \param op_data User-defined pointer to data required by the application for its processing of the group. +!! \param return_value Returns the return value of the first operator that returns a positive value, or +!! zero if all members were processed with no operator returning non-zero. +!! \param hdferr \fortran_error +!! \param lapl_id Link access property list identifier. +!! \param fields Flags specifying the fields to include in object_info. +!! SUBROUTINE h5ovisit_by_name_f(loc_id, object_name, index_type, order, op, op_data, & return_value, hdferr, lapl_id, fields) IMPLICIT NONE @@ -1176,7 +943,6 @@ CONTAINS INTEGER , INTENT(OUT) :: hdferr INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: lapl_id INTEGER , INTENT(IN) , OPTIONAL :: fields -!***** INTEGER(SIZE_T) :: namelen INTEGER(HID_T) :: lapl_id_default @@ -1219,42 +985,31 @@ CONTAINS END SUBROUTINE h5ovisit_by_name_f -!****s* H5O/h5otoken_cmp_f -! NAME -! h5otoken_cmp_f -! -! PURPOSE -! Compare two tokens, which must be from the same file / containers. -! -! Inputs: -! loc_id - Identifier of an object in the file / container. -! token1 - The first token to compare. -! token2 - The second token to compare. -! -! Outputs: -! cmp_value - Returns 0 if tokens are equal, non-zero for unequal tokens. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! Quincey Koziol -! January 10, 2019 -! -! Fortran90 Interface: +!> +!! \ingroup FH5O +!! +!! \brief Compare two tokens, which must be from the same file / containers. +!! +!! \param loc_id Identifier of an object in the file / container. +!! \param token1 The first token to compare. +!! \param token2 The second token to compare. +!! \param cmp_value Returns 0 if tokens are equal, non-zero for unequal tokens. +!! \param hdferr \fortran_error +!! SUBROUTINE h5otoken_cmp_f(loc_id, token1, token2, cmp_value, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: loc_id - TYPE(H5O_TOKEN_T_F), INTENT(IN) :: token1 ! First token - TYPE(H5O_TOKEN_T_F), INTENT(IN) :: token2 ! First token + TYPE(H5O_TOKEN_T_F), INTENT(IN) :: token1 + TYPE(H5O_TOKEN_T_F), INTENT(IN) :: token2 INTEGER , INTENT(OUT) :: cmp_value INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5otoken_cmp_c(loc_id, token1, token2, cmp_value) BIND(C,NAME='h5otoken_cmp_c') IMPORT :: HID_T, C_PTR, H5O_TOKEN_T_F IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: loc_id - TYPE(H5O_TOKEN_T_F), INTENT(IN) :: token1 ! First token - TYPE(H5O_TOKEN_T_F), INTENT(IN) :: token2 ! First token + TYPE(H5O_TOKEN_T_F), INTENT(IN) :: token1 + TYPE(H5O_TOKEN_T_F), INTENT(IN) :: token2 INTEGER, INTENT(OUT) :: cmp_value END FUNCTION h5otoken_cmp_c diff --git a/fortran/src/H5Pff.F90 b/fortran/src/H5Pff.F90 index 96080ce..e55dc58 100644 --- a/fortran/src/H5Pff.F90 +++ b/fortran/src/H5Pff.F90 @@ -1,10 +1,13 @@ -!****h* ROBODoc/H5Pff -! -! NAME -! H5P -! -! PURPOSE -! This file contains Fortran interfaces for H5P functions. +!> @defgroup FH5P Fortran Property List (H5P) Interface +!! +!! @see H5P, C-API +!! +!! @see @ref H5P_UG, User Guide +!! + +!> @ingroup FH5P +!! +!! @brief This module contains Fortran interfaces for H5P functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -32,7 +35,6 @@ ! If you add a new H5P function you must add the function name to the ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. -!***** #include @@ -50,6 +52,8 @@ MODULE H5P PRIVATE h5pregister_integer, h5pregister_ptr PRIVATE h5pinsert_integer, h5pinsert_char, h5pinsert_ptr +#ifndef H5_DOXYGEN_FORTRAN + INTERFACE h5pset_fapl_multi_f MODULE PROCEDURE h5pset_fapl_multi_l MODULE PROCEDURE h5pset_fapl_multi_s @@ -176,58 +180,40 @@ MODULE H5P END FUNCTION h5pinsert_c END INTERFACE +#endif + CONTAINS -!****s* H5P/h5pcreate_f -! NAME -! h5pcreate_f -! -! PURPOSE -! Creates a new property as an instance of a property -! list class. -! -! INPUTS -! class - type of the property class to be created. -! Possible values are: -! H5P_OBJECT_CREATE_F -! H5P_FILE_CREATE_F -! H5P_FILE_ACCESS_F -! H5P_DATASET_CREATE_F -! H5P_DATASET_ACCESS_F -! H5P_DATASET_XFER_F -! H5P_FILE_MOUNT_F -! H5P_GROUP_CREATE_F -! H5P_GROUP_ACCESS_F -! H5P_DATATYPE_CREATE_F -! H5P_DATATYPE_ACCESS_F -! H5P_STRING_CREATE_F -! H5P_ATTRIBUTE_CREATE _F -! H5P_OBJECT_COPY_F -! H5P_LINK_CREATE_F -! H5P_LINK_ACCESS_F -! -! OUTPUTS -! prp_id - property list identifier -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Creates a new property as an instance of a property list class. +!! +!! \param class Type of the property class to be created. Possible values are: +!! \li H5P_OBJECT_CREATE_F +!! \li H5P_FILE_CREATE_F +!! \li H5P_FILE_ACCESS_F +!! \li H5P_DATASET_CREATE_F +!! \li H5P_DATASET_ACCESS_F +!! \li H5P_DATASET_XFER_F +!! \li H5P_FILE_MOUNT_F +!! \li H5P_GROUP_CREATE_F +!! \li H5P_GROUP_ACCESS_F +!! \li H5P_DATATYPE_CREATE_F +!! \li H5P_DATATYPE_ACCESS_F +!! \li H5P_STRING_CREATE_F +!! \li H5P_ATTRIBUTE_CREATE _F +!! \li H5P_OBJECT_COPY_F +!! \li H5P_LINK_CREATE_F +!! \li H5P_LINK_ACCESS_F +!! \param prp_id Property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pcreate_f(class, prp_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: class INTEGER(HID_T), INTENT(OUT) :: prp_id INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5pcreate_c(class, prp_id) & BIND(C,NAME='h5pcreate_c') @@ -241,47 +227,21 @@ CONTAINS hdferr = h5pcreate_c(class, prp_id) END SUBROUTINE h5pcreate_f -!****s* H5P/h5pset_preserve_f -! NAME -! h5pset_preserve_f -! -! PURPOSE -! Sets the dataset transfer property list status to -! TRUE or FALSE for initializing compound datatype -! members during write/read operations. -! -! INPUTS -! prp_id - property list identifier -! flag - status flag -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! OPTIONAL PARAMETERS -! NONE -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Datatype of the flag parameter is changed from -! INTEGER to LOGICAL June 4, 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the dataset transfer property list status to TRUE or FALSE for initializing +!! compound datatype members during write/read operations. +!! +!! \param prp_id Property list identifier. +!! \param flag Status flag. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_preserve_f(prp_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - LOGICAL, INTENT(IN) :: flag ! TRUE/FALSE flag to set the dataset - ! transfer property for partila writing/reading - ! compound datatype - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + LOGICAL, INTENT(IN) :: flag + INTEGER, INTENT(OUT) :: hdferr INTEGER :: flag_c INTERFACE @@ -298,44 +258,20 @@ CONTAINS hdferr = h5pset_preserve_c(prp_id, flag_c) END SUBROUTINE h5pset_preserve_f -!****s* H5P/h5pget_preserve_f -! NAME -! h5pget_preserve_f -! -! PURPOSE -! Checks status of the dataset transfer property list. -! -! INPUTS -! prp_id - property list identifier -! -! OUTPUTS -! flag - status flag -! hdferr - error code -! Success: 0 -! Failure: -1 -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Datatype of the flag parameter is changed from -! INTEGER to LOGICAL -! June 4, 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Checks status of the dataset transfer property list. +!! +!! \param prp_id Property list identifier. +!! \param flag Status flag. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_preserve_f(prp_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - LOGICAL, INTENT(OUT) :: flag ! TRUE/FALSE flag. Shows status of the dataset's - ! transfer property for partial writing/reading - ! compound datatype - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + LOGICAL, INTENT(OUT) :: flag + INTEGER, INTENT(OUT) :: hdferr INTEGER :: flag_c INTERFACE @@ -353,40 +289,20 @@ CONTAINS IF(flag_c .EQ. 1) flag = .TRUE. END SUBROUTINE h5pget_preserve_f -!****s* H5P/h5pget_class_f -! NAME -! h5pget_class_f -! -! PURPOSE -! Returns the property list class for a property list. -! -! INPUTS -! prp_id - property list identifier -! -! OUTPUTS -! classtype - property list class -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns the property list class for a property list. +!! +!! \param prp_id Property list identifier. +!! \param classtype Property list class. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_class_f(prp_id, classtype, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HID_T), INTENT(OUT) :: classtype ! The type of the property list - ! to be created. - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(OUT) :: classtype + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_class_c(prp_id, classtype) & @@ -401,39 +317,20 @@ CONTAINS hdferr = h5pget_class_c(prp_id, classtype) END SUBROUTINE h5pget_class_f -!****s* H5P/h5pcopy_f -! NAME -! h5pcopy_f -! -! PURPOSE -! Copies an existing property list to create a new -! property list -! -! INPUTS -! prp_id - property list identifier -! OUTPUTS -! new_prp_id - new property list identifier -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Copies an existing property list to create a new property list +!! +!! \param prp_id Property list identifier. +!! \param new_prp_id New property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pcopy_f(prp_id, new_prp_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HID_T), INTENT(OUT) :: new_prp_id ! Identifier of property list - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(OUT) :: new_prp_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pcopy_c(prp_id, new_prp_id) & @@ -448,37 +345,18 @@ CONTAINS hdferr = h5pcopy_c(prp_id, new_prp_id) END SUBROUTINE h5pcopy_f -!****s* H5P/h5pclose_f -! NAME -! h5pclose_f -! -! PURPOSE -! Terminates access to a property list. -! -! INPUTS -! prp_id - identifier of the property list to -! terminate access to. -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Terminates access to a property list. +!! +!! \param prp_id Identifier of the property list to terminate access to. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pclose_f(prp_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pclose_c(prp_id) & BIND(C,NAME='h5pclose_c') @@ -491,43 +369,23 @@ CONTAINS hdferr = h5pclose_c(prp_id) END SUBROUTINE h5pclose_f -!****s* H5P/h5pset_chunk_f -! NAME -! h5pset_chunk_f -! -! PURPOSE -! Sets the size of the chunks used to store -! a chunked layout dataset. -! -! INPUTS -! prp_id - dataset creation property list identifier -! ndims - number of dimensions for each chunk -! dims - array with dimension sizes for each chunk -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the size of the chunks used to store +!! a chunked layout dataset. +!! +!! \param prp_id Dataset creation property list identifier. +!! \param ndims Number of dimensions for each chunk. +!! \param dims Array with dimension sizes for each chunk. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_chunk_f(prp_id, ndims, dims, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: ndims ! Number of chunk dimensions + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: ndims INTEGER(HSIZE_T), DIMENSION(ndims), INTENT(IN) :: dims - ! Array containing sizes of - ! chunk dimensions - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_chunk_c(prp_id, ndims, dims) & BIND(C,NAME='h5pset_chunk_c') @@ -542,45 +400,22 @@ CONTAINS hdferr = h5pset_chunk_c(prp_id, ndims, dims) END SUBROUTINE h5pset_chunk_f -!****s* H5P/h5pget_chunk_f -! NAME -! h5pget_chunk_f -! -! PURPOSE -! Retrieves the size of chunks for the raw data of a -! chunked layout dataset -! -! INPUTS -! prp_id - property list identifier -! ndims - size of dims array -! OUTPUTS -! dims - array with dimension sizes for each chunk -! hdferr - error code -! Success: number of chunk dimensions -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the size of chunks for the raw data of a chunked layout dataset +!! +!! \param prp_id Property list identifier. +!! \param ndims Size of dims array. +!! \param dims Array with dimension sizes for each chunk. +!! \param hdferr Returns number of chunk dimensions if successful and -1 if fails. +!! SUBROUTINE h5pget_chunk_f(prp_id, ndims, dims, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: ndims ! Number of chunk dimensions to - ! to return + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: ndims INTEGER(HSIZE_T), DIMENSION(ndims), INTENT(OUT) :: dims - ! Array containing sizes of - ! chunk dimensions - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! number of chunk dimensions on success, - ! -1 on failure -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_chunk_c(prp_id, ndims, dims) & @@ -596,39 +431,20 @@ CONTAINS hdferr = h5pget_chunk_c(prp_id, ndims, dims) END SUBROUTINE h5pget_chunk_f -!****s* H5P/h5pset_deflate_f -! NAME -! h5pset_deflate_f -! -! PURPOSE -! Sets compression method and compression level. -! -! INPUTS -! prp_id - property list identifier -! level - compression level -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets compression method and compression level. +!! +!! \param prp_id Property list identifier. +!! \param level Compression level. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_deflate_f(prp_id, level, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: level ! Compression level - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: level + INTEGER, INTENT(OUT) :: hdferr ! INTEGER, EXTERNAL :: h5pset_deflate_c ! MS FORTRAN needs explicit interface for C functions called here. @@ -646,51 +462,28 @@ CONTAINS END SUBROUTINE h5pset_deflate_f -!****s* H5P/h5pget_version_f -! NAME -! h5pget_version_f -! -! PURPOSE -! Retrieves the version information of various objects -! for a file creation property list -! -! INPUTS -! prp_id - file createion property list identifier -! OUTPUTS -! boot - super block version number -! freelist - global freelist version number -! stab - symbol table version number -! shhdr - shared object header version number -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the version information of various objects for a file creation property list. +!! +!! \param prp_id File createion property list identifier. +!! \param boot Super block version number. +!! \param freelist Global freelist version number. +!! \param stab Symbol table version number. +!! \param shhdr Shared object header version number. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_version_f(prp_id, boot, freelist, & stab, shhdr, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, DIMENSION(:), INTENT(OUT) :: boot ! Array to put boot - ! block version number - INTEGER, DIMENSION(:), INTENT(OUT) :: freelist ! Array to put global - ! Freelist version number + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, DIMENSION(:), INTENT(OUT) :: boot + INTEGER, DIMENSION(:), INTENT(OUT) :: freelist - INTEGER, DIMENSION(:), INTENT(OUT) :: stab ! Array to put symbol - ! table version number - INTEGER, DIMENSION(:), INTENT(OUT) :: shhdr ! Array to put shared - ! object header version number - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER, DIMENSION(:), INTENT(OUT) :: stab + INTEGER, DIMENSION(:), INTENT(OUT) :: shhdr + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_version_c(prp_id, boot, freelist, stab, shhdr) & @@ -708,39 +501,20 @@ CONTAINS hdferr = h5pget_version_c(prp_id, boot, freelist, stab, shhdr) END SUBROUTINE h5pget_version_f -!****s* H5P/h5pset_userblock_f -! NAME -! h5pset_userblock_f -! -! PURPOSE -! Sets user block size -! -! INPUTS -! prp_id - file creation property list to modify -! size - size of the user-block in bytes -! -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets user block size. +!! +!! \param prp_id File creation property list to modify. +!! \param size Size of the user-block in bytes. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_userblock_f (prp_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HSIZE_T), INTENT(IN) :: size ! Size of the user-block in bytes - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HSIZE_T), INTENT(IN) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_userblock_c(prp_id, size) & BIND(C,NAME='h5pset_userblock_c') @@ -754,41 +528,20 @@ CONTAINS hdferr = h5pset_userblock_c(prp_id, size) END SUBROUTINE h5pset_userblock_f -!****s* H5P/h5pget_userblock_f -! NAME -! h5pget_userblock_f -! -! PURPOSE -! Gets user block size. -! -! INPUTS -! -! prp_id - file creation property list identifier -! OUTPUTS -! -! block_size - size of the user block in bytes -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Gets user block size. +!! +!! \param prp_id File creation property list identifier. +!! \param block_size Size of the user block in bytes. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_userblock_f(prp_id, block_size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HSIZE_T), INTENT(OUT) :: block_size ! Size of the - ! user-block in bytes - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HSIZE_T), INTENT(OUT) :: block_size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_userblock_c(prp_id, block_size) & BIND(C,NAME='h5pget_userblock_c') @@ -801,44 +554,22 @@ CONTAINS hdferr = h5pget_userblock_c(prp_id, block_size) END SUBROUTINE h5pget_userblock_f -!****s* H5P/h5pset_sizes_f -! NAME -! h5pset_sizes_f -! -! PURPOSE -! Sets the byte size of the offsets and lengths used -! to address objects in an HDF5 file. -! -! INPUTS -! prp_id - file creation property list identifier -! sizeof_addr - size of an object offset in bytes -! sizeof_size - size of an object length in bytes -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the byte size of the offsets and lengths used to address objects in an HDF5 file. +!! +!! \param prp_id File creation property list identifier. +!! \param sizeof_addr Size of an object offset in bytes. +!! \param sizeof_size Size of an object length in bytes. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_sizes_f (prp_id, sizeof_addr, sizeof_size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(SIZE_T), INTENT(IN) :: sizeof_addr ! Size of an object - ! offset in bytes - INTEGER(SIZE_T), INTENT(IN) :: sizeof_size ! Size of an object - ! length in bytes - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(SIZE_T), INTENT(IN) :: sizeof_addr + INTEGER(SIZE_T), INTENT(IN) :: sizeof_size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_sizes_c(prp_id, sizeof_addr, sizeof_size) & BIND(C,NAME='h5pset_sizes_c') @@ -853,44 +584,22 @@ CONTAINS hdferr = h5pset_sizes_c(prp_id, sizeof_addr, sizeof_size) END SUBROUTINE h5pset_sizes_f -!****s* H5P/h5pget_sizes_f -! NAME -! h5pget_sizes_f -! -! PURPOSE -! Retrieves the size of the offsets and lengths used -! in an HDF5 file -! -! INPUTS -! prp_id - file creation property list identifier -! OUTPUTS -! -! sizeof_addr - size of an object offset in bytes -! sizeof_size - size of an object length in bytes -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the size of the offsets and lengths used in an HDF5 file +!! +!! \param prp_id File Creation property list identifier. +!! \param sizeof_addr Size of an object offset in bytes. +!! \param sizeof_size Size of an object length in bytes. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_sizes_f(prp_id, sizeof_addr, sizeof_size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(SIZE_T), INTENT(OUT) :: sizeof_addr ! Size of an object - ! offset in bytes - INTEGER(SIZE_T), INTENT(OUT) :: sizeof_size ! Size of an object - ! length in bytes - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(SIZE_T), INTENT(OUT) :: sizeof_addr + INTEGER(SIZE_T), INTENT(OUT) :: sizeof_size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_sizes_c(prp_id, sizeof_addr, sizeof_size) & BIND(C,NAME='h5pget_sizes_c') @@ -905,43 +614,22 @@ CONTAINS hdferr = h5pget_sizes_c(prp_id, sizeof_addr, sizeof_size) END SUBROUTINE h5pget_sizes_f -!****s* H5P/h5pset_sym_k_f -! NAME -! h5pset_sym_k_f -! -! PURPOSE -! Sets the size of parameters used to control the -!symbol table nodes -! -! INPUTS -! -! prp_id - file creation property list identifier -! ik - symbol table tree rank -! lk - symbol table node size -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the size of parameters used to control the symbol table nodes. +!! +!! \param prp_id File creation property list identifier. +!! \param ik Symbol table tree rank. +!! \param lk Symbol table node size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_sym_k_f (prp_id, ik, lk, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: ik ! Symbol table tree rank - INTEGER, INTENT(IN) :: lk ! Symbol table node size - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: ik + INTEGER, INTENT(IN) :: lk + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_sym_k_c(prp_id, ik, lk) & BIND(C,NAME='h5pset_sym_k_c') @@ -955,43 +643,22 @@ CONTAINS hdferr = h5pset_sym_k_c(prp_id, ik, lk) END SUBROUTINE h5pset_sym_k_f -!****s* H5P/h5pget_sym_k_f -! NAME -! h5pget_sym_k_f -! -! PURPOSE -! Retrieves the size of the symbol table B-tree 1/2 rank -! and the symbol table leaf node 1/2 size. -! -! INPUTS -! -! prp_id - file creation property list identifier -! OUTPUTS -! -! ik - symbol table tree 1/2 rank -! lk - symbol table node 1/2 size -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the size of the symbol table B-tree 1/2 rank and the symbol table leaf node 1/2 size. +!! +!! \param prp_id File creation property list identifier. +!! \param ik Symbol table tree 1/2 rank. +!! \param lk Symbol table node 1/2 size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_sym_k_f(prp_id, ik, lk, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: ik ! Symbol table tree rank - INTEGER, INTENT(OUT) :: lk ! Symbol table node size - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: ik + INTEGER, INTENT(OUT) :: lk + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_sym_k_c(prp_id, ik, lk) & BIND(C,NAME='h5pget_sym_k_c') @@ -1005,41 +672,20 @@ CONTAINS hdferr = h5pget_sym_k_c(prp_id, ik, lk) END SUBROUTINE h5pget_sym_k_f -!****s* H5P/h5pset_istore_k_f -! NAME -! h5pset_istore_k_f -! -! PURPOSE -! Sets the size of the parameter used to control the -! B-trees for indexing chunked datasets -! -! INPUTS -! -! prp_id - file creation property list identifier -! ik - 1/2 rank of chunked storage B-tree -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the size of the parameter used to control the B-trees for indexing chunked datasets +!! +!! \param prp_id File creation property list identifier +!! \param ik 1/2 rank of chunked storage B-tree +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_istore_k_f (prp_id, ik, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: ik ! 1/2 rank of chunked storage B-tree - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: ik + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_istore_k_c(prp_id, ik) & BIND(C,NAME='h5pset_istore_k_c') @@ -1053,40 +699,20 @@ CONTAINS hdferr = h5pset_istore_k_c(prp_id, ik) END SUBROUTINE h5pset_istore_k_f -!****s* H5P/h5pget_istore_k_f -! NAME -! h5pget_istore_k_f -! -! PURPOSE -! Queries the 1/2 rank of an indexed storage B-tree. -! -! INPUTS -! -! prp_id - file creation property list identifier -! OUTPUTS -! -! ik - 1/2 rank of chunked storage B-tree -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Queries the 1/2 rank of an indexed storage B-tree. +!! +!! \param prp_id File creation property list identifier. +!! \param ik Rank of chunked storage B-tree. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_istore_k_f(prp_id, ik, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: ik ! 1/2 rank of chunked storage B-tree - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: ik + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_istore_k_c(prp_id, ik) & BIND(C,NAME='h5pget_istore_k_c') @@ -1100,41 +726,20 @@ CONTAINS hdferr = h5pget_istore_k_c(prp_id, ik) END SUBROUTINE h5pget_istore_k_f -!****s* H5P/h5pget_driver_f -! NAME -! h5pget_driver_f -! -! PURPOSE -! Returns low-lever driver identifier. -! -! INPUTS -! -! prp_id - file access or data transfer property -! list identifier. -! OUTPUTS -! -! driver - low-level driver identifier -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns low-lever driver identifier. +!! +!! \param prp_id File access or data transfer property list identifier. +!! \param driver Low-level driver identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_driver_f(prp_id, driver, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HID_T), INTENT(OUT) :: driver ! Low-level file driver identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(OUT) :: driver + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_driver_c(prp_id, driver) & BIND(C,NAME='h5pget_driver_c') @@ -1148,38 +753,18 @@ CONTAINS hdferr = h5pget_driver_c(prp_id, driver) END SUBROUTINE h5pget_driver_f -!****s* H5P/h5pset_fapl_stdio_f -! NAME -! h5pset_fapl_stdio_f -! -! PURPOSE -! Sets the standard I/O driver. -! -! INPUTS -! -! prp_id - file access property list identifier -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the standard I/O driver. +!! +!! \param prp_id File access property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fapl_stdio_f (prp_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_fapl_stdio_c(prp_id) & BIND(C,NAME='h5pset_fapl_stdio_c') @@ -1192,162 +777,46 @@ CONTAINS hdferr = h5pset_fapl_stdio_c(prp_id) END SUBROUTINE h5pset_fapl_stdio_f -!****s* H5P/h5pget_stdio_f -! NAME -! h5pget_stdio_f -! -! PURPOSE -! NOT AVAILABLE -! -! INPUTS -! -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! SOURCE -! SUBROUTINE h5pget_stdio_f (prp_id, io, hdferr) -! -! IMPLICIT NONE -! INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier -! INTEGER, INTENT(OUT) :: io ! value indicates that the file - !access property list is set to - !the stdio driver -! INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** -! INTEGER, EXTERNAL :: h5pget_stdio_c -! hdferr = h5pget_stdio_c(prp_id, io) -! END SUBROUTINE h5pget_stdio_f - -!****s* H5P/h5pset_fapl_sec2_f -! NAME -! h5pset_fapl_sec2_f -! -! PURPOSE -! Sets the sec2 driver. -! -! INPUTS -! -! prp_id - file access property list identifier -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the sec2 driver. +!! +!! \param prp_id File access property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fapl_sec2_f (prp_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_fapl_sec2_c(prp_id) & BIND(C,NAME='h5pset_fapl_sec2_c') IMPORT :: HID_T IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier + INTEGER(HID_T), INTENT(IN) :: prp_id END FUNCTION h5pset_fapl_sec2_c END INTERFACE hdferr = h5pset_fapl_sec2_c(prp_id) END SUBROUTINE h5pset_fapl_sec2_f -!****s* H5P/h5pget_sec2_f -! NAME -! h5pget_sec2_f -! -! PURPOSE -! NOT AVAILABLE -! -! INPUTS -! -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! SOURCE! SUBROUTINE h5pget_sec2_f (prp_id, sec2, hdferr) -! IMPLICIT NONE -! INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier -! INTEGER, INTENT(OUT) :: sec2 ! value indicates whether the file - !driver uses the functions declared - !in the unistd.h file -! INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** -! INTEGER, EXTERNAL :: h5pget_sec2_c -! hdferr = h5pget_sec2_c(prp_id, sec2) -! END SUBROUTINE h5pget_sec2_f - -!****s* H5P/h5pset_alignment_f -! NAME -! h5pset_alignment_f -! -! PURPOSE -! Sets alignment properties of a file access property list. -! -! INPUTS -! -! prp_id - file access property list identifier -! threshold - threshold value -! alignment - alignment value -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets alignment properties of a file access property list. +!! +!! \param prp_id File access property list identifier. +!! \param threshold Threshold value. +!! \param alignment Alignment value. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_alignment_f(prp_id, threshold, alignment, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HSIZE_T), INTENT(IN) :: threshold ! Threshold value - INTEGER(HSIZE_T), INTENT(IN) :: alignment ! alignment value - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HSIZE_T), INTENT(IN) :: threshold + INTEGER(HSIZE_T), INTENT(IN) :: alignment + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_alignment_c(prp_id, threshold, alignment) & BIND(C,NAME='h5pset_alignment_c') @@ -1362,42 +831,22 @@ CONTAINS hdferr = h5pset_alignment_c(prp_id, threshold, alignment) END SUBROUTINE h5pset_alignment_f -!****s* H5P/h5pget_alignment_f -! NAME -! h5pget_alignment_f -! -! PURPOSE -! Retrieves the current settings for alignment -! properties from a file access property list. -! -! INPUTS -! prp_id - file access property list identifier -! -! OUTPUTS -! threshold - threshold value -! alignment - alignment value -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the current settings for alignment properties from a file access property list. +!! +!! \param prp_id File access property list identifier. +!! \param threshold Threshold value. +!! \param alignment Alignment value. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_alignment_f(prp_id, threshold, alignment, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HSIZE_T), INTENT(OUT) :: threshold ! Threshold value - INTEGER(HSIZE_T), INTENT(OUT) :: alignment ! alignment value - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HSIZE_T), INTENT(OUT) :: threshold + INTEGER(HSIZE_T), INTENT(OUT) :: alignment + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_alignment_c(prp_id, threshold, alignment) & BIND(C,NAME='h5pget_alignment_c') @@ -1412,44 +861,22 @@ CONTAINS hdferr = h5pget_alignment_c(prp_id, threshold, alignment) END SUBROUTINE h5pget_alignment_f -!****s* H5P/h5pset_fapl_core_f -! NAME -! h5pset_fapl_core_f -! -! PURPOSE -! Modifies the file access property list to use the -! H5FD_CORE driver. -! -! INPUTS -! prp_id - file access property list identifier -! increment - size, in bytes, of memory increments -! backing_store - boolean flag indicating whether to write -! the file contents to disk when the file is closed. -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Modifies the file access property list to use the H5FD_CORE driver. +!! +!! \param prp_id File access property list identifier. +!! \param increment Size, in bytes, of memory increments. +!! \param backing_store Boolean flag indicating whether to write the file contents to disk when the file is closed. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fapl_core_f(prp_id, increment, backing_store, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(SIZE_T), INTENT(IN) :: increment ! File block size in bytes. - LOGICAL, INTENT(IN) :: backing_store ! Flag to indicate that - ! entire file contents are flushed to a file - ! with the same name as this core file. - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(SIZE_T), INTENT(IN) :: increment + LOGICAL, INTENT(IN) :: backing_store + INTEGER, INTENT(OUT) :: hdferr INTEGER :: backing_store_flag INTERFACE INTEGER FUNCTION h5pset_fapl_core_c(prp_id, increment, backing_store_flag) & @@ -1466,44 +893,22 @@ CONTAINS hdferr = h5pset_fapl_core_c(prp_id, increment, backing_store_flag) END SUBROUTINE h5pset_fapl_core_f -!****s* H5P/h5pget_fapl_core_f -! NAME -! h5pget_fapl_core_f -! -! PURPOSE -! Queries core file driver properties. -! -! INPUTS -! prp_id - file access property list identifier -! OUTPUTS -! -! increment - size, in bytes, of memory increments -! backing_store - boolean flag indicating whether to write -! the file contents to disk when the file is closed. -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Queries core file driver properties. +!! +!! \param prp_id File access property list identifier. +!! \param increment Size, in bytes, of memory increments. +!! \param backing_store Boolean flag indicating whether to write the file contents to disk when the file is closed. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_fapl_core_f(prp_id, increment, backing_store, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(SIZE_T), INTENT(OUT) :: increment ! File block size in bytes. - LOGICAL, INTENT(OUT) :: backing_store ! Flag to indicate that - ! entire file contents are flushed to a file - ! with the same name as this core file. - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(SIZE_T), INTENT(OUT) :: increment + LOGICAL, INTENT(OUT) :: backing_store + INTEGER, INTENT(OUT) :: hdferr INTEGER :: backing_store_flag INTERFACE @@ -1522,44 +927,22 @@ CONTAINS IF (backing_store_flag .EQ. 1) backing_store =.TRUE. END SUBROUTINE h5pget_fapl_core_f -!****s* H5P/ h5pset_fapl_family_f -! NAME -! h5pset_fapl_family_f -! -! PURPOSE -! Sets the file access property list to use the family driver. -! -! INPUTS -! prp_id - file access property list identifier -! memb_size - size in bytes of each file member -! memb_plist - identifier of the file access property -! list to be used for each family member -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the file access property list to use the family driver. +!! +!! \param prp_id File access property list identifier. +!! \param memb_size Size in bytes of each file member. +!! \param memb_plist Identifier of the file access property list to be used for each family member +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fapl_family_f(prp_id, memb_size, memb_plist , hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HSIZE_T), INTENT(IN) :: memb_size ! Logical size, in bytes, - ! of each family member - INTEGER(HID_T), INTENT(IN) :: memb_plist ! Identifier of the file - ! access property list for - ! each member of the family - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HSIZE_T), INTENT(IN) :: memb_size + INTEGER(HID_T), INTENT(IN) :: memb_plist + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_fapl_family_c(prp_id, memb_size, memb_plist) & BIND(C,NAME='h5pset_fapl_family_c') @@ -1574,43 +957,22 @@ CONTAINS hdferr = h5pset_fapl_family_c(prp_id, memb_size, memb_plist) END SUBROUTINE h5pset_fapl_family_f -!****s* H5P/h5pget_fapl_family_f -! NAME -! h5pget_fapl_family_f -! -! PURPOSE -! Returns file access property list information. -! -! INPUTS -! prp_id - file access property list identifier -! OUTPUTS -! memb_size - size in bytes of each file member -! memb_plist - identifier of the file access property -! list to be used for each family member -! hdferr - error code -! Success: 0 -! Failure: -1 -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns file access property list information. +!! +!! \param prp_id File access property list identifier. +!! \param memb_size Size in bytes of each file member. +!! \param memb_plist Identifier of the file access property list to be used for each family member +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_fapl_family_f(prp_id, memb_size, memb_plist , hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HSIZE_T), INTENT(OUT) :: memb_size ! Logical size, in bytes, - ! of each family member - INTEGER(HID_T), INTENT(OUT) :: memb_plist ! Identifier of the file - ! access property list for - ! each member of the family - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HSIZE_T), INTENT(OUT) :: memb_size + INTEGER(HID_T), INTENT(OUT) :: memb_plist + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_fapl_family_c(prp_id, memb_size, memb_plist) & BIND(C,NAME='h5pget_fapl_family_c') @@ -1625,52 +987,26 @@ CONTAINS hdferr = h5pget_fapl_family_c(prp_id, memb_size, memb_plist) END SUBROUTINE h5pget_fapl_family_f -!****s* H5P/h5pset_cache_f -! NAME -! h5pset_cache_f -! -! PURPOSE -! Sets the meta data cache and raw data chunk -! cache parameters -! -! INPUTS -! -! prp_id - file access property list identifier -! mdc_nelmts - number of elements (objects) in the meta -! data cache -! rdcc_nelmts - number of elements (objects) in the raw -! data chunk cache -! rdcc_nbytes - total size of the raw data chunk cache, in bytes -! rdcc_w0 - preemption policy (0 or 1) -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the meta data cache and raw data chunk cache parameters +!! +!! \param prp_id File access property list identifier. +!! \param mdc_nelmts Number of elements (objects) in the metadata cache. +!! \param rdcc_nelmts Number of elements (objects) in the raw data chunk cache. +!! \param rdcc_nbytes Total size of the raw data chunk cache, in bytes. +!! \param rdcc_w0 Preemption policy (0 or 1). +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_cache_f(prp_id, mdc_nelmts,rdcc_nelmts, rdcc_nbytes, rdcc_w0, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: mdc_nelmts ! Number of elements (objects) - ! in the meta data cache - INTEGER(SIZE_T), INTENT(IN) :: rdcc_nelmts ! Number of elements (objects) - ! in the meta data cache - INTEGER(SIZE_T), INTENT(IN) :: rdcc_nbytes ! Total size of the raw data - ! chunk cache, in bytes - REAL, INTENT(IN) :: rdcc_w0 ! Preemption policy - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: mdc_nelmts + INTEGER(SIZE_T), INTENT(IN) :: rdcc_nelmts + INTEGER(SIZE_T), INTENT(IN) :: rdcc_nbytes + REAL, INTENT(IN) :: rdcc_w0 + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_cache_c(prp_id,mdc_nelmts,rdcc_nelmts,rdcc_nbytes,rdcc_w0) & BIND(C,NAME='h5pset_cache_c') @@ -1687,54 +1023,26 @@ CONTAINS hdferr = h5pset_cache_c(prp_id, mdc_nelmts, rdcc_nelmts, rdcc_nbytes, rdcc_w0 ) END SUBROUTINE h5pset_cache_f -!****s* H5P/h5pget_cache_f -! NAME -! h5pget_cache_f -! -! PURPOSE -! Queries the meta data cache and raw data chunk cache -! parameters. -! -! INPUTS -! prp_id - file access property list identifier -! -! OUTPUTS -! mdc_nelmts - number of elements (objects) in the meta -! data cache -! rdcc_nelmts - number of elements (objects) in the raw -! data chunk cache -! rdcc_nbytes - total size of the raw data chunk cache, in bytes -! rdcc_w0 - preemption policy (0 or 1) -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Bug fix: type of the rdcc_nelmts parameter should be INTEGER -! instead of INTEGER(SIZE_T) October 10, 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Queries the meta data cache and raw data chunk cache parameters. +!! +!! \param prp_id File access property list identifier. +!! \param mdc_nelmts Number of elements (objects) in the metadata cache +!! \param rdcc_nelmts Number of elements (objects) in the raw data chunk cache +!! \param rdcc_nbytes Total size of the raw data chunk cache, in bytes. +!! \param rdcc_w0 Preemption policy (0 or 1). +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_cache_f(prp_id, mdc_nelmts, rdcc_nelmts, rdcc_nbytes, rdcc_w0, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: mdc_nelmts ! Number of elements (objects) - ! in the meta data cache - INTEGER(SIZE_T), INTENT(OUT) :: rdcc_nelmts ! Number of elements (objects) - ! in the meta data cache - INTEGER(SIZE_T), INTENT(OUT) :: rdcc_nbytes ! Total size of the raw data - ! chunk cache, in bytes - REAL, INTENT(OUT) :: rdcc_w0 ! Preemption policy - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: mdc_nelmts + INTEGER(SIZE_T), INTENT(OUT) :: rdcc_nelmts + INTEGER(SIZE_T), INTENT(OUT) :: rdcc_nbytes + REAL, INTENT(OUT) :: rdcc_w0 + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_cache_c(prp_id,mdc_nelmts,rdcc_nelmts,rdcc_nbytes,rdcc_w0) & BIND(C,NAME='h5pget_cache_c') @@ -1751,52 +1059,26 @@ CONTAINS hdferr = h5pget_cache_c(prp_id, mdc_nelmts,rdcc_nelmts, rdcc_nbytes, rdcc_w0 ) END SUBROUTINE h5pget_cache_f -!****s* H5P/h5pset_fapl_split_f -! NAME -! h5pset_fapl_split_f -! -! PURPOSE -! Emulates the old split file driver. -! -! INPUTS -! -! prp_id - file access property list identifier -! meta_ext - name of the extension for the metafile -! filename -! meta_plist - identifier of the meta file access property -! list -! raw_ext - name extension for the raw file filename -! raw_plist - identifier of the raw file access property list -! -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Emulates the old split file driver. +!! +!! \param prp_id File access property list identifier. +!! \param meta_ext Name of the extension for the metafile filename. +!! \param meta_plist Identifier of the meta file access property list. +!! \param raw_ext Name extension for the raw file filename. +!! \param raw_plist Identifier of the raw file access property list. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fapl_split_f(prp_id, meta_ext, meta_plist, raw_ext, raw_plist, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: meta_ext ! Name of the extension for - ! the metafile filename - INTEGER(HID_T), INTENT(IN) :: meta_plist ! Identifier of the meta file - ! access property list - CHARACTER(LEN=*), INTENT(IN) :: raw_ext ! Name extension for the raw file filename - INTEGER(HID_T), INTENT(IN) :: raw_plist ! Identifier of the raw file - ! access property list - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: meta_ext + INTEGER(HID_T), INTENT(IN) :: meta_plist + CHARACTER(LEN=*), INTENT(IN) :: raw_ext + INTEGER(HID_T), INTENT(IN) :: raw_plist + INTEGER, INTENT(OUT) :: hdferr INTEGER :: meta_len, raw_len INTERFACE INTEGER FUNCTION h5pset_fapl_split_c(prp_id,meta_len,meta_ext,meta_plist,raw_len,raw_ext,raw_plist) & @@ -1818,94 +1100,20 @@ CONTAINS hdferr = h5pset_fapl_split_c(prp_id,meta_len,meta_ext,meta_plist,raw_len,raw_ext,raw_plist) END SUBROUTINE h5pset_fapl_split_f -!****s* H5P/h5pget_split_f -! NAME -! h5pget_split_f -! -! PURPOSE -! NOT AVAILABLE -! -! INPUTS -! -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! SOURCE -! SUBROUTINE h5pget_split_f(prp_id, meta_ext_size, meta_ext, meta_plist,raw_ext_size,& -! raw_ext, raw_plist, hdferr) -! IMPLICIT NONE -! INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier -! INTEGER(SIZE_T), INTENT(IN) :: meta_ext_size ! Number of characters of the meta - ! file extension to be copied to the - ! meta_ext buffer - -! CHARACTER(LEN=*), INTENT(OUT) :: meta_ext !Name of the extension for - !the metafile filename -! INTEGER(HID_T), INTENT(OUT) :: meta_plist ! Identifier of the meta file - ! access property list -! INTEGER(SIZE_T), INTENT(IN) :: raw_ext_size ! Number of characters of the raw - ! file extension to be copied to the - ! raw_ext buffer -! CHARACTER(LEN=*), INTENT(OUT) :: raw_ext !Name extension for the raw file filename -! INTEGER(HID_T), INTENT(OUT) :: raw_plist !Identifier of the raw file - !access property list -! INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** - -! INTEGER, EXTERNAL :: h5pget_split_c -! hdferr = h5pget_split_c(prp_id, meta_ext_size, meta_ext, meta_plist, & -! raw_ext_size, raw_ext, raw_plist ) -! END SUBROUTINE h5pget_split_f - -!****s* H5P/h5pset_gc_references_f -! NAME -! h5pset_gc_references_f -! -! PURPOSE -! Sets garbage collecting references flag. -! -! INPUTS -! -! prp_id - file access property list identifier -! gc_reference - flag for setting garbage collection on -! and off (1 or 0) -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets garbage collecting references flag. +!! +!! \param prp_id File access property list identifier. +!! \param gc_reference Flag for setting garbage collection on and off (1 or 0). +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_gc_references_f (prp_id, gc_reference, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: gc_reference ! The flag for garbage collecting - ! references for the file - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: gc_reference + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_gc_references_c(prp_id, gc_reference) & BIND(C,NAME='h5pset_gc_references_c') @@ -1919,42 +1127,20 @@ CONTAINS hdferr = h5pset_gc_references_c(prp_id, gc_reference) END SUBROUTINE h5pset_gc_references_f -!****s* H5P/h5pget_gc_references_f -! NAME -! h5pget_gc_references_f -! -! PURPOSE -! Returns garbage collecting references setting. -! -! INPUTS -! -! prp_id - file access property list identifier -! OUTPUTS -! -! gc_reference - flag for setting garbage collection on -! and off (1 or 0) -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns garbage collecting references setting. +!! +!! \param prp_id File access property list identifier. +!! \param gc_reference Flag for setting garbage collection on and off (1 or 0) +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_gc_references_f(prp_id, gc_reference, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: gc_reference ! The flag for garbage collecting - ! references for the file - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: gc_reference + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_gc_references_c(prp_id, gc_reference) & BIND(C,NAME='h5pget_gc_references_c') @@ -1968,49 +1154,25 @@ CONTAINS hdferr = h5pget_gc_references_c(prp_id, gc_reference) END SUBROUTINE h5pget_gc_references_f -!****s* H5P/h5pset_layout_f -! NAME -! h5pset_layout_f -! -! PURPOSE -! Sets the type of storage used store the raw data -! for a dataset. -! -! INPUTS -! -! prp_id - data creation property list identifier -! layout - type of storage layout for raw data -! possible values are: -! H5D_COMPACT_F -! H5D_CONTIGUOUS_F -! H5D_CHUNKED_F -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the type of storage used store the raw data +!! for a dataset. +!! +!! \param prp_id Data creation property list identifier. +!! \param layout Type of storage layout for raw data. Possible values are: +!! \li H5D_COMPACT_F +!! \li H5D_CONTIGUOUS_F +!! \li H5D_CHUNKED_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_layout_f (prp_id, layout, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: layout ! Type of storage layout for raw data - ! possible values are: - ! H5D_COMPACT_F - ! H5D_CONTIGUOUS_F + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: layout ! H5D_CHUNKED_F - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_layout_c(prp_id, layout) & BIND(C,NAME='h5pset_layout_c') @@ -2024,48 +1186,24 @@ CONTAINS hdferr = h5pset_layout_c(prp_id, layout) END SUBROUTINE h5pset_layout_f -!****s* H5P/h5pget_layout_f -! NAME -! h5pget_layout_f -! -! PURPOSE -! Returns the layout of the raw data for a dataset. -! -! INPUTS -! -! prp_id - data creation property list identifier -! OUTPUTS -! -! layout - type of storage layout for raw data -! possible values are: -! H5D_COMPACT_F -! H5D_CONTIGUOUS_F -! H5D_CHUNKED_F -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns the layout of the raw data for a dataset. +!! +!! \param prp_id Data creation property list identifier. +!! \param layout Type of storage layout for raw data. Possible values are: +!! \li H5D_COMPACT_F +!! \li H5D_CONTIGUOUS_F +!! \li H5D_CHUNKED_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_layout_f (prp_id, layout, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: layout ! Type of storage layout for raw data - ! possible values are: - ! H5D_COMPACT_F(0) - ! H5D_CONTIGUOUS_F(1) + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: layout ! H5D_CHUNKED_F(2) - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_layout_c(prp_id, layout) & BIND(C,NAME='h5pget_layout_c') @@ -2079,44 +1217,26 @@ CONTAINS hdferr = h5pget_layout_c(prp_id, layout) END SUBROUTINE h5pget_layout_f -!****s* H5P/h5pset_filter_f -! NAME -! h5pset_filter_f -! -! PURPOSE -! Adds a filter to the filter pipeline. -! -! INPUTS -! -! prp_id - data creation or transfer property list -! identifier -! filter - filter to be added to the pipeline -! flags - bit vector specifying certain general -! properties of the filter -! cd_nelmts - number of elements in cd_values -! cd_values - auxiliary data for the filter -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! February, 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Adds a filter to the filter pipeline. +!! +!! \param prp_id Data creation or transfer property list identifier. +!! \param filter Filter to be added to the pipeline. +!! \param flags Bit vector specifying certain general properties of the filter. +!! \param cd_nelmts Number of elements in cd_values. +!! \param cd_values Auxiliary data for the filter. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_filter_f(prp_id, filter, flags, cd_nelmts, cd_values, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: filter ! Filter to be added to the pipeline. - INTEGER, INTENT(IN) :: flags ! Bit vector specifying certain general - ! properties of the filter. - INTEGER(SIZE_T), INTENT(IN) :: cd_nelmts ! Number of elements in cd_values. - INTEGER, DIMENSION(*), INTENT(IN) :: cd_values ! Auxiliary data for the filter. - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: filter + INTEGER, INTENT(IN) :: flags + INTEGER(SIZE_T), INTENT(IN) :: cd_nelmts + INTEGER, DIMENSION(*), INTENT(IN) :: cd_values + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_filter_c(prp_id, filter, flags, cd_nelmts, cd_values) & BIND(C,NAME='h5pset_filter_c') @@ -2133,41 +1253,20 @@ CONTAINS hdferr = h5pset_filter_c(prp_id, filter, flags, cd_nelmts, cd_values ) END SUBROUTINE h5pset_filter_f -!****s* H5P/h5pget_nfilters_f -! NAME -! h5pget_nfilters_f -! -! PURPOSE -! Returns the number of filters in the pipeline. -! -! INPUTS -! -! prp_id - data creation or transfer property list -! identifier -! OUTPUTS -! -! nfilters - number of filters in the pipeline -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns the number of filters in the pipeline. +!! +!! \param prp_id Data creation or transfer property list identifier. +!! \param nfilters Number of filters in the pipeline. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_nfilters_f (prp_id, nfilters, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: nfilters ! The number of filters in the pipeline - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: nfilters + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_nfilters_c(prp_id, nfilters) & BIND(C,NAME='h5pget_nfilters_c') @@ -2181,60 +1280,32 @@ CONTAINS hdferr = h5pget_nfilters_c(prp_id, nfilters) END SUBROUTINE h5pget_nfilters_f -!****s* H5P/h5pget_filter_f -! NAME -! h5pget_filter_f -! -! PURPOSE -! Returns information about a filter in a pipeline -! -! INPUTS -! -! prp_id - data creation or transfer property list -! identifier -! filter_number - sequence number within the filter -! pipeline of the filter for which -! information is sought -! OUTPUTS -! -! filter_id - filter identification number -! flags - bit vector specifying certain general -! properties of the filter -! cd_nelmts - number of elements in cd_values -! cd_values - auxiliary data for the filter -! namelen - number of characters in the name buffer -! name - buffer to retrieve filter name -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns information about a filter in a pipeline +!! +!! \param prp_id Data creation or transfer property list identifier +!! \param filter_number Sequence number within the filter pipeline of the filter for which information is sought +!! \param filter_id Filter identification number. +!! \param flags Bitbit vector specifying certain general properties of the filter. +!! \param cd_nelmts Number of elements in cd_values. +!! \param cd_values Auxiliary data for the filter. +!! \param namelen Number of characters in the name buffer. +!! \param name Buffer to retrieve filter name. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_filter_f(prp_id, filter_number, flags, cd_nelmts, cd_values, namelen, name, filter_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: filter_number ! Sequence number within the filter - ! pipeline of the filter for which - ! information is sought - INTEGER, DIMENSION(*), INTENT(OUT) :: cd_values ! Auxiliary data for the filter. - INTEGER, INTENT(OUT) :: flags ! Bit vector specifying certain general - ! properties of the filter. - INTEGER(SIZE_T), INTENT(INOUT) :: cd_nelmts ! Number of elements in cd_values. - INTEGER(SIZE_T), INTENT(IN) :: namelen ! Anticipated number of characters in name. - CHARACTER(LEN=*), INTENT(OUT) :: name ! Name of the filter - INTEGER, INTENT(OUT) :: filter_id ! Filter identification number - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** - + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: filter_number + INTEGER, DIMENSION(*), INTENT(OUT) :: cd_values + INTEGER, INTENT(OUT) :: flags + INTEGER(SIZE_T), INTENT(INOUT) :: cd_nelmts + INTEGER(SIZE_T), INTENT(IN) :: namelen + CHARACTER(LEN=*), INTENT(OUT) :: name + INTEGER, INTENT(OUT) :: filter_id + INTEGER, INTENT(OUT) :: hdferr ! INTEGER, EXTERNAL :: h5pget_filter_c ! MS FORTRAN needs explicit interface for C functions called here. @@ -2261,50 +1332,24 @@ CONTAINS cd_values, namelen, name, filter_id ) END SUBROUTINE h5pget_filter_f -!****s* H5P/h5pset_external_f -! NAME -! h5pset_external_f -! -! PURPOSE -! Adds an external file to the list of external files. -! -! INPUTS -! -! prp_id - dataset creation property list identifier -! name - name of external file -! offset - offset in bytes from the beginning of the -! file to the location in the file -! where the data starts -! bytes - size of the external file data. -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Changed type of 'offset' from integer to off_t -- MSB January 9, 2012 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Adds an external file to the list of external files. +!! +!! \param prp_id Dataset creation property list identifier. +!! \param name Name of external file. +!! \param offset Offset in bytes from the beginning of the file to the location in the file where the data starts. +!! \param bytes Size of the external file data. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_external_f(prp_id, name, offset, bytes, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of an external file - INTEGER(OFF_T), INTENT(IN) :: offset ! Offset, in bytes, from the beginning - ! of the file to the location in the file - ! where the data starts. - INTEGER(HSIZE_T), INTENT(IN) :: bytes ! Number of bytes reserved in the - ! file for the data - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(OFF_T), INTENT(IN) :: offset + INTEGER(HSIZE_T), INTENT(IN) :: bytes + INTEGER, INTENT(OUT) :: hdferr INTEGER :: namelen INTERFACE @@ -2325,42 +1370,20 @@ CONTAINS hdferr = h5pset_external_c(prp_id, name, namelen, offset, bytes) END SUBROUTINE h5pset_external_f -!****s* H5P/h5pget_external_count_f -! NAME -! h5pget_external_count_f -! -! PURPOSE -! Returns the number of external files for a dataset. -! -! INPUTS -! -! prp_id - dataset creation property list identifier -! OUTPUTS -! -! count - number of external files for the -! specified dataset -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns the number of external files for a dataset. +!! +!! \param prp_id Dataset creation property list identifier. +!! \param count Number of external files for the specified dataset. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_external_count_f (prp_id, count, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: count ! Number of external files for the - ! Specified dataset - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: count + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_external_count_c(prp_id, count) & BIND(C,NAME='h5pget_external_count_c') @@ -2374,56 +1397,28 @@ CONTAINS hdferr = h5pget_external_count_c(prp_id, count) END SUBROUTINE h5pget_external_count_f -!****s* H5P/h5pget_external_f -! NAME -! h5pget_external_f -! -! PURPOSE -! Returns information about an external file. -! -! INPUTS -! -! prp_id - dataset creation property list identifier -! OUTPUTS -! -! idx - external file index -! name_size - maximum size of name array -! name - name of the external file -! name - name of external file -! offset - offset in bytes from the beginning of the -! file to the location in the file -! where the data starts -! bytes - size of the external file data -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Changed type of 'offset' from integer to off_t -- MSB January 9, 2012 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns information about an external file. +!! +!! \param prp_id Dataset creation property list identifier. +!! \param idx External file index. +!! \param name_size Maximum size of name array. +!! \param name Name of the external file. +!! \param offset Offset in bytes from the beginning of the file to the location in the file where the data starts. +!! \param bytes Size of the external file data. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_external_f(prp_id, idx, name_size, name, offset,bytes, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: idx ! External file index. - INTEGER(SIZE_T), INTENT(IN) :: name_size ! Maximum length of name array - CHARACTER(LEN=*), INTENT(OUT) :: name ! Name of an external file - INTEGER(OFF_T), INTENT(OUT) :: offset ! Offset, in bytes, from the beginning - ! of the file to the location in the file - ! where the data starts. - INTEGER(HSIZE_T), INTENT(OUT) :: bytes ! Number of bytes reserved in the - ! file for the data - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: idx + INTEGER(SIZE_T), INTENT(IN) :: name_size + CHARACTER(LEN=*), INTENT(OUT) :: name + INTEGER(OFF_T), INTENT(OUT) :: offset + INTEGER(HSIZE_T), INTENT(OUT) :: bytes + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_external_c(prp_id, idx, name_size, name, offset, bytes) & BIND(C,NAME='h5pget_external_c') @@ -2442,46 +1437,24 @@ CONTAINS hdferr = h5pget_external_c(prp_id, idx, name_size, name, offset, bytes) END SUBROUTINE h5pget_external_f -!****s* H5P/h5pset_btree_ratios_f -! NAME -! h5pset_btree_ratios_f -! -! PURPOSE -! Sets B-tree split ratios for a dataset transfer -! property list. -! -! INPUTS -! -! prp_id - the dataset transfer property list -! identifier -! left - the B-tree split ratio for left-most nodes -! middle - the B-tree split ratio for all other nodes -! right - the B-tree split ratio for right-most nodes -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets B-tree split ratios for a dataset transfer property list. +!! +!! \param prp_id The dataset transfer property list identifier. +!! \param left The B-tree split ratio for left-most nodes. +!! \param middle The B-tree split ratio for all other nodes. +!! \param right The B-tree split ratio for right-most nodes. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_btree_ratios_f(prp_id, left, middle, right, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - REAL, INTENT(IN) :: left ! The B-tree split ratio for left-most nodes. - REAL, INTENT(IN) :: middle ! The B-tree split ratio for all other nodes - REAL, INTENT(IN) :: right ! The B-tree split ratio for right-most - ! nodes and lone nodes. - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + REAL, INTENT(IN) :: left + REAL, INTENT(IN) :: middle + REAL, INTENT(IN) :: right + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_btree_ratios_c(prp_id, left, middle, right) & BIND(C,NAME='h5pset_btree_ratios_c') @@ -2497,46 +1470,24 @@ CONTAINS hdferr = h5pset_btree_ratios_c(prp_id, left, middle, right) END SUBROUTINE h5pset_btree_ratios_f -!****s* H5P/h5pget_btree_ratios_f -! NAME -! h5pget_btree_ratios_f -! -! PURPOSE -! Gets B-tree split ratios for a dataset transfer property list -! -! INPUTS -! -! prp_id - the dataset transfer property list -! identifier -! OUTPUTS -! -! left - the B-tree split ratio for left-most nodes -! middle - the B-tree split ratio for all other nodes -! right - the B-tree split ratio for right-most nodes -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Gets B-tree split ratios for a dataset transfer property list +!! +!! \param prp_id The dataset transfer property list identifier. +!! \param left The B-tree split ratio for left-most nodes. +!! \param middle The B-tree split ratio for all other nodes. +!! \param right The B-tree split ratio for right-most nodes. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_btree_ratios_f(prp_id, left, middle, right, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - REAL, INTENT(OUT) :: left ! The B-tree split ratio for left-most nodes. - REAL, INTENT(OUT) :: middle ! The B-tree split ratio for all other nodes - REAL, INTENT(OUT) :: right ! The B-tree split ratio for right-most - ! nodes and lone nodes. - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + REAL, INTENT(OUT) :: left + REAL, INTENT(OUT) :: middle + REAL, INTENT(OUT) :: right + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_btree_ratios_c(prp_id, left, middle, right) & BIND(C,NAME='h5pget_btree_ratios_c') @@ -2552,46 +1503,25 @@ CONTAINS hdferr = h5pget_btree_ratios_c(prp_id, left, middle, right) END SUBROUTINE h5pget_btree_ratios_f -!****s* H5P/h5pget_fclose_degree_f -! NAME -! h5pget_fclose_degree_f -! -! PURPOSE -! Returns the degree for the file close behavior. -! -! INPUTS -! -! fapl_id - File access property list identifier -! OUTPUTS -! -! degree - Possible values are: -! H5F_CLOSE_DEFAULT_F -! H5F_CLOSE_WEAK_F -! H5F_CLOSE_SEMI_F -! H5F_CLOSE_STRONG_F -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! September 26, 2002 -! -! HISTORY -! -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns the degree for the file close behavior. +!! +!! \param fapl_id File access property list identifier. +!! \param degree Possible values are: +!! \li H5F_CLOSE_DEFAULT_F +!! \li H5F_CLOSE_WEAK_F +!! \li H5F_CLOSE_SEMI_F +!! \li H5F_CLOSE_STRONG_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_fclose_degree_f(fapl_id, degree, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: fapl_id ! File Access Property list identifier - INTEGER, INTENT(OUT) :: degree ! Possible values are: - ! H5F_CLOSE_DEFAULT_F - ! H5F_CLOSE_WEAK_F - ! H5F_CLOSE_SEMI_F - ! H5F_CLOSE_STRONG_F - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: fapl_id + INTEGER, INTENT(OUT) :: degree + ! H5F_CLOSE_STRONG_F + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_fclose_degree_c(fapl_id, degree) & BIND(C,NAME='h5pget_fclose_degree_c') @@ -2605,42 +1535,25 @@ CONTAINS hdferr = h5pget_fclose_degree_c(fapl_id, degree) END SUBROUTINE h5pget_fclose_degree_f -!****s* H5P/h5pset_fclose_degree_f -! NAME -! h5pset_fclose_degree_f -! -! PURPOSE -! Sets the degree for the file close behavior. -! -! INPUTS -! -! fapl_id - file access property list identifier -! degree - Possible values are: -! H5F_CLOSE_DEFAULT_F -! H5F_CLOSE_WEAK_F -! H5F_CLOSE_SEMI_F -! H5F_CLOSE_STRONG_F -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! September 26, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the degree for the file close behavior. +!! +!! \param fapl_id File access property list identifier. +!! \param degree Possible values are: +!! \li H5F_CLOSE_DEFAULT_F +!! \li H5F_CLOSE_WEAK_F +!! \li H5F_CLOSE_SEMI_F +!! \li H5F_CLOSE_STRONG_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fclose_degree_f(fapl_id, degree, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: fapl_id ! File Access Property list identifier - INTEGER, INTENT(IN) :: degree ! Possible values are: - ! H5F_CLOSE_DEFAULT_F - ! H5F_CLOSE_WEAK_F - ! H5F_CLOSE_SEMI_F - ! H5F_CLOSE_STRONG_F - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: fapl_id + INTEGER, INTENT(IN) :: degree + ! H5F_CLOSE_STRONG_F + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_fclose_degree_c(fapl_id, degree) & BIND(C,NAME='h5pset_fclose_degree_c') @@ -2654,38 +1567,22 @@ CONTAINS hdferr = h5pset_fclose_degree_c(fapl_id, degree) END SUBROUTINE h5pset_fclose_degree_f -!****s* H5P/h5pequal_f -! NAME -! h5pequal_f -! -! PURPOSE -! Checks if two property lists are equal -! -! INPUTS -! -! plist1_id - property list identifier -! plist2_id - property list identifier -! OUTPUTS -! -! flag - flag, possible values -! .TRUE. or .FALSE. -! hdferr: - error code -! Success: 0 -! Failure: -1, flag is set to .FALSE. -! -! AUTHOR -! Elena Pourmal -! September 30, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Checks if two property lists are equal +!! +!! \param plist1_id Property list identifier. +!! \param plist2_id Property list identifier. +!! \param flag Flag, Possible values: .TRUE. or .FALSE. +!! \param hdferr: \fortran_error and flag is set to .FALSE. +!! SUBROUTINE h5pequal_f(plist1_id, plist2_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist1_id ! Property list identifier - INTEGER(HID_T), INTENT(IN) :: plist2_id ! Property list identifier - LOGICAL, INTENT(OUT) :: flag ! Flag - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist1_id + INTEGER(HID_T), INTENT(IN) :: plist2_id + LOGICAL, INTENT(OUT) :: flag + INTEGER, INTENT(OUT) :: hdferr INTEGER :: c_flag INTERFACE @@ -2704,36 +1601,20 @@ CONTAINS IF (c_flag .GT. 0) flag = .TRUE. END SUBROUTINE h5pequal_f -!****s* H5P/h5pset_buffer_f -! NAME -! h5pset_buffer_f -! -! PURPOSE -! Sets sixe for conversion buffer -! -! INPUTS -! plist_id - data transfer property list identifier -! size - buffer size -! OUTPUTS -! -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 2, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets sixe for conversion buffer +!! +!! \param plist_id Data transfer property list identifier. +!! \param size Buffer size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_buffer_f(plist_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Data transfer property list identifier - INTEGER(HSIZE_T), INTENT(IN) :: size ! Buffer size in bytes; - ! buffer is allocated and freed by - ! the library. - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER(HSIZE_T), INTENT(IN) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_buffer_c(plist_id, size) & @@ -2748,37 +1629,20 @@ CONTAINS hdferr = h5pset_buffer_c(plist_id, size) END SUBROUTINE h5pset_buffer_f -!****s* H5P/h5pget_buffer_f -! NAME -! h5pget_buffer_f -! -! PURPOSE -! Gets size for conversion buffer -! -! INPUTS -! -! plist_id - data transfer property list identifier -! OUTPUTS -! -! size - buffer size -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 2, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Gets size for conversion buffer +!! +!! \param plist_id Data transfer property list identifier. +!! \param size Buffer size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_buffer_f(plist_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Data transfer property list identifier - INTEGER(HSIZE_T), INTENT(OUT) :: size ! Buffer size in bytes; - ! buffer is allocated and freed by - ! the library. - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER(HSIZE_T), INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_buffer_c(plist_id, size) & @@ -2793,44 +1657,25 @@ CONTAINS hdferr = h5pget_buffer_c(plist_id, size) END SUBROUTINE h5pget_buffer_f -!****s* H5P/h5pfill_value_defined_f -! NAME -! h5pfill_value_defined_f -! -! PURPOSE -! Check if fill value is defined. -! -! INPUTS -! -! plist_id - dataset creation property list identifier -! OUTPUTS -! -! flag - fill value status flag -! Possible values are: -! H5D_FILL_VALUE_ERROR_F -! H5D_FILL_VALUE_UNDEFINED_F -! H5D_FILL_VALUE_DEFAULT_F -! H5D_FILL_VALUE_USER_DEFINED_F -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 4, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Check if fill value is defined. +!! +!! \param plist_id Dataset creation property list identifier. +!! \param flag Fill value status flag. Possible values are: +!! \li H5D_FILL_VALUE_ERROR_F +!! \li H5D_FILL_VALUE_UNDEFINED_F +!! \li H5D_FILL_VALUE_DEFAULT_F +!! \li H5D_FILL_VALUE_USER_DEFINED_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pfill_value_defined_f(plist_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property list identifier - INTEGER, INTENT(OUT) :: flag ! Fill value status flag - ! H5D_FILL_VALUE_ERROR_F - ! H5D_FILL_VALUE_UNDEFINED_F - ! H5D_FILL_VALUE_DEFAULT_F + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER, INTENT(OUT) :: flag ! H5D_FILL_VALUE_USER_DEFINED_F - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pfill_value_defined_c(plist_id, flag) & BIND(C,NAME='h5pfill_value_defined_c') @@ -2844,45 +1689,25 @@ CONTAINS hdferr = h5pfill_value_defined_c(plist_id, flag) END SUBROUTINE h5pfill_value_defined_f -!****s* H5P/h5pset_alloc_time_f -! NAME -! h5pset_alloc_time_f -! -! PURPOSE -! Set space allocation time for dataset during creation. -! -! INPUTS -! -! plist_id - dataset creation property list identifier -! flag - allocation time flag: -! H5D_ALLOC_TIME_ERROR_F -! H5D_ALLOC_TIME_DEFAULT_F -! H5D_ALLOC_TIME_EARLY_F -! H5D_ALLOC_TIME_LATE_F -! H5D_ALLOC_TIME_INCR_F -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 4, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Set space allocation time for dataset during creation. +!! +!! \param plist_id Dataset creation property list identifier. +!! \param flag Allocation time flag: Possible values are: +!! \li H5D_ALLOC_TIME_ERROR_F +!! \li H5D_ALLOC_TIME_DEFAULT_F +!! \li H5D_ALLOC_TIME_EARLY_F +!! \li H5D_ALLOC_TIME_LATE_F +!! \li H5D_ALLOC_TIME_INCR_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_alloc_time_f(plist_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property list identifier - INTEGER, INTENT(IN) :: flag ! Allocation time flag: - ! H5D_ALLOC_TIME_ERROR_F - ! H5D_ALLOC_TIME_DEFAULT_F - ! H5D_ALLOC_TIME_EARLY_F - ! H5D_ALLOC_TIME_LATE_F - ! H5D_ALLOC_TIME_INCR_F - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER, INTENT(IN) :: flag + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_alloc_time_c(plist_id, flag) & @@ -2897,45 +1722,25 @@ CONTAINS hdferr = h5pset_alloc_time_c(plist_id, flag) END SUBROUTINE h5pset_alloc_time_f -!****s* H5P/h5pget_alloc_time_f -! NAME -! h5pget_alloc_time_f -! -! PURPOSE -! Get space allocation time for dataset during creation. -! -! INPUTS -! -! plist_id - dataset creation property list identifier -! OUTPUTS -! -! flag - allocation time flag: -! H5D_ALLOC_TIME_ERROR_F -! H5D_ALLOC_TIME_DEFAULT_F -! H5D_ALLOC_TIME_EARLY_F -! H5D_ALLOC_TIME_LATE_F -! H5D_ALLOC_TIME_INCR_F -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 4, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Get space allocation time for dataset during creation. +!! +!! \param plist_id Dataset creation property list identifier. +!! \param flag Allocation time flag. Possible values are: +!! \li H5D_ALLOC_TIME_ERROR_F +!! \li H5D_ALLOC_TIME_DEFAULT_F +!! \li H5D_ALLOC_TIME_EARLY_F +!! \li H5D_ALLOC_TIME_LATE_F +!! \li H5D_ALLOC_TIME_INCR_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_alloc_time_f(plist_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property list identifier - INTEGER, INTENT(OUT) :: flag ! Allocation time flag: - ! H5D_ALLOC_TIME_ERROR_F - ! H5D_ALLOC_TIME_DEFAULT_F - ! H5D_ALLOC_TIME_EARLY_F - ! H5D_ALLOC_TIME_LATE_F - ! H5D_ALLOC_TIME_INCR_F - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER, INTENT(OUT) :: flag + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_alloc_time_c(plist_id, flag) & @@ -2950,41 +1755,23 @@ CONTAINS hdferr = h5pget_alloc_time_c(plist_id, flag) END SUBROUTINE h5pget_alloc_time_f -!****s* H5P/h5pset_fill_time_f -! NAME -! h5pset_fill_time_f -! -! PURPOSE -! Set fill value writing time for dataset -! -! INPUTS -! -! plist_id - dataset creation property list identifier -! flag - fill time flag: -! H5D_FILL_TIME_ERROR_F -! H5D_FILL_TIME_ALLOC_F -! H5D_FILL_TIME_NEVER_F -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 4, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Set fill value writing time for dataset +!! +!! \param plist_id Dataset creation property list identifier. +!! \param flag Fill time flag: Possible values are: +!! \li H5D_FILL_TIME_ERROR_F +!! \li H5D_FILL_TIME_ALLOC_F +!! \li H5D_FILL_TIME_NEVER_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fill_time_f(plist_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property list identifier - INTEGER, INTENT(IN) :: flag ! Fill time flag: - ! H5D_FILL_TIME_ERROR_F - ! H5D_FILL_TIME_ALLOC_F - ! H5D_FILL_TIME_NEVER_F - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER, INTENT(IN) :: flag + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_fill_time_c(plist_id, flag) & @@ -2999,42 +1786,24 @@ CONTAINS hdferr = h5pset_fill_time_c(plist_id, flag) END SUBROUTINE h5pset_fill_time_f -!****s* H5P/h5pget_fill_time_f -! NAME -! h5pget_fill_time_f -! -! PURPOSE -! Get fill value writing time for dataset -! -! INPUTS -! -! plist_id - dataset creation property list identifier -! OUTPUTS -! -! hdferr: - error code -! Success: 0 -! Failure: -1 -! OPTIONAL PARAMETERS -! -! flag - fill time flag: -! H5D_FILL_TIME_ERROR_F -! H5D_FILL_TIME_ALLOC_F -! H5D_FILL_TIME_NEVER_F -! AUTHOR -! Elena Pourmal -! October 4, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Get fill value writing time for dataset +!! +!! \param plist_id Dataset creation property list identifier. +!! +!! \param flag Fill time flag. Possible values are: +!! \li H5D_FILL_TIME_ERROR_F +!! \li H5D_FILL_TIME_ALLOC_F +!! \li H5D_FILL_TIME_NEVER_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_fill_time_f(plist_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property list identifier - INTEGER, INTENT(OUT) :: flag ! Fill time flag: - ! H5D_FILL_TIME_ERROR_F - ! H5D_FILL_TIME_ALLOC_F - ! H5D_FILL_TIME_NEVER_F - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER, INTENT(OUT) :: flag + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_fill_time_c(plist_id, flag) & @@ -3049,35 +1818,20 @@ CONTAINS hdferr = h5pget_fill_time_c(plist_id, flag) END SUBROUTINE h5pget_fill_time_f -!****s* H5P/ h5pset_meta_block_size_f -! NAME -! h5pset_meta_block_size_f -! -! PURPOSE -! Sets the minimum size of metadata block allocations -! -! INPUTS -! -! plist_id - file access property list identifier -! size - metadata block size -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 7, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the minimum size of metadata block allocations +!! +!! \param plist_id File access property list identifier. +!! \param size Metadata block size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_meta_block_size_f(plist_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list identifier - INTEGER(HSIZE_T), INTENT(IN) :: size ! Block size in bytes; - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER(HSIZE_T), INTENT(IN) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_meta_block_size_c(plist_id, size) & BIND(C,NAME='h5pset_meta_block_size_c') @@ -3091,35 +1845,20 @@ CONTAINS hdferr = h5pset_meta_block_size_c(plist_id, size) END SUBROUTINE h5pset_meta_block_size_f -!****s* H5P/h5pget_meta_block_size_f -! NAME -! h5pget_meta_block_size_f -! -! PURPOSE -! Gets the minimum size of metadata block allocations -! -! INPUTS -! -! plist_id - file access property list identifier -! OUTPUTS -! -! size - metadata block size -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 7, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Gets the minimum size of metadata block allocations +!! +!! \param plist_id File access property list identifier. +!! \param size Metadata block size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_meta_block_size_f(plist_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list identifier - INTEGER(HSIZE_T), INTENT(OUT) :: size ! Block size in bytes; - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER(HSIZE_T), INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_meta_block_size_c(plist_id, size) & BIND(C,NAME='h5pget_meta_block_size_c') @@ -3133,35 +1872,20 @@ CONTAINS hdferr = h5pget_meta_block_size_c(plist_id, size) END SUBROUTINE h5pget_meta_block_size_f -!****s* H5P/h5pset_sieve_buf_size_f -! NAME -! h5pset_sieve_buf_size_f -! -! PURPOSE -! Sets the maximum size of the data sieve buffer -! -! INPUTS -! -! plist_id - file access property list identifier -! size - sieve buffer size -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 7, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the maximum size of the data sieve buffer +!! +!! \param plist_id File access property list identifier. +!! \param size Sieve buffer size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_sieve_buf_size_f(plist_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list identifier - INTEGER(SIZE_T), INTENT(IN) :: size ! Buffer size in bytes; - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER(SIZE_T), INTENT(IN) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_sieve_buf_size_c(plist_id, size) & BIND(C,NAME='h5pset_sieve_buf_size_c') @@ -3175,35 +1899,20 @@ CONTAINS hdferr = h5pset_sieve_buf_size_c(plist_id, size) END SUBROUTINE h5pset_sieve_buf_size_f -!****s* H5P/h5pget_sieve_buf_size_f -! NAME -! h5pget_sieve_buf_size_f -! -! PURPOSE -! Gets the maximum size of the data sieve buffer -! -! INPUTS -! -! plist_id - file access property list identifier -! OUTPUTS -! -! size - sieve buffer size -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 7, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Gets the maximum size of the data sieve buffer +!! +!! \param plist_id File access property list identifier. +!! \param size Sieve buffer size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_sieve_buf_size_f(plist_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list identifier - INTEGER(SIZE_T), INTENT(OUT) :: size ! Buffer size in bytes - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER(SIZE_T), INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_sieve_buf_size_c(plist_id, size) & BIND(C,NAME='h5pget_sieve_buf_size_c') @@ -3217,35 +1926,20 @@ CONTAINS hdferr = h5pget_sieve_buf_size_c(plist_id, size) END SUBROUTINE h5pget_sieve_buf_size_f -!****s* H5P/h5pset_small_data_block_size_f -! NAME -! h5pset_small_data_block_size_f -! -! PURPOSE -! Sets the minimum size of "small" raw data block -! -! INPUTS -! -! plist_id - file access property list identifier -! size - small raw data block size -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 7, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the minimum size of "small" raw data block +!! +!! \param plist_id File access property list identifier. +!! \param size Small raw data block size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_small_data_block_size_f(plist_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list identifier - INTEGER(HSIZE_T), INTENT(IN) :: size ! Small raw data block size - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER(HSIZE_T), INTENT(IN) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_small_data_block_size_c(plist_id, size) & BIND(C,NAME='h5pset_small_data_block_size_c') @@ -3259,35 +1953,20 @@ CONTAINS hdferr = h5pset_small_data_block_size_c(plist_id, size) END SUBROUTINE h5pset_small_data_block_size_f -!****s* H5P/h5pget_small_data_block_size_f -! NAME -! h5pget_small_data_block_size_f -! -! PURPOSE -! Gets the minimum size of "small" raw data block -! -! INPUTS -! -! plist_id - file access property list identifier -! OUTPUTS -! -! size - small raw data block size -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 7, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Gets the minimum size of "small" raw data block +!! +!! \param plist_id File access property list identifier. +!! \param size Small raw data block size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_small_data_block_size_f(plist_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list identifier - INTEGER(HSIZE_T), INTENT(OUT) :: size ! Small raw data block size - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER(HSIZE_T), INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_small_data_block_size_c(plist_id, size) & BIND(C,NAME='h5pget_small_data_block_size_c') @@ -3301,35 +1980,20 @@ CONTAINS hdferr = h5pget_small_data_block_size_c(plist_id, size) END SUBROUTINE h5pget_small_data_block_size_f -!****s* H5P/h5pset_hyper_vector_size_f -! NAME -! h5pset_hyper_vector_size_f -! -! PURPOSE -! Set the number of "I/O" vectors (vector size) -! -! INPUTS -! -! plist_id - dataset transfer property list identifier -! size - vector size -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 7, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Set the number of "I/O" vectors (vector size) +!! +!! \param plist_id Dataset transfer property list identifier. +!! \param size Vector size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_hyper_vector_size_f(plist_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset transfer property list identifier - INTEGER(SIZE_T), INTENT(IN) :: size ! Vector size - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER(SIZE_T), INTENT(IN) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_hyper_vector_size_c(plist_id, size) & BIND(C,NAME='h5pset_hyper_vector_size_c') @@ -3343,35 +2007,20 @@ CONTAINS hdferr = h5pset_hyper_vector_size_c(plist_id, size) END SUBROUTINE h5pset_hyper_vector_size_f -!****s* H5P/ h5pget_hyper_vector_size_f -! NAME -! h5pget_hyper_vector_size_f -! -! PURPOSE -! Get the number of "I/O" vectors (vector size) -! -! INPUTS -! -! plist_id - dataset transfer property list identifier -! OUTPUTS -! -! size - vector size -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 7, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Get the number of "I/O" vectors (vector size) +!! +!! \param plist_id Dataset transfer property list identifier. +!! \param size Vector size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_hyper_vector_size_f(plist_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset transfer property list identifier - INTEGER(SIZE_T), INTENT(OUT) :: size ! Vector size - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER(SIZE_T), INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_hyper_vector_size_c(plist_id, size) & BIND(C,NAME='h5pget_hyper_vector_size_c') @@ -3385,37 +2034,22 @@ CONTAINS hdferr = h5pget_hyper_vector_size_c(plist_id, size) END SUBROUTINE h5pget_hyper_vector_size_f -!****s* H5P/h5pexist_f -! NAME -! h5pexist_f -! -! PURPOSE -! Queries whether a property name exists in a property list or class. -! -! INPUTS -! -! prp_id - property list identifier to query -! name - name of property to check for -! OUTPUTS -! -! flag - logical flag -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Queries whether a property name exists in a property list or class. +!! +!! \param prp_id Property list identifier to query. +!! \param name Name of property to check for. +!! \param flag Logical flag. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pexist_f(prp_id, name, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to modify - LOGICAL, INTENT(OUT) :: flag ! .TRUE. if exists, .FALSE. otherwise - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + LOGICAL, INTENT(OUT) :: flag + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len INTERFACE @@ -3438,41 +2072,22 @@ CONTAINS ENDIF END SUBROUTINE h5pexist_f -!****s* H5P/h5pget_size_f -! -! NAME -! h5pget_size_f -! -! PURPOSE -! Queries the size of a property value in bytes. -! -! INPUTS -! -! prp_id - property list identifier to query -! name - name of property to query -! OUTPUTS -! -! size - size of property in bytes -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! HISTORY -! -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Queries the size of a property value in bytes. +!! +!! \param prp_id Property list identifier to query. +!! \param name Name of property to query. +!! \param size Size of property in bytes. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_size_f(prp_id, name, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to query - INTEGER(SIZE_T), INTENT(OUT) :: size ! Size in bytes - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T), INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len INTERFACE @@ -3491,35 +2106,20 @@ CONTAINS hdferr = h5pget_size_c(prp_id, name , name_len, size) END SUBROUTINE h5pget_size_f -!****s* H5P/h5pget_npros_f -! NAME -! h5pget_npros_f -! -! PURPOSE -! Queries number of properties in property list or class -! -! INPUTS -! -! prp_id - iproperty list identifier to query -! OUTPUTS -! -! nprops - number of properties in property object -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Queries number of properties in property list or class +!! +!! \param prp_id Iproperty list identifier to query. +!! \param nprops Number of properties in property object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_nprops_f(prp_id, nprops, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(SIZE_T), INTENT(OUT) :: nprops ! Number of properties - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(SIZE_T), INTENT(OUT) :: nprops + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_nprops_c(prp_id, nprops) & BIND(C,NAME='h5pget_nprops_c') @@ -3532,43 +2132,24 @@ CONTAINS hdferr = h5pget_nprops_c(prp_id, nprops) END SUBROUTINE h5pget_nprops_f -!****s* H5P/h5pget_class_name_f -! NAME -! h5pget_class_name_f -! -! PURPOSE -! Queries the name of a class. -! -! INPUTS -! -! prp_id - property list identifier to query -! OUTPUTS -! -! name - name of a class -! size - Actual length of the class name -! NOTE: If provided buffer "name" is smaller, -! than name will be truncated to fit into -! provided user buffer. -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! HISTORY -! Returned the size of name as an argument -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Queries the name of a class. +!! +!! \param prp_id Property list identifier to query. +!! \param name Name of a class. +!! \param size Actual length of the class name. +!! NOTE: If provided buffer "name" is smaller, than name will be +!! truncated to fit into provided user buffer. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_class_name_f(prp_id, name, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - CHARACTER(LEN=*), INTENT(OUT) :: name ! Buffer to retrieve class name - INTEGER, INTENT(OUT) :: size ! Actual length of the class name - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(OUT) :: name + INTEGER, INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len INTERFACE @@ -3591,36 +2172,20 @@ CONTAINS END SUBROUTINE h5pget_class_name_f -!****s* H5P/h5pget_class_parent_f -! NAME -! h5pget_class_parent_f -! -! PURPOSE -! Retrieves the parent class of a generic property class. -! -! INPUTS -! -! prp_id - property list identifier to query -! OUTPUTS -! -! parent_id - identifier of the parent class -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the parent class of a generic property class. +!! +!! \param prp_id Property list identifier to query. +!! \param parent_id Identifier of the parent class. +!! \param hdferr: \fortran_error +!! SUBROUTINE h5pget_class_parent_f(prp_id, parent_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HID_T), INTENT(OUT) :: parent_id ! Parent class property list - ! identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(OUT) :: parent_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_class_parent_c(prp_id, parent_id) & BIND(C,NAME='h5pget_class_parent_c') @@ -3633,37 +2198,22 @@ CONTAINS hdferr = h5pget_class_parent_c(prp_id, parent_id) END SUBROUTINE h5pget_class_parent_f -!****s* H5P/h5pisa_class_f -! NAME -! h5pisa_class_f -! -! PURPOSE -! Determines whether a property list is a member of a class. -! -! INPUTS -! -! plist - property list identifier -! pclass - identifier of the property class -! OUTPUTS -! -! flag - .TRUE. if a member, .FALSE. otherwise -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Determines whether a property list is a member of a class. +!! +!! \param plist Property list identifier. +!! \param pclass Identifier of the property class. +!! \param flag TRUE. if a member, .FALSE. otherwise. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pisa_class_f(plist, pclass, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist ! Property list identifier - INTEGER(HID_T), INTENT(IN) :: pclass ! Class identifier - LOGICAL, INTENT(OUT) :: flag ! logical flag - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist + INTEGER(HID_T), INTENT(IN) :: pclass + LOGICAL, INTENT(OUT) :: flag + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pisa_class_c(plist, pclass) & BIND(C,NAME='h5pisa_class_c') @@ -3681,38 +2231,22 @@ CONTAINS ENDIF END SUBROUTINE h5pisa_class_f -!****s* H5P/h5pcopy_prop_f -! NAME -! h5pcopy_prop_f -! -! PURPOSE -! Copies a property from one list or class to another. -! -! INPUTS -! -! dst_id - Identifier of the destination property list -! src_id - Identifier of the source property list -! name - name of the property to copy -! OUTPUTS -! -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Copies a property from one list or class to another. +!! +!! \param dst_id Identifier of the destination property list. +!! \param src_id Identifier of the source property list. +!! \param name Name of the property to copy. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pcopy_prop_f(dst_id, src_id, name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dst_id ! Destination property list - ! identifier - INTEGER(HID_T), INTENT(IN) :: src_id ! Source property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Property name - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: dst_id + INTEGER(HID_T), INTENT(IN) :: src_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len INTERFACE @@ -3731,36 +2265,20 @@ CONTAINS hdferr = h5pcopy_prop_c(dst_id, src_id, name , name_len) END SUBROUTINE h5pcopy_prop_f -!****s* H5P/h5premove_f -! NAME -! h5premove_f -! -! PURPOSE -! Removes a property from a property list. - -! -! INPUTS -! -! plid - Property list identofoer -! name - name of the property to remove -! OUTPUTS -! -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Removes a property from a property list. +!! +!! \param plid Property list identofoer. +!! \param name Name of the property to remove. +!! \param hdferr \fortran_error +!! SUBROUTINE h5premove_f(plid, name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plid ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to remove - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plid + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len INTERFACE @@ -3778,35 +2296,20 @@ CONTAINS hdferr = h5premove_c(plid, name , name_len) END SUBROUTINE h5premove_f -!****s* H5P/h5punregister_f -! NAME -! h5punregister_f -! -! PURPOSE -! Removes a property from a property list class. -! -! INPUTS -! -! class - Property list class identifier -! name - name of the property to remove -! OUTPUTS -! -! hdferr: - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Removes a property from a property list class. +!! +!! \param class Property list class identifier. +!! \param name Name of the property to remove. +!! \param hdferr \fortran_error +!! SUBROUTINE h5punregister_f(class, name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: class ! property list class identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! name of property to remove - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: class + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len INTERFACE @@ -3824,33 +2327,18 @@ CONTAINS hdferr = h5punregister_c(class, name , name_len) END SUBROUTINE h5punregister_f -!****s* H5P/h5pclose_class_f -! NAME -! h5pclose_class_f -! -! PURPOSE -! Closes an existing property list class. -! -! INPUTS -! -! class - Property list class identifier -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Closes an existing property list class. +!! +!! \param class Property list class identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pclose_class_f(class, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: class ! Property list class identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: class + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pclose_class_c(class) & BIND(C,NAME='h5pclose_class_c') @@ -3862,31 +2350,18 @@ CONTAINS hdferr = h5pclose_class_c(class) END SUBROUTINE h5pclose_class_f -!****s* H5P/h5pset_shuffle_f -! NAME -! h5pset_shuffle_f -! -! PURPOSE -! Sets shuffling filter -! -! INPUTS -! prp_id - dataset creation property list identifier -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! March 12, 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets shuffling filter +!! +!! \param prp_id Dataset creation property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_shuffle_f(prp_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_shuffle_c(prp_id) & BIND(C,NAME='h5pset_shuffle_c') @@ -3899,36 +2374,22 @@ CONTAINS END SUBROUTINE h5pset_shuffle_f -!****s* H5P/h5pset_edc_check_f -! NAME -! h5pset_edc_check_f -! -! PURPOSE -! Enables/disables error detecting -! -! INPUTS -! -! prp_id - dataset creation property list identifier -! flag - EDC flag; possible values: -! H5Z_DISABLE_EDC_F -! H5Z_ENABLE_EDC_F -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! March 13, 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Enables/disables error detecting +!! +!! \param prp_id Dataset creation property list identifier. +!! \param flag EDC flag. Possible values: +!! \li H5Z_DISABLE_EDC_F +!! \li H5Z_ENABLE_EDC_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_edc_check_f(prp_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: flag ! Checksum filter flag - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: flag + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_edc_check_c(prp_id, flag) & BIND(C,NAME='h5pset_edc_check_c') @@ -3942,38 +2403,22 @@ CONTAINS END SUBROUTINE h5pset_edc_check_f -!****s* H5P/h5pget_edc_check_f -! NAME -! h5pget_edc_check_f -! -! PURPOSE -! Queries error detecting -! -! INPUTS -! -! prp_id - dataset creation property list identifier -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! March 13, 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Determines whether error-detection is enabled for dataset reads. +!! +!! \param prp_id Dataset creation property list identifier. +!! \param flag EDC flag; possible values: +!! \li H5Z_DISABLE_EDC_F +!! \li H5Z_ENABLE_EDC_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_edc_check_f(prp_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset transfer property list identifier - INTEGER, INTENT(OUT) :: flag ! Checksum filter flag - ! May have one of the following values: - ! H5Z_ERROR_EDC_F - ! H5Z_DISABLE_EDC_F - ! H5Z_ENABLE_EDC_F - ! H5Z_NO_EDC_F - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: flag + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_edc_check_c(prp_id, flag) & BIND(C,NAME='h5pget_edc_check_c') @@ -3987,33 +2432,18 @@ CONTAINS END SUBROUTINE h5pget_edc_check_f -!****s* H5P/h5pset_fletcher32_f -! NAME -! h5pset_fletcher32_f -! -! PURPOSE -! Sets Fletcher32 checksum of EDC for a dataset creation -! property list. -! -! INPUTS -! -! prp_id - dataset creation property list identifier -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! March 13, 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets Fletcher32 checksum of EDC for a dataset creation property list. +!! +!! \param prp_id Dataset creation property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fletcher32_f(prp_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_fletcher32_c(prp_id) & BIND(C,NAME='h5pset_fletcher32_c') @@ -4026,34 +2456,20 @@ CONTAINS END SUBROUTINE h5pset_fletcher32_f -!****s* H5P/ h5pset_family_offset_f -! NAME -! h5pset_family_offset_f -! -! PURPOSE -! Sets offset for family file driver. -! -! INPUTS -! -! prp_id - file creation property list identifier -! offset - file offset -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! 19 March 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets offset for family file driver. +!! +!! \param prp_id File creation property list identifier. +!! \param offset File offset. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_family_offset_f(prp_id, offset, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HSIZE_T), INTENT(IN) :: offset ! Offset in bytes - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HSIZE_T), INTENT(IN) :: offset + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_family_offset_c(prp_id, offset) & BIND(C,NAME='h5pset_family_offset_c') @@ -4067,30 +2483,47 @@ CONTAINS END SUBROUTINE h5pset_family_offset_f -!****s* H5P/h5pset_fapl_multi_l -! NAME -! h5pset_fapl_multi_l -! -! PURPOSE -! Sets up use of the multi-file driver. -! -! INPUTS -! -! prp_id - file creation property list identifier -! mem_map - mapping array -! memb_fapl - property list for each memory usage type -! memb_name - names of member file -! relax - flag -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! 20 March 2003 -! -! Fortran90 Interface: +#ifdef H5_DOXYGEN_FORTRAN + +!> +!! \ingroup FH5P +!! +!! \brief Sets up use of the multi-file driver. +!! +!! \param prp_id File creation property list identifier. +!! \param memb_map Mapping array. +!! \param memb_fapl Property list for each memory usage type. +!! \param memb_name Names of member file. +!! \param memb_addr Offsets within the virtual address space, from 0 (zero) to HADDR_MAX_F, at which each type of data storage begins. +!! \param relax Flag. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pset_fapl_multi_l(prp_id, memb_map, memb_fapl, memb_name, memb_addr, relax, hdferr) + IMPLICIT NONE + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, DIMENSION(*), INTENT(IN) :: memb_map + INTEGER(HID_T), DIMENSION(*), INTENT(IN) :: memb_fapl + CHARACTER(LEN=*), DIMENSION(*), INTENT(IN) :: memb_name + REAL, DIMENSION(*), INTENT(IN) :: memb_addr + LOGICAL, INTENT(IN) :: relax + INTEGER, INTENT(OUT) :: hdferr + END SUBROUTINE h5pset_fapl_multi_l + +#else + +!> +!! \ingroup FH5P +!! +!! \brief Sets up use of the multi-file driver. +!! +!! \param prp_id File creation property list identifier. +!! \param memb_map Mapping array. +!! \param memb_fapl Property list for each memory usage type. +!! \param memb_name Names of member file. +!! \param memb_addr Offsets within the virtual address space, from 0 (zero) to HADDR_MAX_F, at which each type of data storage begins. +!! \param relax Flag. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fapl_multi_l(prp_id, memb_map, memb_fapl, memb_name, memb_addr, relax, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id @@ -4100,7 +2533,6 @@ CONTAINS REAL, DIMENSION(*), INTENT(IN) :: memb_addr LOGICAL, INTENT(IN) :: relax INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER, DIMENSION(1:H5FD_MEM_NTYPES_F) :: lenm INTEGER :: maxlen INTEGER :: flag = 0 @@ -4113,7 +2545,7 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! File creation property list identifier + INTEGER(HID_T), INTENT(IN) :: prp_id INTEGER, DIMENSION(*), INTENT(IN) :: memb_map INTEGER(HID_T), DIMENSION(*), INTENT(IN) :: memb_fapl CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: memb_name @@ -4132,34 +2564,20 @@ CONTAINS hdferr = h5pset_fapl_multi_c(prp_id, memb_map, memb_fapl, memb_name, lenm, maxlen, memb_addr, flag) END SUBROUTINE h5pset_fapl_multi_l -!****s* H5P/h5pset_fapl_multi_s -! NAME -! h5pset_fapl_multi_s -! -! PURPOSE -! Sets up use of the multi-file driver. -! -! INPUTS -! -! prp_id - file creation property list identifier -! relax - flag -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! 31 March 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets up use of the multi-file driver. +!! +!! \param prp_id File creation property list identifier. +!! \param relax Flag. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fapl_multi_s(prp_id, relax, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! File creation property list identifier + INTEGER(HID_T), INTENT(IN) :: prp_id LOGICAL, INTENT(IN) :: relax - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER, INTENT(OUT) :: hdferr INTEGER :: flag INTERFACE @@ -4167,7 +2585,7 @@ CONTAINS BIND(C,NAME='h5pset_fapl_multi_sc') IMPORT :: HID_T IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! File creation property list identifier + INTEGER(HID_T), INTENT(IN) :: prp_id INTEGER, INTENT(IN) :: flag END FUNCTION h5pset_fapl_multi_sc END INTERFACE @@ -4176,52 +2594,37 @@ CONTAINS hdferr = h5pset_fapl_multi_sc(prp_id, flag) END SUBROUTINE h5pset_fapl_multi_s -!****s* H5P/h5pget_fapl_multi_f -! NAME -! h5pget_fapl_multi_f -! -! PURPOSE -! Sets up use of the multi-file driver. -! -! INPUTS -! -! prp_id - file creation property list identifier -! OUTPUTS -! -! mem_map - mapping array -! memb_fapl - property list for each memory usage type -! memb_name - names of member file -! relax - flag -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! OPTIONAL PARAMETERS -! maxlen_out - maximum length for memb_name array element -! -! AUTHOR -! Elena Pourmal -! 24 March 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets up use of the multi-file driver. +!! +!! \param prp_id File creation property list identifier. +!! \param memb_map Mapping array. +!! \param memb_fapl Property list for each memory usage type. +!! \param memb_name Names of member file. +!! \param memb_addr Offsets within the virtual address space, from 0 (zero) to HADDR_MAX_F, at which each type of data storage begins. +!! \param relax Flag. +!! \param hdferr \fortran_error +!! \param maxlen_out Maximum length for memb_name array element. +!! SUBROUTINE h5pget_fapl_multi_f(prp_id, memb_map, memb_fapl, memb_name, memb_addr, relax, hdferr, maxlen_out) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! File creation property list identifier + INTEGER(HID_T), INTENT(IN) :: prp_id INTEGER, DIMENSION(*), INTENT(OUT) :: memb_map INTEGER(HID_T), DIMENSION(*), INTENT(OUT) :: memb_fapl CHARACTER(LEN=*), DIMENSION(*), INTENT(OUT) :: memb_name REAL, DIMENSION(*), INTENT(OUT) :: memb_addr INTEGER, OPTIONAL, INTENT(OUT) :: maxlen_out LOGICAL, INTENT(OUT) :: relax - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER, INTENT(OUT) :: hdferr + INTEGER, DIMENSION(1:H5FD_MEM_NTYPES_F) :: lenm INTEGER :: maxlen INTEGER :: c_maxlen_out INTEGER :: flag INTEGER :: i -! + INTERFACE INTEGER FUNCTION h5pget_fapl_multi_c(prp_id, memb_map, memb_fapl, memb_name, lenm, & maxlen, memb_addr, flag, c_maxlen_out) & @@ -4229,7 +2632,7 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! File creation property list identifier + INTEGER(HID_T), INTENT(IN) :: prp_id INTEGER, DIMENSION(*), INTENT(OUT) :: memb_map INTEGER(HID_T), DIMENSION(*), INTENT(OUT) :: memb_fapl CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(OUT) :: memb_name @@ -4251,51 +2654,32 @@ CONTAINS IF(flag .EQ. 0) relax = .FALSE. IF(PRESENT(maxlen_out)) maxlen_out = c_maxlen_out END SUBROUTINE h5pget_fapl_multi_f -!****s* H5P/h5pset_szip_f -! NAME -! h5pset_szip_f -! -! PURPOSE -! Sets up use of szip compression -! -! INPUTS -! -! prp_id - dataset creation property list identifier -! options_mask - A bit-mask conveying the desired SZIP options. -! Current valid values in Fortran are: -! H5_SZIP_EC_OM_F -! H5_SZIP_NN_OM_F -! pixels_per_block - szip parameters -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! April 10 2003 -! -! Fortran90 Interface: +#endif +!> +!! \ingroup FH5P +!! +!! \brief Sets up use of szip compression +!! +!! \param prp_id Dataset creation property list identifier. +!! \param options_mask A bit-mask conveying the desired SZIP options. Current valid values in Fortran are: +!! \li H5_SZIP_EC_OM_F +!! \li H5_SZIP_NN_OM_F +!! \param pixels_per_block Szip parameters. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_szip_f(prp_id, options_mask, pixels_per_block, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset creation property - ! list identifier - INTEGER, INTENT(IN) :: options_mask ! A bit-mask conveying the desired - ! SZIP options - ! Current valid values in Fortran are: - ! H5_SZIP_EC_OM_F + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: options_mask ! H5_SZIP_NN_OM_F - INTEGER, INTENT(IN) :: pixels_per_block ! The number of pixels or data elements - ! in each data block - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER, INTENT(IN) :: pixels_per_block + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_szip_c(prp_id, options_mask, pixels_per_block) & BIND(C,NAME='h5pset_szip_c') IMPORT :: HID_T IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! File creation property list identifier + INTEGER(HID_T), INTENT(IN) :: prp_id INTEGER, INTENT(IN) :: options_mask INTEGER, INTENT(IN) :: pixels_per_block END FUNCTION h5pset_szip_c @@ -4304,39 +2688,20 @@ CONTAINS END SUBROUTINE h5pset_szip_f -!****s* H5P/h5pall_filters_avail_f -! NAME -! h5pall_filters_avail_f -! -! PURPOSE -! Checks if all filters set in the dataset creation -! property list are available -! -! INPUTS -! -! prp_id - data creation property list identifier -! OUTPUTS -! -! flag - .TRUE. if all filters are available -! .FALSE. otherwise -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! April 10 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Checks if all filters set in the dataset creation property list are available. +!! +!! \param prp_id Data creation property list identifier. +!! \param flag .TRUE. if all filters are available, .FALSE. otherwise. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pall_filters_avail_f(prp_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset creation property - ! list identifier - LOGICAL, INTENT(OUT) :: flag ! .TRUE. if all filters are available - ! .FALSE. otherwise - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + LOGICAL, INTENT(OUT) :: flag + INTEGER, INTENT(OUT) :: hdferr INTEGER :: status INTERFACE @@ -4354,48 +2719,30 @@ CONTAINS END SUBROUTINE h5pall_filters_avail_f -!****s* H5P/h5pget_filter_by_id_f -! NAME -! h5pget_filter_by_id_f -! -! PURPOSE -! Returns information about a filter in a pipeline -! -! INPUTS -! -! prp_id - data creation or transfer property list -! identifier -! OUTPUTS -! -! filter_id - filter identifier -! flags - bit vector specifying certain general -! properties of the filter -! cd_nelmts - number of elements in cd_values -! cd_values - auxiliary data for the filter -! namelen - number of characters in the name buffer -! name - buffer to retrieve filter name -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! April 10 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns information about a filter in a pipeline +!! +!! \param prp_id Data creation or transfer property list identifier +!! \param filter_id Filter identifier. +!! \param flags Bit vector specifying certain general properties of the filter +!! \param cd_nelmts Number of elements in cd_values. +!! \param cd_values Auxiliary data for the filter. +!! \param namelen Number of characters in the name buffer. +!! \param name Buffer to retrieve filter name. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_filter_by_id_f(prp_id, filter_id, flags, cd_nelmts, cd_values, namelen, name, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: filter_id ! Filter identifier - INTEGER(SIZE_T), INTENT(INOUT) :: cd_nelmts ! Number of elements in cd_values. - INTEGER, DIMENSION(*), INTENT(OUT) :: cd_values ! Auxiliary data for the filter. - INTEGER, INTENT(OUT) :: flags ! Bit vector specifying certain general - ! properties of the filter. - INTEGER(SIZE_T), INTENT(IN) :: namelen ! Anticipated number of characters in name. - CHARACTER(LEN=*), INTENT(OUT) :: name ! Name of the filter - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: filter_id + INTEGER(SIZE_T), INTENT(INOUT) :: cd_nelmts + INTEGER, DIMENSION(*), INTENT(OUT) :: cd_values + INTEGER, INTENT(OUT) :: flags + INTEGER(SIZE_T), INTENT(IN) :: namelen + CHARACTER(LEN=*), INTENT(OUT) :: name + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_filter_by_id_c(prp_id, filter_id, flags, cd_nelmts, & cd_values, namelen, name) & @@ -4417,43 +2764,26 @@ CONTAINS cd_values, namelen, name) END SUBROUTINE h5pget_filter_by_id_f -!****s* H5P/h5pmodify_filter_f -! NAME -! h5pmodify_filter_f -! -! PURPOSE -! Adds a filter to the filter pipeline. -! -! INPUTS -! -! prp_id - data creation or transfer property list -! identifier -! filter - filter to be modified -! flags - bit vector specifying certain general -! properties of the filter -! cd_nelmts - number of elements in cd_values -! cd_values - auxiliary data for the filter -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! April 10 2003 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Adds a filter to the filter pipeline. +!! +!! \param prp_id Data creation or transfer property list identifier +!! \param filter Filter to be modified. +!! \param flags Bit vector specifying certain general properties of the filter +!! \param cd_nelmts Number of elements in cd_values. +!! \param cd_values Auxiliary data for the filter. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pmodify_filter_f(prp_id, filter, flags, cd_nelmts, cd_values, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: filter ! Filter to be modified - INTEGER, INTENT(IN) :: flags ! Bit vector specifying certain general - ! properties of the filter - INTEGER(SIZE_T), INTENT(IN) :: cd_nelmts ! Number of elements in cd_values - INTEGER, DIMENSION(*), INTENT(IN) :: cd_values ! Auxiliary data for the filter - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: filter + INTEGER, INTENT(IN) :: flags + INTEGER(SIZE_T), INTENT(IN) :: cd_nelmts + INTEGER, DIMENSION(*), INTENT(IN) :: cd_values + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pmodify_filter_c(prp_id, filter, flags, cd_nelmts, cd_values) & BIND(C,NAME='h5pmodify_filter_c') @@ -4470,36 +2800,20 @@ CONTAINS hdferr = h5pmodify_filter_c(prp_id, filter, flags, cd_nelmts, cd_values ) END SUBROUTINE h5pmodify_filter_f -!****s* H5P/h5premove_filter_f -! NAME -! h5premove_filter_f -! -! PURPOSE -! Delete one or more filters from the filter pipeline. -! -! INPUTS -! -! prp_id - data creation or transfer property list -! identifier -! filter - filter to be removed -! OUTPUTS -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Quincey Koziol -! January 27 2004 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Delete one or more filters from the filter pipeline. +!! +!! \param prp_id Data creation or transfer property list identifier +!! \param filter Filter to be removed. +!! \param hdferr \fortran_error +!! SUBROUTINE h5premove_filter_f(prp_id, filter, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset creation property list - ! identifier - INTEGER, INTENT(IN) :: filter ! Filter to be removed - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: filter + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5premove_filter_c(prp_id, filter) & BIND(C,NAME='h5premove_filter_c') @@ -4513,41 +2827,22 @@ CONTAINS hdferr = h5premove_filter_c(prp_id, filter) END SUBROUTINE h5premove_filter_f -!****s* H5P/H5Pget_attr_phase_change_f -! NAME -! H5Pget_attr_phase_change_f -! -! PURPOSE -! Retrieves attribute storage phase change thresholds -! -! INPUTS -! -! ocpl_id - Object (dataset or group) creation property list identifier -! OUTPUTS -! -! max_compact - Maximum number of attributes to be stored in compact storage -! (Default: 8) -! min_dense - Minimum number of attributes to be stored in dense storage -! (Default: 6) -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves attribute storage phase change thresholds +!! +!! \param ocpl_id Object (dataset or group) creation property list identifier. +!! \param max_compact Maximum number of attributes to be stored in compact storage (Default: 8). +!! \param min_dense Minimum number of attributes to be stored in dense storage (Default: 6). +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: ocpl_id ! Object (dataset or group) creation property list identifier - INTEGER, INTENT(OUT) :: max_compact ! Maximum number of attributes to be stored in compact storage - ! (Default: 8) - INTEGER, INTENT(OUT) :: min_dense ! Minimum number of attributes to be stored in dense storage - ! (Default: 6) - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: ocpl_id + INTEGER, INTENT(OUT) :: max_compact + INTEGER, INTENT(OUT) :: min_dense + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_attr_phase_change_c(ocpl_id, max_compact, min_dense) & BIND(C,NAME='h5pget_attr_phase_change_c') @@ -4563,35 +2858,20 @@ CONTAINS hdferr = h5pget_attr_phase_change_c(ocpl_id, max_compact, min_dense) END SUBROUTINE h5pget_attr_phase_change_f -!****s* H5P/H5Pset_attr_creation_order_f -! NAME -! H5Pset_attr_creation_order_f -! -! PURPOSE -! Sets tracking and indexing of attribute creation order -! -! INPUTS -! -! ocpl_id - Object creation property list identifier -! crt_order_flags - Flags specifying whether to track and index attribute creation order -! OUTPUTS -! -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets tracking and indexing of attribute creation order +!! +!! \param ocpl_id Object creation property list identifier. +!! \param crt_order_flags Flags specifying whether to track and index attribute creation order. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_attr_creation_order_f(ocpl_id, crt_order_flags , hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: ocpl_id ! Object (dataset or group) creation property list identifier - INTEGER, INTENT(IN) :: crt_order_flags ! Flags specifying whether to track and index attribute creation order - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: ocpl_id + INTEGER, INTENT(IN) :: crt_order_flags + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION H5Pset_attr_creation_order_c(ocpl_id, crt_order_flags) & BIND(C,NAME='h5pset_attr_creation_order_c') @@ -4606,37 +2886,20 @@ CONTAINS hdferr = H5Pset_attr_creation_order_c(ocpl_id, crt_order_flags) END SUBROUTINE h5pset_attr_creation_order_f -!****s* H5P/H5Pset_shared_mesg_nindexes_f -! NAME -! H5Pset_shared_mesg_nindexes_f -! -! PURPOSE -! Sets number of shared object header message indexes -! -! INPUTS -! -! plist_id - file creation property list -! nindexes - Number of shared object header message indexes to be available in files created with this property list -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets number of shared object header message indexes +!! +!! \param plist_id File creation property list. +!! \param nindexes Number of shared object header message indexes to be available in files created with this property list. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_shared_mesg_nindexes_f( plist_id, nindexes, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! File creation property list - INTEGER, INTENT(IN) :: nindexes ! Number of shared object header message indexes - ! available in files created WITH this property list - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** -! + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER, INTENT(IN) :: nindexes + INTEGER, INTENT(OUT) :: hdferr ! MS FORTRAN needs explicit interface for C functions called here. ! INTERFACE @@ -4654,41 +2917,24 @@ CONTAINS END SUBROUTINE h5pset_shared_mesg_nindexes_f -!****s* H5P/H5Pset_shared_mesg_index_f -! NAME -! H5Pset_shared_mesg_index_f -! -! PURPOSE -! Configures the specified shared object header message index -! -! INPUTS -! -! fcpl_id - File creation property list identifier. -! index_num - Index being configured. -! mesg_type_flags - Types of messages that should be stored in this index. -! min_mesg_size - Minimum message size. -! -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Configures the specified shared object header message index +!! +!! \param fcpl_id File creation property list identifier. +!! \param index_num Index being configured. +!! \param mesg_type_flags Types of messages that should be stored in this index. +!! \param min_mesg_size Minimum message size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_shared_mesg_index_f(fcpl_id, index_num, mesg_type_flags, min_mesg_size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: fcpl_id ! file creation property list - INTEGER, INTENT(IN) :: index_num ! Index being configured. - INTEGER, INTENT(IN) :: mesg_type_flags ! Types of messages that should be stored in this index. - INTEGER, INTENT(IN) :: min_mesg_size ! Minimum message size. - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** -! + INTEGER(HID_T), INTENT(IN) :: fcpl_id + INTEGER, INTENT(IN) :: index_num + INTEGER, INTENT(IN) :: mesg_type_flags + INTEGER, INTENT(IN) :: min_mesg_size + INTEGER, INTENT(OUT) :: hdferr ! MS FORTRAN needs explicit interface for C functions called here. ! INTERFACE @@ -4707,37 +2953,20 @@ CONTAINS END SUBROUTINE h5pset_shared_mesg_index_f -!****s* H5P/H5Pget_attr_creation_order_f -! NAME -! H5Pget_attr_creation_order_f -! -! PURPOSE -! Retrieves tracking and indexing settings for attribute creation order -! -! INPUTS -! -! ocpl_id - Object (group or dataset) creation property list identifier -! -! OUTPUTS -! -! crt_order_flags - Flags specifying whether to track and index attribute creation order -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! February, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves tracking and indexing settings for attribute creation order +!! +!! \param ocpl_id Object (group or dataset) creation property list identifier. +!! \param crt_order_flags Flags specifying whether to track and index attribute creation order. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_attr_creation_order_f(ocpl_id, crt_order_flags, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: ocpl_id ! Object (group or dataset) creation property list identifier - INTEGER, INTENT(OUT) :: crt_order_flags ! Flags specifying whether to track and index attribute creation order - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** -! + INTEGER(HID_T), INTENT(IN) :: ocpl_id + INTEGER, INTENT(OUT) :: crt_order_flags + INTEGER, INTENT(OUT) :: hdferr ! MS FORTRAN needs explicit interface for C functions called here. ! INTERFACE @@ -4754,39 +2983,24 @@ CONTAINS END SUBROUTINE h5pget_attr_creation_order_f -!****s* H5P/H5Pget_libver_bounds_f -! NAME -! H5Pget_libver_bounds_f -! -! PURPOSE -! Retrieves the lower and upper bounds on the HDF5 library release versions that indirectly -! determine the object format versions used when creating objects in the file. -! -! INPUTS -! -! fapl_id - File access property list identifier -! low - The earliest version of the library that will be used for writing objects. -! high - The latest version of the library that will be used for writing objects. -! -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! February 10, 2020 -! -! Fortran Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the lower and upper bounds on the HDF5 library release versions that indirectly +!! determine the object format versions used when creating objects in the file. +!! +!! \param fapl_id File access property list identifier. +!! \param low The earliest version of the library that will be used for writing objects. +!! \param high The latest version of the library that will be used for writing objects. +!! \param hdferr \fortran_error +!! +!! Fortran Interface: SUBROUTINE h5pget_libver_bounds_f(fapl_id, low, high, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: fapl_id ! File access property list identifier - INTEGER, INTENT(OUT) :: low ! The earliest version of the library that will be used for writing objects. - INTEGER, INTENT(OUT) :: high ! The latest version of the library that will be used for writing objects. - INTEGER, INTENT(OUT) :: hdferr ! Error code: 0 on success and -1 on failure -!***** -! Local variables + INTEGER(HID_T), INTENT(IN) :: fapl_id + INTEGER, INTENT(OUT) :: low + INTEGER, INTENT(OUT) :: high + INTEGER, INTENT(OUT) :: hdferr INTEGER(ENUM_T) :: low_c, high_c INTEGER(C_INT) :: hdferr_c ! @@ -4813,38 +3027,22 @@ CONTAINS END SUBROUTINE h5pget_libver_bounds_f -!****s* H5P/H5Pset_libver_bounds_f -! NAME -! H5Pset_libver_bounds_f -! -! PURPOSE -! Sets bounds on library versions, and indirectly format versions, to be used when creating objects. -! -! INPUTS -! -! fapl_id - File access property list identifier -! low - The earliest version of the library that will be used for writing objects. -! high - The latest version of the library that will be used for writing objects. -! -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! February 18, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets bounds on library versions, and indirectly format versions, to be used when creating objects. +!! +!! \param fapl_id File access property list identifier. +!! \param low The earliest version of the library that will be used for writing objects. +!! \param high The latest version of the library that will be used for writing objects. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_libver_bounds_f(fapl_id, low, high, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: fapl_id ! File access property list identifier - INTEGER, INTENT(IN) :: low ! The earliest version of the library that will be used for writing objects. - INTEGER, INTENT(IN) :: high ! The latest version of the library that will be used for writing objects. - INTEGER, INTENT(OUT) :: hdferr ! Error code: 0 on success and -1 on failure -!***** -! Local variables + INTEGER(HID_T), INTENT(IN) :: fapl_id + INTEGER, INTENT(IN) :: low + INTEGER, INTENT(IN) :: high + INTEGER, INTENT(OUT) :: hdferr INTEGER(C_INT) :: hdferr_c ! ! MS FORTRAN needs explicit interface for C functions called here. @@ -4867,36 +3065,20 @@ CONTAINS END SUBROUTINE h5pset_libver_bounds_f -!****s* H5P/H5Pset_link_creation_order_f -! NAME -! H5Pset_link_creation_order_f -! -! PURPOSE -! Sets creation order tracking and indexing for links in a group. -! -! INPUTS -! -! gcpl_id - Group creation property list identifier -! crt_order_flags - Creation order flag(s) -! -! OUTPUTS -! -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! February 18, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets creation order tracking and indexing for links in a group. +!! +!! \param gcpl_id Group creation property list identifier. +!! \param crt_order_flags Creation order flag(s). +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_link_creation_order_f(gcpl_id, crt_order_flags, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: gcpl_id ! File access property list identifier - INTEGER, INTENT(IN) :: crt_order_flags ! Creation order flag(s) - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: gcpl_id + INTEGER, INTENT(IN) :: crt_order_flags + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_link_creation_order_c(gcpl_id, crt_order_flags) & BIND(C,NAME='h5pset_link_creation_order_c') @@ -4912,37 +3094,22 @@ CONTAINS END SUBROUTINE h5pset_link_creation_order_f -!****s* H5P/H5Pget_link_phase_change_f -! NAME -! H5Pget_link_phase_change_f -! -! PURPOSE -! Queries the settings for conversion between compact and dense groups. -! -! INPUTS -! -! gcpl_id - Group creation property list identifier -! OUTPUTS -! -! max_compact - Maximum number of attributes to be stored in compact storage -! min_dense - Minimum number of attributes to be stored in dense storage -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! February 20, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Queries the settings for conversion between compact and dense groups. +!! +!! \param gcpl_id Group creation property list identifier. +!! \param max_compact Maximum number of attributes to be stored in compact storage. +!! \param min_dense Minimum number of attributes to be stored in dense storage. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_link_phase_change_f(gcpl_id, max_compact, min_dense, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list identifier - INTEGER, INTENT(OUT) :: max_compact ! Maximum number of attributes to be stored in compact storage - INTEGER, INTENT(OUT) :: min_dense ! Minimum number of attributes to be stored in dense storage - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: gcpl_id + INTEGER, INTENT(OUT) :: max_compact + INTEGER, INTENT(OUT) :: min_dense + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_link_phase_change_c(gcpl_id, max_compact, min_dense) & BIND(C,NAME='h5pget_link_phase_change_c') @@ -4958,37 +3125,20 @@ CONTAINS hdferr = h5pget_link_phase_change_c(gcpl_id, max_compact, min_dense) END SUBROUTINE h5pget_link_phase_change_f -!****s* H5P/H5Pget_obj_track_times_f -! NAME -! H5Pget_obj_track_times_f -! -! PURPOSE -! Returns whether times are tracked for an object. -! -! INPUTS -! -! plist_id - property list id -! flag - object timestamp setting -! .TRUE.,.FALSE. -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! February 22, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Returns whether times are tracked for an object. +!! +!! \param plist_id Property list id. +!! \param flag Object timestamp setting, .TRUE. or .FALSE. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_obj_track_times_f(plist_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property - ! list identifier - LOGICAL, INTENT(OUT) :: flag ! Object timestamp setting - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + LOGICAL, INTENT(OUT) :: flag + INTEGER, INTENT(OUT) :: hdferr INTEGER :: status ! ! MS FORTRAN needs explicit interface for C functions called here. @@ -4997,7 +3147,7 @@ CONTAINS INTEGER FUNCTION h5pget_obj_track_times_c(plist_id, status) & BIND(C,NAME='h5pget_obj_track_times_c') IMPORT :: HID_T - INTEGER(HID_T), INTENT(IN) :: plist_id ! File creation property list identifier + INTEGER(HID_T), INTENT(IN) :: plist_id INTEGER, INTENT(OUT) :: status END FUNCTION h5pget_obj_track_times_c END INTERFACE @@ -5007,52 +3157,20 @@ CONTAINS END SUBROUTINE h5pget_obj_track_times_f -!****s* H5P/H5Pset_obj_track_times_f -! NAME -! H5Pset_obj_track_times_f -! -! PURPOSE -! Set whether the birth, access, modification & change times for -! an object are stored. -! -! Birth time is the time the object was created. Access time is -! the last time that metadata or raw data was read from this -! object. Modification time is the last time the data for -! this object was changed (either writing raw data to a dataset -! or inserting/modifying/deleting a link in a group). Change -! time is the last time the metadata for this object was written -! (adding/modifying/deleting an attribute on an object, extending -! the size of a dataset, etc). -! -! If these times are not tracked, they will be reported as -! 12:00 AM UDT, Jan. 1, 1970 (i.e. 0 seconds past the UNIX -! epoch) when queried. -! -! INPUTS -! -! plist_id - property list id -! flag - object timestamp setting -! .TRUE.,.FALSE. -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! February 22, 2008 -! -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Set whether the birth, access, modification & change times for an object are stored. +!! +!! \param plist_id Property list id. +!! \param flag Object timestamp setting, .TRUE. or .FALSE. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_obj_track_times_f(plist_id, flag, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property - ! list identifier - LOGICAL, INTENT(IN) :: flag ! Object timestamp setting - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + LOGICAL, INTENT(IN) :: flag + INTEGER, INTENT(OUT) :: hdferr INTEGER :: status ! ! MS FORTRAN needs explicit interface for C functions called here. @@ -5062,7 +3180,7 @@ CONTAINS BIND(C,NAME='h5pset_obj_track_times_c') IMPORT :: HID_T IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! File creation property list identifier + INTEGER(HID_T), INTENT(IN) :: plist_id INTEGER, INTENT(IN) :: status END FUNCTION h5pset_obj_track_times_c END INTERFACE @@ -5074,41 +3192,20 @@ CONTAINS END SUBROUTINE h5pset_obj_track_times_f -!****s* H5P/H5Pset_create_inter_group_f -! NAME -! H5Pset_create_inter_group_f -! -! PURPOSE -! Specifies in property list whether to create missing intermediate groups. -! -! INPUTS -! -! lcpl_id - Link creation property list identifier -! crt_intermed_group - crt_intermed_group specifying whether -! to create intermediate groups upon the creation -! of an object -! OUTPUTS -! -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! February 22, 2008 -! -! HISTORY -! The long subroutine name (>31) on older f90 compilers causes problems -! so had to shorten the name -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Specifies in property list whether to create missing intermediate groups. +!! +!! \param lcpl_id Link creation property list identifier. +!! \param crt_intermed_group Specifies whether to create intermediate groups upon the creation of an object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_create_inter_group_f(lcpl_id, crt_intermed_group, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: lcpl_id ! Link creation property list identifier - INTEGER, INTENT(IN) :: crt_intermed_group ! specifying whether to create intermediate groups - ! upon the creation of an object - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: lcpl_id + INTEGER, INTENT(IN) :: crt_intermed_group + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_create_inter_group_c(lcpl_id, crt_intermed_group) & BIND(C,NAME='h5pset_create_inter_group_c') @@ -5123,36 +3220,20 @@ CONTAINS END SUBROUTINE h5pset_create_inter_group_f -!****s* H5P/H5Pget_link_creation_order_f -! NAME -! H5Pget_link_creation_order_f -! -! PURPOSE -! Queries whether link creation order is tracked and/or indexed in a group. -! -! INPUTS -! -! gcpl_id - Group creation property list identifier -! -! OUTPUTS -! -! crt_order_flags - Creation order flag(s) -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 3, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Queries whether link creation order is tracked and/or indexed in a group. +!! +!! \param gcpl_id Group creation property list identifier. +!! \param crt_order_flags Creation order flag(s). +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_link_creation_order_f(gcpl_id, crt_order_flags, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list identifier - INTEGER, INTENT(OUT) :: crt_order_flags ! Creation order flag(s) - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: gcpl_id + INTEGER, INTENT(OUT) :: crt_order_flags + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_link_creation_order_c(gcpl_id, crt_order_flags) & BIND(C,NAME='h5pget_link_creation_order_c') @@ -5168,39 +3249,22 @@ CONTAINS END SUBROUTINE h5pget_link_creation_order_f -!****s* H5P/H5Pset_char_encoding_f -! NAME -! H5Pset_char_encoding_f -! -! PURPOSE -! Sets the character encoding used to encode a string. -! -! INPUTS -! -! plist_id - Property list identifier -! encoding - Valid values for encoding are: -! H5T_CSET_ASCII_F -> US ASCII -! H5T_CSET_UTF8_F -> UTF-8 Unicode encoding -! -! OUTPUTS -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 3, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the character encoding used to encode a string. +!! +!! \param plist_id Property list identifier. +!! \param encoding Valid values for encoding are: +!! \li H5T_CSET_ASCII_F -> US ASCII +!! \li H5T_CSET_UTF8_F -> UTF-8 Unicode encoding +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_char_encoding_f(plist_id, encoding, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Property list identifier - INTEGER, INTENT(IN) :: encoding ! String encoding character set: - ! H5T_CSET_ASCII_F -> US ASCII - ! H5T_CSET_UTF8_F -> UTF-8 Unicode encoding - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + INTEGER, INTENT(IN) :: encoding + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_char_encoding_c(plist_id, encoding) & BIND(C,NAME='h5pset_char_encoding_c') @@ -5216,41 +3280,23 @@ CONTAINS END SUBROUTINE h5pset_char_encoding_f -!****s* H5P/H5Pget_char_encoding_f -! NAME -! H5Pget_char_encoding_f -! -! PURPOSE -! Retrieves the character encoding used to create a string -! -! INPUTS -! -! plist_id - Property list identifier -! -! OUTPUTS -! -! encoding - Valid values for encoding are: -! H5T_CSET_ASCII_F -> US ASCII -! H5T_CSET_UTF8_F -> UTF-8 Unicode encoding -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 3, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the character encoding used to create a string +!! +!! \param plist_id Property list identifier. +!! \param encoding Valid values for encoding are: +!! \li H5T_CSET_ASCII_F -> US ASCII +!! \li H5T_CSET_UTF8_F -> UTF-8 Unicode encoding +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_char_encoding_f(plist_id, encoding, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Property list identifier + INTEGER(HID_T), INTENT(IN) :: plist_id - INTEGER, INTENT(OUT) :: encoding ! Valid values for encoding are: - ! H5T_CSET_ASCII_F -> US ASCII - ! H5T_CSET_UTF8_F -> UTF-8 Unicode encoding - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER, INTENT(OUT) :: encoding + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_char_encoding_c(plist_id, encoding) & BIND(C,NAME='h5pget_char_encoding_c') @@ -5266,43 +3312,22 @@ CONTAINS END SUBROUTINE h5pget_char_encoding_f -!****s* H5P/h5pset_copy_object_f -! NAME -! h5pset_copy_object_f -! -! PURPOSE -! Sets properties to be used when an object is copied. -! -! INPUTS -! -! ocp_plist_id - Object copy property list identifier -! copy_options - Copy option(s) to be set -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 3, 2008 -! -! HISTORY -! -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets properties to be used when an object is copied. +!! +!! \param ocp_plist_id Object copy property list identifier. +!! \param copy_options Copy option(s) to be set. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_copy_object_f(ocp_plist_id, copy_options, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: ocp_plist_id ! Object copy property list identifier - INTEGER, INTENT(IN) :: copy_options ! Copy option(s) to be set, valid options are: - ! H5O_COPY_SHALLOW_HIERARCHY_F - ! H5O_COPY_EXPAND_SOFT_LINK_F - ! H5O_COPY_EXPAND_EXT_LINK_F + INTEGER(HID_T), INTENT(IN) :: ocp_plist_id + INTEGER, INTENT(IN) :: copy_options ! H5O_COPY_EXPAND_REFERENCE_F ! H5O_COPY_WITHOUT_ATTR_FLAG_F - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_copy_object_c(ocp_plist_id, copy_options) & BIND(C,NAME='h5pset_copy_object_c') @@ -5315,43 +3340,22 @@ CONTAINS hdferr = h5pset_copy_object_c(ocp_plist_id, copy_options) END SUBROUTINE h5pset_copy_object_f -!****s* H5P/h5pget_copy_object_f -! NAME -! h5pget_copy_object_f -! -! PURPOSE -! Retrieves the properties to be used when an object is copied. -! -! INPUTS -! -! ocp_plist_id - Object copy property list identifier -! OUTPUTS -! -! copy_options - Copy option(s) to be get -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 3, 2008 -! -! HISTORY -! -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the properties to be used when an object is copied. +!! +!! \param ocp_plist_id Object copy property list identifier. +!! \param copy_options Copy option(s) to be get. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_copy_object_f(ocp_plist_id, copy_options, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: ocp_plist_id ! Object copy property list identifier - INTEGER, INTENT(OUT) :: copy_options ! Valid copy options returned are: - ! H5O_COPY_SHALLOW_HIERARCHY_F - ! H5O_COPY_EXPAND_SOFT_LINK_F - ! H5O_COPY_EXPAND_EXT_LINK_F + INTEGER(HID_T), INTENT(IN) :: ocp_plist_id + INTEGER, INTENT(OUT) :: copy_options ! H5O_COPY_EXPAND_REFERENCE_F ! H5O_COPY_WITHOUT_ATTR_FLAG_F - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_copy_object_c(ocp_plist_id, copy_options) & BIND(C,NAME='h5pget_copy_object_c') @@ -5364,43 +3368,25 @@ CONTAINS hdferr = h5pget_copy_object_c(ocp_plist_id, copy_options) END SUBROUTINE h5pget_copy_object_f -!****s* H5P/h5pget_data_transform_f -! NAME -! h5pget_data_transform_f -! -! PURPOSE -! Retrieves a data transform expression. -! -! INPUTS -! -! plist_id - Identifier of the property list or class -! OUTPUTS -! -! expression - buffer to hold transform expression -! hdferr - Error code -! Success: Actual length of the expression -! If provided buffer "expression" is -! smaller, than expression will be -! truncated to fit into -! provided user buffer -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 19, 2008 -! -! HISTORY -! -! Should hdferr return just 0 or 1 and add another argument for the size? -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves a data transform expression. +!! +!! \param plist_id Identifier of the property list or class. +!! \param expression Buffer to hold transform expression. +!! \param hdferr Error code: +!! Success: Actual length of the expression. If provided buffer "expression" is +!! smaller, than expression will be truncated to fit into provided user buffer. +!! Failure: -1 +!! \param size Registered size of the transform expression +!! SUBROUTINE h5pget_data_transform_f(plist_id, expression, hdferr, size) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Identifier of the property list or class - CHARACTER(LEN=*), INTENT(OUT) :: expression ! Buffer to hold transform expression - INTEGER(SIZE_T), INTENT(OUT), OPTIONAL :: size ! Registered size of the transform expression - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + CHARACTER(LEN=*), INTENT(OUT) :: expression + INTEGER(SIZE_T), INTENT(OUT), OPTIONAL :: size + INTEGER, INTENT(OUT) :: hdferr INTEGER :: expression_len INTEGER(SIZE_T) :: size_default @@ -5426,35 +3412,20 @@ SUBROUTINE h5pget_data_transform_f(plist_id, expression, hdferr, size) END SUBROUTINE h5pget_data_transform_f -!****s* H5P/h5pset_data_transform_f -! NAME -! h5pset_data_transform_f -! -! PURPOSE -! Sets a data transform expression. -! -! INPUTS -! -! plist_id - Identifier of the property list or class -! expression - Buffer to hold transform expression -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 19, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets a data transform expression. +!! +!! \param plist_id Identifier of the property list or class. +!! \param expression Buffer to hold transform expression. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_data_transform_f(plist_id, expression, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist_id ! Identifier of the property list or class - CHARACTER(LEN=*), INTENT(IN) :: expression ! Buffer to hold transform expression - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: plist_id + CHARACTER(LEN=*), INTENT(IN) :: expression + INTEGER, INTENT(OUT) :: hdferr INTEGER :: expression_len INTERFACE @@ -5474,35 +3445,20 @@ SUBROUTINE h5pget_data_transform_f(plist_id, expression, hdferr, size) END SUBROUTINE h5pset_data_transform_f -!****s* H5P/H5Pget_local_heap_size_hint_f -! NAME -! H5Pget_local_heap_size_hint_f -! -! PURPOSE -! Queries the local heap size hint for original-style groups. -! -! INPUTS -! -! gcpl_id - Group creation property list identifier -! OUTPUTS -! -! size_hint - Hint for size of local heap -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 21, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Queries the local heap size hint for original-style groups. +!! +!! \param gcpl_id Group creation property list identifier. +!! \param size_hint Hint for size of local heap. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_local_heap_size_hint_f(gcpl_id, size_hint, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list identifier - INTEGER(SIZE_T), INTENT(OUT) :: size_hint ! Hint for size of local heap - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: gcpl_id + INTEGER(SIZE_T), INTENT(OUT) :: size_hint + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_local_heap_size_hint_c(gcpl_id, size_hint) & BIND(C,NAME='h5pget_local_heap_size_hint_c') @@ -5517,40 +3473,22 @@ SUBROUTINE h5pget_data_transform_f(plist_id, expression, hdferr, size) END SUBROUTINE h5pget_local_heap_size_hint_f -!****s* H5P/H5Pget_est_link_info_f -! NAME -! H5Pget_est_link_info_f -! -! PURPOSE -! Queries data required to estimate required local heap or object header size. -! -! INPUTS -! -! gcpl_id - Group creation property list identifier -! OUTPUTS -! -! est_num_entries - Estimated number of links to be inserted into group -! est_name_len - Estimated average length of link names -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 21, 2008 -! -! HISTORY -! -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Queries data required to estimate required local heap or object header size. +!! +!! \param gcpl_id Group creation property list identifier. +!! \param est_num_entries Estimated number of links to be inserted into group. +!! \param est_name_len Estimated average length of link names. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_est_link_info_f(gcpl_id, est_num_entries, est_name_len, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list identifier - INTEGER, INTENT(OUT) :: est_num_entries ! Estimated number of links to be inserted into group - INTEGER, INTENT(OUT) :: est_name_len ! Estimated average length of link names - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: gcpl_id + INTEGER, INTENT(OUT) :: est_num_entries + INTEGER, INTENT(OUT) :: est_name_len + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_est_link_info_c(gcpl_id, est_num_entries, est_name_len) & BIND(C,NAME='h5pget_est_link_info_c') @@ -5566,35 +3504,20 @@ SUBROUTINE h5pget_data_transform_f(plist_id, expression, hdferr, size) END SUBROUTINE h5pget_est_link_info_f -!****s* H5P/H5Pset_local_heap_size_hint_f -! NAME -! H5Pset_local_heap_size_hint_f -! -! PURPOSE -! Sets the local heap size hint for original-style groups. -! -! INPUTS -! -! gcpl_id - Group creation property list identifier -! size_hint - Hint for size of local heap -! OUTPUTS -! -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 21, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the local heap size hint for original-style groups. +!! +!! \param gcpl_id Group creation property list identifier. +!! \param size_hint Hint for size of local heap. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_local_heap_size_hint_f(gcpl_id, size_hint, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list identifier - INTEGER(SIZE_T), INTENT(IN) :: size_hint ! Hint for size of local heap - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: gcpl_id + INTEGER(SIZE_T), INTENT(IN) :: size_hint + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_local_heap_size_hint_c(gcpl_id, size_hint) & BIND(C,NAME='h5pset_local_heap_size_hint_c') @@ -5609,37 +3532,22 @@ SUBROUTINE h5pget_data_transform_f(plist_id, expression, hdferr, size) END SUBROUTINE h5pset_local_heap_size_hint_f -!****s* H5P/h5pset_est_link_info_f -! NAME -! h5pset_est_link_info_f -! -! PURPOSE -! Sets estimated number of links and length of link names in a group. -! -! INPUTS -! -! gcpl_id - Group creation property list identifier -! est_num_entries - Estimated number of links to be inserted into group -! est_name_len - Estimated average length of link names -! OUTPUTS -! -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 21, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets estimated number of links and length of link names in a group. +!! +!! \param gcpl_id Group creation property list identifier. +!! \param est_num_entries Estimated number of links to be inserted into group. +!! \param est_name_len Estimated average length of link names. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_est_link_info_f(gcpl_id, est_num_entries, est_name_len, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list identifier - INTEGER, INTENT(IN) :: est_num_entries ! Estimated number of links to be inserted into group - INTEGER, INTENT(IN) :: est_name_len ! Estimated average length of link names - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: gcpl_id + INTEGER, INTENT(IN) :: est_num_entries + INTEGER, INTENT(IN) :: est_name_len + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_est_link_info_c(gcpl_id, est_num_entries, est_name_len) & BIND(C,NAME='h5pset_est_link_info_c') @@ -5655,37 +3563,22 @@ SUBROUTINE h5pget_data_transform_f(plist_id, expression, hdferr, size) END SUBROUTINE h5pset_est_link_info_f -!****s* H5P/h5pset_link_phase_change_f -! NAME -! h5pset_link_phase_change_f -! -! PURPOSE -! Sets the parameters for conversion between compact and dense groups. -! -! INPUTS -! -! gcpl_id - Group creation property list identifier -! max_compact - Maximum number of attributes to be stored in compact storage -! min_dense - Minimum number of attributes to be stored in dense storage -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 21, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the parameters for conversion between compact and dense groups. +!! +!! \param gcpl_id Group creation property list identifier. +!! \param max_compact Maximum number of attributes to be stored in compact storage. +!! \param min_dense Minimum number of attributes to be stored in dense storage. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_link_phase_change_f(gcpl_id, max_compact, min_dense, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list identifier - INTEGER, INTENT(IN) :: max_compact ! Maximum number of attributes to be stored in compact storage - INTEGER, INTENT(IN) :: min_dense ! Minimum number of attributes to be stored in dense storage - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: gcpl_id + INTEGER, INTENT(IN) :: max_compact + INTEGER, INTENT(IN) :: min_dense + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_link_phase_change_c(gcpl_id, max_compact, min_dense) & BIND(C,NAME='h5pset_link_phase_change_c') @@ -5700,39 +3593,24 @@ SUBROUTINE h5pset_link_phase_change_f(gcpl_id, max_compact, min_dense, hdferr) hdferr = h5pset_link_phase_change_c(gcpl_id, max_compact, min_dense) END SUBROUTINE h5pset_link_phase_change_f -!****s* H5P/h5pset_fapl_direct_f -! NAME -! h5pset_fapl_direct_f -! -! PURPOSE -! Sets up use of the direct I/O driver. -! -! INPUTS -! -! fapl_id - File access property list identifier -! alignment - Required memory alignment boundary -! block_size - File system block size -! cbuf_size - Copy buffer size -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 21, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets up use of the direct I/O driver. +!! +!! \param fapl_id File access property list identifier. +!! \param alignment Required memory alignment boundary. +!! \param block_size File system block size. +!! \param cbuf_size Copy buffer size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fapl_direct_f(fapl_id, alignment, block_size, cbuf_size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: fapl_id ! File access property list identifier - INTEGER(SIZE_T), INTENT(IN) :: alignment ! Required memory alignment boundary! - INTEGER(SIZE_T), INTENT(IN) :: block_size ! File system block size - INTEGER(SIZE_T), INTENT(IN) :: cbuf_size ! Copy buffer size - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: fapl_id + INTEGER(SIZE_T), INTENT(IN) :: alignment + INTEGER(SIZE_T), INTENT(IN) :: block_size + INTEGER(SIZE_T), INTENT(IN) :: cbuf_size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_fapl_direct_c(fapl_id, alignment, block_size, cbuf_size) & BIND(C,NAME='h5pset_fapl_direct_c') @@ -5748,39 +3626,24 @@ SUBROUTINE h5pset_fapl_direct_f(fapl_id, alignment, block_size, cbuf_size, hdfer hdferr = H5Pset_fapl_direct_c(fapl_id, alignment, block_size, cbuf_size) END SUBROUTINE h5pset_fapl_direct_f -!****s* H5P/h5pget_fapl_direct_f -! NAME -! h5pget_fapl_direct_f -! -! PURPOSE -! Gets up use of the direct I/O driver. -! -! INPUTS -! -! fapl_id - File access property list identifier -! OUTPUTS -! -! alignment - Required memory alignment boundary -! block_size - File system block size -! cbuf_size - Copy buffer size -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 21, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Gets up use of the direct I/O driver. +!! +!! \param fapl_id File access property list identifier. +!! \param alignment Required memory alignment boundary. +!! \param block_size File system block size. +!! \param cbuf_size Copy buffer size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_fapl_direct_f(fapl_id, alignment, block_size, cbuf_size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: fapl_id ! File access property list identifier - INTEGER(SIZE_T), INTENT(OUT) :: alignment ! Required memory alignment boundary! - INTEGER(SIZE_T), INTENT(OUT) :: block_size ! File system block size - INTEGER(SIZE_T), INTENT(OUT) :: cbuf_size ! Copy buffer size - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: fapl_id + INTEGER(SIZE_T), INTENT(OUT) :: alignment + INTEGER(SIZE_T), INTENT(OUT) :: block_size + INTEGER(SIZE_T), INTENT(OUT) :: cbuf_size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_fapl_direct_c(fapl_id, alignment, block_size, cbuf_size) & BIND(C,NAME='h5pget_fapl_direct_c') @@ -5794,43 +3657,25 @@ SUBROUTINE h5pset_fapl_direct_f(fapl_id, alignment, block_size, cbuf_size, hdfer END INTERFACE hdferr = H5Pget_fapl_direct_c(fapl_id, alignment, block_size, cbuf_size) + END SUBROUTINE h5pget_fapl_direct_f -!****s* H5P/H5Pset_attr_phase_change_f -! NAME -! H5Pset_attr_phase_change_f -! -! PURPOSE -! Sets attribute storage phase change thresholds. -! -! INPUTS -! -! ocpl_id - Object (dataset or group) creation property list identifier -! OUTPUTS -! -! max_compact - Maximum number of attributes to be stored in compact storage -! (Default: 8) -! min_dense - Minimum number of attributes to be stored in dense storage -! (Default: 6) -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets attribute storage phase change thresholds. +!! +!! \param ocpl_id Object (dataset or group) creation property list identifier. +!! \param max_compact Maximum number of attributes to be stored in compact storage, (Default: 8). +!! \param min_dense Minimum number of attributes to be stored in dense storage, (Default: 6). +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: ocpl_id ! Object (dataset or group) creation property list identifier - INTEGER, INTENT(IN) :: max_compact ! Maximum number of attributes to be stored in compact storage - !(Default: 8) - INTEGER, INTENT(IN) :: min_dense ! Minimum number of attributes to be stored in dense storage - ! (Default: 6) - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: ocpl_id + INTEGER, INTENT(IN) :: max_compact + INTEGER, INTENT(IN) :: min_dense + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_attr_phase_change_c(ocpl_id, max_compact, min_dense) & BIND(C,NAME='h5pset_attr_phase_change_c') @@ -5845,32 +3690,20 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) hdferr = h5pset_attr_phase_change_c(ocpl_id, max_compact, min_dense) - END SUBROUTINE h5pset_attr_phase_change_f -!****s* H5P/H5Pset_nbit_f -! NAME -! H5Pset_nbit_f -! -! PURPOSE -! Sets up the use of the N-Bit filter. -! -! Inputs: -! plist_id - Dataset creation property list identifier. -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! March 21, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets up the use of the N-Bit filter. +!! +!! \param plist_id Dataset creation property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_nbit_f(plist_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: plist_id INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION H5Pset_nbit_c(plist_id) & BIND(C,NAME='h5pset_nbit_c') @@ -5884,37 +3717,25 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pset_nbit_f -!****s* H5P/h5pset_scaleoffset_f -! NAME -! h5pset_scaleoffset_f -! -! PURPOSE -! Sets up the use of the scale-offset filter. -! -! Inputs: -! plist_id - Dataset creation property list identifier. -! scale_type - Flag indicating compression method. Valid values: -! H5Z_SO_FLOAT_DSCALE_F -! H5Z_SO_FLOAT_ESCALE_F -! H5Z_SO_INT_F -! -! scale_factor - Parameter related to scale. -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! March 21, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets up the use of the scale-offset filter. +!! +!! \param plist_id Dataset creation property list identifier. +!! \param scale_type Flag indicating compression method. Valid values: +!! \li H5Z_SO_FLOAT_DSCALE_F +!! \li H5Z_SO_FLOAT_ESCALE_F +!! \li H5Z_SO_INT_F +!! \param scale_factor Parameter related to scale. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_scaleoffset_f(plist_id, scale_type, scale_factor, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: plist_id INTEGER , INTENT(IN) :: scale_type INTEGER , INTENT(IN) :: scale_factor INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5pset_scaleoffset_c(plist_id, scale_type, scale_factor) & @@ -5931,39 +3752,20 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pset_scaleoffset_f -!****s* H5P/h5pset_nlinks_f -! NAME -! h5pset_nlinks_f -! -! PURPOSE -! Sets maximum number of soft or user-defined link traversals. -! -! INPUTS -! -! lapl_id - File access property list identifier -! nlinks - Maximum number of links to traverse -! -! OUTPUTS -! -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 24, 2008 -! -! HISTORY -! -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets maximum number of soft or user-defined link traversals. +!! +!! \param lapl_id File access property list identifier. +!! \param nlinks Maximum number of links to traverse. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_nlinks_f(lapl_id, nlinks, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: lapl_id ! File access property list identifier - INTEGER(SIZE_T), INTENT(IN) :: nlinks ! Maximum number of links to traverse - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: lapl_id + INTEGER(SIZE_T), INTENT(IN) :: nlinks + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_nlinks_c(lapl_id, nlinks) & BIND(C,NAME='h5pset_nlinks_c') @@ -5978,36 +3780,20 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pset_nlinks_f -!****s* H5P/h5pget_nlinks_f -! NAME -! h5pget_nlinks_f -! -! PURPOSE -! Gets maximum number of soft or user-defined link traversals. -! -! INPUTS -! -! lapl_id - File access property list identifier -! nlinks - Maximum number of links to traverse -! -! OUTPUTS -! -! hdferr - error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! March 24, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Gets maximum number of soft or user-defined link traversals. +!! +!! \param lapl_id File access property list identifier. +!! \param nlinks Maximum number of links to traverse. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_nlinks_f(lapl_id, nlinks, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: lapl_id ! File access property list identifier - INTEGER(SIZE_T), INTENT(OUT) :: nlinks ! Maximum number of links to traverse - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: lapl_id + INTEGER(SIZE_T), INTENT(OUT) :: nlinks + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_nlinks_c(lapl_id, nlinks) & BIND(C,NAME='h5pget_nlinks_c') @@ -6022,41 +3808,20 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pget_nlinks_f -!****s* H5P/H5Pget_create_inter_group_f -! NAME -! H5Pget_create_inter_group_f -! -! PURPOSE -! Determines whether property is set to enable creating missing intermediate groups. -! -! INPUTS -! -! lcpl_id - Link creation property list identifier -! crt_intermed_group - Specifying whether to create intermediate groups upon -! the creation of an object -! OUTPUTS -! -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! April 4, 2008 -! -! HISTORY -! -! The long subroutine name (>31) on older f90 compilers causes problems -! so the name was shortened -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Determines whether property is set to enable creating missing intermediate groups. +!! +!! \param lcpl_id Link creation property list identifier. +!! \param crt_intermed_group Specifying whether to create intermediate groups upon the creation of an object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_create_inter_group_f(lcpl_id, crt_intermed_group, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: lcpl_id ! Link creation property list identifier - INTEGER, INTENT(IN) :: crt_intermed_group ! Flag specifying whether to create intermediate groups - ! upon creation of an object - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: lcpl_id + INTEGER, INTENT(IN) :: crt_intermed_group + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_create_inter_group_c(lcpl_id, crt_intermed_group) & BIND(C,NAME='h5pget_create_inter_group_c') @@ -6071,59 +3836,39 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pget_create_inter_group_f -!****s* H5P/H5Pset_chunk_cache_f -! NAME -! H5Pset_chunk_cache_f -! -! PURPOSE -! Set the number of objects in the meta data cache and the -! maximum number of chunks and bytes in the raw data chunk cache. -! Once set, these values will override the values in the file access -! property list. Each of these values can be individually unset -! (or not set at all) by passing the macros: -! H5D_CHUNK_CACHE_NSLOTS_DFLT_F, -! H5D_CHUNK_CACHE_NBYTES_DFLT_F, and/or -! H5D_CHUNK_CACHE_W0_DFLT_F -! as appropriate. -! -! The RDCC_W0 value should be between 0 and 1 inclusive and -! indicates how much chunks that have been fully read or fully -! written are favored for preemption. A value of zero means -! fully read or written chunks are treated no differently than -! other chunks (the preemption is strictly LRU) while a value -! of one means fully read chunks are always preempted before -! other chunks. -! -! INPUTS -! -! dapl_id - Dataset access property list identifier. -! rdcc_nslots - The number of chunk slots in the raw data chunk cache for this dataset. -! rdcc_nbytes - The total size of the raw data chunk cache for this dataset. -! rdcc_w0 - The chunk preemption policy for this dataset. -! OUTPUTS -! -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! April 13, 2009 -! -! HISTORY -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Set the number of objects in the meta data cache and the maximum number of chunks and bytes in the raw data chunk cache. +!! Once set, these values will override the values in the file access +!! property list. Each of these values can be individually unset +!! (or not set at all) by passing the macros: +!! H5D_CHUNK_CACHE_NSLOTS_DFLT_F, +!! H5D_CHUNK_CACHE_NBYTES_DFLT_F, and/or +!! H5D_CHUNK_CACHE_W0_DFLT_F +!! as appropriate. +!! +!! The RDCC_W0 value should be between 0 and 1 inclusive and +!! indicates how much chunks that have been fully read or fully +!! written are favored for preemption. A value of zero means +!! fully read or written chunks are treated no differently than +!! other chunks (the preemption is strictly LRU) while a value +!! of one means fully read chunks are always preempted before +!! other chunks. +!! +!! \param dapl_id Dataset access property list identifier. +!! \param rdcc_nslots The number of chunk slots in the raw data chunk cache for this dataset. +!! \param rdcc_nbytes The total size of the raw data chunk cache for this dataset. +!! \param rdcc_w0 The chunk preemption policy for this dataset. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_chunk_cache_f(dapl_id, rdcc_nslots, rdcc_nbytes, rdcc_w0, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dapl_id ! Dataset access property list identifier. - INTEGER(SIZE_T), INTENT(IN) :: rdcc_nslots ! The number of chunk slots in the raw data - ! chunk cache for this dataset. - INTEGER(SIZE_T), INTENT(IN) :: rdcc_nbytes ! The total size of the raw data chunk cache - ! for this dataset. - REAL, INTENT(IN) :: rdcc_w0 ! The chunk preemption policy for this dataset. - INTEGER, INTENT(OUT) :: hdferr ! Error code - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: dapl_id + INTEGER(SIZE_T), INTENT(IN) :: rdcc_nslots + INTEGER(SIZE_T), INTENT(IN) :: rdcc_nbytes + REAL, INTENT(IN) :: rdcc_w0 + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_chunk_cache_c(dapl_id, rdcc_nslots, rdcc_nbytes, rdcc_w0) & @@ -6141,47 +3886,24 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pset_chunk_cache_f -!****s* H5P/H5Pget_chunk_cache_f -! NAME -! H5Pget_chunk_cache_f -! -! PURPOSE -! Retrieves the maximum possible number of elements in the meta -! data cache and the maximum possible number of elements and -! bytes and the RDCC_W0 value in the raw data chunk cache. Any -! (or all) arguments may be null pointers in which case the -! corresponding datum is not returned. If these properties have -! not been set on this property list, the default values for a -! file access property list are returned. -! -! INPUTS -! -! dapl_id - Dataset access property list identifier. -! OUTPUTS -! -! rdcc_nslots - Number of chunk slots in the raw data chunk cache hash table. -! rdcc_nbytes - Total size of the raw data chunk cache, in bytes. -! rdcc_w0 - Preemption policy. -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! M. Scot Breitenfeld -! April 13, 2009 -! -! HISTORY -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the raw data chunk cache parameters. +!! +!! \param dapl_id Dataset access property list identifier. +!! \param rdcc_nslots Number of chunk slots in the raw data chunk cache hash table. +!! \param rdcc_nbytes Total size of the raw data chunk cache, in bytes. +!! \param rdcc_w0 Preemption policy. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_chunk_cache_f(dapl_id, rdcc_nslots, rdcc_nbytes, rdcc_w0, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dapl_id ! Dataset access property list identifier. - INTEGER(SIZE_T), INTENT(OUT) :: rdcc_nslots ! Number of chunk slots in the raw data chunk cache hash table. - INTEGER(SIZE_T), INTENT(OUT) :: rdcc_nbytes ! Total size of the raw data chunk cache, in bytes. - REAL, INTENT(OUT) :: rdcc_w0 ! Preemption policy. - INTEGER, INTENT(OUT) :: hdferr ! Error code: - ! 0 on success and -1 on failure -!***** + INTEGER(HID_T), INTENT(IN) :: dapl_id + INTEGER(SIZE_T), INTENT(OUT) :: rdcc_nslots + INTEGER(SIZE_T), INTENT(OUT) :: rdcc_nbytes + REAL, INTENT(OUT) :: rdcc_w0 + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_chunk_cache_c(dapl_id, rdcc_nslots, rdcc_nbytes, rdcc_w0) & BIND(C,NAME='h5pget_chunk_cache_c') @@ -6198,59 +3920,288 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pget_chunk_cache_f -! -!****s* H5P (F03)/h5pset_fill_value_f_F90 -! -! NAME -! h5pset_fill_value_f -! -! PURPOSE -! Sets fill value for a dataset creation property list -! -! Inputs: -! prp_id - Property list identifier -! type_id - Datatype identifier of fill value datatype (in memory) -! fillvalue - Fillvalue -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Added the recommended way of passing fillvalue -! and that is by passing the C address, all other -! ways are obsolete and should be avoided. June, 2008 MSB -! -! NOTES -! h5pset(get)fill_value_f function is overloaded to support -! INTEGER, REAL, DOUBLE PRECISION and CHARACTER dtatypes. -! -! Fortran90 Interface: -!! SUBROUTINE h5pset_fill_value_f(prp_id, type_id, fillvalue, hdferr) -!! IMPLICIT NONE -!! INTEGER(HID_T), INTENT(IN) :: prp_id -!! INTEGER(HID_T), INTENT(IN) :: type_id -!! TYPE(VOID) , INTENT(IN) :: fillvalue -!! INTEGER , INTENT(OUT) :: hdferr -!***** +#ifdef H5_DOXYGEN_FORTRAN +!> +!! \ingroup FH5P +!! +!! \brief Sets fill value for a dataset creation property list +!! +!! \note \fortran_approved +!! +!! \param prp_id Property list identifier. +!! \param type_id Datatype identifier of fill value datatype (in memory). +!! \param fillvalue Fillvalue. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pset_fill_value_f(prp_id, type_id, fillvalue, hdferr) + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(IN) :: type_id + TYPE(C_PTR) , INTENT(IN) :: fillvalue + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pset_fill_value_f + +!> +!! \ingroup FH5P +!! +!! \brief Gets fill value for a dataset creation property list +!! +!! \note \fortran_approved +!! +!! \param prp_id Property list identifier. +!! \param type_id Datatype identifier of fill value datatype (in memory). +!! \param fillvalue Fillvalue. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pget_fill_value_f(prp_id, type_id, fillvalue, hdferr) + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(IN) :: type_id + TYPE(C_PTR) , INTENT(IN) :: fillvalue + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pget_fill_value_f + +!> +!! \ingroup FH5P +!! +!! \brief Sets fill value for a dataset creation property list +!! +!! \note \fortran_obsolete +!! +!! \param prp_id Property list identifier. +!! \param type_id Datatype identifier of fill value datatype (in memory). +!! \param fillvalue Fillvalue. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pset_fill_value_f(prp_id, type_id, fillvalue, hdferr) + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(IN) :: type_id + TYPE(TYPE) , INTENT(IN) :: fillvalue + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pset_fill_value_f + +!> +!! \ingroup FH5P +!! +!! \brief Gets fill value for a dataset creation property list. +!! +!! \note \fortran_obsolete +!! +!! \param prp_id Property list identifier. +!! \param type_id Datatype identifier of fill value datatype (in memory). +!! \param fillvalue Fillvalue. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pget_fill_value_f(prp_id, type_id, fillvalue, hdferr) + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(IN) :: type_id + TYPE(TYPE) , INTENT(OUT) :: fillvalue + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pget_fill_value_f + +!> +!! \ingroup FH5P +!! +!! \brief Sets a property list value. +!! +!! \note \fortran_approved +!! +!! \param prp_id Property list identifier to modify. +!! \param name Name of property to modify. +!! \param value Pointer to value to set the property to. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pset_f(prp_id, name, value, hdferr) + INTEGER(HID_T) , INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + TYPE(C_PTR) , INTENT(IN) :: value + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pset_f + +!> +!! \ingroup FH5P +!! +!! \brief Sets a property list value. +!! +!! \note \fortran_obsolete +!! +!! \param prp_id Property list identifier to modify. +!! \param name Name of property to modify. +!! \param value Property value, supported types are: +!! \li INTEGER +!! \li REAL +!! \li DOUBLE PRECISION +!! \li CHARACTER(LEN=*) +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pset_f(prp_id, name, value, hdferr) + INTEGER(HID_T) , INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER , INTENT(IN) :: value + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pset + +!> +!! \ingroup FH5P +!! +!! \brief Sets a property list value. +!! +!! \note \fortran_obsolete +!! +!! \param prp_id Property list identifier to modify. +!! \param name Name of property to modify. +!! \param value Property value, supported types are: +!! \li INTEGER +!! \li REAL +!! \li DOUBLE PRECISION +!! \li CHARACTER(LEN=*) +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pset_f(prp_id, name, value, hdferr) + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(IN) :: value + INTEGER, INTENT(OUT) :: hdferr + END SUBROUTINE h5pset_f +!> +!! \ingroup FH5P +!! +!! \brief Queries the value of a property. +!! +!! \note \fortran_approved +!! +!! \param prp_id Property list identifier to modify. +!! \param name Name of property to get. +!! \param value Pointer to a location to which to copy the value of of the property. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pget_f(prp_id, name, value, hdferr) + INTEGER(HID_T) , INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + TYPE(C_PTR) , INTENT(OUT) :: value + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pget_f + +!> +!! \ingroup FH5P +!! +!! \brief Queries the value of a property. +!! +!! \note \fortran_obsolete +!! +!! \param prp_id Property list identifier to modify. +!! \param name Name of property to get. +!! \param value Property value, supported types are: +!! \li INTEGER +!! \li REAL +!! \li DOUBLE PRECISION +!! \li CHARACTER(LEN=*) +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pget_f(prp_id, name, value, hdferr) + INTEGER(HID_T) , INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER , INTENT(OUT) :: value + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pget_f +!> +!! \ingroup FH5P +!! +!! \brief Registers a permanent property with a property list class. +!! +!! \note \fortran_approved +!! +!! \param class Property list class identifier. +!! \param name Name of property to register. +!! \param size Size of the property value. +!! \param value Pointer to value to set the property to. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pregister_f(class, name, size, value, hdferr) + INTEGER(HID_T) , INTENT(IN) :: class + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T) , INTENT(IN) :: size + TYPE(C_PTR) , INTENT(IN) :: value + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pregister_f +!> +!! \ingroup FH5P +!! +!! \brief Registers a permanent property with a property list class. +!! +!! \note \fortran_obsolete +!! +!! \param class Property list class identifier. +!! \param name Name of property to register. +!! \param size Size of the property value. +!! \param value Property value, supported types are: +!! \li INTEGER +!! \li REAL +!! \li DOUBLE PRECISION +!! \li CHARACTER(LEN=*) +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pregister_f(class, name, size, value, hdferr) + INTEGER(HID_T) , INTENT(IN) :: class + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T) , INTENT(IN) :: size + TYPE(TYPE) , INTENT(IN) :: value + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pregister_f + +!> +!! \ingroup FH5P +!! +!! \brief Registers a temporary property with a property list class. +!! +!! \note \fortran_approved +!! +!! \param plist Property list class identifier. +!! \param name Name of property to insert. +!! \param size Size of the property value. +!! \param value Pointer to new value pointer for the property being modified. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pinsert_f(plist, name, size, value, hdferr) + INTEGER(HID_T) , INTENT(IN) :: plist + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T) , INTENT(IN) :: size + TYPE(C_PTR) , INTENT(IN) :: value + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pinsert_f + +!> +!! \ingroup FH5P +!! +!! \brief Registers a temporary property with a property list class. +!! +!! \note \fortran_obsolete +!! +!! \param plist Property list class identifier. +!! \param name Name of property to insert. +!! \param size Size of the property value. +!! \param value Property value, supported types are: +!! \li INTEGER +!! \li REAL +!! \li DOUBLE PRECISION +!! \li CHARACTER(LEN=*) +!! \param hdferr \fortran_error +!! + SUBROUTINE h5pinsert_f(plist, name, size, value, hdferr) + IMPLICIT NONE + INTEGER(HID_T) , INTENT(IN) :: plist + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T) , INTENT(IN) :: size + TYPE(TYPE) , INTENT(IN) :: value + INTEGER , INTENT(OUT) :: hdferr + END SUBROUTINE h5pinsert_f +#else SUBROUTINE h5pset_fill_value_integer(prp_id, type_id, fillvalue, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier of - ! of fillvalue datatype - ! (in memory) - INTEGER, INTENT(IN), TARGET :: fillvalue ! Fillvalue - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER, INTENT(IN), TARGET :: fillvalue + INTEGER, INTENT(OUT) :: hdferr TYPE(C_PTR) :: f_ptr ! C address f_ptr = C_LOC(fillvalue) @@ -6258,57 +4209,13 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) hdferr = h5pset_fill_value_c(prp_id, type_id, f_ptr) END SUBROUTINE h5pset_fill_value_integer -! -!****s* H5P (F03)/h5pget_fill_value_f_F90 -! -! NAME -! h5pget_fill_value_f -! -! PURPOSE -! Gets fill value for a dataset creation property list -! -! Inputs: -! prp_id - Property list identifier -! type_id - Datatype identifier of fill value datatype (in memory) -! -! Outputs: -! fillvalue - Fillvalue -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Added the recommended way of passing fillvalue -! and that is by passing the C address, all other -! ways are obsolete and should be avoided. June, 2008 MSB -! -! NOTES -! h5pget(get)fill_value_f function is overloaded to support -! INTEGER, REAL, DOUBLE PRECISION and CHARACTER dtatypes. -! -! Fortran90 Interface: -!! SUBROUTINE h5pget_fill_value_f(prp_id, type_id, fillvalue, hdferr) -!! INTEGER(HID_T), INTENT(IN) :: prp_id -!! INTEGER(HID_T), INTENT(IN) :: type_id -!! TYPE(VOID) , INTENT(OUT) :: fillvalue -!! INTEGER , INTENT(OUT) :: hdferr -!***** SUBROUTINE h5pget_fill_value_integer(prp_id, type_id, fillvalue, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier of - ! of fillvalue datatype - ! (in memory) - INTEGER, INTENT(OUT), TARGET :: fillvalue ! Fillvalue - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER, INTENT(OUT), TARGET :: fillvalue + INTEGER, INTENT(OUT) :: hdferr TYPE(C_PTR) :: f_ptr ! C address f_ptr = C_LOC(fillvalue) @@ -6319,12 +4226,10 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) SUBROUTINE h5pset_fill_value_char(prp_id, type_id, fillvalue, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier of - ! of fillvalue datatype - ! (in memory) - CHARACTER(LEN=1), INTENT(IN), TARGET :: fillvalue ! Fillvalue - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(IN) :: type_id + CHARACTER(LEN=1), INTENT(IN), TARGET :: fillvalue + INTEGER, INTENT(OUT) :: hdferr TYPE(C_PTR) :: f_ptr ! C address f_ptr = C_LOC(fillvalue(1:1)) @@ -6334,12 +4239,10 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) SUBROUTINE h5pget_fill_value_char(prp_id, type_id, fillvalue, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier of - ! of fillvalue datatype - ! (in memory) - CHARACTER(LEN=*), INTENT(OUT) :: fillvalue ! Fillvalue - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(IN) :: type_id + CHARACTER(LEN=*), INTENT(OUT) :: fillvalue + INTEGER, INTENT(OUT) :: hdferr INTEGER :: i CHARACTER(LEN=1), ALLOCATABLE, DIMENSION(:), TARGET :: chr @@ -6364,156 +4267,36 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) ENDDO DEALLOCATE(chr) - END SUBROUTINE h5pget_fill_value_char -! -!****s* H5P (F03)/h5pset_fill_value_f_F03 -! -! NAME -! h5pset_fill_value_f -! -! PURPOSE -! Sets fill value for a dataset creation property list -! -! Inputs: -! prp_id - Property list identifier -! type_id - Datatype identifier of fill value datatype (in memory) -! fillvalue - Fillvalue -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Added the recommended way of passing fillvalue -! and that is by passing the C address, all other -! ways are obsolete and should be avoided. June, 2008 MSB -! -! NOTES -! h5pset(get)fill_value_f function is overloaded to support -! INTEGER, REAL, DOUBLE PRECISION and CHARACTER dtatypes. -! -! Fortran2003 Interface: -!! SUBROUTINE h5pset_fill_value_f(prp_id, type_id, fillvalue, hdferr) -!! INTEGER(HID_T), INTENT(IN) :: prp_id -!! INTEGER(HID_T), INTENT(IN) :: type_id -!! TYPE(C_PTR) , INTENT(IN) :: fillvalue -!! INTEGER , INTENT(OUT) :: hdferr -!***** - - SUBROUTINE h5pset_fill_value_ptr(prp_id, type_id, fillvalue, hdferr) - IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier of - ! of fillvalue datatype - ! (in memory) - TYPE(C_PTR), INTENT(IN) :: fillvalue ! Fillvalue - INTEGER, INTENT(OUT) :: hdferr ! Error code - - hdferr = h5pset_fill_value_c(prp_id, type_id, fillvalue) - - END SUBROUTINE h5pset_fill_value_ptr - -! -!****s* H5P (F03)/h5pget_fill_value_f_F03 -! -! NAME -! h5pget_fill_value_f -! -! PURPOSE -! Gets fill value for a dataset creation property list -! -! Inputs: -! prp_id - Property list identifier -! type_id - Datatype identifier of fill value datatype (in memory) -! -! Outputs: -! fillvalue - Fillvalue -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 14, 2001 -! -! Added the recommended way of passing fillvalue -! and that is by passing the C address, all other -! ways are obsolete and should be avoided. June, 2008 MSB -! -! NOTES -! h5pget(get)fill_value_f function is overloaded to support -! INTEGER, REAL, DOUBLE PRECISION and CHARACTER dtatypes. -! -! Fortran2003 Interface: -!! SUBROUTINE h5pget_fill_value_f(prp_id, type_id, fillvalue, hdferr) -!! INTEGER(HID_T), INTENT(IN) :: prp_id -!! INTEGER(HID_T), INTENT(IN) :: type_id -!! TYPE(C_PTR) :: fillvalue -!! INTEGER , INTENT(OUT) :: hdferr -!***** + END SUBROUTINE h5pget_fill_value_char + + SUBROUTINE h5pset_fill_value_ptr(prp_id, type_id, fillvalue, hdferr) + IMPLICIT NONE + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(IN) :: type_id + TYPE(C_PTR), INTENT(IN) :: fillvalue + INTEGER, INTENT(OUT) :: hdferr + + hdferr = h5pset_fill_value_c(prp_id, type_id, fillvalue) + + END SUBROUTINE h5pset_fill_value_ptr SUBROUTINE h5pget_fill_value_ptr(prp_id, type_id, fillvalue, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier of - ! of fillvalue datatype - ! (in memory) + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER(HID_T), INTENT(IN) :: type_id TYPE(C_PTR) :: fillvalue ! Fillvalue - INTEGER , INTENT(OUT) :: hdferr ! Error code + INTEGER , INTENT(OUT) :: hdferr hdferr = h5pget_fill_value_c(prp_id, type_id, fillvalue) END SUBROUTINE h5pget_fill_value_ptr -! -!****s* H5P (F03)/h5pset_f_F90 -! -! NAME -! h5pset_f -! -! PURPOSE -! Sets a property list value -! -! Inputs: -! prp_id - Property list identifier to modify -! name - Name of property to modify -! value - Property value, supported types are: -! INTEGER -! REAL -! DOUBLE PRECISION -! CHARACTER(LEN=*) -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran90 Interface: -!! SUBROUTINE h5pset_f(plid, name, value, hdferr) -!! INTEGER(HID_T) , INTENT(IN) :: plid -!! CHARACTER(LEN=*), INTENT(IN) :: name -!! TYPE , INTENT(IN) :: value -!! INTEGER , INTENT(OUT) :: hdferr -!***** SUBROUTINE h5pset_integer(prp_id, name, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to modify - INTEGER, INTENT(IN), TARGET :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(IN), TARGET :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len TYPE(C_PTR) :: f_ptr @@ -6527,10 +4310,10 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) SUBROUTINE h5pset_char(prp_id, name, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to modify - CHARACTER(LEN=*), INTENT(IN) :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + CHARACTER(LEN=*), INTENT(IN) :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len INTEGER :: i @@ -6560,44 +4343,26 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) DEALLOCATE(chr) END SUBROUTINE h5pset_char -! -!****s* H5P (F03)/h5pget_f_F90 -! -! NAME -! h5pget_f -! -! PURPOSE -! Queries the value of a property. -! -! Inputs: -! prp_id - Property list identifier to modify -! name - Name of property to get -! value - Property value, supported types are: -! INTEGER -! REAL -! DOUBLE PRECISION -! CHARACTER(LEN=*) -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran90 Interface: -!! SUBROUTINE h5pget_f(plid, name, value, hdferr) -!! INTEGER(HID_T) , INTENT(IN) :: plid -!! CHARACTER(LEN=*), INTENT(IN) :: name -!! TYPE , INTENT(OUT) :: value -!! INTEGER , INTENT(OUT) :: hdferr -!***** - +!> +!! \ingroup FH5P +!! +!! \brief Queries the value of a property. +!! +!! \param prp_id Property list identifier to modify. +!! \param name Name of property to get. +!! \param value Property value, supported types are: +!! \li INTEGER +!! \li REAL +!! \li DOUBLE PRECISION +!! \li CHARACTER(LEN=*) +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_integer(prp_id, name, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to modify - INTEGER, INTENT(OUT), TARGET :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(OUT), TARGET :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len TYPE(C_PTR) :: f_ptr @@ -6610,10 +4375,10 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) SUBROUTINE h5pget_char(prp_id, name, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to modify - CHARACTER(LEN=*), INTENT(OUT) :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + CHARACTER(LEN=*), INTENT(OUT) :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len INTEGER :: i @@ -6640,125 +4405,58 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pget_char -! -!****s* H5P (F03)/h5pset_f_F03 -! -! NAME -! h5pset_f -! -! PURPOSE -! Sets a property list value -! -! Inputs: -! prp_id - Property list identifier to modify -! name - Name of property to modify -! value - Pointer to value to set the property to -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran2003 Interface: -!! SUBROUTINE h5pset_f(plid, name, value, hdferr) -!! INTEGER(HID_T) , INTENT(IN) :: plid -!! CHARACTER(LEN=*), INTENT(IN) :: name -!! TYPE(C_PTR) , INTENT(IN) :: value -!! INTEGER , INTENT(OUT) :: hdferr -!***** +!> +!! \ingroup FH5P +!! +!! \brief Sets a property list value +!! +!! \param prp_id Property list identifier to modify. +!! \param name Name of property to modify. +!! \param value Pointer to value to set the property to. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_ptr(prp_id, name, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to modify - TYPE(C_PTR), INTENT(IN) :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + TYPE(C_PTR), INTENT(IN) :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len name_len = LEN(name) hdferr = h5pset_c(prp_id, name, name_len, value) END SUBROUTINE h5pset_ptr -! -!****s* H5P (F03)/h5pget_f_F03 -! -! NAME -! h5pget_f (F03) -! -! PURPOSE -! Queries the value of a property. -! -! Inputs: -! prp_id - Property list identifier to modify -! name - Name of property to get -! value - Pointer to a location to which to copy the value of of the property -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! Fortran2003 Interface: -!! SUBROUTINE h5pget_f(plid, name, value, hdferr) -!! INTEGER(HID_T) , INTENT(IN) :: plid -!! CHARACTER(LEN=*), INTENT(IN) :: name -!! TYPE(C_PTR) , INTENT(OUT) :: value -!! INTEGER , INTENT(OUT) :: hdferr -!***** +!> +!! \ingroup FH5P +!! +!! \brief Queries the value of a property. +!! +!! \param prp_id Property list identifier to modify. +!! \param name Name of property to get. +!! \param value Pointer to a location to which to copy the value of of the property. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_ptr(prp_id, name, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to modify - TYPE(C_PTR), INTENT(OUT) :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: prp_id + CHARACTER(LEN=*), INTENT(IN) :: name + TYPE(C_PTR), INTENT(OUT) :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len name_len = LEN(name) hdferr = h5pget_c(prp_id, name, name_len, value) END SUBROUTINE h5pget_ptr -! -!****s* H5P (F03)/h5pregister_f_F90 -! -! NAME -! h5pregister -! -! PURPOSE -! Registers a permanent property with a property list class. -! -! Inputs: -! class - Property list class identifier -! name - Name of property to register -! size - Size of the property value -! value - Property value, supported types are: -! INTEGER -! REAL -! DOUBLE PRECISION -! CHARACTER(LEN=*) -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! October 10, 2002 -! -! Fortran90 Interface: -!! SUBROUTINE h5pregister_f(class, name, size, value, hdferr) -!! INTEGER(HID_T) , INTENT(IN) :: class -!! CHARACTER(LEN=*), INTENT(IN) :: name -!! INTEGER(SIZE_T) , INTENT(IN) :: size -!! TYPE , INTENT(IN) :: value -!! INTEGER , INTENT(OUT) :: hdferr -!***** + SUBROUTINE h5pregister_integer(class, name, size, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: class ! Property list class identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to register - INTEGER(SIZE_T), INTENT(IN) :: size ! Size of the property value - INTEGER, INTENT(IN), TARGET :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: class + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T), INTENT(IN) :: size + INTEGER, INTENT(IN), TARGET :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len TYPE(C_PTR) :: f_ptr @@ -6769,14 +4467,13 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pregister_integer - SUBROUTINE h5pregister_char(class, name, size, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: class ! Property list class identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to register - INTEGER(SIZE_T), INTENT(IN) :: size ! size of the property value - CHARACTER(LEN=*), INTENT(IN) :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: class + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T), INTENT(IN) :: size + CHARACTER(LEN=*), INTENT(IN) :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len INTEGER :: i @@ -6804,89 +4501,27 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) hdferr = h5pregister_c(class, name, name_len, size, f_ptr) DEALLOCATE(chr) END SUBROUTINE h5pregister_char -! -!****s* H5P (F03)/h5pregister_f_F03 -! -! NAME -! h5pregister (F03) -! -! PURPOSE -! Registers a permanent property with a property list class. -! -! Inputs: -! class - Property list class identifier -! name - Name of property to register -! size - Size of the property value -! value - Pointer to value to set the property to -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! June 24, 2008 -! -! Fortran2003 Interface: -!! SUBROUTINE h5pregister_f(class, name, size, value, hdferr) -!! INTEGER(HID_T) , INTENT(IN) :: class -!! CHARACTER(LEN=*), INTENT(IN) :: name -!! INTEGER(SIZE_T) , INTENT(IN) :: size -!! TYPE(C_PTR) , INTENT(IN) :: value -!! INTEGER , INTENT(OUT) :: hdferr -!***** SUBROUTINE h5pregister_ptr(class, name, size, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: class ! Property list class identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to register - INTEGER(SIZE_T), INTENT(IN) :: size ! Size of the property value - TYPE(C_PTR), INTENT(IN) :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: class + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T), INTENT(IN) :: size + TYPE(C_PTR), INTENT(IN) :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len name_len = LEN(name) hdferr = h5pregister_c(class, name, name_len, size, value) END SUBROUTINE h5pregister_ptr -! -!****s* H5P (F03)/h5pinsert_f_F90 -! -! NAME -! h5pinsert (f90) -! -! PURPOSE -! Registers a temporary property with a property list class. -! -! Inputs: -! plist - Property list class identifier -! name - Name of property to insert -! size - Size of the property value -! value - Property value, supported types are: -! INTEGER -! REAL -! DOUBLE PRECISION -! CHARACTER(LEN=*) -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! October 10, 2002 -! -! Fortran90 Interface: -!! SUBROUTINE h5pinsert_f -!! INTEGER(HID_T) , INTENT(IN) :: plist -!! CHARACTER(LEN=*), INTENT(IN) :: name -!! INTEGER(SIZE_T) , INTENT(IN) :: size -!! TYPE , INTENT(IN) :: value -!! INTEGER , INTENT(OUT) :: hdferr -!***** SUBROUTINE h5pinsert_integer(plist, name, size, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to insert - INTEGER(SIZE_T), INTENT(IN) :: size ! Size of the property value - INTEGER, INTENT(IN), TARGET :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: plist + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T), INTENT(IN) :: size + INTEGER, INTENT(IN), TARGET :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len TYPE(c_ptr) :: f_ptr @@ -6898,11 +4533,11 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) SUBROUTINE h5pinsert_char(plist, name, size, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to insert - INTEGER(SIZE_T), INTENT(IN) :: size ! Size of property value - CHARACTER(LEN=*), INTENT(IN) :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: plist + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T), INTENT(IN) :: size + CHARACTER(LEN=*), INTENT(IN) :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len INTEGER :: i @@ -6933,91 +4568,45 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pinsert_char -! -!****s* H5P (F03)/h5pinsert_f_F03 -! -! NAME -! h5pinsert (f03) -! -! PURPOSE -! Registers a temporary property with a property list class. -! -! Inputs: -! plist - Property list class identifier -! name - Name of property to insert -! size - Size of the property value -! value - Pointer to new value pointer for the property being modified -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! June 24, 2008 -! -! Fortran90 Interface: -!! SUBROUTINE h5pinsert_f -!! INTEGER(HID_T) , INTENT(IN) :: plist -!! CHARACTER(LEN=*), INTENT(IN) :: name -!! INTEGER(SIZE_T) , INTENT(IN) :: size -!! TYPE(C_PTR) , INTENT(IN) :: value -!! INTEGER , INTENT(OUT) :: hdferr -!***** SUBROUTINE h5pinsert_ptr(plist, name, size, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: plist ! Property list identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to insert - INTEGER(SIZE_T), INTENT(IN) :: size ! Size of property value - TYPE(c_ptr), INTENT(IN) :: value ! Property value - INTEGER, INTENT(OUT) :: hdferr ! Error code + INTEGER(HID_T), INTENT(IN) :: plist + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(SIZE_T), INTENT(IN) :: size + TYPE(c_ptr), INTENT(IN) :: value + INTEGER, INTENT(OUT) :: hdferr INTEGER :: name_len name_len = LEN(name) hdferr = h5pinsert_c(plist, name , name_len, size, value) END SUBROUTINE h5pinsert_ptr -! -!****s* H5P (F03)/h5pcreate_class_f_F03 -! -! NAME -! h5pcreate_class_f -! -! PURPOSE -! Create a new property list class -! -! Inputs: -! parent - Parent property list class identifier -! Possible values include: -! H5P_ROOT_F -! H5P_FILE_CREATE_F -! H5P_FILE_ACCESS_F -! H5P_DATASET_CREATE_F -! H5P_DATASET_XFER_F -! H5P_FILE_MOUNT_F -! name - Name of property to create -! -! Outputs: -! class - Property list class identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! Optional parameters: -! H5P_cls_create_func_t (create) - Callback routine called when a property list is created -! create_data - User pointer to any class creation information needed -! H5P_cls_copy_func_t (copy) - Callback routine called when a property list is copied -! copy_data - User pointer to any class copy information needed -! H5P_cls_close_func_t (close) - Callback routine called when a property list is being closed -! close_data - User pointer to any class close information needed -! -! AUTHOR -! Elena Pourmal -! October 9, 2002 -! -! HISTORY -! Added callback arguments -! M. Scot Breitenfeld, July 3, 2008 -! -! Fortran2003 Interface: + +#endif + +!> +!! \ingroup FH5P +!! +!! \brief Create a new property list class +!! +!! \param parent Parent property list class identifier. Possible values include: +!! \li H5P_ROOT_F +!! \li H5P_FILE_CREATE_F +!! \li H5P_FILE_ACCESS_F +!! \li H5P_DATASET_CREATE_F +!! \li H5P_DATASET_XFER_F +!! \li H5P_FILE_MOUNT_F +!! \param name Name of property to create. +!! \param class Property list class identifier. +!! \param hdferr \fortran_error +!! \param create (H5P_cls_create_func_t) - Callback routine called when a property list is created. +!! \param create_data User pointer to any class creation information needed. +!! \param copy (H5P_cls_copy_func_t) - Callback routine called when a property list is copied. +!! \param copy_data User pointer to any class copy information needed. +!! \param close (H5P_cls_close_func_t) - Callback routine called when a property list is being closed. +!! \param close_data User pointer to any class close information needed. +!! SUBROUTINE h5pcreate_class_f(parent, name, class, hdferr, create, create_data, & - copy, copy_data, CLOSE, close_data) + copy, copy_data, close, close_data) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: parent CHARACTER(LEN=*), INTENT(IN) :: name @@ -7025,7 +4614,6 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) INTEGER , INTENT(OUT) :: hdferr TYPE(C_PTR) , OPTIONAL :: create_data, copy_data, close_data TYPE(C_FUNPTR) , OPTIONAL :: create, copy, close -!***** INTEGER :: name_len TYPE(C_PTR) :: create_data_default, copy_data_default, close_data_default TYPE(C_FUNPTR) :: create_default, copy_default, close_default @@ -7066,36 +4654,22 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pcreate_class_f -! -!****s* H5P (F03)/h5pset_file_image_f_F03 -! -! NAME -! h5pset_file_image_f -! -! PURPOSE -! Sets an initial file image in a memory buffer. -! -! Inputs: -! fapl_id - File access property list identifier -! buf_ptr - Pointer to the initial file image, -! or C_NULL_PTR if no initial file image is desired -! buf_len - Size of the supplied buffer, or 0 (zero) if no initial image is desired -! -! Outputs: -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! February 19, 2012 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets an initial file image in a memory buffer. +!! +!! \param fapl_id File access property list identifier. +!! \param buf_ptr Pointer to the initial file image, or C_NULL_PTR if no initial file image is desired. +!! \param buf_len Size of the supplied buffer, or 0 (zero) if no initial image is desired. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_file_image_f(fapl_id, buf_ptr, buf_len, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: fapl_id TYPE(C_PTR) , INTENT(IN) :: buf_ptr INTEGER(SIZE_T), INTENT(IN) :: buf_len INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5pset_file_image_c(fapl_id, buf_ptr, buf_len) & BIND(C, NAME='h5pset_file_image_c') @@ -7110,39 +4684,20 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) hdferr = h5pset_file_image_c(fapl_id, buf_ptr, buf_len) END SUBROUTINE h5pset_file_image_f -! -!****s* H5P (F03)/h5pget_file_image_f_F03 -! -! NAME -! h5pget_file_image_f -! -! PURPOSE -! Retrieves a copy of the file image designated as the initial content and structure of a file. -! -! Inputs: -! fapl_id - File access property list identifier. -! -! Outputs: -! buf_ptr - Will hold either a C_NULL_PTR or a scalar of type -! c_loc. If buf_ptr is not C_NULL_PTR, on successful -! return, buf_ptr shall contain a C pointer to a copy -! of the initial image provided in the last call to -! H5Pset_file_image_f for the supplied fapl_id, or -! buf_ptr shall contain a C_NULL_PTR if there is no -! initial image set. -! -! buf_len_ptr - Contains the value of the buffer parameter for -! the initial image in the supplied fapl_id. The value -! will be 0 if no initial image is set. -! -! -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! February 19, 2012 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves a copy of the file image designated as the initial content and structure of a file. +!! +!! \param fapl_id File access property list identifier. +!! \param buf_ptr Will hold either a C_NULL_PTR or a scalar of type c_loc. If buf_ptr is not C_NULL_PTR, on successful +!! return, buf_ptr shall contain a C pointer to a copy of the initial image provided in the last call to +!! H5Pset_file_image_f for the supplied fapl_id, or buf_ptr shall contain a C_NULL_PTR if there is no +!! initial image set. +!! \param buf_len_ptr Contains the value of the buffer parameter for the initial image in the supplied fapl_id. The value +!! will be 0 if no initial image is set. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_file_image_f(fapl_id, buf_ptr, buf_len_ptr, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: fapl_id @@ -7150,7 +4705,6 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) INTEGER(SIZE_T), INTENT(OUT) :: buf_len_ptr INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5pget_file_image_c(fapl_id, buf_ptr, buf_len_ptr) & BIND(C, NAME='h5pget_file_image_c') @@ -7171,35 +4725,22 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) ! ********************************************************************* #ifdef H5_HAVE_PARALLEL -!****s* H5P/h5pset_fapl_mpio_f -! -! NAME -! h5pset_fapl_mpio_f -! -! PURPOSE -! Stores MPI IO communicator information to the file -! access property list. -! -! INPUTS -! prp_id - file access property list identifier -! comm - MPI-2 communicator -! info - MPI-2 info object -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! November, 2000 -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Stores MPI IO communicator information to the file access property list. +!! +!! \param prp_id File access property list identifier. +!! \param comm MPI-2 communicator. +!! \param info MPI-2 info object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_fapl_mpio_f(prp_id, comm, info, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: comm ! MPI communicator to be used for file open - ! as defined in MPI_FILE_OPEN of MPI-2 - INTEGER, INTENT(IN) :: info ! MPI info object to be used for file open - ! as defined in MPI_FILE_OPEN of MPI-2 - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: comm + INTEGER, INTENT(IN) :: info + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_fapl_mpio_c(prp_id, comm, info) & BIND(C,NAME='h5pset_fapl_mpio_c') @@ -7215,34 +4756,22 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pset_fapl_mpio_f -!****s* H5P/h5pget_fapl_mpio_f -! -! NAME -! h5pget_fapl_mpio_f -! -! PURPOSE -! Returns MPI communicator information. -! -! INPUTS -! prp_id - file access property list identifier -! OUTPUTS -! comm - MPI-2 communicator -! info - MPI-2 info object -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! November, 2000 -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Returns MPI communicator information. +!! +!! \param prp_id File access property list identifier. +!! \param comm MPI-2 communicator. +!! \param info MPI-2 info object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_fapl_mpio_f(prp_id, comm, info, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: comm ! buffer to return communicator - INTEGER, INTENT(OUT) :: info ! buffer to return info object - ! as defined in MPI_FILE_OPEN of MPI-2 - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: comm + INTEGER, INTENT(OUT) :: info + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_fapl_mpio_c(prp_id, comm, info) & BIND(C,NAME='h5pget_fapl_mpio_c') @@ -7258,34 +4787,22 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pget_fapl_mpio_f -!****s* H5P/h5pset_dxpl_mpio_f -! -! NAME -! h5pset_dxpl_mpio_f -! -! PURPOSE -! Sets data transfer mode. -! -! INPUTS -! prp_id - data transfer property list identifier -! data_xfer_mode - transfer mode; possible values are: -! H5FD_MPIO_INDEPENDENT_F -! H5FD_MPIO_COLLECTIVE_F -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! November, 2000 -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Sets data transfer mode. +!! +!! \param prp_id Data transfer property list identifier. +!! \param data_xfer_mode Transfer mode; possible values are: +!! \li H5FD_MPIO_INDEPENDENT_F +!! \li H5FD_MPIO_COLLECTIVE_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_dxpl_mpio_f(prp_id, data_xfer_mode, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(IN) :: data_xfer_mode ! Data transfer mode. Possible values are: - ! H5FD_MPIO_INDEPENDENT_F - ! H5FD_MPIO_COLLECTIVE_F - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(IN) :: data_xfer_mode + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pset_dxpl_mpio_c(prp_id, data_xfer_mode) & BIND(C,NAME='h5pset_dxpl_mpio_c') @@ -7299,35 +4816,22 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) hdferr = h5pset_dxpl_mpio_c(prp_id, data_xfer_mode) END SUBROUTINE h5pset_dxpl_mpio_f -!****s* H5P/h5pget_dxpl_mpio_f -! -! NAME -! h5pget_dxpl_mpio_f -! -! PURPOSE -! Returns the data transfer mode. -! -! INPUTS -! prp_id - data transfer property list identifier -! OUTPUTS -! data_xfer_mode- transfer mode; possible values are: -! H5FD_MPIO_INDEPENDENT_F -! H5FD_MPIO_COLLECTIVE_F -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! November, 2000 -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Returns the data transfer mode. +!! +!! \param prp_id Data transfer property list identifier. +!! \param data_xfer_mode Transfer mode; possible values are: +!! \li H5FD_MPIO_INDEPENDENT_F +!! \li H5FD_MPIO_COLLECTIVE_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_dxpl_mpio_f(prp_id, data_xfer_mode, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier - INTEGER, INTENT(OUT) :: data_xfer_mode ! Data transfer mode. Possible values are: - ! H5FD_MPIO_INDEPENDENT_F - ! H5FD_MPIO_COLLECTIVE_F - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: prp_id + INTEGER, INTENT(OUT) :: data_xfer_mode + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5pget_dxpl_mpio_c(prp_id, data_xfer_mode) & BIND(C,NAME='h5pget_dxpl_mpio_c') @@ -7341,33 +4845,21 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) hdferr = h5pget_dxpl_mpio_c(prp_id, data_xfer_mode) END SUBROUTINE h5pget_dxpl_mpio_f -!****s* H5P/h5pget_mpio_actual_io_mode_f -! NAME -! h5pget_mpio_actual_io_mode_f -! -! PURPOSE -! Retrieves the type of I/O that HDF5 actually performed on the last -! parallel I/O call. This is not necessarily the type of I/O requested. -! -! INPUTS -! dxpl_id - Dataset transfer property list identifier. -! OUTPUTS -! actual_io_mode - The type of I/O performed by this process. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! July 27, 2012 -! -! HISTORY -! -! Fortran90 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the type of I/O that HDF5 actually performed on the last +!! parallel I/O call. This is not necessarily the type of I/O requested. +!! +!! \param dxpl_id Dataset transfer property list identifier. +!! \param actual_io_mode The type of I/O performed by this process. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_mpio_actual_io_mode_f(dxpl_id, actual_io_mode, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dxpl_id INTEGER , INTENT(OUT) :: actual_io_mode INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5pget_mpio_actual_io_mode_c(dxpl_id, actual_io_mode) & BIND(C,NAME='h5pget_mpio_actual_io_mode_c') @@ -7384,35 +4876,23 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pget_mpio_actual_io_mode_f -!****s* H5P/h5pset_all_coll_metadata_ops_f -! NAME -! h5pset_all_coll_metadata_ops_f -! -! PURPOSE -! Sets requirement whether HDF5 metadata read operations using the access property -! list are required to be collective or independent. If collective requirement is -! selected, the HDF5 library will optimize the metadata reads improving performance. -! The default setting is independent (false). -! -! INPUTS -! plist_id - File access property list identifier. -! is_collective - Indicates if metadata writes are collective or not. -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! Feb, 10 2016 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Sets requirement whether HDF5 metadata read operations using the access property +!! list are required to be collective or independent. If collective requirement is +!! selected, the HDF5 library will optimize the metadata reads improving performance. +!! The default setting is independent (false). +!! +!! \param plist_id File access property list identifier. +!! \param is_collective Indicates if metadata writes are collective or not. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_all_coll_metadata_ops_f(plist_id, is_collective, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: plist_id LOGICAL, INTENT(IN) :: is_collective INTEGER, INTENT(OUT) :: hdferr -!***** LOGICAL(C_BOOL) :: c_is_collective INTERFACE @@ -7431,33 +4911,21 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pset_all_coll_metadata_ops_f -!****s* H5P/h5pget_all_coll_metadata_ops_f -! NAME -! h5pget_all_coll_metadata_ops_f -! -! PURPOSE -! Retrieves metadata read mode from the access property list. -! -! INPUTS -! plist_id - File access property list identifier. -! OUTPUTS -! is_collective - Collective access setting. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! Feb, 10 2016 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Retrieves metadata read mode from the access property list. +!! +!! \param plist_id File access property list identifier. +!! \param is_collective Collective access setting. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_all_coll_metadata_ops_f(plist_id, is_collective, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: plist_id LOGICAL, INTENT(OUT) :: is_collective INTEGER, INTENT(OUT) :: hdferr -!***** LOGICAL(C_BOOL) :: c_is_collective INTERFACE @@ -7476,32 +4944,20 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pget_all_coll_metadata_ops_f -!****s* H5P/h5pset_coll_metadata_write_f -! NAME -! h5pset_coll_metadata_write_f -! -! PURPOSE -! Sets metadata writes to collective or independent. Default setting is independent (false). -! -! INPUTS -! fapl_id - File access property list identifier. -! is_collective - Indicates if metadata writes are collective or not. -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! Feb, 10 2016 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Sets metadata writes to collective or independent. Default setting is independent (false). +!! +!! \param plist_id File access property list identifier. +!! \param is_collective Indicates if metadata writes are collective or not. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_coll_metadata_write_f(plist_id, is_collective, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: plist_id LOGICAL, INTENT(IN) :: is_collective INTEGER, INTENT(OUT) :: hdferr -!***** LOGICAL(C_BOOL) :: c_is_collective INTERFACE @@ -7520,33 +4976,21 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pset_coll_metadata_write_f -!****s* H5P/h5pget_coll_metadata_write_f -! NAME -! h5pget_coll_metadata_write_f -! -! PURPOSE -! Retrieves metadata write mode from the file access property list. -! -! INPUTS -! plist_id - File access property list identifier. -! OUTPUTS -! is_collective - Collective access setting. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! Feb, 10 2016 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Retrieves metadata write mode from the file access property list. +!! +!! \param plist_id File access property list identifier. +!! \param is_collective Collective access setting. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_coll_metadata_write_f(plist_id, is_collective, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: plist_id LOGICAL, INTENT(OUT) :: is_collective INTEGER, INTENT(OUT) :: hdferr -!***** LOGICAL(C_BOOL) :: c_is_collective INTERFACE @@ -7571,30 +5015,17 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) ! V I R T U A L D A T S E T S ! -!****s* H5P/h5pset_virtual_view_f -! NAME -! h5pset_virtual_view_f -! -! PURPOSE -! Sets the view of the virtual dataset (VDS) to include or exclude missing mapped elements. -! -! INPUTS -! dapl_id - Identifier of the virtual dataset access property list. -! view - Flag specifying the extent of the data to be included in the view. -! Valid values are: -! H5D_VDS_FIRST_MISSING_F -! H5D_VDS_LAST_AVAILABLE_F -! -! OUTPUTS -! -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! Nov 2, 2015 -! -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Sets the view of the virtual dataset (VDS) to include or exclude missing mapped elements. +!! +!! \param dapl_id Identifier Of the virtual dataset access property list. +!! \param view Flag specifying the extent of the data to be included in the view. Valid values are: +!! \li H5D_VDS_FIRST_MISSING_F +!! \li H5D_VDS_LAST_AVAILABLE_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_virtual_view_f(dapl_id, view, hdferr) IMPLICIT NONE @@ -7602,7 +5033,6 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) INTEGER , INTENT(IN) :: view INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5pset_virtual_view(dapl_id, view) BIND(C,NAME='H5Pset_virtual_view') IMPORT :: HID_T, ENUM_T @@ -7616,35 +5046,23 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pset_virtual_view_f -!****s* H5P/h5pget_virtual_view_f -! NAME -! h5pget_virtual_view_f -! -! PURPOSE -! Retrieves the view of a virtual dataset accessed with dapl_id. -! -! INPUTS -! dapl_id - Dataset access property list identifier for the virtual dataset -! -! OUTPUTS -! view - The flag specifying the view of the virtual dataset. -! Valid values are: -! H5D_VDS_FIRST_MISSING_F -! H5D_VDS_LAST_AVAILABLE_F -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! Nov 2, 2015 -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Retrieves the view of a virtual dataset accessed with dapl_id. +!! +!! \param dapl_id Dataset access property list identifier for the virtual dataset. +!! \param view The flag specifying the view of the virtual dataset. Valid values are: +!! \li H5D_VDS_FIRST_MISSING_F +!! \li H5D_VDS_LAST_AVAILABLE_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_virtual_view_f(dapl_id, view, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dapl_id INTEGER , INTENT(INOUT) :: view INTEGER , INTENT(OUT) :: hdferr -!***** INTEGER(ENUM_T) :: view_enum INTERFACE INTEGER FUNCTION h5pget_virtual_view(dapl_id, view) BIND(C,NAME='H5Pget_virtual_view') @@ -7660,35 +5078,22 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pget_virtual_view_f -!****s* H5P/h5pset_virtual_printf_gap_f -! NAME -! h5pset_virtual_printf_gap_f -! -! PURPOSE -! Sets the maximum number of missing source files and/or datasets with the printf-style names -! when getting the extent of an unlimited virtual dataset. -! -! INPUTS -! dapl_id - Dataset access property list identifier for the virtual dataset. -! gap_size - Maximum number of files and/or datasets allowed to be missing for determining -! the extent of an unlimited virtual dataset with printf-style mappings. -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! Nov 2, 2015 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Sets the maximum number of missing source files and/or datasets with the printf-style names +!! when getting the extent of an unlimited virtual dataset. +!! +!! \param dapl_id Dataset access property list identifier for the virtual dataset. +!! \param gap_size Maximum number of files and/or datasets allowed to be missing for determining +!! the extent of an unlimited virtual dataset with printf-style mappings. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_virtual_printf_gap_f(dapl_id, gap_size, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: dapl_id INTEGER(HSIZE_T), INTENT(IN) :: gap_size INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5pset_virtual_printf_gap(dapl_id, gap_size) BIND(C,NAME='H5Pset_virtual_printf_gap') IMPORT :: HID_T, HSIZE_T @@ -7702,36 +5107,23 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pset_virtual_printf_gap_f -!****s* H5P/h5pget_virtual_printf_gap_f -! NAME -! h5pget_virtual_printf_gap_f -! -! PURPOSE -! Returns the maximum number of missing source files and/or datasets with the -! printf-style names when getting the extent for an unlimited virtual dataset. -! -! INPUTS -! dapl_id - Dataset access property list identifier for the virtual dataset -! -! OUTPUTS -! gap_size - Maximum number of the files and/or datasets allowed to be missing for -! determining the extent of an unlimited virtual dataset with printf-style mappings. -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! Nov 2, 2015 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Returns the maximum number of missing source files and/or datasets with the +!! printf-style names when getting the extent for an unlimited virtual dataset. +!! +!! \param dapl_id Dataset access property list identifier for the virtual dataset. +!! \param gap_size Maximum Number of the files and/or datasets allowed to be missing for +!! determining the extent of an unlimited virtual dataset with printf-style mappings. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_virtual_printf_gap_f(dapl_id, gap_size, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: dapl_id INTEGER(HSIZE_T), INTENT(OUT) :: gap_size INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5pget_virtual_printf_gap(dapl_id, gap_size) BIND(C,NAME='H5Pget_virtual_printf_gap') IMPORT :: HID_T, HSIZE_T @@ -7745,32 +5137,18 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pget_virtual_printf_gap_f -!****s* H5P/h5pset_virtual_f -! NAME -! h5pset_virtual_f -! -! PURPOSE -! Sets the mapping between virtual and source datasets. -! -! INPUTS -! dcpl_id - The identifier of the dataset creation property list that will be -! used when creating the virtual dataset. -! vspace_id - The dataspace identifier with the selection within the virtual -! dataset applied, possibly an unlimited selection. -! src_file_name - The name of the HDF5 file where the source dataset is located. -! src_dset_name - The path to the HDF5 dataset in the file specified by src_file_name. -! src_space_id - The source dataset’s dataspace identifier with a selection applied, possibly an unlimited selection -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails - -! AUTHOR -! M. Scot Breitenfeld -! Nov 2, 2015 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Sets the mapping between virtual and source datasets. +!! +!! \param dcpl_id The identifier of the dataset creation property list that will be used when creating the virtual dataset. +!! \param vspace_id The dataspace identifier with the selection within the virtual dataset applied, possibly an unlimited selection. +!! \param src_file_name The name of the HDF5 file where the source dataset is located. +!! \param src_dset_name The path to the HDF5 dataset in the file specified by src_file_name. +!! \param src_space_id The source dataset’s dataspace identifier with a selection applied, possibly an unlimited selection. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_virtual_f(dcpl_id, vspace_id, src_file_name, src_dset_name, src_space_id, hdferr) IMPLICIT NONE @@ -7780,7 +5158,6 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) CHARACTER(LEN=*), INTENT(IN) :: src_dset_name INTEGER(HID_T), INTENT(IN) :: src_space_id INTEGER, INTENT(OUT) :: hdferr -!***** CHARACTER(LEN=LEN_TRIM(src_file_name)+1,KIND=C_CHAR) :: c_src_file_name CHARACTER(LEN=LEN_TRIM(src_dset_name)+1,KIND=C_CHAR) :: c_src_dset_name @@ -7805,26 +5182,15 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pset_virtual_f -!****s* H5P/h5pget_virtual_count_f -! NAME -! h5pget_virtual_count_f -! -! PURPOSE -! Gets the number of mappings for the virtual dataset. -! -! INPUTS -! dcpl_id - The identifier of the virtual dataset creation property list. -! -! OUTPUTS -! count - The number of mappings. -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! M. Scot Breitenfeld -! Nov 2, 2015 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Gets the number of mappings for the virtual dataset. +!! +!! \param dcpl_id The identifier of the virtual dataset creation property list. +!! \param count The number of mappings. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_virtual_count_f(dcpl_id, count, hdferr) IMPLICIT NONE @@ -7832,7 +5198,6 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) INTEGER(HID_T), INTENT(IN) :: dcpl_id INTEGER(SIZE_T), INTENT(OUT) :: count INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER(C_INT) FUNCTION h5pget_virtual_count(dcpl_id, count) BIND(C,NAME='H5Pget_virtual_count') IMPORT :: HID_T, SIZE_T, C_INT @@ -7846,29 +5211,17 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pget_virtual_count_f -!****s* H5P/h5pget_virtual_vspace_f -! NAME -! h5pget_virtual_vspace_f -! -! PURPOSE -! Gets a dataspace identifier for the selection within the virtual dataset used in the mapping. -! -! INPUTS -! dcpl_id - The identifier of the virtual dataset creation property list. -! index - Mapping index. -! The value of index is 0 (zero) or greater and less than count (0 ≤ index < count), -! where count is the number of mappings returned by h5pget_virtual_count. -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! Nov 2, 2015 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Gets a dataspace identifier for the selection within the virtual dataset used in the mapping. +!! +!! \param dcpl_id The identifier of the virtual dataset creation property list. +!! \param index Mapping index. The value of index is 0 (zero) or greater and less than count (0 ≤ index < count), +!! where count is the number of mappings returned by h5pget_virtual_count. +!! \param ds_id Valid dataspace identifier identifier if successful; otherwise returns H5I_INVALID_HID_F. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_virtual_vspace_f(dcpl_id, index, ds_id, hdferr) IMPLICIT NONE @@ -7877,7 +5230,6 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) INTEGER(HID_T) , INTENT(OUT) :: ds_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER(HID_T) FUNCTION h5pget_virtual_vspace(dcpl_id, index) BIND(C,NAME='H5Pget_virtual_vspace') IMPORT :: HID_T, SIZE_T @@ -7894,31 +5246,17 @@ SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr) END SUBROUTINE h5pget_virtual_vspace_f -!****s* H5P/h5pget_virtual_srcspace_f -! NAME -! h5pget_virtual_srcspace_f -! -! PURPOSE -! Gets a dataspace identifier for the selection within the source dataset used in the mapping. -! -! INPUTS -! dcpl_id - The identifier of the virtual dataset creation property list. -! index - Mapping index. -! The value of index is 0 (zero) or greater and less than count (0 ≤ index < count), -! where count is the number of mappings returned by h5pget_virtual_count. -! -! -! OUTPUTS -! ds_id - dataspace identifier -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! Nov 2, 2015 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Gets a dataspace identifier for the selection within the source dataset used in the mapping. +!! +!! \param dcpl_id The Identifier of the virtual dataset creation property list. +!! \param index Mapping index.The value of index is 0 (zero) or greater and less than count (0 ≤ index < count), +!! where count is the number of mappings returned by h5pget_virtual_count. +!! \param ds_id Dataspace identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_virtual_srcspace_f(dcpl_id, index, ds_id, hdferr) IMPLICIT NONE @@ -7927,7 +5265,6 @@ SUBROUTINE h5pget_virtual_srcspace_f(dcpl_id, index, ds_id, hdferr) INTEGER(HID_T) , INTENT(OUT) :: ds_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER(HID_T) FUNCTION h5pget_virtual_srcspace(dcpl_id, index) BIND(C,NAME='H5Pget_virtual_srcspace') IMPORT :: HID_T, SIZE_T @@ -7944,33 +5281,19 @@ SUBROUTINE h5pget_virtual_srcspace_f(dcpl_id, index, ds_id, hdferr) END SUBROUTINE h5pget_virtual_srcspace_f -!****s* H5P/h5pget_virtual_filename_f -! NAME -! h5pget_virtual_filename_f -! -! PURPOSE -! Gets the filename of a source dataset used in the mapping. -! -! INPUTS -! dcpl_id - The identifier of the virtual dataset creation property list. -! index - Mapping index. -! The value of index is 0 (zero) or greater and less than count (0 ≤ index < count), -! where count is the number of mappings returned by h5pget_virtual_count. -! -! OUTPUTS -! name - A buffer containing the name of the file containing the source dataset. -! hdferr - Returns 0 if successful and -1 if fails. -! -! Optional parameters: -! name_len - The size of name needed to hold the filename. (OUT) -! -! AUTHOR -! M. Scot Breitenfeld -! Nov 2, 2015 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Gets the filename of a source dataset used in the mapping. +!! +!! \param dcpl_id The identifier of the virtual dataset creation property list. +!! \param index Mapping index. The value of index is 0 (zero) or greater and less than count (0 ≤ index < count), +!! where count is the number of mappings returned by h5pget_virtual_count. +!! \param name A buffer containing the name of the file containing the source dataset. +!! \param hdferr \fortran_error +!! \param name_len The size of name needed to hold the filename. (OUT) +!! +!! SUBROUTINE h5pget_virtual_filename_f(dcpl_id, index, name, hdferr, name_len) IMPLICIT NONE @@ -7979,7 +5302,6 @@ SUBROUTINE h5pget_virtual_filename_f(dcpl_id, index, name, hdferr, name_len) CHARACTER(LEN=*), INTENT(OUT) :: name INTEGER, INTENT(OUT) :: hdferr INTEGER(SIZE_T), OPTIONAL :: name_len -!***** CHARACTER(LEN=1,KIND=C_CHAR), DIMENSION(1:LEN(name)+1), TARGET :: c_name TYPE(C_PTR) :: f_ptr @@ -8012,33 +5334,18 @@ SUBROUTINE h5pget_virtual_filename_f(dcpl_id, index, name, hdferr, name_len) END SUBROUTINE h5pget_virtual_filename_f -!****s* H5P/h5pget_virtual_dsetname_f -! NAME -! h5pget_virtual_dsetname_f -! -! PURPOSE -! Gets the name of a source dataset used in the mapping. -! -! INPUTS -! dcpl_id - The identifier of the virtual dataset creation property list. -! index - Mapping index. -! The value of index is 0 (zero) or greater and less than count (0 ≤ index < count), -! where count is the number of mappings returned by h5pget_virtual_count. -! -! OUTPUTS -! name - A buffer containing the name of the source dataset. -! hdferr - Returns 0 if successful and -1 if fails. -! -! Optional parameters: -! name_len - The size of name needed to hold the source dataset name. (OUT) -! -! AUTHOR -! M. Scot Breitenfeld -! January 28, 2016 -! -! HISTORY -! -! SOURCE +!> +!! \ingroup FH5P +!! +!! \brief Gets the name of a source dataset used in the mapping. +!! +!! \param dcpl_id The identifier of the virtual dataset creation property list. +!! \param index Mapping index. The value of index is 0 (zero) or greater and less than count (0 ≤ index < count), +!! where count is the number of mappings returned by h5pget_virtual_count. +!! \param name A buffer containing the name of the source dataset. +!! \param hdferr \fortran_error +!! \param name_len The size of name needed to hold the source dataset name. +!! SUBROUTINE h5pget_virtual_dsetname_f(dcpl_id, index, name, hdferr, name_len) IMPLICIT NONE @@ -8047,7 +5354,6 @@ SUBROUTINE h5pget_virtual_dsetname_f(dcpl_id, index, name, hdferr, name_len) CHARACTER(LEN=*), INTENT(OUT) :: name INTEGER, INTENT(OUT) :: hdferr INTEGER(SIZE_T), OPTIONAL :: name_len -!***** CHARACTER(LEN=1,KIND=C_CHAR), DIMENSION(1:LEN(name)+1), TARGET :: c_name TYPE(C_PTR) :: f_ptr @@ -8079,34 +5385,21 @@ SUBROUTINE h5pget_virtual_dsetname_f(dcpl_id, index, name, hdferr, name_len) END SUBROUTINE h5pget_virtual_dsetname_f -!****s* H5P (F03)/h5pget_dset_no_attrs_hint_f_F03 -! -! NAME -! h5pget_dset_no_attrs_hint_f -! -! PURPOSE -! Gets the value of the "minimize dataset headers" value which creates -! smaller dataset object headers when its set and no attributes are present. -! -! INPUTS -! dcpl_id - Target dataset creation property list identifier. -! -! OUTPUTS -! minimize - Value of the setting. -! hdferr - error code: -! 0 on success and -1 on failure -! -! AUTHOR -! Dana Robinson -! January 2019 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Gets the value of the "minimize dataset headers" value which creates +!! smaller dataset object headers when its set and no attributes are present. +!! +!! \param dcpl_id Target dataset creation property list identifier. +!! \param minimize Value of the setting. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_dset_no_attrs_hint_f(dcpl_id, minimize, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: dcpl_id LOGICAL , INTENT(OUT) :: minimize INTEGER , INTENT(OUT) :: hdferr -!***** LOGICAL(C_BOOL) :: c_minimize INTERFACE @@ -8125,34 +5418,21 @@ END SUBROUTINE h5pget_virtual_dsetname_f END SUBROUTINE h5pget_dset_no_attrs_hint_f -!****s* H5P (F03)/h5pset_dset_no_attrs_hint_f_F03 -! -! NAME -! h5pset_dset_no_attrs_hint_f -! -! PURPOSE -! Sets the value of the "minimize dataset headers" value which creates -! smaller dataset object headers when its set and no attributes are present. -! -! INPUTS -! dcpl_id - Target dataset creation property list identifier. -! minimize - Value of the setting. -! -! OUTPUTS -! hdferr - error code: -! 0 on success and -1 on failure -! -! AUTHOR -! Dana Robinson -! January 2019 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the value of the "minimize dataset headers" value which creates +!! smaller dataset object headers when its set and no attributes are present. +!! +!! \param dcpl_id Target dataset creation property list identifier. +!! \param minimize Value of the setting. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_dset_no_attrs_hint_f(dcpl_id, minimize, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: dcpl_id LOGICAL , INTENT(IN) :: minimize INTEGER , INTENT(OUT) :: hdferr -!***** LOGICAL(C_BOOL) :: c_minimize INTERFACE @@ -8171,37 +5451,22 @@ END SUBROUTINE h5pget_virtual_dsetname_f END SUBROUTINE h5pset_dset_no_attrs_hint_f -!****s* H5P/H5Pset_vol_f -! -! NAME -! H5Pset_vol_f -! -! PURPOSE -! Set the file VOL connector (VOL_ID) for a file access -! property list (PLIST_ID) -! INPUTS -! plist_id - access property list identifier. -! new_vol_id - VOL connector id. -! -! OUTPUTS -! hdferr - error code: -! 0 on success and -1 on failure -! -! OPTIONAL -! new_vol_info - VOL connector info. -! -! AUTHOR -! M.S. Breitenfeld -! May 2019 -! -! Fortran Interface: +!> +!! \ingroup FH5P +!! +!! \brief Set the file VOL connector (VOL_ID) for a file access property list (PLIST_ID) +!! +!! \param plist_id Access property list identifier. +!! \param new_vol_id VOL connector id. +!! \param hdferr \fortran_error +!! \param new_vol_info VOL connector info. +!! SUBROUTINE h5pset_vol_f(plist_id, new_vol_id, hdferr, new_vol_info) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: plist_id INTEGER(HID_T) , INTENT(IN) :: new_vol_id INTEGER , INTENT(OUT) :: hdferr TYPE(C_PTR) , OPTIONAL :: new_vol_info -!***** TYPE(C_PTR) :: new_vol_info_default @@ -8222,33 +5487,20 @@ END SUBROUTINE h5pget_virtual_dsetname_f END SUBROUTINE h5pset_vol_f -!****s* H5P/H5Pget_vol_id_f -! -! NAME -! H5Pget_vol_id_f -! -! PURPOSE -! Get the file VOL connector (VOL_ID) for a file access -! property list (PLIST_ID) -! INPUTS -! plist_id - access property list identifier. -! -! OUTPUTS -! vol_id - VOL connector id. -! hdferr - error code: -! 0 on success and -1 on failure +!> +!! \ingroup FH5P +!! +!! \brief Get the file VOL connector (VOL_ID) for a file access property list (PLIST_ID) ! -! AUTHOR -! M.S. Breitenfeld -! May 2019 -! -! Fortran Interface: +!! \param plist_id Access property list identifier. +!! \param vol_id VOL connector id. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_vol_id_f(plist_id, vol_id, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: plist_id INTEGER(HID_T) , INTENT(OUT) :: vol_id INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5pget_vol_id(plist_id, vol_id) BIND(C, NAME='H5Pget_vol_id') @@ -8263,37 +5515,22 @@ END SUBROUTINE h5pget_virtual_dsetname_f END SUBROUTINE h5pget_vol_id_f -!****s* H5P (F03)/h5pget_file_locking_f_F03 -! -! NAME -! h5pget_file_locking_f -! -! PURPOSE -! Gets the file locking properties. File locking is mainly used to help -! enforce SWMR semantics. -! -! INPUTS -! fapl_id - Target file access property list identifier. -! -! OUTPUTS -! use_file_locking - Whether or not to use file locks. -! ignore_disabled_locks - Whether or not to ignore file locks when locking -! is disabled on a file system. -! hdferr - error code: -! 0 on success and -1 on failure -! -! AUTHOR -! Dana Robinson -! Summer 2020 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Gets the file locking properties. File locking is mainly used to help enforce SWMR semantics. +!! +!! \param fapl_id Target fileTarget file access property list identifier. +!! \param use_file_locking Whether or not to use file locks. +!! \param ignore_disabled_locks Whether or not to ignore file locks when locking is disabled on a file system. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pget_file_locking_f(fapl_id, use_file_locking, ignore_disabled_locks, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: fapl_id LOGICAL , INTENT(OUT) :: use_file_locking LOGICAL , INTENT(OUT) :: ignore_disabled_locks INTEGER , INTENT(OUT) :: hdferr -!***** LOGICAL(C_BOOL) :: c_use_flag LOGICAL(C_BOOL) :: c_ignore_flag @@ -8315,35 +5552,22 @@ END SUBROUTINE h5pget_virtual_dsetname_f END SUBROUTINE h5pget_file_locking_f -!****s* H5P (F03)/h5pset_file_locking_f_F03 -! -! NAME -! h5pset_file_locking_f -! -! PURPOSE -! Sets the file locking properties. File locking is mainly used to help -! enforce SWMR semantics. -! -! INPUTS -! fapl_id - Target file access property list identifier. -! use_file_locking - Whether or not to use file locks. -! ignore_disabled_locks - Whether or not to ignore file locks when locking -! is disabled on a file system. -! hdferr - error code: -! 0 on success and -1 on failure -! -! AUTHOR -! Dana Robinson -! Summer 2020 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5P +!! +!! \brief Sets the file locking properties. File locking is mainly used to help enforce SWMR semantics. +!! +!! \param fapl_id Target file access property list identifier. +!! \param use_file_locking Whether or not to use file locks. +!! \param ignore_disabled_locks Whether or not to ignore file locks when locking is disabled on a file system. +!! \param hdferr \fortran_error +!! SUBROUTINE h5pset_file_locking_f(fapl_id, use_file_locking, ignore_disabled_locks, hdferr) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: fapl_id LOGICAL , INTENT(IN) :: use_file_locking LOGICAL , INTENT(IN) :: ignore_disabled_locks INTEGER , INTENT(OUT) :: hdferr -!***** LOGICAL(C_BOOL) :: c_use_flag LOGICAL(C_BOOL) :: c_ignore_flag diff --git a/fortran/src/H5Rff.F90 b/fortran/src/H5Rff.F90 index 9e12ee8..f5dfb5c 100644 --- a/fortran/src/H5Rff.F90 +++ b/fortran/src/H5Rff.F90 @@ -1,4 +1,13 @@ -!****h* ROBODoc/H5R +!> @defgroup FH5R Fortran References (H5R) Interface +!! +!! @see H5R, C-API +!! +!! @see @ref H5R_UG, User Guide +!! + +!> @ingroup FH5R +!! +!! @brief This module contains Fortran interfaces for H5R functions. ! ! NAME ! MODULE H5R @@ -36,7 +45,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** MODULE H5R USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR, C_CHAR, C_SIGNED_CHAR @@ -62,46 +70,38 @@ MODULE H5R PRIVATE h5rdereference_object_f, h5rdereference_region_f, h5rdereference_ptr_f PRIVATE h5rget_name_object_f, h5rget_name_region_f, h5rget_name_ptr_f - INTERFACE h5rget_object_type_f +!> @brief hdset_reg_ref_t_f03 C compatible reference + TYPE :: hdset_reg_ref_t_f03 + INTEGER(C_SIGNED_CHAR), DIMENSION(1:H5R_DSET_REG_REF_BUF_SIZE_F) :: ref + END TYPE hdset_reg_ref_t_f03 + INTERFACE h5rget_object_type_f MODULE PROCEDURE h5rget_object_type_obj_f - END INTERFACE - TYPE :: hdset_reg_ref_t_f03 - INTEGER(C_SIGNED_CHAR), DIMENSION(1:H5R_DSET_REG_REF_BUF_SIZE_F) :: ref - END TYPE hdset_reg_ref_t_f03 +#ifndef H5_DOXYGEN_FORTRAN INTERFACE h5rget_region_f - + MODULE PROCEDURE h5rget_region_ptr_f ! F2003 MODULE PROCEDURE h5rget_region_region_f ! obsolete - MODULE PROCEDURE h5rget_region_ptr_f ! F2003 - END INTERFACE - INTERFACE h5rcreate_f - + MODULE PROCEDURE h5rcreate_ptr_f ! F2003 MODULE PROCEDURE h5rcreate_object_f ! obsolete MODULE PROCEDURE h5rcreate_region_f ! obsolete - MODULE PROCEDURE h5rcreate_ptr_f ! F2003 - END INTERFACE INTERFACE h5rdereference_f - + MODULE PROCEDURE h5rdereference_ptr_f ! F2003 MODULE PROCEDURE h5rdereference_object_f ! obsolete MODULE PROCEDURE h5rdereference_region_f ! obsolete - MODULE PROCEDURE h5rdereference_ptr_f ! F2003 - END INTERFACE INTERFACE h5rget_name_f - + MODULE PROCEDURE h5rget_name_ptr_f ! F2003 MODULE PROCEDURE h5rget_name_object_f ! obsolete MODULE PROCEDURE h5rget_name_region_f ! obsolete - MODULE PROCEDURE h5rget_name_ptr_f ! F2003 - END INTERFACE INTERFACE @@ -158,54 +158,37 @@ MODULE H5R INTEGER(HID_T), INTENT(OUT) :: space_id END FUNCTION h5rget_region_ptr_c END INTERFACE - +#endif CONTAINS -!****s* H5R/h5rget_object_type_obj_f -! -! NAME -! h5rget_object_type_obj_f -! -! PURPOSE -! Retrieves the type of object that an object reference points to. -! -! INPUTS -! dset_id - identifier of the dataset containing -! reference to the objects -! ref - reference to open -! OUTPUTS -! obj_type - object_type, possible values: -! H5G_UNKNOWN_F -! H5G_GROUP_F -! H5G_DATASET_F -! H5G_TYPE_F -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! NOTES -! This is a module procedure for the h5rget_object_type_f -! subroutine. -! SOURCE - SUBROUTINE h5rget_object_type_obj_f(dset_id, ref, obj_type, hdferr) +!> +!! \ingroup FH5R +!! +!! \brief Retrieves the type of object that an object reference points to. +!! +!! \note \fortran_obsolete +!! +!! \param dset_id Identifier of the dataset containing reference to the objects. +!! \param ref Reference to open. +!! \param obj_type Object_type, possible values: +!! \li H5G_UNKNOWN_F +!! \li H5G_GROUP_F +!! \li H5G_DATASET_F +!! \li H5G_TYPE_F +!! \param hdferr \fortran_error +!! +#ifdef H5_DOXYGEN_FORTRAN + SUBROUTINE h5rget_object_type_f(& +#else + SUBROUTINE h5rget_object_type_obj_f(& +#endif + dset_id, ref, obj_type, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - TYPE(hobj_ref_t_f), INTENT(IN) :: ref ! Object reference - INTEGER, INTENT(OUT) :: obj_type ! Object type - ! H5G_UNKNOWN_F - ! H5G_GROUP_F - ! H5G_DATASET_F - ! H5G_TYPE_F - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: dset_id + TYPE(hobj_ref_t_f), INTENT(IN) :: ref + INTEGER, INTENT(OUT) :: obj_type + INTEGER, INTENT(OUT) :: hdferr INTEGER(HADDR_T) :: ref_f ! Local buffer to pass reference INTERFACE @@ -221,44 +204,31 @@ CONTAINS ref_f = ref%ref hdferr = h5rget_object_type_obj_c(dset_id, ref_f, obj_type ) +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5rget_object_type_f +#else END SUBROUTINE h5rget_object_type_obj_f - - -!****s* H5R/h5rget_region_region_f -! -! NAME -! h5rget_region_region_f -! -! PURPOSE -! Retrieves a dataspace with the specified region selected -! -! INPUTS -! dset_id - identifier of the dataset containing -! reference to the regions -! ref - reference to open -! OUTPUTS -! space_id - dataspace identifier -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! NOTES -! This is a module procedure for the h5rget_region_f subroutine. -! -! SOURCE +#endif + +!> +!! \ingroup FH5R +!! +!! \brief Retrieves a dataspace with the specified region selected. +!! +!! \note \fortran_obsolete +!! +!! \param dset_id Identifier of the dataset containing reference to the regions. +!! \param ref Reference to open. +!! \param space_id Dataspace identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5rget_region_region_f(dset_id, ref, space_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref ! Dataset region reference - INTEGER(HID_T), INTENT(OUT) :: space_id ! Space identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: dset_id + TYPE(hdset_reg_ref_t_f), INTENT(IN) :: ref + INTEGER(HID_T), INTENT(OUT) :: space_id + INTEGER, INTENT(OUT) :: hdferr + INTEGER :: ref_f(REF_REG_BUF_LEN) ! Local buffer to pass reference INTERFACE @@ -276,79 +246,57 @@ CONTAINS END SUBROUTINE h5rget_region_region_f -!****s* H5R/h5rget_region_ptr_f -! -! NAME -! h5rget_region_ptr_f -! -! PURPOSE -! Retrieves a dataspace with the specified region -! selected using pointer -! -! INPUTS -! dset_id - identifier of the dataset containing -! reference to the regions -! ref - reference to open -! OUTPUTS -! space_id - dataspace identifier -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! M. Scot Breitenfeld -! August 4, 2012 -! -! NOTES -! This is a module procedure for the h5rget_region_f subroutine. -! -! SOURCE - SUBROUTINE h5rget_region_ptr_f(dset_id, ref, space_id, hdferr) +!> +!! \ingroup FH5R +!! +!! \brief Retrieves a dataspace with the specified region selected using pointer. +!! +!! \note \fortran_approved +!! +!! \param dset_id Identifier of the dataset containing reference to the regions. +!! \param ref Reference to open. +!! \param space_id Dataspace identifier. +!! \param hdferr \fortran_error +!! +#ifdef H5_DOXYGEN_FORTRAN + SUBROUTINE h5rget_region_f(& +#else + SUBROUTINE h5rget_region_ptr_f(& +#endif + dset_id, ref, space_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: dset_id ! Dataset identifier - TYPE(C_PTR), INTENT(IN) :: ref ! Dataset region reference - INTEGER(HID_T), INTENT(OUT) :: space_id ! Space identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: dset_id + TYPE(C_PTR), INTENT(IN) :: ref + INTEGER(HID_T), INTENT(OUT) :: space_id + INTEGER, INTENT(OUT) :: hdferr - hdferr = h5rget_region_ptr_c(dset_id, ref, space_id ) + hdferr = h5rget_region_ptr_c(dset_id, ref, space_id) +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5rget_region_f +#else END SUBROUTINE h5rget_region_ptr_f - - -!****s* H5R (F03)/h5rcreate_object_f -! -! NAME -! h5rcreate_object_f -! -! PURPOSE -! Creates reference to the object -! -! Inputs: -! loc_id - location identifier -! name - name of the object at the specified location -! Outputs: -! ref - reference to the specified object -! hdferr - returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! NOTES -! This is a module procedure for the h5rcreate_f subroutine. -! -! Signature: +#endif + +!> +!! \ingroup FH5R +!! +!! \brief Creates reference to the object. +!! +!! \note \fortran_obsolete +!! +!! \param loc_id Location identifier. +!! \param name Name of the object at the specified location. +!! \param ref Reference to the specified object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5rcreate_object_f(loc_id, name, ref, hdferr) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Location identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the object at location specified - ! by loc_id identifier - TYPE(hobj_ref_t_f), INTENT(INOUT), TARGET :: ref ! Object reference - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + TYPE(hobj_ref_t_f), INTENT(INOUT), TARGET :: ref + INTEGER, INTENT(OUT) :: hdferr INTEGER :: namelen ! Name length TYPE(C_PTR) :: f_ptr @@ -360,43 +308,26 @@ CONTAINS END SUBROUTINE h5rcreate_object_f -!****s* H5R (F90)/h5rcreate_region_f -! -! NAME -! h5rcreate_region_f -! -! PURPOSE -! Creates reference to the dataset region -! -! INPUTS -! loc_id - location identifier -! name - name of the dataset at the specified location -! space_id - dataspace identifier that describes selected region -! OUTPUTS -! ref - reference to the dataset region -! hdferr - returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! NOTES -! This is a module procedure for the h5rcreate_f subroutine. -! -! SOURCE +!> +!! \ingroup FH5R +!! +!! \brief Creates reference to the dataset region +!! +!! \note \fortran_obsolete +!! +!! \param loc_id Location identifier. +!! \param name Name of the dataset at the specified location. +!! \param space_id Dataspace identifier that describes selected region. +!! \param ref Reference to the dataset region. +!! \param hdferr \fortran_error +!! SUBROUTINE h5rcreate_region_f(loc_id, name, space_id, ref, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Location identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the dataset at location specified - ! by loc_id identifier - INTEGER(HID_T), INTENT(IN) :: space_id ! Dataset's dataspace identifier - TYPE(hdset_reg_ref_t_f), INTENT(OUT) :: ref ! Dataset region reference - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER(HID_T), INTENT(IN) :: space_id + TYPE(hdset_reg_ref_t_f), INTENT(OUT) :: ref + INTEGER, INTENT(OUT) :: hdferr INTEGER :: namelen ! Name length INTEGER :: ref_f(REF_REG_BUF_LEN) ! Local buffer to pass reference @@ -420,46 +351,36 @@ CONTAINS END SUBROUTINE h5rcreate_region_f -!****s* H5R (F03)/h5rcreate_ptr_f -! -! NAME -! h5rcreate_ptr_f -! -! PURPOSE -! Creates a reference. -! -! Inputs: -! loc_id - location identifier -! name - name of the dataset at the specified location -! ref_type - type of reference: -! H5R_OBJECT -! H5T_STD_REF_DSETREG -! Outputs: -! ref - reference created by the function call. -! hdferr - returns 0 if successful and -1 if fails. -! OPTIONAL -! space_id - dataspace identifier that describes selected region -! -! AUTHOR -! M. Scot Breitenfeld -! June 20, 2008 -! -! NOTES -! This is a module procedure for the h5rcreate_f -! subroutine where the output is a pointer. -! -! Signature: - SUBROUTINE h5rcreate_ptr_f(loc_id, name, ref_type, ref, hdferr, space_id) +!> +!! \ingroup FH5R +!! +!! \brief Creates a reference. +!! +!! \note \fortran_approved +!! +!! \param loc_id Location identifier. +!! \param name Name of the dataset at the specified location. +!! \param ref_type Type of reference: +!! \li H5R_OBJECT_F +!! \li H5T_STD_REF_DSETREG_F +!! \param ref Reference created by the function call. +!! \param hdferr \fortran_error +!! \param space_id Dataspace identifier that describes selected region. +!! +#ifdef H5_DOXYGEN_FORTRAN + SUBROUTINE h5rcreate_f(& +#else + SUBROUTINE h5rcreate_ptr_f(& +#endif + loc_id, name, ref_type, ref, hdferr, space_id) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! Location identifier - CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the dataset at location specified - ! by loc_id identifier - INTEGER, INTENT(IN) :: ref_type ! type of reference - TYPE(C_PTR), INTENT(INOUT) :: ref ! Reference created by the function call - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), INTENT(IN), OPTIONAL :: space_id ! Dataset's dataspace identifier -!***** + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: name + INTEGER, INTENT(IN) :: ref_type + TYPE(C_PTR), INTENT(INOUT) :: ref + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), INTENT(IN), OPTIONAL :: space_id INTEGER :: namelen ! Name length INTEGER(HID_T) :: space_id_c @@ -468,86 +389,56 @@ CONTAINS IF(PRESENT(space_id)) space_id_c = space_id hdferr = h5rcreate_ptr_c(ref, loc_id, name, namelen, ref_type, space_id_c) +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5rcreate_f +#else END SUBROUTINE h5rcreate_ptr_f -!****s* H5R (F03)/h5rdereference_object_f -! -! NAME -! h5rdereference_object_f -! -! PURPOSE -! Opens the HDF5 object referenced -! -! Inputs: -! dset_id - identifier of the dataset containing -! reference -! ref - reference to open -! Outputs: -! obj_id - object_identifier -! hdferr - returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! NOTES -! This is a module procedure for the h5rdereference_f subroutine. -! -! Signature: +#endif +!> +!! \ingroup FH5R +!! +!! \brief Opens the HDF5 object referenced +!! +!! \note \fortran_obsolete +!! +!! \param obj_id Identifier of the dataset containing reference. +!! \param ref Reference to open. +!! \param ref_obj_id Object_identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5rdereference_object_f(obj_id, ref, ref_obj_id, hdferr) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Dataset identifier - TYPE(hobj_ref_t_f), INTENT(IN), TARGET :: ref ! Object reference - INTEGER(HID_T), INTENT(OUT) :: ref_obj_id ! Object identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + TYPE(hobj_ref_t_f), INTENT(IN), TARGET :: ref + INTEGER(HID_T), INTENT(OUT) :: ref_obj_id + INTEGER, INTENT(OUT) :: hdferr TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(ref) hdferr = h5rdereference_ptr_c(obj_id, 0, f_ptr, ref_obj_id) END SUBROUTINE h5rdereference_object_f -!****s* H5R (F03)/h5rdereference_region_f -! -! NAME -! h5rdereference_region_f -! -! PURPOSE -! Opens the dataset region -! -! Inputs: -! dset_id - identifier of the dataset containing -! reference to the regions -! ref - reference to open -! Outputs: -! obj_id - dataspace identifier -! hdferr - returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! NOTES -! This is a module procedure for the h5rdereference_f subroutine. -! -! Signature: + +!> +!! \ingroup FH5R +!! +!! \brief Opens the dataset region +!! +!! \note \fortran_obsolete +!! +!! \param obj_id Object identifier. +!! \param ref Reference to open. +!! \param ref_obj_id Identifier of the object containing reference to the regions. +!! \param hdferr \fortran_error +!! SUBROUTINE h5rdereference_region_f(obj_id, ref, ref_obj_id, hdferr) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Dataset identifier - TYPE(hdset_reg_ref_t_f), INTENT(IN), TARGET :: ref ! Object reference - INTEGER(HID_T), INTENT(OUT) :: ref_obj_id ! Dataspace identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: obj_id + TYPE(hdset_reg_ref_t_f), INTENT(IN), TARGET :: ref + INTEGER(HID_T), INTENT(OUT) :: ref_obj_id + INTEGER, INTENT(OUT) :: hdferr TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(ref) @@ -555,72 +446,45 @@ CONTAINS END SUBROUTINE h5rdereference_region_f -!****s* H5R (F03)/h5rdereference_ptr_f -! -! NAME -! h5rdereference_ptr_f -! -! PURPOSE -! Opens the HDF5 object referenced. -! -! Inputs: -! obj_id - valid identifier for the file containing the -! referenced object or any object in that file. -! ref_type - the reference type of ref. -! ref - Reference to open. -! Outputs: -! ref_obj_id - identifier of referenced object -! hdferr - returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! June 20, 2008 -! -! NOTES -! This is a module procedure for the h5rdereference_f -! subroutine using pointers. -! -! Signature: +!> +!! \ingroup FH5R +!! +!! \brief Opens the HDF5 object referenced. +!! +!! \note \fortran_approved +!! +!! \param obj_id Valid identifier for the file containing the referenced object or any object in that file. +!! \param ref_type The reference type of ref. +!! \param ref Reference to open. +!! \param ref_obj_id Identifier of referenced object. +!! \param hdferr \fortran_error +!! SUBROUTINE h5rdereference_ptr_f(obj_id, ref_type, ref, ref_obj_id, hdferr) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: obj_id ! Valid identifier for the file containing the - ! referenced object or any object in that file. - INTEGER, INTENT(IN) :: ref_type ! The reference type of ref. - TYPE(C_PTR), INTENT(IN) :: ref ! Object reference + INTEGER(HID_T), INTENT(IN) :: obj_id + INTEGER, INTENT(IN) :: ref_type + TYPE(C_PTR), INTENT(IN) :: ref INTEGER(HID_T), INTENT(OUT) :: ref_obj_id - ! Identifier of referenced object - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER, INTENT(OUT) :: hdferr + hdferr = h5rdereference_ptr_c(obj_id, ref_type, ref, ref_obj_id) END SUBROUTINE h5rdereference_ptr_f -! -!****s* H5R (F03)/h5rget_name_object_f -! -! NAME -! h5rget_name_object_f -! -! PURPOSE -! Retrieves a name of a referenced object. -! -! Inputs: -! loc_id - Identifier for the file containing the reference or for any object in that file. -! ref - An object or dataset region reference. -! -! Outputs: -! name - A name associated with the referenced object or dataset region. -! hdferr - Returns 0 if successful and -1 if fails. -! -! Optional parameters: -! size - The size of the name buffer, returning 0 (zero) if no name is associated -! with the identifier. -! -! AUTHOR -! M. Scot Breitenfeld -! March 28, 2008 -! -! Signature: + +!> +!! \ingroup FH5R +!! +!! \brief Retrieves a name of a referenced object. +!! +!! \note \fortran_obsolete +!! +!! \param loc_id Identifier for the file containing the reference or for any object in that file. +!! \param ref An object or dataset region reference. +!! \param name A name associated with the referenced object or dataset region. +!! \param hdferr \fortran_error +!! \param size The size of the name buffer, returning 0 (zero) if no name is associated with the identifier. +!! SUBROUTINE h5rget_name_object_f(loc_id, ref, name, hdferr, size) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE @@ -629,7 +493,6 @@ CONTAINS INTEGER(SIZE_T), OPTIONAL, INTENT(OUT) :: size CHARACTER(LEN=*), INTENT(INOUT) :: name INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER(SIZE_T) :: size_default INTEGER(SIZE_T) :: name_len @@ -644,30 +507,20 @@ CONTAINS IF(PRESENT(size)) size = size_default END SUBROUTINE h5rget_name_object_f -!****s* H5R (F03)/h5rget_name_region_f -! -! NAME -! h5rget_name_region_f -! -! PURPOSE -! Retrieves a name of a dataset region. -! -! Inputs: -! loc_id - Identifier for the file containing the reference or for any object in that file. -! ref - An object or dataset region reference. -! -! Outputs: -! name - A name associated with the referenced object or dataset region. -! hdferr - Returns 0 if successful and -1 if fails. -! -! Optional parameters: -! size - The size of the name buffer, returning 0 (zero) if no name is associated with the identifier -! -! AUTHOR -! M. Scot Breitenfeld -! March 28, 2008 -! -! Signature: + +!> +!! \ingroup FH5R +!! +!! \brief Retrieves a name of a dataset region. +!! +!! \note \fortran_obsolete +!! +!! \param loc_id Identifier for the file containing the reference or for any object in that file. +!! \param ref An object or dataset region reference. +!! \param name A name associated with the referenced object or dataset region. +!! \param hdferr \fortran_error +!! \param size The size of the name buffer, returning 0 (zero) if no name is associated with the identifier. +!! SUBROUTINE h5rget_name_region_f(loc_id, ref, name, hdferr, size) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE @@ -676,7 +529,6 @@ CONTAINS INTEGER(SIZE_T), OPTIONAL, INTENT(OUT) :: size CHARACTER(LEN=*), INTENT(INOUT) :: name INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER(SIZE_T) :: size_default INTEGER(SIZE_T) :: name_len TYPE(C_PTR) :: f_ptr @@ -691,33 +543,27 @@ CONTAINS END SUBROUTINE h5rget_name_region_f - !****s* H5R (F03)/h5rget_name_ptr_f - ! - ! NAME - ! h5rget_name_ptr_f - ! - ! PURPOSE - ! Retrieves a name of a referenced object. - ! - ! Inputs: - ! loc_id - Identifier for the file containing the reference or for any object in that file. - ! ref_type - Type of reference. - ! ref - An object or dataset region reference. - ! - ! Outputs: - ! name - A name associated with the referenced object or dataset ptr. - ! hdferr - Returns 0 if successful and -1 if fails. - ! - ! Optional parameters: - ! size - The size of the name buffer, returning 0 (zero) if no name is associated - ! with the identifier - ! - ! AUTHOR - ! M. Scot Breitenfeld - ! March 28, 2008 - ! - ! Signature: - SUBROUTINE h5rget_name_ptr_f(loc_id, ref_type, ref, name, hdferr, size) +!> +!! \ingroup FH5R +!! +!! \brief Retrieves a name of a referenced object. +!! +!! \note \fortran_approved +!! +!! \param loc_id Identifier for the file containing the reference or for any object in that file. +!! \param ref_type Type of reference. +!! \param ref An object or dataset region reference. +!! \param name A name associated with the referenced object or dataset ptr. +!! \param hdferr \fortran_error +!!\param size The size of the name buffer, returning 0 (zero) if no name is associated with the identifier. +!! + +#ifdef H5_DOXYGEN_FORTRAN + SUBROUTINE h5rget_name_f(& +#else + SUBROUTINE h5rget_name_ptr_f(& +#endif + loc_id, ref_type, ref, name, hdferr, size) USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: loc_id @@ -726,7 +572,6 @@ CONTAINS CHARACTER(LEN=*), INTENT(INOUT) :: name INTEGER, INTENT(OUT) :: hdferr INTEGER(SIZE_T), OPTIONAL, INTENT(OUT) :: size -!***** INTEGER(SIZE_T) :: size_default INTEGER(SIZE_T) :: name_len @@ -736,37 +581,29 @@ CONTAINS IF(PRESENT(size)) size = size_default +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5rget_name_f +#else END SUBROUTINE h5rget_name_ptr_f - - !****s* H5R (F03)/h5rget_obj_type_f - ! - ! NAME - ! h5rget_obj_type_f - ! - ! PURPOSE - ! Retrieves the type of object that an object reference points to. - ! - ! Inputs: - ! loc_id - Identifier for the dataset containing the reference or - ! for the group that dataset is in. - ! ref_type - Type of reference to query. - ! ref - Reference to query. - ! - ! Outputs: - ! obj_type - Type of referenced object. - ! H5G_UNKNOWN_F - ! H5G_GROUP_F - ! H5G_DATASET_F - ! H5G_TYPE_F - ! - ! hdferr - Returns 0 if successful and -1 if fails. - ! - ! AUTHOR - ! M. Scot Breitenfeld - ! Decemeber 17, 2008 - ! - ! Signature: +#endif + +!> +!! \ingroup FH5R +!! +!! \brief Retrieves the type of object that an object reference points to. +!! +!! loc_id - Identifier for the dataset containing the reference or for the group that dataset is in. +!! ref_type - Type of reference to query. +!! ref - Reference to query. +!! obj_type - Type of referenced object: +!! \li H5G_UNKNOWN_F +!! \li H H5G_GROUP_F +!! \li H H5G_DATASET_F +!! \li H H5G_TYPE_F +!! hdferr - \fortran_error +!! SUBROUTINE h5rget_obj_type_f(loc_id, ref_type, ref, obj_type, hdferr) + USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: loc_id @@ -774,7 +611,6 @@ CONTAINS TYPE(C_PTR), INTENT(IN) :: ref INTEGER, INTENT(OUT) :: obj_type INTEGER, INTENT(OUT) :: hdferr - !***** INTERFACE INTEGER FUNCTION h5rget_obj_type_c(loc_id, ref_type, ref, obj_type) & diff --git a/fortran/src/H5Sff.F90 b/fortran/src/H5Sff.F90 index 76b0dea..c803f8c 100644 --- a/fortran/src/H5Sff.F90 +++ b/fortran/src/H5Sff.F90 @@ -1,13 +1,13 @@ -!****h* ROBODoc/H5S -! -! NAME -! MODULE H5S -! -! FILE -! fortran/src/H5Sff.F90 -! -! PURPOSE -! This file contains Fortran interfaces for H5S functions. +!> @defgroup FH5S Fortran Dataspace (H5S) Interface +!! +!! @see H5S, C-API +!! +!! @see @ref H5S_UG, User Guide +!! + +!> @ingroup FH5S +!! +!! @brief This module contains Fortran interfaces for H5S functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -36,40 +36,23 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** MODULE H5S USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR, C_CHAR, C_INT USE H5GLOBAL CONTAINS -! -!****s* H5S/h5screate_simple_f -! -! NAME -! h5screate_simple_f -! -! PURPOSE -! Creates a new simple data space and opens it for access . -! -! INPUTS -! rank - number of dimensions -! dims - an array of the size of each dimension -! OUTPUTS -! space_id - dataspace identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! maxdims - an array of the maximum size of each dimension -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Creates a new simple data space and opens it for access. +!! +!! \param rank Number of dimensions. +!! \param dims An array of the size of each dimension. +!! \param space_id Dataspace identifier. +!! \param hdferr \fortran_error +!! \param maxdims An array of the maximum size of each dimension. +!! SUBROUTINE h5screate_simple_f(rank, dims, space_id, hdferr, maxdims) IMPLICIT NONE @@ -78,7 +61,6 @@ CONTAINS INTEGER(HID_T), INTENT(OUT) :: space_id INTEGER, INTENT(OUT) :: hdferr INTEGER(HSIZE_T), OPTIONAL, INTENT(IN) :: maxdims(rank) -!***** INTEGER(HSIZE_T), ALLOCATABLE, DIMENSION(:) :: f_maxdims INTERFACE @@ -107,34 +89,18 @@ CONTAINS END SUBROUTINE h5screate_simple_f -! -!****s* H5S/h5sclose_f -! -! NAME -! h5sclose_f -! -! PURPOSE -! Releases and terminates access to a dataspace. -! -! INPUTS -! space_id - identifier of dataspace to release -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Releases and terminates access to a dataspace. +!! +!! \param space_id Identifier of dataspace to release. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sclose_f(space_id, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: space_id ! Dataspace identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: space_id + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5sclose_c(space_id) BIND(C,NAME='h5sclose_c') IMPORT :: HID_T @@ -147,44 +113,23 @@ CONTAINS END SUBROUTINE h5sclose_f -! -!****s* H5S/h5screate_f -! -! NAME -! h5screate_f -! -! PURPOSE -! Creates a new dataspace of a specified type. -! -! INPUTS -! classtype - The type of the dataspace to be created -! Possible values are: -! H5S_SCALAR_F -! H5S_SIMPLE_F -! H5S_NULL_F -! OUTPUTS -! space_id - Dataspace identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! NOTES -! - -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Creates a new dataspace of a specified type. +!! +!! \param classtype The type of the dataspace to be created. Possible values are: +!! \li H5S_SCALAR_F +!! \li H5S_SIMPLE_F +!! \li H5S_NULL_F +!! \param space_id Dataspace identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5screate_f(classtype, space_id, hdferr) IMPLICIT NONE INTEGER, INTENT(IN) :: classtype INTEGER(HID_T), INTENT(OUT) :: space_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5screate_c(classtype, space_id) BIND(C,NAME='h5screate_c') IMPORT :: HID_T @@ -198,40 +143,20 @@ CONTAINS END SUBROUTINE h5screate_f -! -!****s* H5S/h5scopy_f -! -! NAME -! h5scopy_f -! -! PURPOSE -! Creates an exact copy of a dataspace. -! -! INPUTS -! space_id - dataspace identifier -! OUTPUTS -! new_space_id - identifier of dataspace's copy -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! NOTES -! - -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Creates an exact copy of a dataspace. +!! +!! \param space_id Dataspace identifier. +!! \param new_space_id Identifier of dataspace's copy. +!! \param hdferr \fortran_error +!! SUBROUTINE h5scopy_f(space_id, new_space_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER(HID_T), INTENT(OUT) :: new_space_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5scopy_c(space_id, new_space_id) BIND(C,NAME='h5scopy_c') IMPORT :: HID_T @@ -245,37 +170,20 @@ CONTAINS END SUBROUTINE h5scopy_f -! -!****s* H5S/h5sget_select_hyper_nblocks_f -! -! NAME -! h5sget_select_hyper_nblocks_f -! -! PURPOSE -! Get number of hyperslab blocks. -! -! INPUTS -! space_id - dataspace identifier -! OUTPUTS -! num_blocks - number of hyperslab blocks in the current -! hyperslab selection -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Get number of hyperslab blocks. +!! +!! \param space_id Dataspace identifier. +!! \param num_blocks Number of hyperslab blocks in the current hyperslab selection. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_select_hyper_nblocks_f(space_id, num_blocks, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER(HSSIZE_T), INTENT(OUT) :: num_blocks INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sget_select_hyper_nblocks_c (space_id, num_blocks) & BIND(C,NAME='h5sget_select_hyper_nblocks_c') @@ -290,32 +198,17 @@ CONTAINS END SUBROUTINE h5sget_select_hyper_nblocks_f -! -!****s* H5S/h5sget_select_hyper_blocklist_f -! -! NAME -! h5sget_select_hyper_blocklist_f -! -! PURPOSE -! Gets the list of hyperslab blocks currently selected. -! -! INPUTS -! space_id - dataspace identifier -! startblock - hyperslab block to start with -! num_blocks - number of blocks to get -! OUTPUTS -! buf - buffer to hold block list -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Gets the list of hyperslab blocks currently selected. +!! +!! \param space_id Dataspace identifier. +!! \param startblock Hyperslab block to start with. +!! \param num_blocks Number of blocks to get. +!! \param buf Buffer to hold block list. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_select_hyper_blocklist_f(space_id, startblock, & num_blocks, buf, hdferr) IMPLICIT NONE @@ -324,7 +217,6 @@ CONTAINS INTEGER(HSIZE_T), INTENT(IN) :: num_blocks INTEGER(HSIZE_T), DIMENSION(*), INTENT(OUT) :: buf INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sget_select_hyper_blocklist_c(space_id, startblock, & num_blocks, buf ) BIND(C,NAME='h5sget_select_hyper_blocklist_c') @@ -341,42 +233,22 @@ CONTAINS END SUBROUTINE h5sget_select_hyper_blocklist_f -! -!****s* H5S/h5sget_select_bounds_f -! -! NAME -! h5sget_select_bounds_f -! -! PURPOSE -! Gets the bounding box containing the current selection. -! -! INPUTS -! space_id - dataspace identifier -! -! OUTPUTS -! start - starting coordinates of bounding box -! end - ending coordinates of bounding box -! i.e., the coordinates of the diagonally opposite corner -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! NONE -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Gets the bounding box containing the current selection. +!! +!! \param space_id Dataspace identifier. +!! \param start Starting coordinates of bounding box. +!! \param end Ending coordinates of bounding box, i.e., the coordinates of the diagonally opposite corner. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_select_bounds_f(space_id, start, END, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER(HSIZE_T), DIMENSION(*), INTENT(OUT) :: start INTEGER(HSIZE_T), DIMENSION(*), INTENT(OUT) :: END INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sget_select_bounds_c(space_id, start, end) & BIND(C,NAME='h5sget_select_bounds_c') @@ -392,37 +264,20 @@ CONTAINS END SUBROUTINE h5sget_select_bounds_f -! -!****s* H5S/h5sget_select_elem_npoints_f -! -! NAME -! h5sget_select_elem_npoints_f -! -! PURPOSE -! Gets the number of element points in the current selection -! -! INPUTS -! space_id - dataspace identifier -! OUTPUTS -! num_points - number of element points in the current -! dataspace selection -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Gets the number of element points in the current selection +!! +!! \param space_id Dataspace identifier. +!! \param num_points Number of element points in the current dataspace selection +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_select_elem_npoints_f(space_id, num_points, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER(HSSIZE_T), INTENT(OUT) :: num_points INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sget_select_elem_npoints_c (space_id, num_points) BIND(C,NAME='h5sget_select_elem_npoints_c') IMPORT :: HID_T, HSSIZE_T @@ -435,32 +290,17 @@ CONTAINS END SUBROUTINE h5sget_select_elem_npoints_f -! -!****s* H5S/h5sget_select_elem_pointlist_f -! -! NAME -! h5sget_select_elem_pointlist_f -! -! PURPOSE -! Gets the list of element points currently selected. -! -! INPUTS -! space_id - dataspace identifier -! startpoint - element point to start with -! num_points - number of element points to get -! OUTPUTS -! buf - buffer with element points selected -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Gets the list of element points currently selected. +!! +!! \param space_id Dataspace identifier. +!! \param startpoint Element point to start with. +!! \param num_points Number of element points to get. +!! \param buf Buffer with element points selected. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_select_elem_pointlist_f(space_id, startpoint, & num_points, buf, hdferr) IMPLICIT NONE @@ -469,7 +309,6 @@ CONTAINS INTEGER(HSIZE_T), INTENT(IN) :: num_points INTEGER(HSIZE_T), DIMENSION(*), INTENT(OUT) :: buf INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sget_select_elem_pointlist_c(space_id, startpoint, & num_points, buf ) BIND(C,NAME='h5sget_select_elem_pointlist_c') @@ -487,38 +326,22 @@ CONTAINS END SUBROUTINE h5sget_select_elem_pointlist_f -! -!****s* H5S/h5sselect_elements_f -! -! NAME -! h5sselect_elements_f -! -! PURPOSE -! Selects elements to be included in the selection for -! a dataspace -! -! INPUTS -! space_id - dataspace identifier -! operator - flag, valid values are: -! H5S_SELECT_SET_F -! H5S_SELECT_APPEND_F -! H5S_SELECT_PREPEND_F -! rank - number of dataspace dimensions -! num_elements - number of elements to be selected -! coord - 2D (rank x num_elements) array with the -! elements coordinates ( 1-based); in C the -! array is stored in 2D as (num_element x rank) -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Selects elements to be included in the selection for a dataspace +!! +!! \param space_id Dataspace identifier. +!! \param operator Flag, valid values are: +!! \li H5S_SELECT_SET_F +!! \li H5S_SELECT_APPEND_F +!! \li H5S_SELECT_PREPEND_F +!! \param rank Number of dataspace dimensions. +!! \param num_elements Number of elements to be selected. +!! \param coord 2D (rank x num_elements) array with the elements coordinates ( 1-based); in C the +!! array is stored in 2D as (num_element x rank). +!! \param hdferr \fortran_error +!! SUBROUTINE h5sselect_elements_f(space_id, OPERATOR, rank, & num_elements, coord, hdferr) IMPLICIT NONE @@ -528,7 +351,6 @@ CONTAINS INTEGER(SIZE_T), INTENT(IN) :: num_elements INTEGER(HSIZE_T), INTENT(IN) , DIMENSION(rank,num_elements) :: coord INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER(HSIZE_T), ALLOCATABLE, DIMENSION(:,:) :: c_coord INTEGER :: error, i @@ -568,35 +390,18 @@ CONTAINS END SUBROUTINE h5sselect_elements_f -! -!****s* H5S/h5sselect_all_f -! -! NAME -! h5sselect_all_f -! -! PURPOSE -! Selects the entire dataspace. -! -! INPUTS -! space_id - Identifier for the dataspace in which -! selection being made -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Selects the entire dataspace. +!! +!! \param space_id Identifier for the dataspace in which selection being made. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sselect_all_f(space_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sselect_all_c(space_id) BIND(C,NAME='h5sselect_all_c') IMPORT :: HID_T @@ -609,36 +414,18 @@ CONTAINS END SUBROUTINE h5sselect_all_f -! -!****s* H5S/h5sselect_none_f -! -! NAME -! h5sselect_none_f -! -! PURPOSE -! Resets the selection region to include no elements. -! -! INPUTS -! space_id - the identifier for the dataspace in which -! the selection is being reset. -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Resets the selection region to include no elements. +!! +!! \param space_id The identifier for the dataspace in which the selection is being reset. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sselect_none_f(space_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sselect_none_c(space_id) BIND(C,NAME='h5sselect_none_c') IMPORT :: HID_T @@ -651,40 +438,20 @@ CONTAINS END SUBROUTINE h5sselect_none_f -! -!****s* H5S/h5sselect_valid_f -! -! NAME -! h5sselect_valid_f -! -! PURPOSE -! Verifies that the selection is within the extent of -! the dataspace. -! -! INPUTS -! space_id - identifier for the dataspace for which -! selection is verified -! OUTPUTS -! status - TRUE if the selection is contained within -! the extent, FALSE otherwise. -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Verifies that the selection is within the extent of the dataspace. +!! +!! \param space_id Identifier for the dataspace for whichselection is verified +!! \param status TRUE if the selection is contained within the extent, FALSE otherwise. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sselect_valid_f(space_id, status, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id LOGICAL, INTENT(OUT) :: status INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: flag ! "TRUE/FALSE/ERROR" flag from C routine INTERFACE @@ -702,37 +469,20 @@ CONTAINS END SUBROUTINE h5sselect_valid_f -! -!****s* H5S/h5sget_simple_extent_npoints_f -! -! NAME -! h5sget_simple_extent_npoints_f -! -! PURPOSE -! Determines the number of elements in a dataspace. -! -! INPUTS -! space_id - dataspace identifier -! OUTPUTS -! npoints - number of elements in the dataspace -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Determines the number of elements in a dataspace. +!! +!! \param space_id Dataspace identifier. +!! \param npoints Number of elements in the dataspace. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_simple_extent_npoints_f(space_id, npoints, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER(HSIZE_T), INTENT(OUT) :: npoints INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sget_simple_extent_npoints_c( space_id, npoints) BIND(C,NAME='h5sget_simple_extent_npoints_c') IMPORT :: HID_T, HSIZE_T @@ -746,35 +496,20 @@ CONTAINS END SUBROUTINE h5sget_simple_extent_npoints_f -! -!****s* H5S/h5sget_select_npoints_f -! -! NAME -! h5sget_select_npoints_f -! -! PURPOSE -! Determines the number of elements in a dataspace selection. -! -! INPUTS -! space_id - dataspace identifier -! OUTPUTS -! npoints - number of points in the dataspace selection -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Determines the number of elements in a dataspace selection. +!! +!! \param space_id Dataspace identifier. +!! \param npoints Number of points in the dataspace selection. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_select_npoints_f(space_id, npoints, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER(HSSIZE_T), INTENT(OUT) :: npoints INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sget_select_npoints_c(space_id, npoints) BIND(C,NAME='h5sget_select_npoints_c') IMPORT :: HID_T, HSSIZE_T @@ -788,36 +523,20 @@ CONTAINS END SUBROUTINE h5sget_select_npoints_f -! -!****s* H5S/h5sget_simple_extent_ndims_f -! -! NAME -! h5sget_simple_extent_ndims_f -! -! PURPOSE -! Determines the dimensionality of a dataspace -! -! INPUTS -! space_id - dataspace identifier -! OUTPUTS -! rank - number of dataspace dimensions -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Determines the dimensionality of a dataspace +!! +!! \param space_id Dataspace identifier. +!! \param rank Number of dataspace dimensions. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_simple_extent_ndims_f(space_id, rank, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER, INTENT(OUT) :: rank INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sget_simple_extent_ndims_c(space_id, rank) BIND(C,NAME='h5sget_simple_extent_ndims_c') IMPORT :: HID_T @@ -830,40 +549,22 @@ CONTAINS hdferr = h5sget_simple_extent_ndims_c(space_id, rank) END SUBROUTINE h5sget_simple_extent_ndims_f -! -!****s* H5S/h5sget_simple_extent_dims_f -! -! NAME -! h5sget_simple_extent_dims_f -! -! PURPOSE -! Retrieves dataspace dimension size and maximum size. -! -! INPUTS -! space_id - dataspace identifier -! -! OUTPUTS -! dims - array to store size of each dimension -! maxdims - array to store maximum size of each dimension -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Retrieves dataspace dimension size and maximum size. +!! +!! \param space_id Dataspace identifier. +!! \param dims Array to store size of each dimension. +!! \param maxdims Array to store maximum size of each dimension. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_simple_extent_dims_f(space_id, dims, maxdims, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER(HSIZE_T), DIMENSION(*), INTENT(OUT) :: dims INTEGER(HSIZE_T), DIMENSION(*), INTENT(OUT) :: maxdims INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sget_simple_extent_dims_c(space_id, dims, maxdims) BIND(C,NAME='h5sget_simple_extent_dims_c') IMPORT :: HID_T, HSIZE_T @@ -878,40 +579,24 @@ CONTAINS END SUBROUTINE h5sget_simple_extent_dims_f -! -!****s* H5S/h5sget_simple_extent_type_f -! -! NAME -! h5sget_simple_extent_type_f -! -! PURPOSE -! Determine the current class of a dataspace -! -! INPUTS -! space_id - dataspace identifier -! OUTPUTS -! classtype - class type, possible values are: -! H5S_NO_CLASS_F -! H5S_SCALAR_F -! H5S_SIMPLE_F -! H5S_NULL_F -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Determine the current class of a dataspace +!! +!! \param space_id Dataspace identifier. +!! \param classtype Class type, possible values are: +!! \li H5S_NO_CLASS_F +!! \li H5S_SCALAR_F +!! \li H5S_SIMPLE_F +!! \li H5S_NULL_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_simple_extent_type_f(space_id, classtype, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER, INTENT(OUT) :: classtype INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sget_simple_extent_type_c(space_id, classtype) BIND(C,NAME='h5sget_simple_extent_type_c') IMPORT :: HID_T @@ -925,32 +610,17 @@ CONTAINS END SUBROUTINE h5sget_simple_extent_type_f ! -!****s* H5S/h5sset_extent_simple_f -! -! NAME -! h5sset_extent_simple_f -! -! PURPOSE -! Sets or resets the size of an existing dataspace. -! -! INPUTS -! space_id - dataspace identifier -! rank - dataspace number of dimensions -! current_size - array with the new sizes of dimensions -! maximum_size - array with the new maximum sizes of -! dimensions -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Sets or resets the size of an existing dataspace. +!! +!! \param space_id Dataspace identifier. +!! \param rank Dataspace number of dimensions. +!! \param current_size Array with the new sizes of dimensions. +!! \param maximum_size Array with the new maximum sizes of dimensions. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sset_extent_simple_f(space_id, rank, current_size, & maximum_size, hdferr) IMPLICIT NONE @@ -959,7 +629,6 @@ CONTAINS INTEGER(HSIZE_T), DIMENSION(rank), INTENT(IN) :: current_size INTEGER(HSIZE_T), DIMENSION(rank), INTENT(IN) :: maximum_size INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sset_extent_simple_c(space_id, rank, & current_size, maximum_size) BIND(C,NAME='h5sset_extent_simple_c') @@ -975,37 +644,20 @@ CONTAINS maximum_size) END SUBROUTINE h5sset_extent_simple_f -! -!****s* H5S/h5sis_simple_f -! -! NAME -! h5sis_simple_f -! -! PURPOSE -! Determines whether a dataspace is a simple dataspace. -! -! INPUTS -! space_id - dataspace identifier -! OUTPUTS -! status - flag to indicate if dataspace -! is simple or not (TRUE or FALSE) -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Determines whether a dataspace is a simple dataspace. +!! +!! \param space_id Dataspace identifier. +!! \param status Flag to indicate if dataspace is simple or not (TRUE or FALSE). +!! \param hdferr \fortran_error +!! SUBROUTINE h5sis_simple_f(space_id, status, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id LOGICAL, INTENT(OUT) :: status INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: flag ! "TRUE/FALSE/ERROR from C" INTERFACE @@ -1023,40 +675,20 @@ CONTAINS END SUBROUTINE h5sis_simple_f -! -!****s* H5S/h5soffset_simple_f -! -! NAME -! h5soffset_simple_f -! -! PURPOSE -! Sets the offset of a simple dataspace. -! -! INPUTS -! space_id - dataspace identifier -! offset - the offset at which to position the -! selection -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! NONE -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Sets the offset of a simple dataspace. +!! +!! \param space_id Dataspace identifier. +!! \param offset The offset at which to position the selection. +!! \param hdferr \fortran_error +!! SUBROUTINE h5soffset_simple_f(space_id, offset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER(HSSIZE_T), DIMENSION(*), INTENT(IN) :: offset INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5soffset_simple_c(space_id, offset) BIND(C,NAME='h5soffset_simple_c') IMPORT :: HID_T, HSSIZE_T @@ -1070,44 +702,20 @@ CONTAINS END SUBROUTINE h5soffset_simple_f -! -!****s* H5S/h5sextent_copy_f -! -! NAME -! h5sextent_copy_f -! -! PURPOSE -! Copies the extent of a dataspace. -! -! INPUTS -! dest_space_id - the identifier for the dataspace to which -! the extent is copied -! source_space_id - the identifier for the dataspace from -! which the extent is copied -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! NONE -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! NOTES -! - -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Copies the extent of a dataspace. +!! +!! \param dest_space_id The identifier for the dataspace to which the extent is copied. +!! \param source_space_id The identifier for the dataspace from which the extent is copied. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sextent_copy_f(dest_space_id, source_space_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dest_space_id INTEGER(HID_T), INTENT(IN) :: source_space_id - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5sextent_copy_c(dest_space_id, source_space_id) BIND(C,NAME='h5sextent_copy_c') IMPORT :: HID_T @@ -1121,34 +729,18 @@ CONTAINS END SUBROUTINE h5sextent_copy_f -! -!****s* H5S/h5sset_extent_none_f -! -! NAME -! h5sset_extent_none_f -! -! PURPOSE -! Removes the extent from a dataspace. -! -! INPUTS -! space_id - dataspace identifier -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Removes the extent from a dataspace. +!! +!! \param space_id Dataspace identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sset_extent_none_f(space_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sset_extent_none_c(space_id) BIND(C,NAME='h5sset_extent_none_c') IMPORT :: HID_T @@ -1160,39 +752,22 @@ CONTAINS hdferr = h5sset_extent_none_c(space_id) END SUBROUTINE h5sset_extent_none_f -! -!****s* H5S/h5sselect_hyperslab_f -! -! NAME -! h5sselect_hyperslab_f -! -! PURPOSE -! Selects a hyperslab region to add to the current selected -! region -! -! INPUTS -! space_id - dataspace identifier -! operator - flag, valid values are: -! H5S_SELECT_SET_F -! H5S_SELECT_OR_F -! start - array with hyperslab offsets -! count - number of blocks included in the hyperslab -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! stride - array with hyperslab strides -! block - array with hyperslab block sizes -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 6, 2001 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Selects a hyperslab region to add to the current selected +!! region +!! +!! \param space_id Dataspace identifier. +!! \param operator Flag, valid values are: +!! \li H5S_SELECT_SET_F +!! \li H5S_SELECT_OR_F +!! \param start Array with hyperslab offsets. +!! \param count Number of blocks included in the hyperslab. +!! \param hdferr \fortran_error +!! \param stride Array with hyperslab strides. +!! \param block Array with hyperslab block sizes. +!! SUBROUTINE h5sselect_hyperslab_f(space_id, OPERATOR, start, count, & hdferr, stride, BLOCK) IMPLICIT NONE @@ -1203,7 +778,6 @@ CONTAINS INTEGER, INTENT(OUT) :: hdferr INTEGER(HSIZE_T), DIMENSION(:), OPTIONAL, INTENT(IN) :: stride INTEGER(HSIZE_T), DIMENSION(:), OPTIONAL, INTENT(IN) :: BLOCK -!***** INTEGER(HSIZE_T), DIMENSION(:), ALLOCATABLE :: def_block INTEGER(HSIZE_T), DIMENSION(:), ALLOCATABLE :: def_stride INTEGER :: rank @@ -1276,79 +850,62 @@ CONTAINS END SUBROUTINE h5sselect_hyperslab_f ! !$! -! !$!****s* H5S/h5scombine_hyperslab_f -! !$! -! !$! NAME -! !$! h5scombine_hyperslab_f -! !$! -! !$! PURPOSE -! !$! Combine a hyperslab selection with the current -! !$! selection for a dataspace -! !$! -! !$! INPUTS -! !$! space_id - dataspace of selection to use -! !$! operator - flag, valid values are: -! !$! H5S_SELECT_NOOP_F -! !$! H5S_SELECT_SET_F -! !$! H5S_SELECT_OR_F -! !$! H5S_SELECT_AND_F -! !$! H5S_SELECT_XOR_F -! !$! H5S_SELECT_NOTB_F -! !$! H5S_SELECT_NOTA_F -! !$! H5S_SELECT_APPEND_F -! !$! H5S_SELECT_PREPEND_F -! !$! start - array with hyperslab offsets -! !$! count - number of blocks included in the -! !$! hyperslab -! !$! OUTPUTS -! !$! hyper_id - identifier for the new hyperslab -! !$! hdferr: - error code -! !$! Success: 0 -! !$! Failure: -1 -! !$! OPTIONAL PARAMETERS -! !$! stride - array with hyperslab strides -! !$! block - array with hyperslab block sizes -! !$! -! !$! AUTHOR -! !$! Elena Pourmal -! !$! October 7, 2002 -! !$! -! !$! HISTORY -! !$! -! !$! -! !$! NOTES -! !$! Commented out until 1.6 ? 10/08/2002 -! !$! -! !$! SOURCE +!> +!! !$! +!! !$! NAME +!! !$! h5scombine_hyperslab_f +!! !$! +!! !$! PURPOSE +!! !$! Combine a hyperslab selection with the current +!! !$! selection for a dataspace +!! !$! +!! !$! INPUTS +!! !$! space_id - dataspace of selection to use +!! !$! operator - flag, valid values are: +!! !$! H5S_SELECT_NOOP_F +!! !$! H5S_SELECT_SET_F +!! !$! H5S_SELECT_OR_F +!! !$! H5S_SELECT_AND_F +!! !$! H5S_SELECT_XOR_F +!! !$! H5S_SELECT_NOTB_F +!! !$! H5S_SELECT_NOTA_F +!! !$! H5S_SELECT_APPEND_F +!! !$! H5S_SELECT_PREPEND_F +!! !$! start - array with hyperslab offsets +!! !$! count - number of blocks included in the +!! !$! hyperslab +!! !$! OUTPUTS +!! !$! hyper_id - identifier for the new hyperslab +!! !$! hdferr: - error code +!! !$! Success: 0 +!! !$! Failure: -1 +!! !$! OPTIONAL PARAMETERS +!! !$! stride - array with hyperslab strides +!! !$! block - array with hyperslab block sizes +!! !$! +!! !$! AUTHOR +!! !$! Elena Pourmal +!! !$! October 7, 2002 +!! !$! +!! !$! HISTORY +!! !$! +!! !$! +!! !$! NOTES +!! !$! Commented out until 1.6 ? 10/08/2002 +!! !$! +!! !$! SOURCE ! SUBROUTINE h5scombine_hyperslab_f(space_id, operator, start, count, & ! hyper_id, hdferr, stride, block) ! IMPLICIT NONE -! INTEGER(HID_T), INTENT(IN) :: space_id ! Dataspace identifier -! INTEGER, INTENT(IN) :: operator ! Flag, valid values are: - ! H5S_SELECT_NOOP_F - ! H5S_SELECT_SET_F - ! H5S_SELECT_OR_F - ! H5S_SELECT_AND_F - ! H5S_SELECT_XOR_F - ! H5S_SELECT_NOTB_F - ! H5S_SELECT_NOTA_F - ! H5S_SELECT_APPEND_F - ! H5S_SELECT_PREPEND_F + + ! H5S_SELECT_AND_F + ! H5S_SELECT_XOR_F + ! H5S_SELECT_NOTB_F + ! H5S_SELECT_NOTA_F + ! H5S_SELECT_APPEND_F + ! H5S_SELECT_PREPEND_F ! -! INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: start - ! Starting coordinates of the hyperslab -! INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: count - ! Number of blocks to select - ! from dataspace -! INTEGER(HID_T), INTENT(OUT) :: hyper_id ! New hyperslab identifier -! INTEGER, INTENT(OUT) :: hdferr ! Error code -! INTEGER(HSIZE_T), DIMENSION(:), OPTIONAL, INTENT(IN) :: stride - ! Array of how many elements to move - ! in each direction -! INTEGER(HSIZE_T), DIMENSION(:), OPTIONAL, INTENT(IN) :: block - ! Sizes of element block -! INTEGER(HSIZE_T), DIMENSION(:), ALLOCATABLE :: def_block -! INTEGER(HSIZE_T), DIMENSION(:), ALLOCATABLE :: def_stride + ! INTEGER :: rank ! INTEGER :: error1, error2 @@ -1359,15 +916,7 @@ CONTAINS ! !DEC$IF DEFINED(HDF5F90_WINDOWS) ! !DEC$ATTRIBUTES C,reference,decorate,alias:'H5SCOMBINE_HYPERSLAB_C'::h5scombine_hyperslab_c ! !DEC$ENDIF -! INTEGER(HID_T), INTENT(IN) :: space_id -! INTEGER, INTENT(IN) :: operator -! INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: start -! INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: count -! INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL, INTENT(IN) :: stride -! INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL, INTENT(IN) :: block -! INTEGER(HID_T), INTENT(OUT) :: hyper_id -! END FUNCTION h5scombine_hyperslab_c -! END INTERFACE + ! if (present(stride).and. present(block)) then ! hdferr = h5scombine_hyperslab_c(space_id, operator, start, count, & @@ -1423,78 +972,64 @@ CONTAINS ! END SUBROUTINE h5scombine_hyperslab_f ! !$! -! !$!****s* H5S/ -! !$! -! !$! NAME -! !$! h5scombine_select_f -! !$! -! !$! PURPOSE -! !$! Combine two hyperslab selections with an operation -! !$! and return a dataspace with resulting selection. -! !$! -! !$! INPUTS -! !$! space1_id - dataspace of selection to use -! !$! operator - flag, valid values are: -! !$! H5S_SELECT_NOOP_F -! !$! H5S_SELECT_SET_F -! !$! H5S_SELECT_OR_F -! !$! H5S_SELECT_AND_F -! !$! H5S_SELECT_XOR_F -! !$! H5S_SELECT_NOTB_F -! !$! H5S_SELECT_NOTA_F -! !$! H5S_SELECT_APPEND_F -! !$! H5S_SELECT_PREPEND_F -! !$! space2_id - dataspace of selection to use -! !$! OUTPUTS -! !$! ds_id - idataspace identifier with the new selection -! !$! hdferr: - error code -! !$! Success: 0 -! !$! Failure: -1 -! !$! OPTIONAL PARAMETERS - NONE -! !$! -! !$! AUTHOR -! !$! Elena Pourmal -! !$! October 7, 2002 -! !$! -! !$! HISTORY -! !$! -! !$! -! !$! NOTES commented out until 1.6 release(?) 10/08/2002 -! !$! - -! ! SOURCE +!> +!! !$! +!! !$! NAME +!! !$! h5scombine_select_f +!! !$! +!! !$! PURPOSE +!! !$! Combine two hyperslab selections with an operation +!! !$! and return a dataspace with resulting selection. +!! !$! +!! !$! INPUTS +!! !$! space1_id - dataspace of selection to use +!! !$! operator - flag, valid values are: +!! !$! H5S_SELECT_NOOP_F +!! !$! H5S_SELECT_SET_F +!! !$! H5S_SELECT_OR_F +!! !$! H5S_SELECT_AND_F +!! !$! H5S_SELECT_XOR_F +!! !$! H5S_SELECT_NOTB_F +!! !$! H5S_SELECT_NOTA_F +!! !$! H5S_SELECT_APPEND_F +!! !$! H5S_SELECT_PREPEND_F +!! !$! space2_id - dataspace of selection to use +!! !$! OUTPUTS +!! !$! ds_id - idataspace identifier with the new selection +!! !$! hdferr: - error code +!! !$! Success: 0 +!! !$! Failure: -1 +!! !$! OPTIONAL PARAMETERS - NONE +!! !$! +!! !$! AUTHOR +!! !$! Elena Pourmal +!! !$! October 7, 2002 +!! !$! +!! !$! HISTORY +!! !$! +!! !$! +!! !$! NOTES commented out until 1.6 release(?) 10/08/2002 +!! !$! +! +!! ! SOURCE ! !$ SUBROUTINE h5scombine_select_f(space1_id, operator, space2_id, & ! ds_id, hdferr) ! IMPLICIT NONE -! INTEGER(HID_T), INTENT(IN) :: space1_id ! First dataspace identifier -! INTEGER(HID_T), INTENT(IN) :: space2_id ! Second dataspace identifier -! INTEGER, INTENT(IN) :: operator ! Flag, valid values are: - ! H5S_SELECT_NOOP_F - ! H5S_SELECT_SET_F - ! H5S_SELECT_OR_F - ! H5S_SELECT_AND_F - ! H5S_SELECT_XOR_F - ! H5S_SELECT_NOTB_F - ! H5S_SELECT_NOTA_F - ! H5S_SELECT_APPEND_F - ! H5S_SELECT_PREPEND_F + + ! H5S_SELECT_AND_F + ! H5S_SELECT_XOR_F + ! H5S_SELECT_NOTB_F + ! H5S_SELECT_NOTA_F + ! H5S_SELECT_APPEND_F + ! H5S_SELECT_PREPEND_F ! -! INTEGER(HID_T), INTENT(OUT) :: ds_id ! New dataspace identifier -! INTEGER, INTENT(OUT) :: hdferr ! Error code -! -! INTERFACE -! INTEGER FUNCTION h5scombine_select_c(space1_id, operator, & + ! space2_id, ds_id) ! USE H5GLOBAL ! !DEC$IF DEFINED(HDF5F90_WINDOWS) ! !DEC$ATTRIBUTES C,reference,decorate,alias:'H5SCOMBINE_SELECT_C'::h5scombine_select_c ! !DEC$ENDIF -! INTEGER(HID_T), INTENT(IN) :: space1_id -! INTEGER(HID_T), INTENT(IN) :: space2_id -! INTEGER, INTENT(IN) :: operator -! INTEGER(HID_T), INTENT(OUT) :: ds_id -! END FUNCTION h5scombine_select_c -! END INTERFACE + ! hdferr = h5scombine_select_c(space1_id, operator, space2_id, & ! ds_id) @@ -1503,113 +1038,90 @@ CONTAINS ! END SUBROUTINE h5scombine_select_f ! !$! -! !$!****s* H5S/ -! !$! -! !$! NAME -! !$! h5smodify_select_f -! !$! -! !$! PURPOSE -! !$! Refine a hyperslab selection with an operation -! !$! using second hyperslab -! !$! -! !$! INPUTS -! !$! space1_id - dataspace of selection to modify -! !$! operator - flag, valid values are: -! !$! H5S_SELECT_NOOP_F -! !$! H5S_SELECT_SET_F -! !$! H5S_SELECT_OR_F -! !$! H5S_SELECT_AND_F -! !$! H5S_SELECT_XOR_F -! !$! H5S_SELECT_NOTB_F -! !$! H5S_SELECT_NOTA_F -! !$! H5S_SELECT_APPEND_F -! !$! H5S_SELECT_PREPEND_F -! !$! space2_id - dataspace of selection to use -! !$! -! !$! OUTPUTS -! !$! hdferr: - error code -! !$! Success: 0 -! !$! Failure: -1 -! !$! OPTIONAL PARAMETERS - NONE -! !$! -! !$! AUTHOR -! !$! Elena Pourmal -! !$! October 7, 2002 -! !$! -! !$! HISTORY -! !$! -! !$! -! !$! NOTESCommented out until 1.6 release(?) 10/08/2002 EIP -! !$! - -! ! SOURCE +!> +!! !$! +!! !$! NAME +!! !$! h5smodify_select_f +!! !$! +!! !$! PURPOSE +!! !$! Refine a hyperslab selection with an operation +!! !$! using second hyperslab +!! !$! +!! !$! INPUTS +!! !$! space1_id - dataspace of selection to modify +!! !$! operator - flag, valid values are: +!! !$! H5S_SELECT_NOOP_F +!! !$! H5S_SELECT_SET_F +!! !$! H5S_SELECT_OR_F +!! !$! H5S_SELECT_AND_F +!! !$! H5S_SELECT_XOR_F +!! !$! H5S_SELECT_NOTB_F +!! !$! H5S_SELECT_NOTA_F +!! !$! H5S_SELECT_APPEND_F +!! !$! H5S_SELECT_PREPEND_F +!! !$! space2_id - dataspace of selection to use +!! !$! +!! !$! OUTPUTS +!! !$! hdferr: - error code +!! !$! Success: 0 +!! !$! Failure: -1 +!! !$! OPTIONAL PARAMETERS - NONE +!! !$! +!! !$! AUTHOR +!! !$! Elena Pourmal +!! !$! October 7, 2002 +!! !$! +!! !$! HISTORY +!! !$! +!! !$! +!! !$! NOTESCommented out until 1.6 release(?) 10/08/2002 EIP +!! !$! +! +!! ! SOURCE ! SUBROUTINE h5smodify_select_f(space1_id, operator, space2_id, & ! hdferr) ! IMPLICIT NONE -! INTEGER(HID_T), INTENT(INOUT) :: space1_id ! Dataspace identifier to - ! modify -! INTEGER(HID_T), INTENT(IN) :: space2_id ! Second dataspace identifier -! INTEGER, INTENT(IN) :: operator ! Flag, valid values are: - ! H5S_SELECT_NOOP_F - ! H5S_SELECT_SET_F - ! H5S_SELECT_OR_F - ! H5S_SELECT_AND_F - ! H5S_SELECT_XOR_F - ! H5S_SELECT_NOTB_F - ! H5S_SELECT_NOTA_F - ! H5S_SELECT_APPEND_F - ! H5S_SELECT_PREPEND_F + + ! H5S_SELECT_AND_F + ! H5S_SELECT_XOR_F + ! H5S_SELECT_NOTB_F + ! H5S_SELECT_NOTA_F + ! H5S_SELECT_APPEND_F + ! H5S_SELECT_PREPEND_F ! -! INTEGER, INTENT(OUT) :: hdferr ! Error code -! INTERFACE -! INTEGER FUNCTION h5smodify_select_c(space1_id, operator, & + ! space2_id) ! USE H5GLOBAL ! !DEC$IF DEFINED(HDF5F90_WINDOWS) ! !DEC$ATTRIBUTES C,reference,decorate,alias:'H5SMODIFY_SELECT_C'::h5smodify_select_c ! !DEC$ENDIF -! INTEGER(HID_T), INTENT(INOUT) :: space1_id -! INTEGER(HID_T), INTENT(IN) :: space2_id -! INTEGER, INTENT(IN) :: operator -! END FUNCTION h5smodify_select_c -! END INTERFACE + ! hdferr = h5smodify_select_c(space1_id, operator, space2_id) ! return ! END SUBROUTINE h5smodify_select_f -! -!****s* H5S/h5sget_select_type_f -! -! NAME -! h5sget_select_type_f -! -! PURPOSE -! Retrieve the type of selection -! -! INPUTS -! space_id - dataspace identifier with selection -! OUTPUTS -! type - selection type flag, valid values are: -! H5S_SEL_ERROR_F -! H5S_SEL_NONE_F -! H5S_SEL_POINTS_F -! H5S_SEL_HYPERSLABS_F -! H5S_SEL_ALL_F -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! October 7, 2002 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Retrieve the type of selection +!! +!! \param space_id Dataspace identifier with selection. +!! \param type Selection type flag, valid values are: +!! \li H5S_SEL_ERROR_F +!! \li H5S_SEL_NONE_F +!! \li H5S_SEL_POINTS_F +!! \li H5S_SEL_HYPERSLABS_F +!! \li H5S_SEL_ALL_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_select_type_f(space_id, TYPE, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(INOUT) :: space_id INTEGER, INTENT(OUT) :: TYPE INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sget_select_type_c(space_id, TYPE) BIND(C,NAME='h5sget_select_type_c') IMPORT :: HID_T @@ -1624,37 +1136,26 @@ CONTAINS END SUBROUTINE h5sget_select_type_f -! -!****s* H5S/H5Sdecode_f -! -! NAME -! H5Sdecode_f -! -! PURPOSE -! Decode a binary object description of data space and return a new object handle. -! -! INPUTS -! buf - Buffer for the data space object to be decoded. -! obj_id - Object ID -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! March 26, 2008 -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Decode a binary object description of data space and return a new object handle. +!! +!! \param buf Buffer for the data space object to be decoded. +!! \param obj_id Object ID. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sdecode_f(buf, obj_id, hdferr) IMPLICIT NONE CHARACTER(LEN=*), INTENT(IN) :: buf INTEGER(HID_T), INTENT(OUT) :: obj_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5sdecode_c(buf, obj_id) BIND(C,NAME='h5sdecode_c') IMPORT :: C_CHAR IMPORT :: HID_T CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: buf - INTEGER(HID_T), INTENT(OUT) :: obj_id ! Object ID + INTEGER(HID_T), INTENT(OUT) :: obj_id END FUNCTION h5sdecode_c END INTERFACE @@ -1662,35 +1163,24 @@ CONTAINS END SUBROUTINE h5sdecode_f -! -!****s* H5S/H5Sencode_f -! -! NAME -! H5Sencode_f -! -! PURPOSE -! Encode a data space object description into a binary buffer. -! -! INPUTS -! obj_id - Identifier of the object to be encoded. -! buf - Buffer for the object to be encoded into. -! nalloc - The size of the allocated buffer. -! OUTPUTS -! nalloc - The size of the buffer needed. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! March 26, 2008 -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Encode a data space object description into a binary buffer. +!! +!! \param obj_id Identifier of the object to be encoded. +!! \param buf Buffer for the object to be encoded into. +!! \param nalloc The size of the buffer needed. +!! \param hdferr \fortran_error +!! \param fapl_id File access property list identifier. +!! SUBROUTINE h5sencode_f(obj_id, buf, nalloc, hdferr, fapl_id) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: obj_id CHARACTER(LEN=*), INTENT(OUT) :: buf INTEGER(SIZE_T), INTENT(INOUT) :: nalloc INTEGER, INTENT(OUT) :: hdferr - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: fapl_id ! File access property list -!***** + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: fapl_id INTEGER(HID_T) :: fapl_id_default INTERFACE @@ -1712,32 +1202,22 @@ CONTAINS END SUBROUTINE h5sencode_f -!****s* H5S/h5sextent_equal_f -! -! NAME -! h5sextent_equal_f -! -! PURPOSE -! Determines whether two dataspace extents are equal. -! -! INPUTS -! space1_id - First dataspace identifier. -! space2_id - Second dataspace identifier. -! OUTPUTS -! Equal - .TRUE. if equal, .FALSE. if unequal. -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! M. Scot Breitenfeld -! April 2, 2008 -! -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Determines whether two dataspace extents are equal. +!! +!! \param space1_id First dataspace identifier. +!! \param space2_id Second dataspace identifier. +!! \param Equal .TRUE. if equal, .FALSE. if unequal. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sextent_equal_f(space1_id, space2_id, equal, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space1_id INTEGER(HID_T), INTENT(IN) :: space2_id LOGICAL, INTENT(OUT) :: Equal INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER(HID_T) :: c_equal INTERFACE @@ -1756,28 +1236,18 @@ CONTAINS END SUBROUTINE h5sextent_equal_f -! -!****s* H5S/h5sget_regular_hyperslab_f -! -! NAME -! h5sget_regular_hyperslab_f -! -! PURPOSE -! Retrieves a regular hyperslab selection. -! -! INPUTS -! space_id - The identifier of the dataspace. -! OUTPUTS -! start - Offset of the start of the regular hyperslab. -! stride - Stride of the regular hyperslab. -! count - Number of blocks in the regular hyperslab. -! block - Size of a block in the regular hyperslab. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! January, 28 2016 -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Retrieves a regular hyperslab selection. +!! +!! \param space_id The identifier of the dataspace. +!! \param start Offset of the start of the regular hyperslab. +!! \param stride Stride of the regular hyperslab. +!! \param count Number of blocks in the regular hyperslab. +!! \param block Size of a block in the regular hyperslab. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sget_regular_hyperslab_f(space_id, start, stride, count, block, hdferr) IMPLICIT NONE @@ -1787,7 +1257,6 @@ CONTAINS INTEGER(HSIZE_T), INTENT(OUT), DIMENSION(*), TARGET :: count INTEGER(HSIZE_T), INTENT(OUT), DIMENSION(*), TARGET :: block INTEGER, INTENT(OUT) :: hdferr -!***** TYPE(C_PTR) :: start_c, stride_c, count_c, block_c INTEGER :: n @@ -1824,30 +1293,20 @@ CONTAINS END SUBROUTINE h5sget_regular_hyperslab_f -!****s* H5S/h5sis_regular_hyperslab_f -! -! NAME -! h5sis_regular_hyperslab_f -! -! PURPOSE -! Retrieves a regular hyperslab selection. -! -! INPUTS -! space_id - The identifier of the dataspace. -! OUTPUTS -! IsRegular - TRUE or FALSE for hyperslab selection if successful. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! January, 28 2016 -! SOURCE +!> +!! \ingroup FH5S +!! +!! \brief Retrieves a regular hyperslab selection. +!! +!! \param space_id The identifier of the dataspace. +!! \param IsRegular TRUE or FALSE for hyperslab selection if successful. +!! \param hdferr \fortran_error +!! SUBROUTINE h5sis_regular_hyperslab_f(space_id, IsRegular, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: space_id LOGICAL :: IsRegular INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER(C_INT) :: status INTERFACE diff --git a/fortran/src/H5Tff.F90 b/fortran/src/H5Tff.F90 index 0a11976..ceb5447 100644 --- a/fortran/src/H5Tff.F90 +++ b/fortran/src/H5Tff.F90 @@ -1,10 +1,13 @@ -!****h* ROBODoc/H5T -! -! NAME -! MODULE H5T -! -! PURPOSE -! This file contains Fortran interfaces for H5T functions. +!> @defgroup FH5T Fortran Datatype (H5T) Interface +!! +!! @see H5T, C-API +!! +!! @see @ref H5T_UG, User Guide +!! + +!> @ingroup FH5T +!! +!! @brief This module contains Fortran interfaces for H5T functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -33,7 +36,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** MODULE H5T @@ -43,53 +45,34 @@ MODULE H5T PRIVATE h5tenum_insert_f03, h5tenum_insert_f90 -!****t* H5T/hvl_t ! Fortran2003 Derived Type: TYPE hvl_t - INTEGER(size_t) :: len ! Length of VL data (in base type units) - TYPE(C_PTR) :: p ! Pointer to VL data + INTEGER(size_t) :: len !< Length of VL data (in base type units) + TYPE(C_PTR) :: p !< Pointer to VL data END TYPE hvl_t -!***** +#ifndef H5_DOXYGEN_FORTRAN INTERFACE h5tenum_insert_f MODULE PROCEDURE h5tenum_insert_f03 MODULE PROCEDURE h5tenum_insert_f90 END INTERFACE +#endif + CONTAINS -! -!****s* H5T/h5topen_f -! -! NAME -! h5topen_f -! -! PURPOSE -! Opens named datatype. -! -! INPUTS -! loc_id - location identifier -! name - a datatype name -! OUTPUTS -! type_id - datatype identifier -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! tapl_id - datatype access property list identifier. -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! Added optional parameter 'tapl_id' for compatibility -! with H5Topen2. April 9, 2009. -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Opens named datatype. +!! +!! \param loc_id Location identifier. +!! \param name A datatype name. +!! \param type_id Datatype identifier. +!! \param hdferr \fortran_error +!! \param tapl_id Datatype access property list identifier. +!! SUBROUTINE h5topen_f(loc_id, name, type_id, hdferr, tapl_id) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: loc_id @@ -97,7 +80,6 @@ CONTAINS INTEGER(HID_T), INTENT(OUT) :: type_id INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tapl_id -!***** INTEGER :: namelen ! Name length INTEGER(HID_T) :: tapl_id_default @@ -121,53 +103,29 @@ CONTAINS hdferr = h5topen_c(loc_id, name, namelen, type_id, tapl_id_default) END SUBROUTINE h5topen_f -! -!****s* H5T/h5tcommit_f -! -! NAME -! h5tcommit_f -! -! PURPOSE -! Commits a transient datatype to a file, creating a -! new named datatype. -! -! INPUTS -! loc_id - location identifier -! name - name of the datatype to be stored -! at the specified location -! type_id - identifier of a datatype to be stored -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! lcpl_id - Link creation property list -! tcpl_id - Datatype creation property list -! tapl_id - Datatype access property list -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! - Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! - Added optional parameters introduced in version 1.8 -! M. Scot Breitenfeld -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Commits a transient datatype to a file, creating a new named datatype. +!! +!! \param loc_id Location identifier. +!! \param name Name of the datatype to be stored at the specified location +!! \param type_id Identifier of a datatype to be stored. +!! \param hdferr \fortran_error +!! \param lcpl_id Link creation property list. +!! \param tcpl_id Datatype creation property list. +!! \param tapl_id Datatype access property list. +!! SUBROUTINE h5tcommit_f(loc_id, name, type_id, hdferr, & lcpl_id, tcpl_id, tapl_id ) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier + INTEGER(HID_T), INTENT(IN) :: loc_id CHARACTER(LEN=*), INTENT(IN) :: name - ! Datatype name within file or group - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier - INTEGER, INTENT(OUT) :: hdferr ! Error code - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id ! Link creation property list - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tcpl_id ! Datatype creation property list - INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tapl_id ! Datatype access property list -!***** + INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER, INTENT(OUT) :: hdferr + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tcpl_id + INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tapl_id INTEGER :: namelen ! Name length @@ -205,36 +163,20 @@ CONTAINS lcpl_id_default, tcpl_id_default, tapl_id_default ) END SUBROUTINE h5tcommit_f -! -!****s* H5T/h5tcopy_f -! -! NAME -! h5tcopy_f -! -! PURPOSE -! Creates a copy of existing datatype. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! new_type_id - identifier of datatype's copy -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Creates a copy of existing datatype. +!! +!! \param type_id Datatype identifier. +!! \param new_type_id Identifier of datatype's copy. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tcopy_f(type_id, new_type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER(HID_T), INTENT(OUT) :: new_type_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tcopy_c(type_id, new_type_id) BIND(C,NAME='h5tcopy_c') IMPORT :: HID_T @@ -245,39 +187,22 @@ CONTAINS hdferr = h5tcopy_c(type_id, new_type_id) END SUBROUTINE h5tcopy_f -! -!****s* H5T/h5tequal_f -! -! NAME -! h5tequal_f -! -! PURPOSE -! Determines whether two datatype identifiers refer -! to the same datatype. -! -! INPUTS -! type1_id - datatype identifier -! type2_id - datatype identifier -! OUTPUTS -! flag - TRUE/FALSE flag to indicate -! if two datatypes are equal -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Determines whether two datatype identifiers refer to the same datatype. +!! +!! \param type1_id Datatype identifier. +!! \param type2_id Datatype identifier. +!! \param flag TRUE/FALSE flag to indicate if two datatypes are equal. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tequal_f(type1_id, type2_id, flag, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type1_id INTEGER(HID_T), INTENT(IN) :: type2_id LOGICAL, INTENT(OUT) :: flag INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: c_flag INTERFACE INTEGER FUNCTION h5tequal_c(type1_id, type2_id, c_flag) BIND(C,NAME='h5tequal_c') @@ -293,35 +218,18 @@ CONTAINS hdferr = h5tequal_c(type1_id, type2_id, c_flag) IF(c_flag .GT. 0) flag = .TRUE. END SUBROUTINE h5tequal_f -! -!****s* H5T/h5tclose_f -! -! NAME -! h5tclose_f -! -! PURPOSE -! Releases a datatype. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Releases a datatype. +!! +!! \param type_id Datatype identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tclose_f(type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tclose_c(type_id) BIND(C,NAME='h5tclose_c') IMPORT :: HID_T @@ -332,49 +240,32 @@ CONTAINS hdferr = h5tclose_c(type_id) END SUBROUTINE h5tclose_f -! -!****s* H5T/h5tget_class_f -! -! NAME -! h5tget_class_f -! -! PURPOSE -! Returns the datatype class identifier. -! -! INPUTS -! type_id - Datatype identifier -! OUTPUTS -! class - Class, possible values are: -! H5T_NO_CLASS_F (-1) -! H5T_INTEGER_F (0) -! H5T_FLOAT_F (1) -! H5T_TIME_F (2) -! H5T_STRING_F (3) -! H5T_BITFIELD_F (4) -! H5T_OPAQUE_F (5) -! H5T_COMPOUND_F (6) -! H5T_REFERENCE_F (7) -! H5T_ENUM_F (8) -! H5T_VLEN_F (9) -! H5T_ARRAY_F (10) -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns the datatype class identifier. +!! +!! \param type_id Datatype identifier. +!! \param class Class, possible values are: +!! \li H5T_NO_CLASS_F +!! \li H5T_INTEGER_F +!! \li H5T_FLOAT_F +!! \li H5T_TIME_F +!! \li H5T_STRING_F +!! \li H5T_BITFIELD_F +!! \li H5T_OPAQUE_F +!! \li H5T_COMPOUND_F +!! \li H5T_REFERENCE_F +!! \li H5T_ENUM_F +!! \li H5T_VLEN_F +!! \li H5T_ARRAY_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_class_f(type_id, class, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: class INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_class_c(type_id, class) BIND(C,NAME='h5tget_class_c') IMPORT :: HID_T @@ -386,37 +277,20 @@ CONTAINS hdferr = h5tget_class_c(type_id, class) END SUBROUTINE h5tget_class_f -! -!****s* H5T/h5tget_size_f -! -! NAME -! h5tget_size_f -! -! PURPOSE -! Returns the size of a datatype. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! size - datatype size -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns the size of a datatype. +!! +!! \param type_id Datatype identifier. +!! \param size Datatype size. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_size_f(type_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier - INTEGER(SIZE_T), INTENT(OUT) :: size ! Datatype size - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER(SIZE_T), INTENT(OUT) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5tget_size_c(type_id, size) BIND(C,NAME='h5tget_size_c') IMPORT :: HID_T, SIZE_T @@ -429,38 +303,20 @@ CONTAINS hdferr = h5tget_size_c(type_id, size) END SUBROUTINE h5tget_size_f -! -!****s* H5T/h5tset_size_f -! -! NAME -! h5tset_size_f -! -! PURPOSE -! Sets the total size for an atomic datatype. -! -! INPUTS -! type_id - datatype identifier -! size - size of the datatype -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Sets the total size for an atomic datatype. +!! +!! \param type_id Datatype identifier. +!! \param size Size of the datatype. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_size_f(type_id, size, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier - INTEGER(SIZE_T), INTENT(IN) :: size ! Datatype size - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER(SIZE_T), INTENT(IN) :: size + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5tset_size_c(type_id, size) BIND(C,NAME='h5tset_size_c') IMPORT :: HID_T, SIZE_T @@ -473,44 +329,24 @@ CONTAINS hdferr = h5tset_size_c(type_id, size) END SUBROUTINE h5tset_size_f -! -!****s* H5T/h5tget_order_f -! -! NAME -! h5tget_order_f -! -! PURPOSE -! Returns the byte order of an atomic datatype. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! order - byte order for the datatype, possible -! values are: -! H5T_ORDER_LE_F -! H5T_ORDER_BE_F -! H5T_ORDER_VAX_F (not implemented yet) -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns the byte order of an atomic datatype. +!! +!! \param type_id Datatype identifier. +!! \param order Byte order for the datatype, possible values are: +!! \li H5T_ORDER_LE_F +!! \li H5T_ORDER_BE_F +!! \li H5T_ORDER_VAX_F (not implemented yet) +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_order_f(type_id, order, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier + INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: order - ! Datatype byte order, possible values are: - ! H5T_ORDER_LE_F - ! H5T_ORDER_BE_F ! H5T_ORDER_VAX_F - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5tget_order_c(type_id, order) BIND(C,NAME='h5tget_order_c') IMPORT :: HID_T @@ -522,43 +358,24 @@ CONTAINS hdferr = h5tget_order_c(type_id, order) END SUBROUTINE h5tget_order_f -! -!****s* H5T/h5tset_order_f -! -! NAME -! h5tset_order_f -! -! PURPOSE -! Sets the byte ordering of an atomic datatype. -! -! INPUTS -! type_id - datatype identifier -! order - datatype byte order Possible values are: -! H5T_ORDER_LE_F -! H5T_ORDER_BE_F -! H5T_ORDER_VAX_F (not implemented yet) -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Sets the byte ordering of an atomic datatype. +!! +!! \param type_id Datatype identifier. +!! \param order Datatype byte order Possible values are: +!! \li H5T_ORDER_LE_F +!! \li H5T_ORDER_BE_F +!! \li H5T_ORDER_VAX_F (not implemented yet) +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_order_f(type_id, order, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier - INTEGER, INTENT(IN) :: order ! Datatype byte order, possible values - ! are: - ! H5T_ORDER_LE_F - ! H5T_ORDER_BE_F + INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER, INTENT(IN) :: order ! H5T_ORDER_VAX_F - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5tset_order_c(type_id, order) BIND(C,NAME='h5tset_order_c') IMPORT :: HID_T @@ -571,37 +388,20 @@ CONTAINS hdferr = h5tset_order_c(type_id, order) END SUBROUTINE h5tset_order_f -! -!****s* H5T/h5tget_precision_f -! -! NAME -! h5tget_precision_f -! -! PURPOSE -! Returns the precision of an atomic datatype. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! precision - precision of the datatype -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns the precision of an atomic datatype. +!! +!! \param type_id Datatype identifier. +!! \param precision Precision of the datatype. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_precision_f(type_id, PRECISION, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER(SIZE_T), INTENT(OUT) :: precision INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_precision_c(type_id, PRECISION) BIND(C,NAME='h5tget_precision_c') IMPORT :: HID_T, SIZE_T @@ -614,37 +414,20 @@ CONTAINS hdferr = h5tget_precision_c(type_id, PRECISION) END SUBROUTINE h5tget_precision_f -! -!****s* H5T/h5tset_precision_f -! -! NAME -! h5tset_precision_f -! -! PURPOSE -! Sets the precision of an atomic datatype. -! -! INPUTS -! type_id - datatype identifier -! precision - datatype precision -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Sets the precision of an atomic datatype. +!! +!! \param type_id Datatype identifier. +!! \param precision Datatype precision. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_precision_f(type_id, PRECISION, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER(SIZE_T), INTENT(IN) :: PRECISION INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tset_precision_c (type_id, PRECISION) BIND(C,NAME='h5tset_precision_c') IMPORT :: HID_T, SIZE_T @@ -657,36 +440,20 @@ CONTAINS hdferr = h5tset_precision_c(type_id, PRECISION) END SUBROUTINE h5tset_precision_f -! -!****s* H5T/h5tget_offset_f -! -! NAME -! h5tget_offset_f -! -! PURPOSE -! Retrieves the bit offset of the first significant bit. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! offset - offset value -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves the bit offset of the first significant bit. +!! +!! \param type_id Datatype identifier. +!! \param offset Offset value. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_offset_f(type_id, offset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER(SIZE_T), INTENT(OUT) :: offset INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_offset_c(type_id, offset) BIND(C,NAME='h5tget_offset_c') IMPORT :: HID_T, SIZE_T @@ -699,36 +466,20 @@ CONTAINS hdferr = h5tget_offset_c(type_id, offset) END SUBROUTINE h5tget_offset_f -! -!****s* H5T/h5tset_offset_f -! -! NAME -! h5tset_offset_f -! -! PURPOSE -! Sets the bit offset of the first significant bit. -! -! INPUTS -! type_id - datatype identifier -! offset - offset value -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Sets the bit offset of the first significant bit. +!! +!! \param type_id Datatype identifier. +!! \param offset Offset value. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_offset_f(type_id, offset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER(SIZE_T), INTENT(IN) :: offset INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tset_offset_c(type_id, offset) BIND(C,NAME='h5tset_offset_c') IMPORT :: HID_T, SIZE_T @@ -741,46 +492,27 @@ CONTAINS hdferr = h5tset_offset_c(type_id, offset) END SUBROUTINE h5tset_offset_f -! -!****s* H5T/h5tget_pad_f -! -! NAME -! h5tget_pad_f -! -! PURPOSE -! Retrieves the padding type of the least and -! most -significant bit padding. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! lsbpad - least-significant bit padding type -! msbpad - most-significant bit padding type -! Possible values of padding type are: -! H5T_PAD_ERROR_F -! H5T_PAD_ZERO_F -! H5T_PAD_ONE_F -! H5T_PAD_BACKGROUND_F -! H5T_PAD_NPAD_F -! hdferr - Returns 0 if successful and -1 if fails - -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves the padding type of the least and most-significant bit padding. +!! +!! \param type_id Datatype identifier. +!! \param lsbpad Least-significant bit padding type. +!! \param msbpad Most-significant bit padding type. Possible values are: +!! \li H5T_PAD_ERROR_F +!! \li H5T_PAD_ZERO_F +!! \li H5T_PAD_ONE_F +!! \li H5T_PAD_BACKGROUND_F +!! \li H5T_PAD_NPAD_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_pad_f(type_id, lsbpad, msbpad, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: lsbpad INTEGER, INTENT(OUT) :: msbpad INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_pad_c(type_id, lsbpad, msbpad) BIND(C,NAME='h5tget_pad_c') IMPORT :: HID_T @@ -794,44 +526,27 @@ CONTAINS hdferr = h5tget_pad_c(type_id, lsbpad, msbpad) END SUBROUTINE h5tget_pad_f -! -!****s* H5T/h5tset_pad_f -! -! NAME -! h5tset_pad_f -! -! PURPOSE -! Sets the least and most-significant bits padding types. -! -! INPUTS -! type_id - datatype identifier -! lsbpad - least-significant bit padding type -! msbpad - most-significant bit padding type -! Possible values of padding type are: -! H5T_PAD_ERROR_F = -1 -! H5T_PAD_ZERO_F = 0 -! H5T_PAD_ONE_F = 1 -! H5T_PAD_BACKGROUND_F = 2 -! H5T_PAD_NPAD_F = 3 -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Sets the least and most-significant bits padding types. +!! +!! \param type_id Datatype identifier. +!! \param lsbpad Least-significant bit padding type. +!! \param msbpad Most-significant bit padding type. Possible values are: +!! \li H5T_PAD_ERROR_F +!! \li H5T_PAD_ZERO_F +!! \li H5T_PAD_ONE_F +!! \li H5T_PAD_BACKGROUND_F +!! \li H5T_PAD_NPAD_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_pad_f(type_id, lsbpad, msbpad, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(IN) :: lsbpad INTEGER, INTENT(IN) :: msbpad INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tset_pad_c(type_id, lsbpad, msbpad) BIND(C,NAME='h5tset_pad_c') IMPORT :: HID_T @@ -845,42 +560,26 @@ CONTAINS hdferr = h5tset_pad_c(type_id, lsbpad, msbpad) END SUBROUTINE h5tset_pad_f -! -!****s* H5T/h5tget_sign_f -! -! NAME -! h5tget_sign_f -! -! PURPOSE -! Retrieves the sign type for an integer type. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! sign - sign type -! Possible values are: -! - Unsigned integer type -! H5T_SGN_NONE_F = 0 -! - Two's complement signed integer type -! H5T_SGN_2_F = 1 -! - error value: H5T_SGN_ERROR_F=-1 -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves the sign type for an integer type. +!! +!! \param type_id Datatype identifier. +!! \param sign Sign type. Possible values are: +!! \li Unsigned integer type +!! H5T_SGN_NONE_F = 0 +!! \li Two's complement signed integer type +!! H5T_SGN_2_F = 1 +!! \li Error value +!! H5T_SGN_ERROR_F = -1 +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_sign_f(type_id, sign, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: sign INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_sign_c(type_id, sign) BIND(C,NAME='h5tget_sign_c') @@ -894,42 +593,26 @@ CONTAINS hdferr = h5tget_sign_c(type_id, sign) END SUBROUTINE h5tget_sign_f -! -!****s* H5T/h5tset_sign_f -! -! NAME -! h5tset_sign_f -! -! PURPOSE -! Sets the sign property for an integer type. -! -! INPUTS -! type_id - datatype identifier -! sign - sign type -! Possible values are: -! - Unsigned integer type -! H5T_SGN_NONE_F = 0 -! - Two's complement signed integer type -! H5T_SGN_2_F = 1 -! - error value: H5T_SGN_ERROR_F=-1 -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Sets the sign property for an integer type. +!! +!! \param type_id Datatype identifier. +!! \param sign Sign type. Possible values are: +!! \li Unsigned integer type +!! H5T_SGN_NONE_F = 0 +!! \li Two's complement signed integer type +!! H5T_SGN_2_F = 1 +!! \li Error value +!! H5T_SGN_ERROR_F = -1 +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_sign_f(type_id, sign, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(IN) :: sign INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tset_sign_c(type_id, sign) BIND(C,NAME='h5tset_sign_c') IMPORT :: HID_T @@ -942,34 +625,19 @@ CONTAINS hdferr = h5tset_sign_c(type_id, sign) END SUBROUTINE h5tset_sign_f -! -!****s* H5T/h5tget_fields_f -! -! NAME -! h5tget_fields_f -! -! PURPOSE -! Retrieves floating point datatype bit field information. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! spos - sign bit-position -! epos - exponent bit-position -! esize - size of exponent in bits -! mpos - mantissa position -! msize - size of mantissa in bits -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves floating point datatype bit field information. +!! +!! \param type_id Datatype identifier. +!! \param spos Sign bit-position. +!! \param epos Exponent bit-position. +!! \param esize Size of exponent in bits. +!! \param mpos Mantissa position. +!! \param msize Size of mantissa in bits. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_fields_f(type_id, spos, epos, esize, mpos, msize, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id @@ -979,7 +647,6 @@ CONTAINS INTEGER(SIZE_T), INTENT(OUT) :: mpos INTEGER(SIZE_T), INTENT(OUT) :: msize INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_fields_c(type_id, spos, epos, esize, mpos, msize) & @@ -998,34 +665,19 @@ CONTAINS hdferr = h5tget_fields_c(type_id, spos, epos, esize, mpos, msize) END SUBROUTINE h5tget_fields_f -! -!****s* H5T/h5tset_fields_f -! -! NAME -! h5tset_fields_f -! -! PURPOSE -! Sets locations and sizes of floating point bit fields. -! -! INPUTS -! type_id - datatype identifier -! spos - sign bit-position -! epos - exponent bit-position -! esize - size of exponent in bits -! mpos - mantissa position -! msize - size of mantissa in bits -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Sets locations and sizes of floating point bit fields. +!! +!! \param type_id Datatype identifier. +!! \param spos Sign bit-position. +!! \param epos Exponent bit-position. +!! \param esize Size of exponent in bits. +!! \param mpos Mantissa position. +!! \param msize Size of mantissa in bits. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_fields_f(type_id, spos, epos, esize, mpos, msize, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id @@ -1035,7 +687,6 @@ CONTAINS INTEGER(SIZE_T), INTENT(IN) :: mpos INTEGER(SIZE_T), INTENT(IN) :: msize INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tset_fields_c(type_id, spos, epos, esize, mpos, msize) & @@ -1054,36 +705,20 @@ CONTAINS hdferr = h5tset_fields_c(type_id, spos, epos, esize, mpos, msize) END SUBROUTINE h5tset_fields_f -! -!****s* H5T/h5tget_ebias_f -! -! NAME -! h5tget_ebias_f -! -! PURPOSE -! Retrieves the exponent bias of a floating-point type. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! ebias - datatype exponent bias -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves the exponent bias of a floating-point type. +!! +!! \param type_id Datatype identifier. +!! \param ebias Datatype exponent bias. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_ebias_f(type_id, ebias, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER(SIZE_T), INTENT(OUT) :: ebias INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_ebias_c(type_id, ebias) BIND(C,NAME='h5tget_ebias_c') @@ -1097,36 +732,20 @@ CONTAINS hdferr = h5tget_ebias_c(type_id, ebias) END SUBROUTINE h5tget_ebias_f -! -!****s* H5T/h5tset_ebias_f -! -! NAME -! h5tset_ebias_f -! -! PURPOSE -! Sets the exponent bias of a floating-point type. -! -! INPUTS -! type_id - datatype identifier -! ebias - datatype exponent bias -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Sets the exponent bias of a floating-point type. +!! +!! \param type_id Datatype identifier. +!! \param ebias Datatype exponent bias. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_ebias_f(type_id, ebias, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER(SIZE_T), INTENT(IN) :: ebias INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tset_ebias_c(type_id, ebias) BIND(C,NAME='h5tset_ebias_c') IMPORT :: HID_T, SIZE_T @@ -1139,40 +758,23 @@ CONTAINS hdferr = h5tset_ebias_c(type_id, ebias) END SUBROUTINE h5tset_ebias_f -! -!****s* H5T/h5tget_norm_f -! -! NAME -! h5tget_norm_f -! -! PURPOSE -! Retrieves mantissa normalization of a floating-point -! datatype. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! norm - normalization types, valid values are: -! H5T_NORM_IMPLIED_F -! H5T_NORM_MSBSET_F -! H5T_NORM_NONE_F -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves mantissa normalization of a floating-point datatype. +!! +!! \param type_id Datatype identifier. +!! \param norm Normalization types, valid values are: +!! \li H5T_NORM_IMPLIED_F +!! \li H5T_NORM_MSBSET_F +!! \li H5T_NORM_NONE_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_norm_f(type_id, norm, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: norm INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_norm_c(type_id, norm) BIND(C,NAME='h5tget_norm_c') @@ -1186,40 +788,23 @@ CONTAINS hdferr = h5tget_norm_c(type_id, norm) END SUBROUTINE h5tget_norm_f -! -!****s* H5T/h5tset_norm_f -! -! NAME -! h5tset_norm_f -! -! PURPOSE -! Sets the mantissa normalization of a floating-point datatype. -! -! INPUTS -! type_id - datatype identifier -! norm - normalization types, valid values are: -! H5T_NORM_IMPLIED_F -! H5T_NORM_MSBSET_F -! H5T_NORM_NONE_F -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Sets the mantissa normalization of a floating-point datatype. +!! +!! \param type_id Datatype identifier. +!! \param norm Normalization types, valid values are: +!! \li H5T_NORM_IMPLIED_F +!! \li H5T_NORM_MSBSET_F +!! \li H5T_NORM_NONE_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_norm_f(type_id, norm, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(IN) :: norm INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tset_norm_c(type_id, norm) BIND(C,NAME='h5tset_norm_c') IMPORT :: HID_T @@ -1232,41 +817,23 @@ CONTAINS hdferr = h5tset_norm_c(type_id, norm) END SUBROUTINE h5tset_norm_f -! -!****s* H5T/h5tget_inpad_f -! -! NAME -! h5tget_inpad_f -! -! PURPOSE -! Retrieves the internal padding type for unused bits -! in floating-point datatypes. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! padtype - padding type for unused bits -! Possible values of padding type are: -! H5T_PAD_ZERO_F -! H5T_PAD_ONE_F -! H5T_PAD_BACKGROUND_F -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves the internal padding type for unused bits in floating-point datatypes. +!! +!! \param type_id Datatype identifier. +!! \param padtype Padding type for unused bits. Possible values are: +!! \li H5T_PAD_ZERO_F +!! \li H5T_PAD_ONE_F +!! \li H5T_PAD_BACKGROUND_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_inpad_f(type_id, padtype, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: padtype INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_inpad_c(type_id, padtype) BIND(C,NAME='h5tget_inpad_c') IMPORT :: HID_T @@ -1279,40 +846,23 @@ CONTAINS hdferr = h5tget_inpad_c(type_id, padtype) END SUBROUTINE h5tget_inpad_f -! -!****s* H5T/h5tset_inpad_f -! -! NAME -! h5tset_inpad_f -! -! PURPOSE -! Fills unused internal floating point bits. -! -! INPUTS -! type_id - datatype identifier -! padtype - padding type for unused bits -! Possible values of padding type are: -! H5T_PAD_ZERO_F -! H5T_PAD_ONE_F -! H5T_PAD_BACKGROUND_F -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Fills unused internal floating point bits. +!! +!! \param type_id Datatype identifier. +!! \param padtype Padding type for unused bits. Possible values are: +!! \li H5T_PAD_ZERO_F +!! \li H5T_PAD_ONE_F +!! \li H5T_PAD_BACKGROUND_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_inpad_f(type_id, padtype, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(IN) :: padtype INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tset_inpad_c(type_id, padtype) BIND(C,NAME='h5tset_inpad_c') IMPORT :: HID_T @@ -1325,39 +875,22 @@ CONTAINS hdferr = h5tset_inpad_c(type_id, padtype) END SUBROUTINE h5tset_inpad_f -! -!****s* H5T/h5tget_cset_f -! -! NAME -! h5tget_cset_f -! -! PURPOSE -! Retrieves the character set type of a string datatype. -! -! INPUTS -! type_id - Datatype identifier -! OUTPUTS -! cset - Character set type of a string datatype -! Possible values are: -! H5T_CSET_ASCII_F -! H5T_CSET_UTF8_F -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves the character set type of a string datatype. +!! +!! \param type_id Datatype identifier. +!! \param cset Character set type of a string datatype. Possible values are: +!! \li H5T_CSET_ASCII_F +!! \li H5T_CSET_UTF8_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_cset_f(type_id, cset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: cset - INTEGER, INTENT(OUT) :: hdferr ! Error code -!***** + INTEGER, INTENT(OUT) :: hdferr INTERFACE INTEGER FUNCTION h5tget_cset_c(type_id, cset) BIND(C,NAME='h5tget_cset_c') IMPORT :: HID_T @@ -1370,39 +903,22 @@ CONTAINS hdferr = h5tget_cset_c(type_id, cset) END SUBROUTINE h5tget_cset_f -! -!****s* H5T/h5tset_cset_f -! -! NAME -! h5tset_cset_f -! -! PURPOSE -! Sets character set to be used. -! -! INPUTS -! type_id - datatype identifier -! cset - character set type of a string datatype -! Possible values are: -! H5T_CSET_ASCII_F -! H5T_CSET_UTF8_F -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Sets character set to be used. +!! +!! \param type_id Datatype identifier. +!! \param cset Character set type of a string datatype. Possible values are: +!! \li H5T_CSET_ASCII_F +!! \li H5T_CSET_UTF8_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_cset_f(type_id, cset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(IN) :: cset INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tset_cset_c(type_id, cset) BIND(C,NAME='h5tset_cset_c') IMPORT :: HID_T @@ -1414,41 +930,24 @@ CONTAINS hdferr = h5tset_cset_c(type_id, cset) END SUBROUTINE h5tset_cset_f -! -!****s* H5T/h5tget_strpad_f -! -! NAME -! h5tget_strpad_f -! -! PURPOSE -! Retrieves the storage mechanism for a string datatype. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! strpad - storage method for a string datatype -! Possible values are: -! H5T_STR_NULLTERM_F, -! H5T_STR_NULLPAD_F, -! H5T_STR_SPACEPAD_F -! H5T_STR_ERROR_F -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves the storage mechanism for a string datatype. +!! +!! \param type_id Datatype identifier. +!! \param strpad Storage method for a string datatype. Possible values are: +!! \li H5T_STR_NULLTERM_F +!! \li H5T_STR_NULLPAD_F +!! \li H5T_STR_SPACEPAD_F +!! \li H5T_STR_ERROR_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_strpad_f(type_id, strpad, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: strpad INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_strpad_c(type_id, strpad) BIND(C,NAME='h5tget_strpad_c') IMPORT :: HID_T @@ -1461,41 +960,24 @@ CONTAINS hdferr = h5tget_strpad_c(type_id, strpad) END SUBROUTINE h5tget_strpad_f -! -!****s* H5T/h5tset_strpad_f -! -! NAME -! h5tset_strpad_f -! -! PURPOSE -! Defines the storage mechanism for character strings. -! -! INPUTS -! type_id - datatype identifier -! strpad - storage method for a string datatype -! Possible values are: -! H5T_STR_NULLTERM_F, -! H5T_STR_NULLPAD_F, -! H5T_STR_SPACEPAD_F, -! H5T_STR_ERROR_F. -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Defines the storage mechanism for character strings. +!! +!! \param type_id Datatype identifier. +!! \param strpad Storage method for a string datatype. Possible values are: +!! \li H5T_STR_NULLTERM_F +!! \li H5T_STR_NULLPAD_F +!! \li H5T_STR_SPACEPAD_F +!! \li H5T_STR_ERROR_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_strpad_f(type_id, strpad, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(IN) :: strpad INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tset_strpad_c(type_id, strpad) BIND(C,NAME='h5tset_strpad_c') IMPORT :: HID_T @@ -1508,37 +990,20 @@ CONTAINS hdferr = h5tset_strpad_c(type_id, strpad) END SUBROUTINE h5tset_strpad_f -! -!****s* H5T/h5tget_nmembers_f -! -! NAME -! h5tget_nmembers_f -! -! PURPOSE -! Retrieves the number of fields in a compound datatype. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! num_members - number of members -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves the number of fields in a compound datatype. +!! +!! \param type_id Datatype identifier. +!! \param num_members Number of members. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_nmembers_f(type_id, num_members, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: num_members INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_nmembers_c(type_id, num_members) BIND(C,NAME='h5tget_nmembers_c') IMPORT :: HID_T @@ -1551,32 +1016,17 @@ CONTAINS hdferr = h5tget_nmembers_c(type_id, num_members) END SUBROUTINE h5tget_nmembers_f -! -!****s* H5T/h5tget_member_name_f -! -! NAME -! h5tget_member_name_f -! -! PURPOSE -! Retrieves the name of a field of a compound datatype. -! -! INPUTS -! type_id - datatype identifier -! index - filed index (0-based) -! OUTPUTS -! member_name - buffer to hold member's name -! namelen - name length -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves the name of a field of a compound datatype. +!! +!! \param type_id Datatype identifier. +!! \param index Filed index (0-based). +!! \param member_name Buffer to hold member's name. +!! \param namelen Name length. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_member_name_f(type_id, index, member_name, namelen, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id @@ -1584,7 +1034,6 @@ CONTAINS CHARACTER(LEN=*), INTENT(OUT) :: member_name INTEGER, INTENT(OUT) :: namelen INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_member_name_c(type_id, index, member_name, namelen) BIND(C,NAME='h5tget_member_name_c') IMPORT :: C_CHAR @@ -1600,38 +1049,22 @@ CONTAINS hdferr = h5tget_member_name_c(type_id, index, member_name, namelen) END SUBROUTINE h5tget_member_name_f -! -!****s* H5T/h5tget_member_offset_f -! -! NAME -! h5tget_member_offset_f -! -! PURPOSE -! Retrieves the offset of a field of a compound datatype. -! -! INPUTS -! type_id - datatype identifier -! member_no - number of the field -! OUTPUTS -! offset - byte offset of the requested field -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves the offset of a field of a compound datatype. +!! +!! \param type_id Datatype identifier. +!! \param member_no Number of the field. +!! \param offset Byte offset of the requested field. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_member_offset_f(type_id, member_no, offset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(IN) :: member_no INTEGER(SIZE_T), INTENT(OUT) :: offset INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_member_offset_c(type_id, member_no, offset ) BIND(C,NAME='h5tget_member_offset_c') IMPORT :: HID_T, SIZE_T @@ -1644,35 +1077,22 @@ CONTAINS hdferr = h5tget_member_offset_c(type_id, member_no, offset ) END SUBROUTINE h5tget_member_offset_f -! -!****s* H5T/h5tget_member_index_f -! -! NAME -! h5tget_member_index_f -! -! PURPOSE -! Retrieves the index of a compound or enumeration datatype member. -! -! INPUTS -! type_id - datatype identifier -! name - name of the field or member whose index to -! to be retrieved from the datatype. -! OUTPUTS -! index - 0-based index of the filed or member (0 to N-1) -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! September 26, 2002 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Retrieves the index of a compound or enumeration datatype member. +!! +!! \param type_id Datatype identifier. +!! \param name Name of the field or member whose index to be retrieved from the datatype. +!! \param index Based index of the filed or member (0 to N-1). +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_member_index_f(type_id, name, index, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id CHARACTER(LEN=*), INTENT(IN) :: name INTEGER, INTENT(OUT) :: index INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: namelen ! Name length INTERFACE @@ -1693,79 +1113,52 @@ CONTAINS ! !$! -! !$!****s* H5T/h5tget_member_dim_f -! !$! -! !$! NAME -! !$! h5tget_member_dim_f -! !$! -! !$! PURPOSE -! !$! This function is not supported in hdf5-1.4.* -! !$! -! !$! INPUTS -! !$! OUTPUTS -! !$! hdferr: - error code -! !$! Success: 0 -! !$! Failure: -1 -! !$! -! !$! AUTHOR -! !$! Elena Pourmal -! !$! August 12, 1999 -! !$! -! !$! HISTORY -! !$! Explicit Fortran interfaces were added for -! !$! called C functions (it is needed for Windows -! !$! port). March 7, 2001 -! !$! -! !$! SOURCE +!> +!! !$! +!! !$! NAME +!! !$! h5tget_member_dim_f +!! !$! +!! !$! PURPOSE +!! !$! This function is not supported in hdf5-1.4.* +!! !$! +!! !$! INPUTS +!! !$! OUTPUTS +!! !$! hdferr: - error code +!! !$! Success: 0 +!! !$! Failure: -1 +!! !$! +!! !$! AUTHOR +!! !$! Elena Pourmal +!! !$! August 12, 1999 +!! !$! +!! !$! HISTORY +!! !$! Explicit Fortran interfaces were added for +!! !$! called C functions (it is needed for Windows +!! !$! port). March 7, 2001 +!! !$! +!! !$! SOURCE ! !$! SUBROUTINE h5tget_member_dims_f(type_id, field_idx,dims, field_dims, perm, hdferr) ! !$! ! !$! IMPLICIT NONE -! !$! INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier -! !$! INTEGER, INTENT(IN) :: field_idx !Field index (0-based) of -! !$! !field_dims, perm) -! !$! INTEGER, INTENT(OUT) :: dims !number of dimensions of the field -! !$! -! !$! INTEGER(SIZE_T),DIMENSION(*), INTENT(OUT) :: field_dims !buffer to store the -! !$! !dimensions of the field -! !$! INTEGER, DIMENSION(*), INTENT(OUT) :: perm !buffer to store the -! !$! !permutation vector of the field -! !$! INTEGER, INTENT(OUT) :: hdferr ! Error code -! !$!*****! -! !$! INTEGER, EXTERNAL :: h5tget_member_dims_c -! !$! hdferr = h5tget_member_dims_c(type_id, field_idx, dims, field_dims, perm) + ! !$! ! !$! END SUBROUTINE h5tget_member_dims_f -!****s* H5T/h5tget_array_dims_f -! -! NAME -! h5tget_array_dims_f -! -! PURPOSE -! Returns sizes of array dimensions. -! -! INPUTS -! type_id - array datatype identifier -! OUTPUTS -! dims - buffer to store array datatype dimensions -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns sizes of array dimensions. +!! +!! \param type_id Array datatype identifier. +!! \param dims Buffer to store array datatype dimensions. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_array_dims_f(type_id, dims, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER(HSIZE_T),DIMENSION(*), INTENT(OUT) :: dims INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_array_dims_c(type_id, dims) BIND(C,NAME='h5tget_array_dims_c') IMPORT :: HID_T, HSIZE_T @@ -1779,36 +1172,20 @@ CONTAINS END SUBROUTINE h5tget_array_dims_f -! -!****s* H5T/h5tget_array_ndims_f -! -! NAME -! h5tget_array_ndims_f -! -! PURPOSE -! Returns the rank of an array datatype. -! -! INPUTS -! type_id - array datatype identifier -! OUTPUTS -! ndims - number of array dimensions -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns the rank of an array datatype. +!! +!! \param type_id Array datatype identifier. +!! \param ndims Number of array dimensions. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_array_ndims_f(type_id, ndims, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: ndims INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_array_ndims_c(type_id, ndims) BIND(C,NAME='h5tget_array_ndims_c') IMPORT :: HID_T @@ -1822,36 +1199,20 @@ CONTAINS END SUBROUTINE h5tget_array_ndims_f -! -!****s* H5T/h5tget_super_f -! -! NAME -! h5tget_super_f -! -! PURPOSE -! Returns the base datatype from which a datatype is derived. -! -! INPUTS -! type_id - datatype identifier -! OUTPUTS -! base_type_id - identifier of the base type -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns the base datatype from which a datatype is derived. +!! +!! \param type_id Datatype identifier. +!! \param base_type_id Identifier of the base type. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_super_f(type_id, base_type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER(HID_T), INTENT(OUT) :: base_type_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_super_c(type_id, base_type_id) BIND(C,NAME='h5tget_super_c') IMPORT :: HID_T @@ -1865,39 +1226,22 @@ CONTAINS END SUBROUTINE h5tget_super_f -! -!****s* H5T/h5tget_member_type_f -! -! NAME -! h5tget_member_type_f -! -! PURPOSE -! Returns the datatype of the specified member. -! -! INPUTS -! type_id - compound datatype identifier -! field_idx - field index (0-based) -! -! OUTPUTS -! datatype - identifier of the member's datatype -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns the datatype of the specified member. +!! +!! \param type_id Compound datatype identifier. +!! \param field_idx Field index (0-based). +!! \param datatype Identifier of the member's datatype. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_member_type_f(type_id, field_idx, datatype, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(IN) :: field_idx INTEGER(HID_T), INTENT(OUT) :: datatype INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_member_type_c(type_id, field_idx , datatype) & BIND(C,NAME='h5tget_member_type_c') @@ -1912,43 +1256,26 @@ CONTAINS hdferr = h5tget_member_type_c(type_id, field_idx , datatype) END SUBROUTINE h5tget_member_type_f -! -!****s* H5T/h5tcreate_f -! -! NAME -! h5tcreate_f -! -! PURPOSE -! Creates a new datatype. -! -! INPUTS -! class - Datatype class can be one of: -! H5T_COMPOUND_F -! H5T_ENUM_F -! H5T_OPAQUE_F -! H5T_STRING_F -! -! size - Size of the datatype. -! OUTPUTS -! type_id - Datatype identifier. -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Creates a new datatype. +!! +!! \param class Datatype class can be one of: +!! \li H5T_COMPOUND_F +!! \li H5T_ENUM_F +!! \li H5T_OPAQUE_F +!! \li H5T_STRING_F +!! \param size Size of the datatype. +!! \param type_id Datatype identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tcreate_f(class, size, type_id, hdferr) IMPLICIT NONE INTEGER , INTENT(IN) :: class INTEGER(SIZE_T), INTENT(IN) :: size INTEGER(HID_T) , INTENT(OUT) :: type_id INTEGER , INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tcreate_c(class, size, type_id) BIND(C,NAME='h5tcreate_c') IMPORT :: HID_T, SIZE_T @@ -1962,33 +1289,17 @@ CONTAINS hdferr = h5tcreate_c(class, size, type_id) END SUBROUTINE h5tcreate_f -! -!****s* H5T/h5tinsert_f -! -! NAME -! h5tinsert_f -! -! PURPOSE -! Adds a new member to a compound datatype. -! -! INPUTS -! type_id - compound datatype identifier -! name - name of the field to insert -! offset - start of the member in an instance of -! the compound datatype -! field_id - datatype identifier of the field to insert -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Adds a new member to a compound datatype. +!! +!! \param type_id Compound datatype identifier. +!! \param name Name of the field to insert. +!! \param offset Start of the member in an instance of the compound datatype. +!! \param field_id Datatype identifier of the field to insert. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tinsert_f(type_id, name, offset, field_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id @@ -1996,7 +1307,6 @@ CONTAINS INTEGER(SIZE_T), INTENT(IN) :: offset INTEGER(HID_T), INTENT(IN) :: field_id INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: namelen INTERFACE @@ -2016,34 +1326,18 @@ CONTAINS hdferr = h5tinsert_c(type_id, name, namelen, offset, field_id ) END SUBROUTINE h5tinsert_f -! -!****s* H5T/h5tpack_f -! -! NAME -! h5tpack_f -! -! PURPOSE -! Recursively removes padding from within a compound datatype. -! -! INPUTS -! type_id - compound datatype identifier -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Recursively removes padding from within a compound datatype. +!! +!! \param type_id Compound datatype identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tpack_f(type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tpack_c(type_id) BIND(C,NAME='h5tpack_c') IMPORT :: HID_T @@ -2056,45 +1350,32 @@ CONTAINS END SUBROUTINE h5tpack_f ! !$! -! !$!****s* H5T/h5tinsert_array_f -! !$! -! !$! NAME -! !$! h5tinsert_array_f -! !$! -! !$! PURPOSE -! !$! This function is not available on hdf5-1.4.* -! !$! -! !$! INPUTS -! !$! OUTPUTS -! !$! hdferr: - error code -! !$! Success: 0 -! !$! Failure: -1 -! !$! -! !$! AUTHOR -! !$! Elena Pourmal -! !$! August 12, 1999 -! !$! -! !$! HISTORY -! !$! Explicit Fortran interfaces were added for -! !$! called C functions (it is needed for Windows -! !$! port). March 7, 2001 -! !$! SOURCE +!> +!! !$! +!! !$! NAME +!! !$! h5tinsert_array_f +!! !$! +!! !$! PURPOSE +!! !$! This function is not available on hdf5-1.4.* +!! !$! +!! !$! INPUTS +!! !$! OUTPUTS +!! !$! hdferr: - error code +!! !$! Success: 0 +!! !$! Failure: -1 +!! !$! +!! !$! AUTHOR +!! !$! Elena Pourmal +!! !$! August 12, 1999 +!! !$! +!! !$! HISTORY +!! !$! Explicit Fortran interfaces were added for +!! !$! called C functions (it is needed for Windows +!! !$! port). March 7, 2001 +!! !$! SOURCE ! SUBROUTINE h5tinsert_array_f(parent_id,name,offset, ndims, dims, member_id, hdferr, perm) ! IMPLICIT NONE -! INTEGER(HID_T), INTENT(IN) :: parent_id ! identifier of the parent compound datatype -! CHARACTER(LEN=*), INTENT(IN) :: name !Name of the new member -! INTEGER(SIZE_T), INTENT(IN) :: offset !Offset to start of new member -! !within compound datatype -! INTEGER, INTENT(IN) :: ndims !Dimensionality of new member. -! !Valid values are 0 (zero) through 4 (four) -! INTEGER(SIZE_T), DIMENSION(*), INTENT(IN) :: dims !Size of new member array -! INTEGER(HID_T), INTENT(IN) :: member_id ! identifier of the datatype of the new member -! INTEGER, INTENT(OUT) :: hdferr ! Error code -! !*****! -! INTEGER, DIMENSION(*), OPTIONAL, INTENT(IN) :: perm -! !Pointer to buffer to store -! !the permutation vector of the field -! INTEGER :: namelen, sizeofperm + ! INTEGER, EXTERNAL :: h5tinsert_array_c, h5tinsert_array_c2 ! namelen = LEN(name) ! if (present(perm)) then @@ -2105,33 +1386,17 @@ CONTAINS ! ! END SUBROUTINE h5tinsert_array_f -! -!****s* H5T/h5tarray_create_f -! -! NAME -! h5tarray_create_f -! -! PURPOSE -! Creates an array datatype object. -! -! INPUTS -! base_id - datatype identifier for the array -! base datatype -! rank - rank of the array -! dims - array dimension sizes -! OUTPUTS -! type_id - array datatype identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Creates an array datatype object. +!! +!! \param base_id Datatype identifier for the array base datatype +!! \param rank Rank of the array. +!! \param dims Array dimension sizes. +!! \param type_id Array datatype identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tarray_create_f(base_id, rank, dims, type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: base_id @@ -2139,7 +1404,6 @@ CONTAINS INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: dims INTEGER(HID_T), INTENT(OUT) :: type_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tarray_create_c(base_id, rank, dims, type_id) BIND(C,NAME='h5tarray_create_c') IMPORT :: HID_T, HSIZE_T @@ -2155,36 +1419,20 @@ CONTAINS END SUBROUTINE h5tarray_create_f -! -!****s* H5T/h5tenum_create_f -! -! NAME -! h5tenum_create_f -! -! PURPOSE -! Creates a new enumeration datatype. -! -! INPUTS -! parent_id - datatype identifier for base datatype -! OUTPUTS -! new_type_id - datatype identifier for the enumeration datatype -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Creates a new enumeration datatype. +!! +!! \param parent_id Datatype identifier for base datatype. +!! \param new_type_id Datatype identifier for the enumeration datatype. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tenum_create_f(parent_id, new_type_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: parent_id INTEGER(HID_T), INTENT(OUT) :: new_type_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tenum_create_c(parent_id, new_type_id) BIND(C,NAME='h5tenum_create_c') @@ -2197,39 +1445,17 @@ CONTAINS hdferr = h5tenum_create_c(parent_id, new_type_id) END SUBROUTINE h5tenum_create_f -! -!****s* H5T/h5tenum_nameof_f -! -! NAME -! h5tenum_nameof_f -! -! PURPOSE -! Returns the symbol name corresponding to a specified -! member of an enumeration datatype. -! -! INPUTS -! type_id - datatype identifier -! value - value of the enumeration datatype -! namelen - name buffer size -! OUTPUTS -! name - buffer to hold symbol name -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! NOTE -! According to the standard: Because an INTENT(OUT) variable is considered undefined -! on entry to the procedure, any default initialization specified for its type will -! be applied. So we need to blank out the "name" to be portable and eliminate any -! characters the "name' may contain upon entry, depending on compiler implementation. -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns the symbol name corresponding to a specified member of an enumeration datatype. +!! +!! \param type_id Datatype identifier. +!! \param value Value of the enumeration datatype. +!! \param namelen Name buffer size. +!! \param name Buffer to hold symbol name. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tenum_nameof_f(type_id, value, namelen, name, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id @@ -2237,7 +1463,6 @@ CONTAINS INTEGER(SIZE_T), INTENT(IN) :: namelen INTEGER, INTENT(IN) :: value INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tenum_nameof_c(type_id, value, name, namelen) BIND(C,NAME='h5tenum_nameof_c') IMPORT :: C_CHAR @@ -2254,40 +1479,22 @@ CONTAINS hdferr = h5tenum_nameof_c(type_id, value, name, namelen) END SUBROUTINE h5tenum_nameof_f -! -!****s* H5T/h5tenum_valuof_f -! -! NAME -! h5tenum_valuof_f -! -! PURPOSE -! Returns the value corresponding to a specified -! member of an enumeration datatype. -! -! INPUTS -! type_id - datatype identifier -! name - symbol name -! OUTPUTS -! value - value of the enumeration datatype -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns the value corresponding to a specified member of an enumeration datatype. +!! +!! \param type_id Datatype identifier. +!! \param name Symbol name. +!! \param value Value of the enumeration datatype. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tenum_valueof_f(type_id, name, value, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id CHARACTER(LEN=*), INTENT(IN) :: name INTEGER, INTENT(OUT) :: value INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: namelen INTERFACE @@ -2307,38 +1514,22 @@ CONTAINS hdferr = h5tenum_valueof_c(type_id, name, namelen, value) END SUBROUTINE h5tenum_valueof_f -! -!****s* H5T/h5tget_member_value_f -! -! NAME -! h5tget_member_value_f -! -! PURPOSE -! Returns the value of an enumeration datatype member. -! -! INPUTS -! type_id - datatype identifier -! member_no - number of the enumeration datatype member -! OUTPUTS -! value - value of the enumeration datatype -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns the value of an enumeration datatype member. +!! +!! \param type_id Datatype identifier. +!! \param member_no Number of the enumeration datatype member. +!! \param value Value of the enumeration datatype. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_member_value_f(type_id, member_no, value, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(IN) :: member_no INTEGER, INTENT(OUT) :: value INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_member_value_c(type_id, member_no, value) & BIND(C,NAME='h5tget_member_value_c') @@ -2353,37 +1544,20 @@ CONTAINS hdferr = h5tget_member_value_c(type_id, member_no, value) END SUBROUTINE h5tget_member_value_f -! -!****s* H5T/h5tset_tag_f -! -! NAME -! h5tset_tag_f -! -! PURPOSE -! Tags an opaque datatype. -! -! INPUTS -! type_id - identifier for opaque datatype -! tag - unique ASCII string with which the opaque -! datatype is to be tagged. -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Tags an opaque datatype. +!! +!! \param type_id Identifier for opaque datatype. +!! \param tag Unique ASCII string with which the opaque datatype is to be tagged. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tset_tag_f(type_id, tag, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id CHARACTER(LEN=*), INTENT(IN) :: tag INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: taglen INTERFACE @@ -2401,39 +1575,22 @@ CONTAINS hdferr = h5tset_tag_c(type_id, tag, taglen) END SUBROUTINE h5tset_tag_f -! -!****s* H5T/h5tget_tag_f -! -! NAME -! h5tget_tag_f -! -! PURPOSE -! Gets the tag associated with an opaque datatype. -! -! INPUTS -! type_id - identifier for opaque datatype -! OUTPUTS -! tag - unique ASCII string associated with opaque -! datatype -! taglen - Length of tag -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Gets the tag associated with an opaque datatype. +!! +!! \param type_id Identifier for opaque datatype. +!! \param tag Unique ASCII string associated with opaque datatype. +!! \param taglen Length of tag. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_tag_f(type_id, tag,taglen, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id CHARACTER(LEN=*), INTENT(OUT) :: tag INTEGER, INTENT(OUT) :: taglen INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER(SIZE_T):: tag_size ! Declared character length of tab INTERFACE INTEGER FUNCTION h5tget_tag_c(type_id, tag, tag_size, taglen) & @@ -2452,35 +1609,20 @@ CONTAINS hdferr = h5tget_tag_c(type_id, tag, tag_size, taglen ) END SUBROUTINE h5tget_tag_f -! -!****s* H5T/h5tvlen_create_f -! -! NAME -! h5tvlen_create_f -! -! PURPOSE -! Creates a new variable-length datatype. -! -! INPUTS -! type_id - identifier iof base datatype -! OUTPUTS -! vltype_id - identifier for VL datatype -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! Wednesday, October 23, 2002 -! -! NOTES -! Only basic Fortran base datatypes are supported -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Creates a new variable-length datatype. +!! +!! \param type_id Identifier iof base datatype. +!! \param vltype_id Identifier for VL datatype. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tvlen_create_f(type_id, vltype_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER(HID_T), INTENT(OUT) :: vltype_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tvlen_create_c(type_id, vltype_id) BIND(C,NAME='h5tvlen_create_c') IMPORT :: HID_T @@ -2493,33 +1635,20 @@ CONTAINS hdferr = h5tvlen_create_c(type_id, vltype_id) END SUBROUTINE h5tvlen_create_f -! -!****s* H5T/h5tis_variable_str_f -! -! NAME -! h5tis_variable_str_f -! -! PURPOSE -! Determines whether a dattype is a variable string. -! -! INPUTS -! type_id - datartpe identifier -! OUTPUTS -! status - flag to indicate if datatype -! is a variable string ( TRUE or FALSE) -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! March 12, 2003 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Determines whether a dattype is a variable string. +!! +!! \param type_id Datartpe identifier. +!! \param status Flag to indicate if datatype is a variable string ( TRUE or FALSE). +!! \param hdferr \fortran_error +!! SUBROUTINE h5tis_variable_str_f(type_id, status, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id LOGICAL, INTENT(OUT) :: status INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: flag ! "TRUE/FALSE/ERROR from C" INTERFACE @@ -2538,47 +1667,34 @@ CONTAINS END SUBROUTINE h5tis_variable_str_f -! -!****s* H5T/h5tget_member_class_f -! -! NAME -! h5tget_member_class_f -! -! PURPOSE -! Returns datatype class of compound datatype member. -! -! INPUTS -! type_id - datartpe identifier -! member_no - index of compound datatype member -! OUTPUTS -! class - class type for compound dadtype member -! Valid classes: -! H5T_NO_CLASS_F (error) -! H5T_INTEGER_F -! H5T_FLOAT_F -! H5T_TIME_F -! H5T_STRING_F -! H5T_BITFIELD_F -! H5T_OPAQUE_F -! H5T_COMPOUND_F -! H5T_REFERENCE_F -! H5T_ENUM_F -! H5T_VLEN_F -! H5T_ARRAY_F -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! April 6, 2005 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns datatype class of compound datatype member. +!! +!! \param type_id Datartpe identifier. +!! \param member_no Index of compound datatype member. +!! \param class Class type for compound dadtype member. Valid classes: +!! \li H5T_NO_CLASS_F (error) +!! \li H5T_INTEGER_F +!! \li H5T_FLOAT_F +!! \li H5T_TIME_F +!! \li H5T_STRING_F +!! \li H5T_BITFIELD_F +!! \li H5T_OPAQUE_F +!! \li H5T_COMPOUND_F +!! \li H5T_REFERENCE_F +!! \li H5T_ENUM_F +!! \li H5T_VLEN_F +!! \li H5T_ARRAY_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_member_class_f(type_id, member_no, class, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id INTEGER, INTENT(IN) :: member_no INTEGER, INTENT(OUT) :: class INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_member_class_c(type_id, member_no, class) & BIND(C,NAME='h5tget_member_class_c') @@ -2594,35 +1710,17 @@ CONTAINS END SUBROUTINE h5tget_member_class_f -! -!****s* H5T/h5tcommit_anon_f -! -! NAME -! h5tcommit_anon_f -! -! PURPOSE -! Commits a transient datatype to a file, -! creating a new named datatype, -! but does not link it into the file structure. -! -! INPUTS -! loc_id - A file or group identifier specifying the file -! in which the new named datatype is to be created. -! dtype_id - A datatype identifier. -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! OPTIONAL PARAMETERS -! tcpl_id - A datatype creation property list identifier. -! (H5P_DEFAULT_F for the default property list.) -! tapl_id - A datatype access property list identifier. -! should always be passed as the value H5P_DEFAULT_F. -! -! AUTHOR -! M. Scot Breitenfeld -! February 25, 2008 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Commits a transient datatype to a file, creating a new named datatype, but does not link it into the file structure. +!! +!! \param loc_id A file or group identifier specifying the file in which the new named datatype is to be created. +!! \param dtype_id A datatype identifier. +!! \param hdferr \fortran_error +!! \param tcpl_id A datatype creation property list identifier (H5P_DEFAULT_F for the default property list.) +!! \param tapl_id A datatype access property list identifier should always be passed as the value H5P_DEFAULT_F. +!! SUBROUTINE h5tcommit_anon_f(loc_id, dtype_id, hdferr, tcpl_id, tapl_id) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: loc_id @@ -2630,7 +1728,6 @@ CONTAINS INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tcpl_id INTEGER(HID_T), OPTIONAL, INTENT(IN) :: tapl_id -!***** INTEGER(HID_T) :: tcpl_id_default INTEGER(HID_T) :: tapl_id_default @@ -2657,33 +1754,20 @@ CONTAINS END SUBROUTINE h5tcommit_anon_f -! -!****s* H5T/h5tcommitted_f -! -! NAME -! h5tcommitted_f -! -! PURPOSE -! Determines whether a datatype is a named type or a transient type. -! -! INPUTS -! dtype_id - A datatype identifier. -! -! OUTPUTS -! committed - .TRUE., if the datatype has been committed -! .FALSE., if the datatype has not been committed. -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! M. Scot Breitenfeld -! February 25, 2008 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Determines whether a datatype is a named type or a transient type. +!! +!! \param dtype_id A datatype identifier. +!! \param committed .TRUE. if the datatype has been committed, and .FALSE. if the datatype has not been committed. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tcommitted_f(dtype_id, committed, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dtype_id LOGICAL, INTENT(OUT) :: committed INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tcommitted_c(dtype_id) BIND(C,NAME='h5tcommitted_c') IMPORT :: HID_T @@ -2706,38 +1790,27 @@ CONTAINS END SUBROUTINE h5tcommitted_f -! -!****s* H5T/H5Tdecode_f -! -! NAME -! H5Tdecode_f -! -! PURPOSE -! Decode a binary object description of data type and return a new object handle. -! INPUTS -! buf - Buffer for the data space object to be decoded. -! obj_id - Object ID -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! April 9, 2008 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Decode A binary object description of data type and return a new object handle. +!! +!! \param buf Buffer for the data space object to be decoded. +!! \param obj_id Object ID. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tdecode_f(buf, obj_id, hdferr) IMPLICIT NONE CHARACTER(LEN=*), INTENT(IN) :: buf INTEGER(HID_T), INTENT(OUT) :: obj_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tdecode_c(buf, obj_id) BIND(C,NAME='h5tdecode_c') IMPORT :: C_CHAR IMPORT :: HID_T IMPLICIT NONE CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: buf - INTEGER(HID_T), INTENT(OUT) :: obj_id ! Object ID + INTEGER(HID_T), INTENT(OUT) :: obj_id END FUNCTION h5tdecode_c END INTERFACE @@ -2745,34 +1818,22 @@ CONTAINS END SUBROUTINE h5tdecode_f -! -!****s* H5T/H5Tencode_f -! -! NAME -! H5Tencode_f -! -! PURPOSE -! Encode a data type object description into a binary buffer. -! -! INPUTS -! obj_id - Identifier of the object to be encoded. -! buf - Buffer for the object to be encoded into. -! nalloc - The size of the allocated buffer. -! OUTPUTS -! nalloc - The size of the buffer needed. -! hdferr - Returns 0 if successful and -1 if fails. -! -! AUTHOR -! M. Scot Breitenfeld -! April 9, 2008 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Encode a data type object description into a binary buffer. +!! +!! \param obj_id Identifier of the object to be encoded. +!! \param buf Buffer for the object to be encoded into. +!! \param nalloc If set to zero, returns the size of the buffer needed. Otherwise, it sets the size of \p buf allocated. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tencode_f(obj_id, buf, nalloc, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: obj_id CHARACTER(LEN=*), INTENT(OUT) :: buf INTEGER(SIZE_T), INTENT(INOUT) :: nalloc INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tencode_c(buf, obj_id, nalloc) BIND(C,NAME='h5tencode_c') @@ -2789,32 +1850,20 @@ CONTAINS END SUBROUTINE h5tencode_f -! -!****s* H5T/h5tget_create_plist_f -! -! NAME -! h5tget_create_plist_f -! -! PURPOSE -! Returns a copy of a datatype creation property list. -! -! INPUTS -! dtype_id - Datatype identifier -! OUTPUTS -! dtpl_id - Datatype property list identifier -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! April 9, 2008 -! -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns a copy of a datatype creation property list. +!! +!! \param dtype_id Datatype identifier. +!! \param dtpl_id Datatype property list identifier. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_create_plist_f(dtype_id, dtpl_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dtype_id INTEGER(HID_T), INTENT(OUT) :: dtpl_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_create_plist_c(dtype_id, dtpl_id) BIND(C,NAME='h5tget_create_plist_c') IMPORT :: HID_T @@ -2827,33 +1876,22 @@ CONTAINS hdferr = h5tget_create_plist_c(dtype_id, dtpl_id) END SUBROUTINE h5tget_create_plist_f -! -!****s* H5T/h5tcompiler_conv_f -! -! NAME -! h5tcompiler_conv_f -! -! PURPOSE -! Check whether the library’s default conversion is hard conversion.R -! -! INPUTS -! src_id - Identifier for the source datatype. -! dst_id - Identifier for the destination datatype. -! OUTPUTS -! flag - TRUE for compiler conversion, FALSE for library conversion -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! April 9, 2008 -! SOURCE - SUBROUTINE h5tcompiler_conv_f( src_id, dst_id, flag, hdferr) +!> +!! \ingroup FH5T +!! +!! \brief Check whether the library’s default conversion is hard conversion. +!! +!! \param src_id Identifier for the source datatype. +!! \param dst_id Identifier for the destination datatype. +!! \param flag .TRUE. for compiler conversion, .FALSE. for library conversion. +!! \param hdferr \fortran_error +!! + SUBROUTINE h5tcompiler_conv_f(src_id, dst_id, flag, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: src_id INTEGER(HID_T), INTENT(IN) :: dst_id LOGICAL, INTENT(OUT) :: flag INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: c_flag INTERFACE @@ -2873,39 +1911,26 @@ CONTAINS END SUBROUTINE h5tcompiler_conv_f -! -!****s* H5T/h5tget_native_type_f -! -! NAME -! h5tget_native_type_f -! -! PURPOSE -! Returns the native datatype of a specified datatype. -! -! INPUTS -! dtype_id - Datatype identifier for the dataset datatype. -! -! direction - Direction of search: -! H5T_DIR_DEFAULT, default direction is inscendent, -! H5T_DIR_ASCEND , in inscendent order, -! H5T_DIR_DESCEND, in descendent order. -! -! * NOTE: In C it is defined as a structure: H5T_direction_t -! -! OUTPUTS -! native_dtype_id - The native datatype identifier for the specified dataset datatype -! hdferr - Returns 0 if successful and -1 if fails -! AUTHOR -! M. Scot Breitenfeld -! June 18, 2008 -! SOURCE +!> +!! \ingroup FH5T +!! +!! \brief Returns the native datatype of a specified datatype. +!! +!! \param dtype_id Datatype identifier for the dataset datatype. +!! \param direction Direction of search: +!! H5T_DIR_DEFAULT, default direction is inscendent, +!! H5T_DIR_ASCEND , in inscendent order, +!! H5T_DIR_DESCEND, in descendent order. +!! * NOTE: In C it is defined as a structure: H5T_direction_t +!! \param native_dtype_id The native datatype identifier for the specified dataset datatype. +!! \param hdferr \fortran_error +!! SUBROUTINE h5tget_native_type_f(dtype_id, direction, native_dtype_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dtype_id INTEGER, INTENT(IN) :: direction INTEGER(HID_T), INTENT(OUT) :: native_dtype_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5tget_native_type_c(dtype_id, direction, native_dtype_id) BIND(C,NAME='h5tget_native_type_c') IMPORT :: HID_T @@ -2919,31 +1944,19 @@ CONTAINS hdferr = h5tget_native_type_c(dtype_id, direction, native_dtype_id) END SUBROUTINE h5tget_native_type_f -!****s* H5T/H5Tconvert_f_F03 -! -! NAME -! H5Tconvert_f -! -! PURPOSE -! Converts data from between specified datatypes. -! -! Inputs: -! src_id - Identifier for the source datatype. -! dst_id - Identifier for the destination datatype. -! nelmts - Size of array buf. -! buf - Array containing pre-conversion values. -! background - Optional background buffer. -! plist_id - Dataset transfer property list identifier. -! -! Outputs: -! buf - Array containing post-conversion values. -! hdferr - error code: -! 0 on success and -1 on failure -! AUTHOR -! M. Scot Breitenfeld -! Decemember 8, 2008 -! -! Fortran2003 Interface: +!> +!! \ingroup FH5T +!! +!! \brief Converts data from between specified datatypes. +!! +!! \param src_id Identifier for the source datatype. +!! \param dst_id Identifier for the destination datatype. +!! \param nelmts Size of array buf. +!! \param buf Array containing pre-conversion values. +!! \param hdferr \fortran_error +!! \param background Background buffer. +!! \param plist_id Dataset transfer property list identifier. +!! SUBROUTINE h5tconvert_f(src_id, dst_id, nelmts, buf, hdferr, background, plist_id) IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: src_id @@ -2953,7 +1966,6 @@ CONTAINS INTEGER , INTENT(OUT) :: hdferr TYPE(C_PTR) , INTENT(INOUT), OPTIONAL :: background INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: plist_id -!***** INTEGER(HID_T) :: plist_id_default TYPE(C_PTR) :: background_default @@ -2981,102 +1993,94 @@ CONTAINS hdferr = H5Tconvert_c(src_id, dst_id, nelmts, buf, background_default, plist_id_default) END SUBROUTINE h5tconvert_f -! -!****s* H5T/h5tenum_insert_f90 -! -! NAME -! h5tenum_insert_f -! -! PURPOSE -! Inserts a new enumeration datatype member. -! -! INPUTS -! type_id - Datatype identifier for the enumeration datatype. -! name - Datatype identifier. -! value - Value of the new member. -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). March 7, 2001 -! SOURCE - SUBROUTINE h5tenum_insert_f90(type_id, name, value, hdferr) + +!> +!! \ingroup FH5T +!! +!! \brief Inserts a new enumeration datatype member. +!! +!! \note \fortran_approved +!! +!! \param type_id Datatype identifier for the enumeration datatype. +!! \param name Datatype identifier. +!! \param value Pointer to the value of the new member. +!! \param hdferr \fortran_error +!! +#ifdef H5_DOXYGEN_FORTRAN + SUBROUTINE h5tenum_insert_f(& +#else + SUBROUTINE h5tenum_insert_f03(& +#endif + type_id, name, value, hdferr) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: type_id + INTEGER(HID_T) , INTENT(IN) :: type_id CHARACTER(LEN=*), INTENT(IN) :: name - INTEGER, INTENT(IN) :: value + TYPE(C_PTR) , INTENT(IN) :: value INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: namelen + INTERFACE - INTEGER FUNCTION h5tenum_insert_c(type_id, name, namelen, value) BIND(C,NAME='h5tenum_insert_c') - IMPORT :: C_CHAR + INTEGER FUNCTION h5tenum_insert_ptr_c(type_id, name, namelen, value) & + BIND(C, NAME='h5tenum_insert_ptr_c') + IMPORT :: C_CHAR, C_PTR IMPORT :: HID_T IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: name - INTEGER, INTENT(IN) :: value INTEGER :: namelen - END FUNCTION h5tenum_insert_c + TYPE(C_PTR), VALUE :: value + END FUNCTION h5tenum_insert_ptr_c END INTERFACE namelen = LEN(name) - hdferr = h5tenum_insert_c(type_id, name, namelen, value) - END SUBROUTINE h5tenum_insert_f90 - -! -!****s* H5T/h5tenum_insert_f03 -! -! NAME -! h5tenum_insert_f -! -! PURPOSE -! Inserts a new enumeration datatype member. -! -! INPUTS -! type_id - Datatype identifier for the enumeration datatype. -! name - Datatype identifier. -! value - Pointer to the value of the new member. -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! -! AUTHOR -! M. Scot Breitenfeld -! February 6, 2015 -! -! HISTORY -! F2003 implementation of function -! SOURCE - SUBROUTINE h5tenum_insert_f03(type_id, name, value, hdferr) + hdferr = h5tenum_insert_ptr_c(type_id, name, namelen, value) +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5tenum_insert_f +#else + END SUBROUTINE h5tenum_insert_f03 +#endif + +!> +!! \ingroup FH5T +!! +!! \brief Inserts a new enumeration datatype member. +!! +!! \note \fortran_obsolete +!! +!! \param type_id Datatype identifier for the enumeration datatype. +!! \param name Datatype identifier. +!! \param value Value of the new member. +!! \param hdferr \fortran_error +!! +#ifdef H5_DOXYGEN_FORTRAN + SUBROUTINE h5tenum_insert_f(type_id, name, value, hdferr) +#else + SUBROUTINE h5tenum_insert_f90(type_id, name, value, hdferr) +#endif IMPLICIT NONE - INTEGER(HID_T) , INTENT(IN) :: type_id + INTEGER(HID_T), INTENT(IN) :: type_id CHARACTER(LEN=*), INTENT(IN) :: name - TYPE(C_PTR) , INTENT(IN) :: value + INTEGER, INTENT(IN) :: value INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: namelen - INTERFACE - INTEGER FUNCTION h5tenum_insert_ptr_c(type_id, name, namelen, value) & - BIND(C, NAME='h5tenum_insert_ptr_c') - IMPORT :: C_CHAR, C_PTR + INTEGER FUNCTION h5tenum_insert_c(type_id, name, namelen, value) BIND(C,NAME='h5tenum_insert_c') + IMPORT :: C_CHAR IMPORT :: HID_T IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: type_id CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: name + INTEGER, INTENT(IN) :: value INTEGER :: namelen - TYPE(C_PTR), VALUE :: value - END FUNCTION h5tenum_insert_ptr_c + END FUNCTION h5tenum_insert_c END INTERFACE namelen = LEN(name) - hdferr = h5tenum_insert_ptr_c(type_id, name, namelen, value) - END SUBROUTINE h5tenum_insert_f03 + hdferr = h5tenum_insert_c(type_id, name, namelen, value) +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5tenum_insert_f +#else + END SUBROUTINE h5tenum_insert_f90 +#endif END MODULE H5T diff --git a/fortran/src/H5VLff.F90 b/fortran/src/H5VLff.F90 index 364f0ae..1d60848 100644 --- a/fortran/src/H5VLff.F90 +++ b/fortran/src/H5VLff.F90 @@ -1,10 +1,13 @@ -!****h* ROBODoc/H5VL -! -! NAME -! MODULE H5VL -! -! PURPOSE -! This file contains Fortran interfaces for H5VL (VOL) functions. +!> @defgroup FH5VL Fortran VOL (H5VL) Interface +!! +!! @see H5VL, C-API +!! +!! @see @ref H5VL_UG, User Guide +!! + +!> @ingroup FH5VL +!! +!! @brief This module contains Fortran interfaces for H5VL (VOL) functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -32,7 +35,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** MODULE H5VL @@ -46,30 +48,22 @@ CONTAINS ! H5VLregister_connector -! -!****s* H5VL/H5VLregister_connector_by_name_f -! -! NAME -! H5VLregister_connector_by_name_f -! -! PURPOSE -! Registers a new VOL connector as a member of the virtual object -! layer class by name. -! -! INPUTS -! name - Connector name -! OUTPUTS -! vol_id - VOL id -! hdferr - Returns 0 if successful and -1 if fails -! SOURCE - +!> +!! \ingroup FH5V +!! +!! \brief Registers a new VOL connector as a member of the virtual object layer class by name. +!! +!! \param name Connector name. +!! \param vol_id VOL connector identifier if successful; otherwise returns H5I_INVALID_HID_F. +!! \param hdferr \fortran_error +!! \param vipl_id VOL initialization property list identifier. +!! SUBROUTINE H5VLregister_connector_by_name_f(name, vol_id, hdferr, vipl_id) IMPLICIT NONE CHARACTER(LEN=*), INTENT(IN) :: name INTEGER(HID_T), INTENT(OUT) :: vol_id INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T), OPTIONAL, INTENT(IN) :: vipl_id -!***** CHARACTER(LEN=LEN_TRIM(name)+1,KIND=C_CHAR) :: c_name INTEGER(HID_T) :: vipl_id_default @@ -93,14 +87,22 @@ CONTAINS IF(vol_id.LT.0) hdferr = H5I_INVALID_HID_F END SUBROUTINE H5VLregister_connector_by_name_f - +!> +!! \ingroup FH5V +!! +!! \brief Registers a new VOL connector by value. +!! +!! \param connector_value Connector value. +!! \param vol_id VOL connector identifier if successful; otherwise returns H5I_INVALID_HID_F. +!! \param hdferr \fortran_error +!! \param vipl_id VOL initialization property list identifier. +!! SUBROUTINE H5VLregister_connector_by_value_f(connector_value, vol_id, hdferr, vipl_id) IMPLICIT NONE INTEGER, INTENT(IN) :: connector_value INTEGER(HID_T), INTENT(OUT) :: vol_id INTEGER, INTENT(OUT) :: hdferr INTEGER(HID_T), OPTIONAL, INTENT(IN) :: vipl_id -!***** INTEGER(HID_T) :: vipl_id_default INTERFACE @@ -123,29 +125,20 @@ CONTAINS END SUBROUTINE H5VLregister_connector_by_value_f -! -!****s* H5VL/H5VLis_connector_registered_by_name_f -! -! NAME -! H5VLis_connector_registered_by_name_f -! -! PURPOSE -! Tests whether a VOL class has been registered or not -! according to a specified connector name. -! -! INPUTS -! name - Connector name -! OUTPUTS -! registered - state of VOL class registration -! hdferr - Returns 0 if successful and -1 if fails -! SOURCE - +!> +!! \ingroup FH5V +!! +!! \brief Determines whether a VOL class has been registered or not ccording to a specified connector name. +!! +!! \param name Connector name. +!! \param registered State of VOL class registration. +!! \param hdferr \fortran_error +!! SUBROUTINE H5VLis_connector_registered_by_name_f(name, registered, hdferr) IMPLICIT NONE CHARACTER(LEN=*), INTENT(IN) :: name LOGICAL, INTENT(OUT) :: registered INTEGER, INTENT(OUT) :: hdferr -!***** CHARACTER(LEN=LEN_TRIM(name)+1,KIND=C_CHAR) :: c_name INTEGER(C_INT) :: registered_c @@ -167,29 +160,20 @@ CONTAINS END SUBROUTINE H5VLis_connector_registered_by_name_f -! -!****s* H5VL/H5VLis_connector_registered_by_value_f -! -! NAME -! H5VLis_connector_registered_by_value_f -! -! PURPOSE -! Tests whether a VOL class has been registered or not -! according to a specified connector value (ID). -! -! INPUTS -! value - Connector value -! OUTPUTS -! registered - state of VOL class registration -! hdferr - Returns 0 if successful and -1 if fails -! SOURCE - +!> +!! \ingroup FH5V +!! +!! \brief Determines whether a VOL class has been registered or not according to a specified connector value (ID). +!! +!! \param value ConneConnector value. +!! \param registered State of VOL class registration. +!! \param hdferr Retu\fortran_error +!! SUBROUTINE H5VLis_connector_registered_by_value_f(value, registered, hdferr) IMPLICIT NONE INTEGER, INTENT(IN) :: value LOGICAL, INTENT(OUT) :: registered INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER(C_INT) :: registered_c INTERFACE @@ -208,28 +192,20 @@ CONTAINS END SUBROUTINE H5VLis_connector_registered_by_value_f -! -!****s* H5VL/H5VLget_connector_id_f -! -! NAME -! H5VLget_connector_id_f -! -! PURPOSE -! Retrieves the ID for a registered VOL connector. -! -! INPUTS -! obj_id - Object id -! OUTPUTS -! vol_id - Connector id -! hdferr - Returns 0 if successful and -1 if fails -! SOURCE - +!> +!! \ingroup FH5V +!! +!! \brief Retrieves the ID for a registered VOL connector. +!! +!! \param obj_id Object id. +!! \param vol_id Connector id. +!! \param hdferr \fortran_error +!! SUBROUTINE H5VLget_connector_id_f(obj_id, vol_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: obj_id INTEGER(HID_T), INTENT(OUT) :: vol_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER(HID_T) FUNCTION H5VLget_connector_id(obj_id) BIND(C,NAME='H5VLget_connector_id') @@ -247,28 +223,20 @@ CONTAINS END SUBROUTINE H5VLget_connector_id_f -! -!****s* H5VL/H5VLget_connector_id_by_name_f -! -! NAME -! H5VLget_connector_id_by_name_f -! -! PURPOSE -! Retrieves the ID for a registered VOL connector. -! -! INPUTS -! name - Connector name -! OUTPUTS -! vol_id - Connector id -! hdferr - Returns 0 if successful and -1 if fails -! SOURCE - +!> +!! \ingroup FH5V +!! +!! \brief Retrieves the ID for a registered VOL connector. +!! +!! \param name Connector name. +!! \param vol_id Connector id. +!! \param hdferr \fortran_error +!! SUBROUTINE H5VLget_connector_id_by_name_f(name, vol_id, hdferr) IMPLICIT NONE CHARACTER(LEN=*), INTENT(IN) :: name INTEGER(HID_T), INTENT(OUT) :: vol_id INTEGER, INTENT(OUT) :: hdferr -!***** CHARACTER(LEN=LEN_TRIM(name)+1,KIND=C_CHAR) :: c_name INTERFACE @@ -290,28 +258,20 @@ CONTAINS END SUBROUTINE H5VLget_connector_id_by_name_f -! -!****s* H5VL/H5VLget_connector_id_by_value_f -! -! NAME -! H5VLget_connector_id_by_value_f -! -! PURPOSE -! Retrieves the ID for a registered VOL connector. -! -! INPUTS -! value - Connector value -! OUTPUTS -! vol_id - Connector id -! hdferr - Returns 0 if successful and -1 if fails -! SOURCE - +!> +!! \ingroup FH5V +!! +!! \brief Retrieves the ID for a registered VOL connector. +!! +!! \param value CConnector value. +!! \param vol_id Connector id. +!! \param hdferr \fortran_error +!! SUBROUTINE H5VLget_connector_id_by_value_f(value, vol_id, hdferr) IMPLICIT NONE INTEGER, INTENT(IN) :: value INTEGER(HID_T), INTENT(OUT) :: vol_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER(HID_T) FUNCTION H5VLget_connector_id_by_value(value) BIND(C,NAME='H5VLget_connector_id_by_value') IMPORT :: C_INT @@ -329,14 +289,22 @@ CONTAINS ENDIF END SUBROUTINE H5VLget_connector_id_by_value_f - +!> +!! \ingroup FH5V +!! +!! \brief Retrieves a connector name for a VOL. +!! +!! \param obj_id Object identifier or file identifier. +!! \param name Connector name. +!! \param hdferr \fortran_error +!! \param name_len Maximum length of the name to retrieve. +!! SUBROUTINE H5VLget_connector_name_f(obj_id, name, hdferr, name_len) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: obj_id CHARACTER(LEN=*), INTENT(OUT) :: name INTEGER, INTENT(OUT) :: hdferr INTEGER(SIZE_T), OPTIONAL :: name_len -!***** CHARACTER(LEN=1,KIND=C_CHAR), DIMENSION(1:LEN(name)+1), TARGET :: c_name INTEGER(SIZE_T) :: l @@ -346,7 +314,6 @@ CONTAINS IMPLICIT NONE INTEGER(HID_T) , INTENT(IN), VALUE :: obj_id CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(OUT) :: name - ! TYPE(C_PTR), value :: name INTEGER(SIZE_T), INTENT(IN), VALUE :: size END FUNCTION H5VLget_connector_name END INTERFACE @@ -367,28 +334,18 @@ CONTAINS END SUBROUTINE H5VLget_connector_name_f -! -! -!****s* H5VL/H5VLclose_f -! -! NAME -! H5VLclose_f -! -! PURPOSE -! Closes a VOL connector ID. -! -! INPUTS -! vol_id - A valid identifier of the connectory to unregister. -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! SOURCE - +!> +!! \ingroup FH5V +!! +!! \brief Closes a VOL connector ID. +!! +!! \param vol_id A valid identifier of the connectory to unregister. +!! \param hdferr \fortran_error +!! SUBROUTINE H5VLclose_f(vol_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: vol_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION H5VLclose(vol_id) BIND(C, NAME='H5VLclose') @@ -401,27 +358,18 @@ CONTAINS END SUBROUTINE H5VLclose_f -! -!****s* H5VL/H5VLunregister_connector_f -! -! NAME -! H5VLunregister_connector_f -! -! PURPOSE -! Removes a VOL connector ID from the library. -! -! INPUTS -! plugin_id - A valid identifier of the connector to unregister. -! -! OUTPUTS -! hdferr - Returns 0 if successful and -1 if fails -! SOURCE - +!> +!! \ingroup FH5V +!! +!! \brief Removes a VOL connector ID from the library. +!! +!! \param plugin_id A valid identifier of the connector to unregister.. +!! \param hdferr Ret\fortran_error +!! SUBROUTINE H5VLunregister_connector_f(plugin_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: plugin_id INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION H5VLunregister_connector(plugin_id) BIND(C, NAME='H5VLunregister_connector') diff --git a/fortran/src/H5Zff.F90 b/fortran/src/H5Zff.F90 index 15f3c67..711e26b 100644 --- a/fortran/src/H5Zff.F90 +++ b/fortran/src/H5Zff.F90 @@ -1,10 +1,13 @@ -!****h* ROBODoc/H5Z -! -! NAME -! MODULE H5Z -! -! PURPOSE -! This file contains Fortran interfaces for H5Z functions. +!> @defgroup FH5Z Fortran Filter (H5Z) Interface +!! +!! @see H5Z, C-API +!! +!! @see @ref H5Z_UG, User Guide +!! + +!> @ingroup FH5Z +!! +!! @brief This module contains Fortran interfaces for H5Z functions. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -14,10 +17,10 @@ ! * ! This file is part of HDF5. The full HDF5 copyright notice, including * ! terms governing use, modification, and redistribution, is contained in * -! the COPYING file, which can be found at the root of the source code * -! distribution tree, or in https://www.hdfgroup.org/licenses. * -! If you do not have access to either file, you may request a copy from * -! help@hdfgroup.org. * +! the COPYING file, which can be found at the root of the source code * +! distribution tree, or in https://www.hdfgroup.org/licenses. * +! If you do not have access to either file, you may request a copy from * +! help@hdfgroup.org. * ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ! ! NOTES! @@ -32,7 +35,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** MODULE H5Z @@ -40,38 +42,24 @@ MODULE H5Z CONTAINS -!****s* H5Z/h5zunregister_f -! -! NAME -! h5zunregister_f -! -! PURPOSE -! Unregisters specified filetr -! -! INPUTS -! filter - Filter; may have one of the following values: -! H5Z_FILTER_DEFLATE_F -! H5Z_FILTER_SZIP_F -! H5Z_FILTER_NBIT_F -! H5Z_FILTER_SCALEOFFSET_F -! H5Z_FILTER_SHUFFLE_F -! H5Z_FILTER_FLETCHER32_F -! -! OUTPUTS -! hdferr - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! March 12, 2003 -! -! SOURCE +!> +!! \ingroup FH5Z +!! +!! \brief Unregisters specified filters. +!! +!! \param filter Filter; may have one of the following values: +!! \li H5Z_FILTER_DEFLATE_F +!! \li H5Z_FILTER_SZIP_F +!! \li H5Z_FILTER_NBIT_F +!! \li H5Z_FILTER_SCALEOFFSET_F +!! \li H5Z_FILTER_SHUFFLE_F +!! \li H5Z_FILTER_FLETCHER32_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5zunregister_f(filter, hdferr) IMPLICIT NONE INTEGER, INTENT(IN) :: filter INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5zunregister_c(filter) BIND(C,NAME='h5zunregister_c') INTEGER, INTENT(IN) :: filter @@ -80,39 +68,26 @@ CONTAINS hdferr = h5zunregister_c(filter) END SUBROUTINE h5zunregister_f -!****s* H5Z/h5zfilter_avail_f -! NAME -! h5zfilter_avail_f -! -! PURPOSE -! Queries if filter is available -! -! INPUTS -! filter - Filter; may be one of the following: -! H5Z_FILTER_DEFLATE_F -! H5Z_FILTER_SZIP_F -! H5Z_FILTER_NBIT_F -! H5Z_FILTER_SCALEOFFSET_F -! H5Z_FILTER_SHUFFLE_F -! H5Z_FILTER_FLETCHER32_F -! OUTPUTS -! status - Flag; .TRUE. if filter is available, -! .FALSE. otherwise -! hdferr: - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Elena Pourmal -! March 12, 2003 -! -! SOURCE +!> +!! \ingroup FH5Z +!! +!! \brief Queries if filter is available +!! +!! \param filter Filter; may be one of the following: +!! \li H5Z_FILTER_DEFLATE_F +!! \li H5Z_FILTER_SZIP_F +!! \li H5Z_FILTER_NBIT_F +!! \li H5Z_FILTER_SCALEOFFSET_F +!! \li H5Z_FILTER_SHUFFLE_F +!! \li H5Z_FILTER_FLETCHER32_F +!! \param status Flag; .TRUE. if filter is available, .FALSE. otherwise. +!! \param hdferr \fortran_error +!! SUBROUTINE h5zfilter_avail_f(filter, status, hdferr) IMPLICIT NONE INTEGER, INTENT(IN) :: filter LOGICAL, INTENT(OUT) :: status INTEGER, INTENT(OUT) :: hdferr -!***** INTEGER :: flag ! "TRUE/FALSE/ERROR from C" INTERFACE @@ -129,43 +104,28 @@ CONTAINS END SUBROUTINE h5zfilter_avail_f -!****s* H5Z/h5zget_filter_info_f -! -! NAME -! h5zget_filter_info_f -! -! PURPOSE -! Queries if filter has its encoder and/or decoder -! available -! -! INPUTS -! filter - Filter; may be one of the following: -! H5Z_FILTER_DEFLATE_F -! H5Z_FILTER_SZIP_F -! H5Z_FILTER_NBIT_F -! H5Z_FILTER_SCALEOFFSET_F -! H5Z_FILTER_SHUFFLE_F -! H5Z_FILTER_FLETCHER32_Ffilter -! OUTPUTS -! config_flags - Flag, indicates if filter has its encoder -! and/or decoder available, possibly containing the -! following values: -! H5Z_FILTER_ENCODE_ENABLED_F -! H5Z_FILTER_DECODE_ENABLED_F -! hdferr: - Error code -! Success: 0 -! Failure: -1 -! -! AUTHOR -! Nat Furrer and James Laird -! June 16, 2004 -! SOURCE +!> +!! \ingroup FH5Z +!! +!! \brief Queries if filter has its encoder and/or decoder available. +!! +!! \param filter Filter; may be one of the following: +!! \li H5Z_FILTER_DEFLATE_F +!! \li H5Z_FILTER_SZIP_F +!! \li H5Z_FILTER_NBIT_F +!! \li H5Z_FILTER_SCALEOFFSET_F +!! \li H5Z_FILTER_SHUFFLE_F +!! \li H5Z_FILTER_FLETCHER32_Ffilter +!! \param config_flags Flag, indicates if filter has its encoder and/or decoder available, possible values: +!! \li H5Z_FILTER_ENCODE_ENABLED_F +!! \li H5Z_FILTER_DECODE_ENABLED_F +!! \param hdferr \fortran_error +!! SUBROUTINE h5zget_filter_info_f(filter, config_flags, hdferr) IMPLICIT NONE INTEGER, INTENT(IN) :: filter INTEGER, INTENT(OUT) :: config_flags INTEGER, INTENT(OUT) :: hdferr -!***** INTERFACE INTEGER FUNCTION h5zget_filter_info_c(filter, config_flags) BIND(C,NAME='h5zget_filter_info_c') diff --git a/fortran/src/H5_buildiface.F90 b/fortran/src/H5_buildiface.F90 index 090b6db..30d29ba 100644 --- a/fortran/src/H5_buildiface.F90 +++ b/fortran/src/H5_buildiface.F90 @@ -423,7 +423,7 @@ PROGRAM H5_buildiface ! buf - Data buffer; may be a scalar or an array ! ! Outputs: -! hdferr - Returns 0 if successful and -1 if fails +! hdferr - \fortran_error ! ! AUTHOR ! Elena Pourmal @@ -550,7 +550,7 @@ PROGRAM H5_buildiface ! ! Outputs: ! buf - Data buffer; may be a scalar or an array -! hdferr - Returns 0 if successful and -1 if fails +! hdferr - \fortran_error ! ! AUTHOR ! Elena Pourmal diff --git a/fortran/src/H5_ff.F90 b/fortran/src/H5_ff.F90 index 84922c3..b51ad07 100644 --- a/fortran/src/H5_ff.F90 +++ b/fortran/src/H5_ff.F90 @@ -1,10 +1,13 @@ -!****h* ROBODoc/H5LIB -! -! NAME -! MODULE H5LIB -! -! PURPOSE -! This module provides fortran specific helper functions for the HDF library +!> @defgroup FH5 Fortran Library (H5) Interface +!! +!! @see H5, C-API +!! +!! @see @ref H5_UG, User Guide +!! + +!> @ingroup FH5 +!! +!! @brief This module provides fortran specific helper functions for the HDF library. ! ! COPYRIGHT ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -32,7 +35,6 @@ ! Windows dll file 'hdf5_fortrandll.def.in' in the fortran/src directory. ! This is needed for Windows based operating systems. ! -!***** #include @@ -145,36 +147,18 @@ MODULE H5LIB PUBLIC :: h5garbage_collect_f, h5check_version_f CONTAINS -!****s* H5LIB/h5open_f -! -! NAME -! h5open_f -! -! PURPOSE -! Initializes HDF5 Fortran interface. -! -! Outputs: -! error - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! Removed call to h5open_c since this may cause a problem for an -! application that uses HDF5 library outside HDF5 Fortran APIs. -! October 13, 2011 -! Fortran90 Interface: +!> +!! \ingroup FH5 +!! +!! \brief Initializes HDF5 Fortran interface. +!! +!! \param error \fortran_error +!! SUBROUTINE h5open_f(error) USE H5F, ONLY : h5fget_obj_count_f, H5OPEN_NUM_OBJ IMPLICIT NONE INTEGER, INTENT(OUT) :: error INTEGER(SIZE_T) :: H5OPEN_NUM_OBJ_LOC = 0 -!***** INTERFACE INTEGER FUNCTION h5init_types_c(p_types, f_types, i_types) & @@ -250,6 +234,9 @@ CONTAINS END INTERFACE + ! Check if H5open_f has already been called. If so, skip doing it again. + IF(H5OPEN_NUM_OBJ .NE. 0) RETURN + error = h5init_types_c(predef_types, floating_types, integer_types) H5T_NATIVE_INTEGER_KIND(1:5) = predef_types(1:5) @@ -642,34 +629,17 @@ CONTAINS END SUBROUTINE h5open_f -!****s* H5LIB/h5close_f -! -! NAME -! h5close_f -! -! PURPOSE -! Closes HDF5 Fortran interface. -! -! Outputs: -! error - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! August 12, 1999 -! -! HISTORY -! Explicit Fortran interfaces were added for -! called C functions (it is needed for Windows -! port). February 28, 2001 -! -! Removed call to h5close_c since this may cause a problem for an -! application that uses HDF5 library outside HDF5 Fortran APIs. -! October 13, 2011 -! Fortran90 Interface: +!> +!! \ingroup FH5 +!! +!! \brief Closes HDF5 Fortran interface. +!! +!! \param error \fortran_error +!! SUBROUTINE h5close_f(error) + USE H5F, ONLY : h5fget_obj_count_f, H5OPEN_NUM_OBJ IMPLICIT NONE INTEGER, INTENT(OUT) :: error -!***** INTERFACE INTEGER FUNCTION h5close_types_c(p_types, P_TYPES_LEN, & f_types, F_TYPES_LEN, & @@ -684,35 +654,32 @@ CONTAINS INTEGER(HID_T), DIMENSION(1:I_TYPES_LEN) :: i_types END FUNCTION h5close_types_c END INTERFACE + + ! Check if h5close_f has already been called. Skip doing it again. + IF(H5OPEN_NUM_OBJ .EQ. 0) RETURN + error = h5close_types_c(predef_types, PREDEF_TYPES_LEN, & floating_types, FLOATING_TYPES_LEN, & integer_types, INTEGER_TYPES_LEN ) + ! Reset the number of open objects from h5open_f to zero + CALL h5fget_obj_count_f(INT(H5F_OBJ_ALL_F,HID_T), H5F_OBJ_ALL_F, H5OPEN_NUM_OBJ, error) + END SUBROUTINE h5close_f -!****s* H5LIB/h5get_libversion_f -! -! NAME -! h5get_libversion_f -! -! PURPOSE -! Returns the HDF5 LIbrary release number -! -! Outputs: -! majnum - major version of the library -! minnum - minor version of the library -! relnum - release version of the library -! error - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! September 24, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5 +!! +!! \brief Returns the HDF5 LIbrary release number +!! +!! \param majnum Major version of the library. +!! \param minnum Minor version of the library. +!! \param relnum Release version of the library. +!! \param error \fortran_error +!! SUBROUTINE h5get_libversion_f(majnum, minnum, relnum, error) IMPLICIT NONE INTEGER, INTENT(OUT) :: majnum, minnum, relnum, error -!***** INTERFACE INTEGER FUNCTION h5get_libversion_c(majnum, minnum, relnum) & BIND(C,NAME='h5get_libversion_c') @@ -725,32 +692,20 @@ CONTAINS END SUBROUTINE h5get_libversion_f -!****s* H5LIB/h5check_version_f -! -! NAME -! h5check_version_f -! -! PURPOSE -! Verifies that library versions are consistent. -! -! Inputs: -! majnum - major version of the library -! minnum - minor version of the library -! relnum - release version of the library -! -! Outputs: -! error - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! September 24, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5 +!! +!! \brief Verifies that library versions are consistent. +!! +!! \param majnum Major version of the library. +!! \param minnum Minor version of the library. +!! \param relnum Release version of the library. +!! \param error \fortran_error +!! SUBROUTINE h5check_version_f(majnum, minnum, relnum, error) IMPLICIT NONE INTEGER, INTENT(IN) :: majnum, minnum, relnum INTEGER, INTENT(OUT) :: error -!***** INTERFACE INTEGER FUNCTION h5check_version_c(majnum, minnum, relnum) & BIND(C,NAME='h5check_version_c') @@ -762,58 +717,38 @@ CONTAINS error = h5check_version_c(majnum, minnum, relnum) END SUBROUTINE h5check_version_f -!****s* H5LIB/h5garbage_collect_f -! -! NAME -! h5garbage_collect_f -! -! PURPOSE -! Garbage collects on all free-lists of all types. -! -! Outputs: -! error - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! September 24, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5 +!! +!! \brief Garbage collects on all free-lists of all types. +!! +!! \param error \fortran_error +!! SUBROUTINE h5garbage_collect_f(error) IMPLICIT NONE INTEGER, INTENT(OUT) :: error -!***** INTERFACE - INTEGER FUNCTION h5garbage_collect_c() & - BIND(C,NAME='h5garbage_collect_c') + INTEGER FUNCTION h5garbage_collect_c() BIND(C,NAME='h5garbage_collect_c') + IMPLICIT NONE END FUNCTION h5garbage_collect_c END INTERFACE error = h5garbage_collect_c() END SUBROUTINE h5garbage_collect_f -!****s* H5LIB/h5dont_atexit_f -! -! NAME -! h5dont_atexit_f -! -! PURPOSE -! Instructs library not to install atexit cleanup routine. -! -! Outputs: -! error - Returns 0 if successful and -1 if fails -! -! AUTHOR -! Elena Pourmal -! September 24, 2002 -! -! Fortran90 Interface: +!> +!! \ingroup FH5 +!! +!! \brief Instructs library not to install atexit cleanup routine. +!! +!! \param error \fortran_error +!! SUBROUTINE h5dont_atexit_f(error) IMPLICIT NONE INTEGER, INTENT(OUT) :: error -!***** INTERFACE - INTEGER FUNCTION h5dont_atexit_c() & - BIND(C,NAME='h5dont_atexit_c') + INTEGER FUNCTION h5dont_atexit_c() BIND(C,NAME='h5dont_atexit_c') + IMPLICIT NONE END FUNCTION h5dont_atexit_c END INTERFACE @@ -821,34 +756,23 @@ CONTAINS END SUBROUTINE h5dont_atexit_f -!****f* H5LIB/h5kind_to_type -! -! NAME -! h5kind_to_type -! -! PURPOSE -! Converts the KIND to the correct HDF type -! -! Inputs: -! kind - Fortran KIND parameter -! flag - Whether KIND is of type INTEGER or REAL: -! H5_INTEGER_KIND - integer -! H5_REAL_KIND - real -! Outputs: -! h5_type - Returns the type -! -! AUTHOR -! M. Scot Breitenfeld -! August 25, 2008 -! -! Fortran90 Interface: +!> +!! \ingroup FH5 +!! +!! \brief Converts the KIND to the correct HDF type +!! +!! \param ikind Fortran KIND parameter +!! \param flag Whether KIND is of type INTEGER or REAL: +!! \li H5_INTEGER_KIND - integer +!! \li H5_REAL_KIND - real +!! \result h5_type Returns the type. +!! INTEGER(HID_T) FUNCTION h5kind_to_type(ikind, flag) RESULT(h5_type) USE ISO_C_BINDING IMPLICIT NONE INTEGER, INTENT(IN) :: ikind INTEGER, INTENT(IN) :: flag INTEGER :: i -!***** !#if H5_HAVE_Fortran_INTEGER_SIZEOF_16!=0 ! ! (1) The array index assumes INTEGER*16 the last integer in the series, and @@ -884,34 +808,20 @@ CONTAINS END FUNCTION h5kind_to_type -!****f* H5LIB_PROVISIONAL/h5offsetof -! -! NAME -! h5offsetof -! -! PURPOSE -! Computes the offset in memory -! -! Inputs: -! start - starting pointer address -! end - ending pointer address -! -! Outputs: -! offset - offset of a member within the derived type -! -! AUTHOR -! M. Scot Breitenfeld -! August 25, 2008 -! -! ACKNOWLEDGEMENTS -! Joe Krahn -! -! Fortran2003 Interface: +!> +!! \ingroup FH5 +!! +!! \brief Computes the offset in memory +!! +!! \param start Starting pointer address +!! \param end Ending pointer address +!! +!! \result offset Offset of a member within the derived type. +!! FUNCTION h5offsetof(start,end) RESULT(offset) IMPLICIT NONE INTEGER(SIZE_T) :: offset TYPE(C_PTR), VALUE, INTENT(IN) :: start, end -!***** INTEGER(C_INTPTR_T) :: int_address_start, int_address_end int_address_start = TRANSFER(start, int_address_start) int_address_end = TRANSFER(end , int_address_end ) @@ -920,38 +830,26 @@ CONTAINS END FUNCTION h5offsetof -!****f* H5LIB_PROVISIONAL/h5gmtime -! -! NAME -! h5gmtime -! -! PURPOSE -! Convert time_t structure (C) to Fortran DATE AND TIME storage format. -! -! Inputs: -! stdtime_t - Object of type time_t that contains a time value -! -! Outputs: -! datetime - A date/time array using Fortran conventions: -! datetime(1) = year -! datetime(2) = month -! datetime(3) = day -! datetime(4) = 0 ! time is expressed as UTC (or GMT timezone) */ -! datetime(5) = hour -! datetime(6) = minute -! datetime(7) = second -! datetime(8) = millisecond -- not available, assigned - HUGE(0) -! -! AUTHOR -! M. Scot Breitenfeld -! January, 2019 -! -! Fortran Interface: - FUNCTION h5gmtime(stdtime_t) +!> +!! \ingroup FH5 +!! +!! \brief Convert time_t structure (C) to Fortran DATE AND TIME storage format. +!! +!! \param stdtime_t Object of type time_t that contains a time value +!! \result datetime A date/time array using Fortran conventions: +!! \li datetime(1) = year +!! \li datetime(2) = month +!! \li datetime(3) = day +!! \li datetime(4) = 0 ! time is expressed as UTC (or GMT timezone) +!! \li datetime(5) = hour +!! \li datetime(6) = minute +!! \li datetime(7) = second +!! \li datetime(8) = millisecond -- not available, assigned - HUGE(0) +!! + FUNCTION h5gmtime(stdtime_t) RESULT(datetime) IMPLICIT NONE INTEGER(KIND=TIME_T), INTENT(IN) :: stdtime_t - INTEGER, DIMENSION(1:8) :: h5gmtime -!***** + INTEGER, DIMENSION(1:8) :: datetime TYPE(C_PTR) :: cptr INTEGER(C_INT), DIMENSION(:), POINTER :: c_time @@ -967,14 +865,14 @@ CONTAINS cptr = gmtime(stdtime_t) CALL C_F_POINTER(cptr, c_time, [9]) - h5gmtime(1) = INT(c_time(6)+1900) ! year starts at 1900 - h5gmtime(2) = INT(c_time(5)+1) ! month starts at 0 in C - h5gmtime(3) = INT(c_time(4)) ! day - h5gmtime(4) = 0 ! time is expressed as UTC (or GMT timezone) - h5gmtime(5) = INT(c_time(3)) ! hour - h5gmtime(6) = INT(c_time(2)) ! minute - h5gmtime(7) = INT(c_time(1)) ! second - h5gmtime(8) = -32767 ! millisecond is not available, assign it -HUGE(0) + datetime(1) = INT(c_time(6)+1900) ! year starts at 1900 + datetime(2) = INT(c_time(5)+1) ! month starts at 0 in C + datetime(3) = INT(c_time(4)) ! day + datetime(4) = 0 ! time is expressed as UTC (or GMT timezone) + datetime(5) = INT(c_time(3)) ! hour + datetime(6) = INT(c_time(2)) ! minute + datetime(7) = INT(c_time(1)) ! second + datetime(8) = -32767 ! millisecond is not available, assign it -HUGE(0) END FUNCTION h5gmtime diff --git a/hl/fortran/src/H5DSff.F90 b/hl/fortran/src/H5DSff.F90 index bbd9918..dcc6ed0 100644 --- a/hl/fortran/src/H5DSff.F90 +++ b/hl/fortran/src/H5DSff.F90 @@ -1,3 +1,14 @@ +!> @defgroup FH5DS Fortran High Level Dimension Scales (H5DS) Interface +!! +!! @see H5DS, C-HL API +!! +!! @see @ref H5DS_UG, User Guide +!! + +!> @ingroup FH5DS +!! +!! @brief This module contains Fortran interfaces for H5DS +! ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ! Copyright by The HDF Group. * ! Copyright by the Board of Trustees of the University of Illinois. * @@ -10,12 +21,19 @@ ! If you do not have access to either file, you may request a copy from * ! help@hdfgroup.org. * ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +! _____ __ __ _____ ____ _____ _______ _ _ _______ +! |_ _| \/ | __ \ / __ \| __ \__ __|/\ | \ | |__ __| +! **** | | | \ / | |__) | | | | |__) | | | / \ | \| | | | **** +! **** | | | |\/| | ___/| | | | _ / | | / /\ \ | . ` | | | **** +! **** _| |_| | | | | | |__| | | \ \ | |/ ____ \| |\ | | | **** +! |_____|_| |_|_| \____/|_| \_\ |_/_/ \_\_| \_| |_| ! -! -! This file contains FORTRAN90 interfaces for H5DS functions +! If you add a new function here then you MUST add the function name to the +! Windows dll file 'hdf5_hl_fortrandll.def.in' in the hl/fortran/src directory. +! This is needed for Windows based operating systems. ! -MODULE h5ds +MODULE H5DS USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR, C_CHAR, C_FLOAT, C_DOUBLE, C_LOC, C_CHAR USE h5fortran_types @@ -23,32 +41,24 @@ MODULE h5ds CONTAINS -!------------------------------------------------------------------------- -! Function: H5DSset_scale_f -! -! Purpose: Convert dataset dsid to a dimension scale, with optional name, dimname. -! -! Return: Success: 0, Failure: -1 -! -! Programmer: M. Scot Breitenfeld -! -! Date: April 17, 2011 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5DS +!! +!! \brief Convert dataset \p dsid to a dimension scale, with optional name, \p dimname. +!! +!! \param dsid The dataset to be made a Dimemsion Scale. +!! \param errcode \fortran_error +!! \param dimname The dimension name +!! SUBROUTINE H5DSset_scale_f( dsid, errcode, dimname) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: dsid ! The dataset to be made a Dimension Scale - CHARACTER(LEN=*), INTENT(in), OPTIONAL :: dimname ! The dimension name - INTEGER :: errcode ! Error code + INTEGER(hid_t), INTENT(in) :: dsid + CHARACTER(LEN=*), INTENT(in), OPTIONAL :: dimname + INTEGER :: errcode - INTEGER(SIZE_T) :: dimname_len ! length of dimname (if present) + INTEGER(SIZE_T) :: dimname_len ! length of dimname (if present) INTERFACE INTEGER FUNCTION H5DSset_scale_c(dsid, dimname, dimname_len) & @@ -56,8 +66,8 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: dsid ! The dataset to be made a Dimension Scale - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dimname ! The dimension name + INTEGER(hid_t), INTENT(in) :: dsid + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dimname INTEGER(SIZE_T), INTENT(in) :: dimname_len END FUNCTION H5DSset_scale_c END INTERFACE @@ -71,31 +81,24 @@ CONTAINS END SUBROUTINE H5DSset_scale_f -!------------------------------------------------------------------------- -! Function: H5DSattach_scale_f -! -! Purpose: Attach dimension scale dsid to dimension idx of dataset did. -! -! Return: Success: 0, Failure: -1 -! -! Programmer: M. Scot Breitenfeld -! -! Date: April 17, 2011 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5DS +!! +!! \brief Attach dimension scale dsid to dimension \p idx of dataset \p did. +!! +!! \param did The dataset. +!! \param dsid The scale to be attached. +!! \param idx The dimension of \p did that \p dsid is associated with. +!! \param errcode \fortran_error +!! SUBROUTINE H5DSattach_scale_f( did, dsid, idx, errcode) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! the dataset - INTEGER(hid_t), INTENT(in) :: dsid ! the scale to be attached - INTEGER , INTENT(in) :: idx ! the dimension of did that dsid is associated with. - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: did + INTEGER(hid_t), INTENT(in) :: dsid + INTEGER , INTENT(in) :: idx + INTEGER :: errcode INTEGER :: c_idx INTERFACE @@ -103,9 +106,9 @@ CONTAINS BIND(C,NAME='h5dsattach_scale_c') IMPORT :: HID_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! the dataset - INTEGER(hid_t), INTENT(in) :: dsid ! the scale to be attached - INTEGER , INTENT(in) :: idx ! the dimension of did that dsid is associated with. + INTEGER(hid_t), INTENT(in) :: did + INTEGER(hid_t), INTENT(in) :: dsid + INTEGER , INTENT(in) :: idx END FUNCTION H5DSattach_scale_c END INTERFACE @@ -115,31 +118,25 @@ CONTAINS END SUBROUTINE H5DSattach_scale_f -!------------------------------------------------------------------------- -! Function: H5DSdetach_scale_f -! -! Purpose: Detach dimension scale dsid from the dimension idx of Dataset did. -! -! Return: Success: 0, Failure: -1 -! -! Programmer: M. Scot Breitenfeld -! -! Date: April 17, 2011 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- +!> +!! \ingroup FH5DS +!! +!! \brief Detach dimension scale dsid from the dimension idx of dataset \p did. +!! +!! \param did The dataset. +!! \param dsid The scale to be detached. +!! \param idx The dimension of \p did to detach. +!! \param errcode \fortran_error +!! SUBROUTINE H5DSdetach_scale_f( did, dsid, idx, errcode) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! the dataset - INTEGER(hid_t), INTENT(in) :: dsid ! the scale to be detached - INTEGER , INTENT(in) :: idx ! the dimension of did to detach - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: did + INTEGER(hid_t), INTENT(in) :: dsid + INTEGER , INTENT(in) :: idx + INTEGER :: errcode INTEGER :: c_idx INTERFACE @@ -147,9 +144,9 @@ CONTAINS BIND(C,NAME='h5dsdetach_scale_c') IMPORT :: HID_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! the dataset - INTEGER(hid_t), INTENT(in) :: dsid ! the scale to be detached - INTEGER , INTENT(in) :: idx ! the dimension of did to detach + INTEGER(hid_t), INTENT(in) :: did + INTEGER(hid_t), INTENT(in) :: dsid + INTEGER , INTENT(in) :: idx END FUNCTION H5DSdetach_scale_c END INTERFACE @@ -159,34 +156,26 @@ CONTAINS END SUBROUTINE H5DSdetach_scale_f - -!------------------------------------------------------------------------- -! Function: H5DSis_attached_f -! -! Purpose: Report if dimension scale dsid is currently attached to dimension idx of dataset did. -! -! Return: Success: 0, Failure: -1 -! -! Programmer: M. Scot Breitenfeld -! -! Date: April 17, 2011 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5DS +!! +!! \brief Report if dimension scale dsid is currently attached to dimension idx of dataset did. +!! +!! \param did The dataset. +!! \param dsid The scale to be attached. +!! \param idx The dimension of \p did that \p dsid is associated with. +!! \param is_attached If dimension scale \p dsid is currently attached to dimension \p idx of dataset \p did. +!! \param errcode \fortran_error +!! SUBROUTINE H5DSis_attached_f( did, dsid, idx, is_attached, errcode) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! the dataset - INTEGER(hid_t), INTENT(in) :: dsid ! the scale to be attached - INTEGER , INTENT(in) :: idx ! the dimension of did that dsid is associated with - LOGICAL , INTENT(out) :: is_attached ! logical: dimension scale dsid is currently attached to - ! dimension idx of dataset did - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: did + INTEGER(hid_t), INTENT(in) :: dsid + INTEGER , INTENT(in) :: idx + LOGICAL , INTENT(out) :: is_attached + INTEGER :: errcode INTEGER :: c_is_attached INTEGER :: c_idx @@ -195,10 +184,10 @@ CONTAINS BIND(C,NAME='h5dsis_attached_c') IMPORT :: HID_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! the dataset - INTEGER(hid_t), INTENT(in) :: dsid ! the scale to be detached - INTEGER , INTENT(in) :: idx ! the dimension of did to detach - INTEGER , INTENT(out) :: c_is_attached ! dimension scale dsid is currently attached to + INTEGER(hid_t), INTENT(in) :: did + INTEGER(hid_t), INTENT(in) :: dsid + INTEGER , INTENT(in) :: idx + INTEGER , INTENT(out) :: c_is_attached END FUNCTION H5DSis_attached_c END INTERFACE @@ -218,32 +207,22 @@ CONTAINS ! ! H5DSiterate_scales: Implement in F2003 ! - -!------------------------------------------------------------------------- -! Function: H5DSis_scale_f -! -! Purpose: Determines whether dset is a Dimension Scale. -! -! Return: Success: 0, Failure: -1 -! -! Programmer: M. Scot Breitenfeld -! -! Date: April 18, 2011 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5DS +!! +!! \brief Determines whether \p did is a Dimension Scale. +!! +!! \param did The data set to query. +!! \param is_scale If is a Dimension Scale. +!! \param errcode \fortran_error +!! SUBROUTINE H5DSis_scale_f( did, is_scale, errcode) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! the data set to query - LOGICAL , INTENT(out) :: is_scale ! logical: - ! .TRUE. if did is a Dimension Scale - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: did + LOGICAL , INTENT(out) :: is_scale + INTEGER , INTENT(out) :: errcode INTEGER :: c_is_scale INTERFACE @@ -267,30 +246,23 @@ CONTAINS END SUBROUTINE H5DSis_scale_f -!------------------------------------------------------------------------- -! Function: H5DSset_label_f -! -! Purpose: Set label for the dimension idx of did to the value label -! -! Return: Success: 0, Failure: -1 -! -! Programmer: M. Scot Breitenfeld -! -! Date: April 18, 2011 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5DS +!! +!! \brief Set label for the dimension \p idx of \p did to the value \p label. +!! +!! \param did The data set. +!! \param idx The dimension. +!! \param label The label. +!! \param errcode \fortran_error +!! SUBROUTINE H5DSset_label_f( did, idx, label, errcode) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! The dataset - INTEGER , INTENT(in) :: idx ! The dimension - CHARACTER(LEN=*), INTENT(in) :: label ! The label + INTEGER(hid_t), INTENT(in) :: did + INTEGER , INTENT(in) :: idx + CHARACTER(LEN=*), INTENT(in) :: label INTEGER :: errcode ! Error code INTEGER(SIZE_T) :: label_len ! Length of label @@ -302,10 +274,10 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! The dataset - INTEGER , INTENT(in) :: idx ! The dimension - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: label ! The label - INTEGER(SIZE_T), INTENT(in) :: label_len ! Length of label + INTEGER(hid_t), INTENT(in) :: did + INTEGER , INTENT(in) :: idx + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: label + INTEGER(SIZE_T), INTENT(in) :: label_len END FUNCTION H5DSset_label_c END INTERFACE @@ -316,32 +288,26 @@ CONTAINS END SUBROUTINE H5DSset_label_f -!------------------------------------------------------------------------- -! Function: H5DSget_label_f -! -! Purpose: Read the label for dimension idx of did into buffer label. -! -! Return: Success: 0, Failure: -1 -! -! Programmer: M. Scot Breitenfeld -! -! Date: April 18, 2011 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5DS +!! +!! \brief Read the \p label for dimension \p idx of \p did into buffer \p label. +!! +!! \param did The dataset. +!! \param idx The dimension. +!! \param label The label. +!! \param size The length of the \p label buffer. +!! \param errcode \fortran_error +!! SUBROUTINE H5DSget_label_f( did, idx, label, size, errcode) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! The dataget - INTEGER , INTENT(in) :: idx ! The dimension - CHARACTER(LEN=*), INTENT(INOUT) :: label ! The label - INTEGER(size_t) , INTENT(INOUT) :: size ! The length of the label buffer - INTEGER :: errcode ! Error code + INTEGER(hid_t), INTENT(in) :: did + INTEGER , INTENT(in) :: idx + CHARACTER(LEN=*), INTENT(INOUT) :: label + INTEGER(size_t) , INTENT(INOUT) :: size + INTEGER :: errcode INTEGER :: c_idx INTERFACE @@ -350,10 +316,10 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! The dataget - INTEGER , INTENT(in) :: idx ! The dimension - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(INOUT) :: label ! The label - INTEGER(SIZE_T), INTENT(inout) :: size ! Length of label + INTEGER(hid_t), INTENT(in) :: did + INTEGER , INTENT(in) :: idx + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(INOUT) :: label + INTEGER(SIZE_T), INTENT(inout) :: size END FUNCTION H5DSget_label_c END INTERFACE @@ -363,32 +329,24 @@ CONTAINS END SUBROUTINE H5DSget_label_f - -!------------------------------------------------------------------------- -! Function: H5DSget_scale_name_f -! -! Purpose: Read the name of scale did into buffer name. -! -! Return: Success: 0, Failure: -1 -! -! Programmer: M. Scot Breitenfeld -! -! Date: April 18, 2011 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5DS +!! +!! \brief Read the name of scale \p did into buffer name. +!! +!! \param did Dimension scale identifier. +!! \param name Buffer to contain the returned name. +!! \param size Size in bytes, of the name buffer. +!! \param errcode \fortran_error +!! SUBROUTINE H5DSget_scale_name_f(did, name, size, errcode) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! The dataget - CHARACTER(LEN=*), INTENT(INOUT) :: name ! The name - INTEGER(size_t) , INTENT(INOUT) :: size ! The length of the name buffer - INTEGER :: errcode ! Error code + INTEGER(hid_t), INTENT(in) :: did + CHARACTER(LEN=*), INTENT(INOUT) :: name + INTEGER(size_t) , INTENT(INOUT) :: size + INTEGER :: errcode INTERFACE INTEGER FUNCTION H5DSget_scale_name_c(did, name, size) & @@ -396,9 +354,9 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! The dataget - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(INOUT) :: name ! The name - INTEGER(SIZE_T), INTENT(inout) :: size ! Length of name + INTEGER(hid_t), INTENT(in) :: did + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(INOUT) :: name + INTEGER(SIZE_T), INTENT(inout) :: size END FUNCTION H5DSget_scale_name_c END INTERFACE @@ -406,30 +364,23 @@ CONTAINS END SUBROUTINE H5DSget_scale_name_f -!------------------------------------------------------------------------- -! Function: H5DSget_num_scales_f -! -! Purpose: Determines how many Dimension Scales are attached to dimension idx of did -! -! Return: Success: 0, Failure: -1 -! -! Programmer: M. Scot Breitenfeld -! -! Date: April 18, 2011 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5DS +!! +!! \brief Determines how many Dimension Scales are attached to dimension idx of \p did. +!! +!! \param did The dataset to query. +!! \param idx The dimension of \p did to query. +!! \param num_scales Number of Dimension Scales associated with \p did. +!! \param errcode \fortran_error +!! SUBROUTINE H5DSget_num_scales_f( did, idx, num_scales, errcode) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! the dataset - INTEGER , INTENT(in) :: idx ! the dimension of did to query - INTEGER , INTENT(INOUT) :: num_scales ! the number of Dimension Scales associated with did - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: did + INTEGER , INTENT(in) :: idx + INTEGER , INTENT(INOUT) :: num_scales + INTEGER :: errcode INTEGER :: c_idx INTERFACE @@ -437,9 +388,9 @@ CONTAINS BIND(C,NAME='h5dsget_num_scales_c') IMPORT :: HID_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: did ! the dataset - INTEGER , INTENT(in) :: idx ! the dimension of did to query - INTEGER , INTENT(INOUT) :: num_scales ! the number of Dimension Scales associated with did + INTEGER(hid_t), INTENT(in) :: did + INTEGER , INTENT(in) :: idx + INTEGER , INTENT(INOUT) :: num_scales END FUNCTION H5DSget_num_scales_c END INTERFACE diff --git a/hl/fortran/src/H5IMff.F90 b/hl/fortran/src/H5IMff.F90 index 9709032..967c35d 100644 --- a/hl/fortran/src/H5IMff.F90 +++ b/hl/fortran/src/H5IMff.F90 @@ -1,3 +1,14 @@ +!> @defgroup FH5IM Fortran High Level Images (H5IM) Interface +!! +!! @see H5IM, C-HL API +!! +!! @see @ref H5IM_UG, User Guide +!! + +!> @ingroup FH5IM +!! +!! @brief This module contains Fortran interfaces for H5IM. +! ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ! Copyright by The HDF Group. * ! Copyright by the Board of Trustees of the University of Illinois. * @@ -10,12 +21,6 @@ ! If you do not have access to either file, you may request a copy from * ! help@hdfgroup.org. * ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * -! -! -! This file contains FORTRAN interfaces for H5IM functions -! -! NOTES -! ! _____ __ __ _____ ____ _____ _______ _ _ _______ ! |_ _| \/ | __ \ / __ \| __ \__ __|/\ | \ | |__ __| ! **** | | | \ / | |__) | | | | |__) | | | / \ | \| | | | **** @@ -28,29 +33,24 @@ ! This is needed for Windows based operating systems. ! -MODULE h5im +MODULE H5IM USE, INTRINSIC :: ISO_C_BINDING USE h5fortran_types USE hdf5 CONTAINS -!------------------------------------------------------------------------- -! Function: h5immake_image_8bit_f -! -! Purpose: Creates and writes an image an 8 bit image -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 05, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5IM +!! +!! \brief Creates and writes an image an 8 bit image +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to create. +!! \param width The width of the image. +!! \param height The height of the image +!! \param buf Buffer with data to be written to the dataset +!! \param errcode \fortran_error +!! SUBROUTINE h5immake_image_8bit_f(loc_id,& dset_name,& width,& @@ -60,13 +60,13 @@ CONTAINS IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in) :: width ! width of image - INTEGER(hsize_t), INTENT(in) :: height ! height of image - INTEGER, INTENT(in), DIMENSION(*) :: buf ! buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(in) :: width + INTEGER(hsize_t), INTENT(in) :: height + INTEGER, INTENT(in), DIMENSION(*) :: buf + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTERFACE INTEGER FUNCTION h5immake_image_8bit_c(loc_id,namelen,dset_name,width,height,buf) & @@ -74,12 +74,12 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in) :: width ! width of image - INTEGER(hsize_t), INTENT(in) :: height ! height of image - INTEGER , INTENT(in), DIMENSION(*) :: buf ! buffer + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(in) :: width + INTEGER(hsize_t), INTENT(in) :: height + INTEGER , INTENT(in), DIMENSION(*) :: buf END FUNCTION h5immake_image_8bit_c END INTERFACE @@ -88,22 +88,16 @@ CONTAINS END SUBROUTINE h5immake_image_8bit_f -!------------------------------------------------------------------------- -! Function: h5imread_image_f -! -! Purpose: Reads image data from disk. -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 05, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- +!> +!! \ingroup FH5IM +!! +!! \brief Reads image data from disk. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to create. +!! \param buf Buffer with data to store the image. +!! \param errcode \fortran_error +!! SUBROUTINE h5imread_image_f(loc_id,& dset_name,& buf,& @@ -111,11 +105,11 @@ CONTAINS IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(inout), DIMENSION(*) :: buf ! buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: dset_name + INTEGER, INTENT(inout), DIMENSION(*) :: buf + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTERFACE INTEGER FUNCTION h5imread_image_c(loc_id,namelen,dset_name,buf) & @@ -123,10 +117,10 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(inout), DIMENSION(*) :: buf ! buffer + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + INTEGER, INTENT(inout), DIMENSION(*) :: buf END FUNCTION h5imread_image_c END INTERFACE @@ -135,42 +129,32 @@ CONTAINS END SUBROUTINE h5imread_image_f -!------------------------------------------------------------------------- -! Function: h5immake_image_24bit_f -! -! Purpose: Creates and writes an image a 24 bit image -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 05, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - - SUBROUTINE h5immake_image_24bit_f(loc_id,& - dset_name,& - width,& - height,& - il,& - buf,& - errcode ) +!> +!! \ingroup FH5IM +!! +!! \brief Creates and writes an image a 24 bit image. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to create. +!! \param width The width of the image. +!! \param height The height of the image. +!! \param il String defining the interlace mode. +!! \param buf Buffer with data to be written to the dataset. +!! \param errcode \fortran_error +!! + SUBROUTINE h5immake_image_24bit_f(loc_id, dset_name, width, height, il, buf, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in) :: width ! width of image - INTEGER(hsize_t), INTENT(in) :: height ! height of image - CHARACTER(len=*), INTENT(in) :: il ! interlace - INTEGER, INTENT(in), DIMENSION(*) :: buf ! buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: ILEN ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(in) :: width + INTEGER(hsize_t), INTENT(in) :: height + CHARACTER(len=*), INTENT(in) :: il + INTEGER, INTENT(in), DIMENSION(*) :: buf + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: ILEN ! name length INTERFACE INTEGER FUNCTION h5immake_image_24bit_c(loc_id,namelen,dset_name,ILEN,il,width,height,buf) & @@ -178,14 +162,14 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in) :: width ! width of image - INTEGER(hsize_t), INTENT(in) :: height ! height of image - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: il ! interlace - INTEGER, INTENT(in), DIMENSION(*) :: buf ! buffer - INTEGER(size_t) :: namelen ! length of name buffer - INTEGER(size_t) :: ILEN ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(in) :: width + INTEGER(hsize_t), INTENT(in) :: height + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: il + INTEGER, INTENT(in), DIMENSION(*) :: buf + INTEGER(size_t) :: namelen + INTEGER(size_t) :: ILEN END FUNCTION h5immake_image_24bit_c END INTERFACE @@ -196,24 +180,20 @@ CONTAINS END SUBROUTINE h5immake_image_24bit_f -!------------------------------------------------------------------------- -! Function: h5imget_image_info_f -! -! Purpose: Gets information about an image dataset (dimensions, interlace mode -! and number of associated palettes). -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 05, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5IM +!! +!! \brief Gets information about an image dataset (dimensions, interlace mode and number of associated palettes). +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset. +!! \param width The width of the image. +!! \param height The height of the image. +!! \param planes The number of color planes of the image. +!! \param interlace The interlace mode of the image. +!! \param npals The number of palettes associated to the image. +!! \param errcode \fortran_error +!! SUBROUTINE h5imget_image_info_f(loc_id,& dset_name,& width,& @@ -225,16 +205,16 @@ CONTAINS IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(inout) :: width ! width of image - INTEGER(hsize_t), INTENT(inout) :: height ! height of image - INTEGER(hsize_t), INTENT(inout) :: planes ! color planes - INTEGER(hsize_t), INTENT(inout) :: npals ! palettes - CHARACTER(len=*), INTENT(inout) :: interlace ! interlace - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: ILEN ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(inout) :: width + INTEGER(hsize_t), INTENT(inout) :: height + INTEGER(hsize_t), INTENT(inout) :: planes + INTEGER(hsize_t), INTENT(inout) :: npals + CHARACTER(len=*), INTENT(inout) :: interlace + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: ILEN ! name length INTERFACE INTEGER FUNCTION h5imget_image_info_c(loc_id,namelen,dset_name,width,height,planes,npals,ILEN,interlace) & @@ -242,15 +222,15 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(inout) :: width ! width of image - INTEGER(hsize_t), INTENT(inout) :: height ! height of image - INTEGER(hsize_t), INTENT(inout) :: planes ! color planes - INTEGER(hsize_t), INTENT(inout) :: npals ! palettes - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(inout) :: interlace ! interlace - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: ILEN ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(inout) :: width + INTEGER(hsize_t), INTENT(inout) :: height + INTEGER(hsize_t), INTENT(inout) :: planes + INTEGER(hsize_t), INTENT(inout) :: npals + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(inout) :: interlace + INTEGER(size_t) :: namelen + INTEGER(size_t) :: ILEN END FUNCTION h5imget_image_info_c END INTERFACE @@ -260,32 +240,22 @@ CONTAINS END SUBROUTINE h5imget_image_info_f -!------------------------------------------------------------------------- -! Function: h5imis_image_f -! -! Purpose: Inquires if a dataset is an image -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 05, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - - INTEGER FUNCTION h5imis_image_f(loc_id,& - dset_name) +!> +!! \ingroup FH5IM +!! +!! \brief Inquires if a dataset is an image. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset. +!! + INTEGER FUNCTION h5imis_image_f(loc_id, dset_name) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: dset_name + INTEGER :: errcode ! error code + INTEGER(size_t) :: namelen ! name length INTERFACE INTEGER FUNCTION h5imis_image_c(loc_id,namelen,dset_name) & @@ -293,9 +263,9 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name END FUNCTION h5imis_image_c END INTERFACE @@ -305,339 +275,285 @@ CONTAINS END FUNCTION h5imis_image_f - -!------------------------------------------------------------------------- -! Function: h5immake_palette_f -! -! Purpose: Creates and writes a palette -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 06, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5IM +!! +!! \brief Creates and writes a palette +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param pal_name The name of the palette. +!! \param pal_dims An array of the size of the palette dimensions. +!! \param pal_data Buffer with data to be written to the dataset. +!! \param errcode \fortran_error +!! SUBROUTINE h5immake_palette_f(loc_id,& - dset_name,& + pal_name,& pal_dims,& - buf,& + pal_data,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in), DIMENSION(*) :: pal_dims ! dimensions - INTEGER, INTENT(in), DIMENSION(*) :: buf ! buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: pal_name + INTEGER(hsize_t), INTENT(in), DIMENSION(*) :: pal_dims + INTEGER, INTENT(in), DIMENSION(*) :: pal_data + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTERFACE - INTEGER FUNCTION h5immake_palette_c(loc_id,namelen,dset_name,pal_dims,buf) & + INTEGER FUNCTION h5immake_palette_c(loc_id,namelen,pal_name,pal_dims,pal_data) & BIND(C,NAME='h5immake_palette_c') IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in), DIMENSION(*) :: pal_dims ! dimensions - INTEGER, INTENT(in), DIMENSION(*) :: buf ! buffer + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: pal_name + INTEGER(hsize_t), INTENT(in), DIMENSION(*) :: pal_dims + INTEGER, INTENT(in), DIMENSION(*) :: pal_data END FUNCTION h5immake_palette_c END INTERFACE - namelen = LEN(dset_name) - errcode = h5immake_palette_c(loc_id,namelen,dset_name,pal_dims,buf) + namelen = LEN(pal_name) + errcode = h5immake_palette_c(loc_id,namelen,pal_name,pal_dims,pal_data) END SUBROUTINE h5immake_palette_f -!------------------------------------------------------------------------- -! Function: h5imlink_palette_f -! -! Purpose: This function attaches a palette to an existing image dataset -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 06, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5IM +!! +!! \brief This function attaches a palette to an existing image dataset. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param image_name The name of the dataset to attach the palette to. +!! \param pal_name The name of the palette. +!! \param errcode \fortran_error +!! SUBROUTINE h5imlink_palette_f(loc_id,& - dset_name,& + image_name,& pal_name,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(len=*), INTENT(in) :: pal_name ! palette name - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: ILEN ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: image_name + CHARACTER(len=*), INTENT(in) :: pal_name + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: ILEN ! name length INTERFACE - INTEGER FUNCTION h5imlink_palette_c(loc_id,namelen,dset_name,ILEN,pal_name) & + INTEGER FUNCTION h5imlink_palette_c(loc_id,namelen,image_name,ILEN,pal_name) & BIND(C,NAME='h5imlink_palette_c') IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: pal_name ! palette name - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: ILEN ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: image_name + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: pal_name + INTEGER(size_t) :: namelen + INTEGER(size_t) :: ILEN END FUNCTION h5imlink_palette_c END INTERFACE - namelen = LEN(dset_name) + namelen = LEN(image_name) ILEN = LEN(pal_name) - errcode = h5imlink_palette_c(loc_id,namelen,dset_name,ILEN,pal_name) + errcode = h5imlink_palette_c(loc_id,namelen,image_name,ILEN,pal_name) END SUBROUTINE h5imlink_palette_f - -!------------------------------------------------------------------------- -! Function: h5imunlink_palette_f -! -! Purpose: This function dettaches a palette to an existing image dataset -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 06, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- +!> +!! \ingroup FH5IM +!! +!! \brief This function dettaches a palette to an existing image dataset. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param image_name The name of the image dataset. +!! \param pal_name The name of the palette. +!! \param errcode \fortran_error SUBROUTINE h5imunlink_palette_f(loc_id,& - dset_name,& + image_name,& pal_name,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(len=*), INTENT(in) :: pal_name ! palette name - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: ILEN ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: image_name + CHARACTER(len=*), INTENT(in) :: pal_name + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: ILEN ! name length INTERFACE - INTEGER FUNCTION h5imunlink_palette_c(loc_id,namelen,dset_name,ILEN,pal_name) & + INTEGER FUNCTION h5imunlink_palette_c(loc_id,namelen,image_name,ILEN,pal_name) & BIND(C,NAME='h5imunlink_palette_c') IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: pal_name ! palette name - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: ILEN ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: image_name + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: pal_name + INTEGER(size_t) :: namelen + INTEGER(size_t) :: ILEN END FUNCTION h5imunlink_palette_c END INTERFACE - namelen = LEN(dset_name) + namelen = LEN(image_name) ILEN = LEN(pal_name) - errcode = h5imunlink_palette_c(loc_id,namelen,dset_name,ILEN,pal_name) + errcode = h5imunlink_palette_c(loc_id,namelen,image_name,ILEN,pal_name) END SUBROUTINE h5imunlink_palette_f -!------------------------------------------------------------------------- -! Function: h5imget_npalettes_f -! -! Purpose: Gets the number of palettes associated to an image -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 05, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5IM +!! +!! \brief Gets the number of palettes associated to an image. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param image_name The name of the image dataset. +!! \param npals The number of palettes. +!! \param errcode \fortran_error +!! SUBROUTINE h5imget_npalettes_f(loc_id,& - dset_name,& + image_name,& npals,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(inout) :: npals ! palettes - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: image_name + INTEGER(hsize_t), INTENT(inout) :: npals + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTERFACE - INTEGER FUNCTION h5imget_npalettes_c(loc_id,namelen,dset_name,npals) & + INTEGER FUNCTION h5imget_npalettes_c(loc_id,namelen,image_name,npals) & BIND(C,NAME='h5imget_npalettes_c') IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(inout) :: npals ! palettes - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: image_name + INTEGER(hsize_t), INTENT(inout) :: npals + INTEGER(size_t) :: namelen END FUNCTION h5imget_npalettes_c END INTERFACE - namelen = LEN(dset_name) - errcode = h5imget_npalettes_c(loc_id,namelen,dset_name,npals) + namelen = LEN(image_name) + errcode = h5imget_npalettes_c(loc_id,namelen,image_name,npals) END SUBROUTINE h5imget_npalettes_f - - -!------------------------------------------------------------------------- -! Function: h5imget_palette_info_f -! -! Purpose: Get palette information -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 06, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5IM +!! +!! \brief Gets information about a palette dataset (dimensions). +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param image_name The name of the image dataset. +!! \param pal_number The zero based index that identifies the palette. +!! \param pal_dims The dimensions of the palette dataset. +!! \param errcode \fortran_error +!! SUBROUTINE h5imget_palette_info_f(loc_id,& - dset_name,& + image_name,& pal_number,& - dims,& + pal_dims,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: pal_number ! palette number - INTEGER(hsize_t), DIMENSION(*), INTENT(inout) :: dims ! dimensions - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: image_name + INTEGER, INTENT(in) :: pal_number + INTEGER(hsize_t), DIMENSION(*), INTENT(inout) :: pal_dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTERFACE - INTEGER FUNCTION h5imget_palette_info_c(loc_id,namelen,dset_name,pal_number,dims) & + INTEGER FUNCTION h5imget_palette_info_c(loc_id,namelen,image_name,pal_number,pal_dims) & BIND(C,NAME='h5imget_palette_info_c') IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: pal_number ! palette number - INTEGER(hsize_t), DIMENSION(*), INTENT(inout) :: dims ! dimensions - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: image_name + INTEGER, INTENT(in) :: pal_number + INTEGER(hsize_t), DIMENSION(*), INTENT(inout) :: pal_dims + INTEGER(size_t) :: namelen END FUNCTION h5imget_palette_info_c END INTERFACE - namelen = LEN(dset_name) - errcode = h5imget_palette_info_c(loc_id,namelen,dset_name,pal_number,dims) + namelen = LEN(image_name) + errcode = h5imget_palette_info_c(loc_id,namelen,image_name,pal_number,pal_dims) END SUBROUTINE h5imget_palette_info_f -!------------------------------------------------------------------------- -! Function: h5imget_palette_f -! -! Purpose: Reads palette -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 06, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5IM +!! +!! \brief Gets the palette dataset +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param image_name The name of the image dataset. +!! \param pal_number The zero based index that identifies the palette. +!! \param pal_data The palette dataset. +!! \param errcode \fortran_error +!! SUBROUTINE h5imget_palette_f(loc_id,& - dset_name,& + image_name,& pal_number,& - buf,& + pal_data,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: pal_number ! palette number - INTEGER, INTENT(inout), DIMENSION(*) :: buf ! buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: image_name + INTEGER, INTENT(in) :: pal_number + INTEGER, INTENT(inout), DIMENSION(*) :: pal_data + INTEGER :: errcode + INTEGER(size_t) :: namelen ! length of name buffer INTERFACE - INTEGER FUNCTION h5imget_palette_c(loc_id,namelen,dset_name,pal_number,buf) & + INTEGER FUNCTION h5imget_palette_c(loc_id,namelen,image_name,pal_number,pal_data) & BIND(C,NAME='h5imget_palette_c') IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: pal_number ! palette number - INTEGER, INTENT(inout), DIMENSION(*) :: buf ! buffer + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: image_name + INTEGER, INTENT(in) :: pal_number + INTEGER, INTENT(inout), DIMENSION(*) :: pal_data END FUNCTION h5imget_palette_c END INTERFACE - namelen = LEN(dset_name) - errcode = h5imget_palette_c(loc_id,namelen,dset_name,pal_number,buf) + namelen = LEN(image_name) + errcode = h5imget_palette_c(loc_id,namelen,image_name,pal_number,pal_data) END SUBROUTINE h5imget_palette_f - -!------------------------------------------------------------------------- -! Function: h5imis_palette_f -! -! Purpose: Inquires if a dataset is a palette -! -! Return: true, false, fail -! -! Programmer: Pedro Vicente -! -! Date: October 06, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - - INTEGER FUNCTION h5imis_palette_f(loc_id,& - dset_name) +!> +!! \ingroup FH5IM +!! +!! \brief Inquires if a dataset is a palette. Returns zero (false), a positive (true) or a negative (failure) value. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset. +!! + INTEGER FUNCTION h5imis_palette_f(loc_id, dset_name) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: dset_name + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTERFACE INTEGER FUNCTION h5imis_palette_c(loc_id,namelen,dset_name) & @@ -645,9 +561,9 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name END FUNCTION h5imis_palette_c END INTERFACE @@ -659,7 +575,3 @@ CONTAINS END MODULE H5IM - - - - diff --git a/hl/fortran/src/H5LTff.F90 b/hl/fortran/src/H5LTff.F90 index a4ab247..3b50ad8 100644 --- a/hl/fortran/src/H5LTff.F90 +++ b/hl/fortran/src/H5LTff.F90 @@ -1,3 +1,14 @@ +!> @defgroup FH5LT Fortran High Level Lite (H5LT) Interface +!! +!! @see H5LT, C-HL API +!! +!! @see @ref H5LT_UG, User Guide +!! + +!> @ingroup H5LT +!! +!! @brief This module contains Fortran interfaces for H5LT. +! ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ! Copyright by The HDF Group. * ! Copyright by the Board of Trustees of the University of Illinois. * @@ -10,12 +21,6 @@ ! If you do not have access to either file, you may request a copy from * ! help@hdfgroup.org. * ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * -! -! -! This file contains FORTRAN interfaces for H5LT functions -! -! NOTES -! ! _____ __ __ _____ ____ _____ _______ _ _ _______ ! |_ _| \/ | __ \ / __ \| __ \__ __|/\ | \ | |__ __| ! **** | | | \ / | |__) | | | | |__) | | | / \ | \| | | | **** @@ -30,11 +35,18 @@ #include +#ifdef H5_DOXYGEN_FORTRAN +MODULE H5LT +#else MODULE H5LT_CONST +#endif + USE, INTRINSIC :: ISO_C_BINDING USE h5fortran_types USE hdf5 +#ifndef H5_DOXYGEN_FORTRAN + INTERFACE h5ltmake_dataset_f MODULE PROCEDURE h5ltmake_dataset_f_ptr END INTERFACE @@ -86,8 +98,7 @@ MODULE H5LT_CONST CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: attr_name ! name of the attribute INTEGER(size_t), INTENT(in) :: size ! size of attribute array TYPE(C_PTR), VALUE :: buf ! data buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dtype ! flag indicating the datatype of the - ! the buffer: + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dtype ! flag indicating the datatype of the buffer: ! R=Real, D=DOUBLE, I=Integer, C=Character INTEGER(size_t) :: SizeOf_buf ! Sizeof the buf datatype END FUNCTION h5ltset_attribute_c @@ -105,76 +116,88 @@ MODULE H5LT_CONST CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: attr_name ! name of the attribute TYPE(C_PTR), VALUE :: buf ! data buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dtype ! flag indicating the datatype of the - ! the buffer: + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dtype ! flag indicating the datatype of the buffer: ! R=Real, D=DOUBLE, I=Integer INTEGER(size_t), INTENT(in) :: SizeOf_buf ! Sizeof the buf data type END FUNCTION h5ltget_attribute_c END INTERFACE +#endif + CONTAINS - !------------------------------------------------------------------------- - ! Make/Read dataset functions - !------------------------------------------------------------------------- !------------------------------------------------------------------------- - ! Function(s): h5ltmake_dataset_f_ptr - ! - ! Purpose: Creates and writes a dataset of a type TYPE_ID - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: M. Scot Breitenfeld - ! - ! Date: APR 29, 2015 - ! - ! Comments: - ! - ! Modifications: - ! + ! Make/Read dataset functions !------------------------------------------------------------------------- - SUBROUTINE h5ltmake_dataset_f_ptr(loc_id,& +#ifdef H5_DOXYGEN_FORTRAN + !> + !! \ingroup FH5LT + !! + !! \brief Creates and writes a dataset of a type \p type_id. + !! + !! \note \fortran_approved + !! + !! \param loc_id Location identifier. The identifier may be that of a file or group. + !! \param dset_name The name of the dataset to create. + !! \param rank Number of dimensions of dataspace. + !! \param dims An array of the size of each dimension. + !! \param type_id Identifier of the datatype to use when creating the dataset. + !! \param buf Buffer with data to be written to the dataset. + !! \param errcode \fortran_error + !! + SUBROUTINE h5ltmake_dataset_f(& +#else + SUBROUTINE h5ltmake_dataset_f_ptr( & +#endif + loc_id,& dset_name,& rank,& dims,& type_id,& buf,& - errcode ) + errcode) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - TYPE(C_PTR) :: buf ! data buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER(hid_t), INTENT(in) :: type_id + TYPE(C_PTR) :: buf + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length namelen = LEN(dset_name) errcode = h5ltmake_dataset_c(loc_id,namelen,dset_name,rank,dims,type_id,buf) +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5ltmake_dataset_f +#else END SUBROUTINE h5ltmake_dataset_f_ptr +#endif - !------------------------------------------------------------------------- - ! Function(s): h5ltmake_dataset_f_int(1-7) - ! - ! Purpose: Creates and writes a dataset of a type TYPE_ID - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: September 1, 2004 - ! - ! Comments: - ! - ! Modifications: Changed to passing C_PTR. - ! - !------------------------------------------------------------------------- - - SUBROUTINE h5ltmake_dataset_f_int1(loc_id,& +#ifdef H5_DOXYGEN_FORTRAN + !> + !! \ingroup FH5LT + !! + !! \brief Creates and writes a dataset of a type \p type_id. + !! + !! \note \fortran_obsolete + !! + !! \param loc_id Location identifier. The identifier may be that of a file or group. + !! \param dset_name The name of the dataset to create. + !! \param rank Number of dimensions of dataspace. + !! \param dims An array of the size of each dimension. Limited to seven dimensions. + !! \param type_id Identifier of the datatype to use when creating the dataset. + !! \param buf Buffer with data to be written to the dataset. + !! \param errcode \fortran_error + !! + SUBROUTINE h5ltmake_dataset_f(& +#else + SUBROUTINE h5ltmake_dataset_f_int1(& +#endif + loc_id,& dset_name,& rank,& dims,& @@ -183,20 +206,26 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER, INTENT(in), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER(hid_t), INTENT(in) :: type_id +#ifdef H5_DOXYGEN_FORTRAN + TYPE(TYPE), INTENT(in), DIMENSION(*,*,...) :: buf +#else + INTEGER, INTENT(in), DIMENSION(*), TARGET :: buf +#endif + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1)) namelen = LEN(dset_name) errcode = h5ltmake_dataset_c(loc_id,namelen,dset_name,rank,dims,type_id,f_ptr) - +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5ltmake_dataset_f +#else END SUBROUTINE h5ltmake_dataset_f_int1 SUBROUTINE h5ltmake_dataset_f_int2(loc_id,& @@ -208,15 +237,15 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(len=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(len=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & - DIMENSION(dims(1),dims(2)), TARGET :: buf ! data buffer + DIMENSION(dims(1),dims(2)), TARGET :: buf ! data buffer TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1,1)) @@ -235,15 +264,15 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & - DIMENSION(dims(1),dims(2),dims(3)), TARGET :: buf ! data buffer + DIMENSION(dims(1),dims(2),dims(3)), TARGET :: buf ! data buffer TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1,1,1)) @@ -257,15 +286,15 @@ CONTAINS type_id, buf, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & - DIMENSION(dims(1),dims(2),dims(3),dims(4)), TARGET :: buf ! data buffer + DIMENSION(dims(1),dims(2),dims(3),dims(4)), TARGET :: buf ! data buffer TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1,1,1,1)) @@ -279,15 +308,15 @@ CONTAINS type_id, buf, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & - DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5)), TARGET :: buf ! data buffer + DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5)), TARGET :: buf ! data buffer TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1,1,1,1,1)) @@ -301,15 +330,15 @@ CONTAINS type_id, buf, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & - DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5),dims(6)), TARGET :: buf ! data buffer + DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5),dims(6)), TARGET :: buf ! data buffer TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1,1,1,1,1,1)) @@ -323,13 +352,13 @@ CONTAINS type_id, buf, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5),dims(6),dims(7)), TARGET :: buf ! data buffer TYPE(C_PTR) :: f_ptr @@ -340,62 +369,68 @@ CONTAINS errcode = h5ltmake_dataset_c(loc_id,namelen,dset_name,rank,dims,type_id,f_ptr) END SUBROUTINE h5ltmake_dataset_f_int7 +#endif - - !------------------------------------------------------------------------- - ! Function(s): h5ltread_dataset_f_ptr - ! - ! Purpose: Read a dataset of a type TYPE_ID - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: M. Scot Breitenfeld - ! - ! Date: Apr 29, 2015 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - - SUBROUTINE h5ltread_dataset_f_ptr(loc_id,& +#ifdef H5_DOXYGEN_FORTRAN + !> + !! \ingroup FH5LT + !! + !! \brief Reads a dataset of a type \p type_id. + !! + !! \note \fortran_approved + !! + !! \param loc_id Location identifier. The identifier may be that of a file or group. + !! \param dset_name The name of the dataset to create. + !! \param type_id Identifier of the datatype to use when creating the dataset. + !! \param buf Buffer with data to be written to the dataset. + !! \param errcode \fortran_error + !! + SUBROUTINE h5ltread_dataset_f(& +#else + SUBROUTINE h5ltread_dataset_f_ptr(& +#endif + loc_id,& dset_name,& type_id,& buf,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - TYPE(C_PTR) :: buf ! data buffer - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hid_t), INTENT(in) :: type_id + TYPE(C_PTR) :: buf + INTEGER :: errcode INTEGER(size_t) :: namelen namelen = LEN(dset_name) errcode = h5ltread_dataset_c(loc_id,namelen,dset_name,type_id, buf) - +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5ltread_dataset_f +#else END SUBROUTINE h5ltread_dataset_f_ptr +#endif - !------------------------------------------------------------------------- - ! Function(s): h5ltread_dataset_f_int(1-7) - ! - ! Purpose: Read a dataset of a type TYPE_ID - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: September 22, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - - SUBROUTINE h5ltread_dataset_f_int1(loc_id,& +#ifdef H5_DOXYGEN_FORTRAN + !> + !! \ingroup FH5LT + !! + !! \brief Reads a dataset of a type \p type_id. + !! + !! \note \fortran_obsolete + !! + !! \param loc_id Location identifier. The identifier may be that of a file or group. + !! \param dset_name The name of the dataset to create. + !! \param type_id Identifier of the datatype to use when creating the dataset. + !! \param buf Buffer with data to be written to the dataset. + !! \param dims An array of the size of each dimension. Limited to seven dimensions. + !! \param errcode \fortran_error + !! + SUBROUTINE h5ltread_dataset_f(& +#else + SUBROUTINE h5ltread_dataset_f_int1(& +#endif + loc_id,& dset_name,& type_id,& buf,& @@ -403,12 +438,16 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER, INTENT(inout), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims +#ifdef H5_DOXYGEN_FORTRAN + TYPE(TYPE), INTENT(inout), DIMENSION(*,*,...) :: buf +#else + INTEGER, INTENT(inout), DIMENSION(*), TARGET :: buf +#endif + INTEGER :: errcode INTEGER(size_t) :: namelen TYPE(C_PTR) :: f_ptr @@ -417,25 +456,11 @@ CONTAINS namelen = LEN(dset_name) errcode = h5ltread_dataset_c(loc_id,namelen,dset_name,type_id,f_ptr) +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5ltread_dataset_f +#else END SUBROUTINE h5ltread_dataset_f_int1 - !------------------------------------------------------------------------- - ! Function: h5ltread_dataset_f_int2 - ! - ! Purpose: Read a dataset of a type TYPE_ID - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: September 22, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - SUBROUTINE h5ltread_dataset_f_int2(loc_id,& dset_name,& type_id,& @@ -444,12 +469,12 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -469,12 +494,12 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2),dims(3)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -490,12 +515,12 @@ CONTAINS dims, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2),dims(3),dims(4)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -511,12 +536,12 @@ CONTAINS dims, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -528,33 +553,16 @@ CONTAINS END SUBROUTINE h5ltread_dataset_f_int5 - !------------------------------------------------------------------------- - ! Function: h5ltread_dataset_f_int6 - ! - ! Purpose: Read a dataset of a type TYPE_ID - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: M. Scot Breitenfeld - ! - ! Date: March 12, 2011 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - SUBROUTINE h5ltread_dataset_f_int6(loc_id, dset_name, type_id, buf, & dims, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5),dims(6)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -570,12 +578,12 @@ CONTAINS dims, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hid_t), INTENT(in) :: type_id ! datatype identifier - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hid_t), INTENT(in) :: type_id + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5),dims(6),dims(7)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -587,11 +595,10 @@ CONTAINS END SUBROUTINE h5ltread_dataset_f_int7 - !------------------------------------------------------------------------- ! Function: h5ltmake_dataset_int_f_1 ! - ! Purpose: Creates and writes a dataset of H5T_NATIVE_INT type + !! \brief Creates and writes a dataset of H5T_NATIVE_INT type ! ! Return: Success: 0, Failure: -1 ! @@ -613,13 +620,13 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER, INTENT(in), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER, INTENT(in), DIMENSION(*), TARGET :: buf + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1)) @@ -637,12 +644,12 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & DIMENSION(dims(1),dims(2)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -662,12 +669,12 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & DIMENSION(dims(1),dims(2),dims(3)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -683,12 +690,12 @@ CONTAINS buf, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & DIMENSION(dims(1),dims(2),dims(3),dims(4)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -704,12 +711,12 @@ CONTAINS buf, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -725,12 +732,12 @@ CONTAINS buf, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5),dims(6)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -746,12 +753,12 @@ CONTAINS buf, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: rank ! rank - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: rank + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(in), & DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5),dims(6),dims(7)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -766,7 +773,7 @@ CONTAINS !------------------------------------------------------------------------- ! Function(s): h5ltread_dataset_int_f_(1-7) ! - ! Purpose: Read a dataset + !! \brief Read a dataset ! ! Return: Success: 0, Failure: -1 ! @@ -787,11 +794,11 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -810,11 +817,11 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -833,11 +840,11 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2),dims(3)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -852,11 +859,11 @@ CONTAINS SUBROUTINE h5ltread_dataset_int_f_4(loc_id, dset_name, buf, dims, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2),dims(3),dims(4)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -871,11 +878,11 @@ CONTAINS SUBROUTINE h5ltread_dataset_int_f_5(loc_id, dset_name, buf, dims, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -890,11 +897,11 @@ CONTAINS SUBROUTINE h5ltread_dataset_int_f_6(loc_id, dset_name, buf, dims, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5),dims(6)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -909,11 +916,11 @@ CONTAINS SUBROUTINE h5ltread_dataset_int_f_7(loc_id, dset_name, buf, dims, errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims ! size of the buffer buf - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), DIMENSION(*), INTENT(in) :: dims + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTEGER, INTENT(inout), & DIMENSION(dims(1),dims(2),dims(3),dims(4),dims(5),dims(6),dims(7)), TARGET :: buf TYPE(C_PTR) :: f_ptr @@ -929,7 +936,7 @@ CONTAINS !------------------------------------------------------------------------- ! Function: h5ltmake_dataset_string_f ! - ! Purpose: Creates and writes a dataset + !! \brief Creates and writes a dataset ! ! Return: Success: 0, Failure: -1 ! @@ -949,10 +956,10 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: buf ! data buffer - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + CHARACTER(LEN=*), INTENT(in) :: buf + INTEGER :: errcode INTEGER(size_t) :: namelen ! name length INTEGER(size_t) :: buflen ! buffer length @@ -962,11 +969,11 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier + INTEGER(hid_t), INTENT(in) :: loc_id INTEGER(size_t) :: namelen ! length of name buffer INTEGER(size_t) :: buflen ! length of data buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: buf ! data buffer + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: buf END FUNCTION h5ltmake_dataset_string_c END INTERFACE @@ -979,7 +986,7 @@ CONTAINS !------------------------------------------------------------------------- ! Function: h5ltread_dataset_string_f ! - ! Purpose: Read a dataset + !! \brief Read a dataset ! ! Return: Success: 0, Failure: -1 ! @@ -999,10 +1006,10 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(inout) :: buf ! data buffer - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + CHARACTER(LEN=*), INTENT(inout) :: buf + INTEGER :: errcode INTEGER(size_t) :: namelen ! name length INTERFACE @@ -1011,10 +1018,10 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier + INTEGER(hid_t), INTENT(in) :: loc_id INTEGER(size_t) :: namelen ! length of name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(inout) :: buf ! data buffer + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(inout) :: buf END FUNCTION h5ltread_dataset_string_c END INTERFACE @@ -1023,49 +1030,51 @@ CONTAINS END SUBROUTINE h5ltread_dataset_string_f - !------------------------------------------------------------------------- - ! Make/Read attribute functions - !------------------------------------------------------------------------- +#endif !------------------------------------------------------------------------- - ! Function: h5ltset_attribute_f - ! - ! Purpose: Create and write an attribute - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: M. Scot Breitenfeld - ! - ! Date: May 4, 2015 - ! - ! Comments: - ! - ! Modifications: - ! + ! Make/Read attribute functions !------------------------------------------------------------------------- + !> + !! \ingroup FH5LT + !! + !! \brief Creates and writes an attribute and is a generic replacement for data type specific + !! Fortran h5ltset_attribute_*_f APIs. There is no C equivalent API. + !! + !! \note \fortran_approved + !! + !! \param loc_id Location identifier. The identifier may be that of a file or group. + !! \param dset_name The name of the dataset to create. + !! \param attr_name The name of the attribute to create. + !! \param buf The data buffer. + !! \param buf_type Valid data types are CHARACTER, INTEGER or REAL. + !! NOTE: only the first character matters and is case insensitive. + !! \param SizeOf_buf_type Size of \p buf's data type, in bytes. + !! \param size Size of attribute array. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltset_attribute_f(loc_id,& dset_name,& attr_name,& buf,& - buf_type, SizeOf_buf_type, & + buf_type,& + SizeOf_buf_type, & size,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - TYPE(C_PTR) :: buf ! data buffer - CHARACTER(LEN=*), INTENT(in) :: buf_type ! valid data types are: - ! CHARACTER, INTEGER or REAL - ! NOTE: only the first character matters and is case insensitive - INTEGER(size_t), INTENT(in) :: size ! size of attribute array - INTEGER(size_t), INTENT(in) :: SizeOf_buf_type ! size of buf's data type - INTEGER, INTENT(out) :: errcode ! error code - - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + TYPE(C_PTR) :: buf + CHARACTER(LEN=*), INTENT(in) :: buf_type + INTEGER(size_t), INTENT(in) :: size + INTEGER(size_t), INTENT(in) :: SizeOf_buf_type + INTEGER, INTENT(out) :: errcode + + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! name length CHARACTER(KIND=C_CHAR) :: buf_type_uppercase namelen = LEN(dset_name) @@ -1085,39 +1094,37 @@ CONTAINS END SUBROUTINE h5ltset_attribute_f - !------------------------------------------------------------------------- - ! Function: h5ltset_attribute_int_f - ! - ! Purpose: Create and write an attribute - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: October 05, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Creates and writes an attribute. + !! + !! \note \fortran_obsolete + !! + !! \param loc_id Identifier of the object (dataset or group) to create the attribute within + !! \param obj_name The name of the object to attach the attribute. + !! \param attr_name The attribute name. + !! \param buf Buffer with data to be written to the attribute. + !! \param size The size of the 1D array (one in the case of a scalar attribute). + !! This value is used by H5Screate_simple() to create the dataspace. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltset_attribute_int_f(loc_id,& - dset_name,& + obj_name,& attr_name,& buf,& size,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - INTEGER(size_t), INTENT(in) :: size ! size of attribute array - INTEGER :: errcode ! error code - INTEGER, DIMENSION(*), TARGET :: buf ! data buffer - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: obj_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + INTEGER(size_t), INTENT(in) :: size + INTEGER :: errcode + INTEGER, DIMENSION(*), TARGET :: buf + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! name length TYPE(C_PTR) :: f_ptr INTEGER(size_t) :: SizeOf_buf_type @@ -1129,46 +1136,44 @@ CONTAINS SizeOf_buf_type = SIZEOF(buf(1)) #endif - namelen = LEN(dset_name) + namelen = LEN(obj_name) attrlen = LEN(attr_name) - errcode = h5ltset_attribute_c(loc_id,namelen,dset_name,attrlen,attr_name,size,& + errcode = h5ltset_attribute_c(loc_id,namelen,obj_name,attrlen,attr_name,size,& f_ptr,'I'//C_NULL_CHAR,SizeOf_buf_type) END SUBROUTINE h5ltset_attribute_int_f - !------------------------------------------------------------------------- - ! Function: h5ltset_attribute_float_f - ! - ! Purpose: Create and write an attribute - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: October 05, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Creates and writes an attribute. + !! + !! \note \fortran_obsolete + !! + !! \param loc_id Identifier of the object (dataset or group) to create the attribute within + !! \param obj_name The name of the object to attach the attribute. + !! \param attr_name The attribute name. + !! \param buf Buffer with data to be written to the attribute. + !! \param size The size of the 1D array (one in the case of a scalar attribute). + !! This value is used by H5Screate_simple() to create the dataspace. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltset_attribute_float_f(loc_id,& - dset_name,& + obj_name,& attr_name,& buf,& size,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - INTEGER(size_t), INTENT(in) :: size ! size of attribute array - INTEGER :: errcode ! error code - REAL(KIND=C_FLOAT), INTENT(in), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: obj_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + INTEGER(size_t), INTENT(in) :: size + INTEGER :: errcode + REAL(KIND=C_FLOAT), INTENT(in), DIMENSION(*), TARGET :: buf + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! name length TYPE(C_PTR) :: f_ptr INTEGER(size_t) :: SizeOf_buf_type @@ -1179,46 +1184,44 @@ CONTAINS SizeOf_buf_type = SIZEOF(buf(1)) #endif - namelen = LEN(dset_name) + namelen = LEN(obj_name) attrlen = LEN(attr_name) - errcode = h5ltset_attribute_c(loc_id,namelen,dset_name,attrlen,attr_name,size,& + errcode = h5ltset_attribute_c(loc_id,namelen,obj_name,attrlen,attr_name,size,& f_ptr,'R'//C_NULL_CHAR, SizeOf_buf_type) END SUBROUTINE h5ltset_attribute_float_f - !------------------------------------------------------------------------- - ! Function: h5ltset_attribute_double_f - ! - ! Purpose: Create and write an attribute - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: October 05, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Creates and writes an attribute. + !! + !! \note \fortran_obsolete + !! + !! \param loc_id Identifier of the object (dataset or group) to create the attribute within + !! \param obj_name The name of the object to attach the attribute. + !! \param attr_name The attribute name. + !! \param buf Buffer with data to be written to the attribute. + !! \param size The size of the 1D array (one in the case of a scalar attribute). + !! This value is used by H5Screate_simple() to create the dataspace. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltset_attribute_double_f(loc_id,& - dset_name,& + obj_name,& attr_name,& buf,& size,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - INTEGER(size_t), INTENT(in) :: size ! size of attribute array - INTEGER :: errcode ! error code - REAL(KIND=C_DOUBLE), INTENT(in), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: obj_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + INTEGER(size_t), INTENT(in) :: size + INTEGER :: errcode + REAL(KIND=C_DOUBLE), INTENT(in), DIMENSION(*), TARGET :: buf + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! name length TYPE(C_PTR) :: f_ptr INTEGER(size_t) :: SizeOf_buf_type @@ -1230,46 +1233,41 @@ CONTAINS SizeOf_buf_type = SIZEOF(buf(1)) #endif - namelen = LEN(dset_name) + namelen = LEN(obj_name) attrlen = LEN(attr_name) - errcode = h5ltset_attribute_c(loc_id,namelen,dset_name,attrlen,attr_name,size,& + errcode = h5ltset_attribute_c(loc_id,namelen,obj_name,attrlen,attr_name,size,& f_ptr,'R'//C_NULL_CHAR,SizeOf_buf_type) END SUBROUTINE h5ltset_attribute_double_f - - !------------------------------------------------------------------------- - ! Function: h5ltset_attribute_string_f - ! - ! Purpose: Create and write an attribute - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: October 05, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Creates and writes an attribute. + !! + !! \note \fortran_obsolete + !! + !! \param loc_id Identifier of the object (dataset or group) to create the attribute within + !! \param obj_name The name of the object to attach the attribute. + !! \param attr_name The attribute name. + !! \param buf Buffer with data to be written to the attribute. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltset_attribute_string_f(loc_id,& - dset_name,& + obj_name,& attr_name,& buf,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - INTEGER :: errcode ! error code - CHARACTER(LEN=*), DIMENSION(*), INTENT(in), TARGET :: buf ! data buffer - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! name length - INTEGER(size_t) :: buflen ! data buffer length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: obj_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + INTEGER :: errcode + CHARACTER(LEN=*), DIMENSION(*), INTENT(in), TARGET :: buf + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! name length + INTEGER(size_t) :: buflen ! data buffer length TYPE(C_PTR) :: f_ptr INTEGER(size_t) :: SizeOf_buf_type @@ -1281,52 +1279,48 @@ CONTAINS SizeOf_buf_type = SIZEOF(buf(1:1)(1:1)) #endif - namelen = LEN(dset_name) + namelen = LEN(obj_name) attrlen = LEN(attr_name) buflen = LEN(buf) - errcode = h5ltset_attribute_c(loc_id,namelen,dset_name,attrlen,attr_name,buflen,& + errcode = h5ltset_attribute_c(loc_id,namelen,obj_name,attrlen,attr_name,buflen,& f_ptr,'C'//C_NULL_CHAR, SizeOf_buf_type) END SUBROUTINE h5ltset_attribute_string_f - - !------------------------------------------------------------------------- - ! Function: h5ltget_attribute_f - ! - ! Purpose: Reads an attribute named ATTR_NAME - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: M. Scot Breitenfeld - ! - ! Date: Apr 29, 2015 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Reads an attribute from disk. + !! + !! \note \fortran_approved + !! + !! \param loc_id Location identifier. The identifier may be that of a file or group. + !! \param obj_name The name of the object that the attribute is attached to. + !! \param attr_name The name of the attribute to create. + !! \param buf The data buffer. + !! \param buf_type Valid data types are CHARACTER, INTEGER or REAL. + !! NOTE: only the first character matters and is case insensitive. + !! \param SizeOf_buf_type Size of \p buf's data type, in bytes. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltget_attribute_f(loc_id,& - dset_name,& + obj_name,& attr_name,& buf, buf_type, SizeOf_buf_type, & errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - TYPE(C_PTR) :: buf ! data buffer - CHARACTER(LEN=*), INTENT(in) :: buf_type ! valid data types are: - ! CHARACTER, INTEGER or REAL - ! NOTE: only the first character matters and is case insensitive - INTEGER(size_t), INTENT(in) :: SizeOf_buf_type ! size of buf's data type - INTEGER, INTENT(out) :: errcode ! error code - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! attr length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: obj_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + TYPE(C_PTR) :: buf + CHARACTER(LEN=*), INTENT(in) :: buf_type + INTEGER(size_t), INTENT(in) :: SizeOf_buf_type + INTEGER, INTENT(out) :: errcode + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! attr length CHARACTER(KIND=C_CHAR) :: buf_type_uppercase - namelen = LEN(dset_name) + namelen = LEN(obj_name) attrlen = LEN(attr_name) buf_type_uppercase(1:1) = buf_type(1:1) @@ -1337,43 +1331,38 @@ CONTAINS ELSE IF(buf_type_uppercase(1:1).EQ.'c')THEN buf_type_uppercase(1:1) = 'C' ENDIF - errcode = h5ltget_attribute_c(loc_id,namelen,dset_name,attrlen,attr_name, & + errcode = h5ltget_attribute_c(loc_id,namelen,obj_name,attrlen,attr_name, & buf, buf_type_uppercase//C_NULL_CHAR, SizeOf_buf_type) - END SUBROUTINE h5ltget_attribute_f - !------------------------------------------------------------------------- - ! Function: h5ltget_attribute_int_f - ! - ! Purpose: Reads an attribute named ATTR_NAME - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: October 05, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Reads an attribute from disk. + !! + !! \note \fortran_obsolete + !! + !! \param loc_id Identifier of the object (dataset or group) to create the attribute within + !! \param obj_name The name of the object that the attribute is attached to. + !! \param attr_name The attribute name. + !! \param buf Buffer with data to be written to the attribute. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltget_attribute_int_f(loc_id,& - dset_name,& + obj_name,& attr_name,& buf,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - INTEGER :: errcode ! error code - INTEGER, INTENT(inout), DIMENSION(*), TARGET :: buf! data buffer - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: obj_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + INTEGER :: errcode + INTEGER, INTENT(inout), DIMENSION(*), TARGET :: buf + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! name length TYPE(C_PTR) :: f_ptr INTEGER(size_t) :: SizeOf_buf @@ -1384,43 +1373,39 @@ CONTAINS #else SizeOf_buf = SIZEOF(buf(1)) #endif - namelen = LEN(dset_name) + namelen = LEN(obj_name) attrlen = LEN(attr_name) - errcode = h5ltget_attribute_c(loc_id,namelen,dset_name,attrlen,attr_name,f_ptr,'I'//C_NULL_CHAR, SizeOf_buf) + errcode = h5ltget_attribute_c(loc_id,namelen,obj_name,attrlen,attr_name,f_ptr,'I'//C_NULL_CHAR, SizeOf_buf) END SUBROUTINE h5ltget_attribute_int_f - !------------------------------------------------------------------------- - ! Function: h5ltget_attribute_float_f - ! - ! Purpose: Reads an attribute named ATTR_NAME - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: October 05, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Reads an attribute from disk. + !! + !! \note \fortran_obsolete + !! + !! \param loc_id Identifier of the object (dataset or group) to create the attribute within + !! \param obj_name The name of the object that the attribute is attached to. + !! \param attr_name The attribute name. + !! \param buf Buffer with data to be written to the attribute. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltget_attribute_float_f(loc_id,& - dset_name,& + obj_name,& attr_name,& buf,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: obj_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + INTEGER :: errcode REAL(KIND=C_FLOAT), INTENT(inout), DIMENSION(*), TARGET :: buf - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! name length + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! name length TYPE(C_PTR) :: f_ptr INTEGER(size_t) :: SizeOf_buf @@ -1430,43 +1415,39 @@ CONTAINS #else SizeOf_buf = SIZEOF(buf(1)) #endif - namelen = LEN(dset_name) + namelen = LEN(obj_name) attrlen = LEN(attr_name) - errcode = h5ltget_attribute_c(loc_id,namelen,dset_name,attrlen,attr_name,f_ptr,'R'//C_NULL_CHAR, SizeOf_buf) + errcode = h5ltget_attribute_c(loc_id,namelen,obj_name,attrlen,attr_name,f_ptr,'R'//C_NULL_CHAR, SizeOf_buf) END SUBROUTINE h5ltget_attribute_float_f - !------------------------------------------------------------------------- - ! Function: h5ltget_attribute_c_double_f - ! - ! Purpose: Reads an attribute named ATTR_NAME - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: October 05, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Reads an attribute from disk. + !! + !! \note \fortran_obsolete + !! + !! \param loc_id Identifier of the object (dataset or group) to create the attribute within + !! \param obj_name The name of the object that the attribute is attached to. + !! \param attr_name The attribute name. + !! \param buf Buffer with data to be written to the attribute. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltget_attribute_double_f(loc_id,& - dset_name,& + obj_name,& attr_name,& buf,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: obj_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + INTEGER :: errcode REAL(KIND=C_DOUBLE),INTENT(inout),DIMENSION(*), TARGET :: buf - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! name length + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! name length TYPE(C_PTR) :: f_ptr INTEGER(size_t) :: SizeOf_buf @@ -1477,66 +1458,62 @@ CONTAINS SizeOf_buf = SIZEOF(buf(1)) #endif - namelen = LEN(dset_name) + namelen = LEN(obj_name) attrlen = LEN(attr_name) - errcode = h5ltget_attribute_c(loc_id,namelen,dset_name,attrlen,attr_name,f_ptr,'R'//C_NULL_CHAR, SizeOf_buf) + errcode = h5ltget_attribute_c(loc_id,namelen,obj_name,attrlen,attr_name,f_ptr,'R'//C_NULL_CHAR, SizeOf_buf) END SUBROUTINE h5ltget_attribute_double_f - !------------------------------------------------------------------------- - ! Function: h5ltget_attribute_string_f - ! - ! Purpose: Reads an attribute named ATTR_NAME - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: October 05, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Reads an attribute from disk. + !! + !! \note \fortran_obsolete + !! + !! \param loc_id Identifier of the object (dataset or group) to create the attribute within + !! \param obj_name The name of the object that the attribute is attached to. + !! \param attr_name The attribute name. + !! \param buf Buffer with data to be written to the attribute. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltget_attribute_string_f(loc_id,& - dset_name,& + obj_name,& attr_name,& buf,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: obj_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + INTEGER :: errcode CHARACTER(LEN=*), INTENT(inout) :: buf - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! name length - INTEGER(size_t) :: buf_size ! buf size + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! name length + INTEGER(size_t) :: buf_size ! buf size INTERFACE - INTEGER FUNCTION h5ltget_attribute_string_c(loc_id,namelen,dset_name,attrlen,attr_name,buf,buf_size) & + INTEGER FUNCTION h5ltget_attribute_string_c(loc_id,namelen,obj_name,attrlen,attr_name,buf,buf_size) & BIND(C,NAME='h5ltget_attribute_string_c') IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - INTEGER(size_t) :: attrlen ! length of attr name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: attr_name ! name of the attribute - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(inout) :: buf ! data buffer - INTEGER(size_t) :: buf_size ! data buffer size + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + INTEGER(size_t) :: attrlen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: obj_name + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: attr_name + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(inout) :: buf + INTEGER(size_t) :: buf_size END FUNCTION h5ltget_attribute_string_c END INTERFACE - namelen = LEN(dset_name) + namelen = LEN(obj_name) attrlen = LEN(attr_name) buf_size = LEN(buf) - errcode = h5ltget_attribute_string_c(loc_id,namelen,dset_name,attrlen,attr_name,buf,buf_size) + errcode = h5ltget_attribute_string_c(loc_id,namelen,obj_name,attrlen,attr_name,buf,buf_size) END SUBROUTINE h5ltget_attribute_string_f @@ -1544,34 +1521,27 @@ CONTAINS ! Query dataset functions !------------------------------------------------------------------------- - !------------------------------------------------------------------------- - ! Function: h5ltget_dataset_ndims_f - ! - ! Purpose: Gets the dimensionality of a dataset - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: September 30, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Gets the dimensionality of a dataset. + !! + !! \param loc_id Identifier of the object to locate the dataset within. + !! \param dset_name The dataset name. + !! \param rank The dimensionality of the dataset. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltget_dataset_ndims_f(loc_id,& dset_name,& rank,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(inout) :: rank ! rank - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(inout) :: rank + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTERFACE INTEGER FUNCTION h5ltget_dataset_ndims_c(loc_id,namelen,dset_name,rank) & @@ -1579,10 +1549,10 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(inout) :: rank ! rank + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + INTEGER, INTENT(inout) :: rank END FUNCTION h5ltget_dataset_ndims_c END INTERFACE @@ -1591,33 +1561,24 @@ CONTAINS END SUBROUTINE h5ltget_dataset_ndims_f - - !------------------------------------------------------------------------- - ! Function: h5ltfind_dataset_f - ! - ! Purpose: Inquires if a dataset named dset_name exists attached - ! to the object loc_id. - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: October 05, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Determines whether a dataset exists. + !! + !! \param loc_id Identifier of the group containing the dataset. + !! \param dset_name The dataset name. + !! + !! \result Returns zero (false), a positive (true) or a negative (failure) value. + !! INTEGER FUNCTION h5ltfind_dataset_f(loc_id,& dset_name) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTERFACE INTEGER FUNCTION h5ltfind_dataset_c(loc_id,namelen,dset_name) & @@ -1625,9 +1586,9 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name END FUNCTION h5ltfind_dataset_c END INTERFACE @@ -1637,23 +1598,18 @@ CONTAINS END FUNCTION h5ltfind_dataset_f - !------------------------------------------------------------------------- - ! Function: h5ltget_dataset_info_f - ! - ! Purpose: Gets information about a dataset - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: September 30, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Retrieves information about a dataset. + !! + !! \param loc_id Identifier of the object to locate the dataset within. + !! \param dset_name The dataset name. + !! \param dims The dimensions of the dataset. + !! \param type_class The class identifier. See H5Tget_class_f() for a list of class types. + !! \param type_size The size of the datatype in bytes. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltget_dataset_info_f(loc_id,& dset_name,& dims,& @@ -1662,13 +1618,13 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t),DIMENSION(*),INTENT(inout):: dims ! dimensions - INTEGER, INTENT(inout) :: type_class ! type class - INTEGER(size_t), INTENT(inout) :: type_size ! type size - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t),DIMENSION(*),INTENT(inout):: dims + INTEGER, INTENT(inout) :: type_class + INTEGER(size_t), INTENT(inout) :: type_size + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTERFACE INTEGER FUNCTION h5ltget_dataset_info_c(loc_id,namelen,dset_name,dims,type_class,type_size) & @@ -1676,12 +1632,12 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t),DIMENSION(*),INTENT(inout):: dims ! dimensions - INTEGER, INTENT(inout) :: type_class ! type class - INTEGER(size_t), INTENT(inout) :: type_size ! type size + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + INTEGER(hsize_t),DIMENSION(*),INTENT(inout):: dims + INTEGER, INTENT(inout) :: type_class + INTEGER(size_t), INTENT(inout) :: type_size END FUNCTION h5ltget_dataset_info_c END INTERFACE @@ -1695,80 +1651,68 @@ CONTAINS ! Query attribute functions !------------------------------------------------------------------------- - - !------------------------------------------------------------------------- - ! Function: h5ltget_attribute_ndims_f - ! - ! Purpose: Create and write an attribute - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: October 05, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Gets the dimensionality of an attribute. + !! + !! \param loc_id Identifier of the object (dataset or group) to read the attribute from. + !! \param obj_name The name of the object that the attribute is attached to. + !! \param attr_name The attribute name. + !! \param rank The dimensionality of the attribute. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltget_attribute_ndims_f(loc_id,& - dset_name,& + obj_name,& attr_name,& rank,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - INTEGER, INTENT(inout) :: rank ! rank - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: obj_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + INTEGER, INTENT(inout) :: rank + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! name length INTERFACE - INTEGER FUNCTION h5ltget_attribute_ndims_c(loc_id,namelen,dset_name,attrlen,attr_name,rank) & + INTEGER FUNCTION h5ltget_attribute_ndims_c(loc_id,namelen,obj_name,attrlen,attr_name,rank) & BIND(C,NAME='h5ltget_attribute_ndims_c') IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - INTEGER(size_t) :: attrlen ! length of attr name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: attr_name ! name of the attribute - INTEGER, INTENT(inout) :: rank ! rank + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + INTEGER(size_t) :: attrlen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: obj_name + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: attr_name + INTEGER, INTENT(inout) :: rank END FUNCTION h5ltget_attribute_ndims_c END INTERFACE - namelen = LEN(dset_name) + namelen = LEN(obj_name) attrlen = LEN(attr_name) - errcode = h5ltget_attribute_ndims_c(loc_id,namelen,dset_name,attrlen,attr_name,rank) + errcode = h5ltget_attribute_ndims_c(loc_id,namelen,obj_name,attrlen,attr_name,rank) END SUBROUTINE h5ltget_attribute_ndims_f - - !------------------------------------------------------------------------- - ! Function: h5ltget_attribute_info_f - ! - ! Purpose: Gets information about an attribute - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: Pedro Vicente - ! - ! Date: September 30, 2004 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Gets information about an attribute. + !! + !! \param loc_id Identifier of the object (dataset or group) to read the attribute from. + !! \param obj_name The name of the object that the attribute is attached to. + !! \param attr_name The attribute name. + !! \param dims The dimensions of the attribute. + !! \param type_class The class identifier. For a list of valid class types see: H5Tget_class_f(). + !! \param type_size The size of the datatype in bytes. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltget_attribute_info_f(loc_id,& - dset_name,& + obj_name,& attr_name,& dims,& type_class,& @@ -1776,65 +1720,58 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: attr_name ! name of the attribute - INTEGER(hsize_t),DIMENSION(*),INTENT(inout):: dims ! dimensions - INTEGER, INTENT(inout) :: type_class ! type class - INTEGER(size_t), INTENT(inout) :: type_size ! type size - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: attrlen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: obj_name + CHARACTER(LEN=*), INTENT(in) :: attr_name + INTEGER(hsize_t),DIMENSION(*),INTENT(inout):: dims + INTEGER, INTENT(inout) :: type_class + INTEGER(size_t), INTENT(inout) :: type_size + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: attrlen ! name length INTERFACE - INTEGER FUNCTION h5ltget_attribute_info_c(loc_id,namelen,dset_name,attrlen,attr_name,dims,type_class,type_size) & + INTEGER FUNCTION h5ltget_attribute_info_c(loc_id,namelen,obj_name,attrlen,attr_name,dims,type_class,type_size) & BIND(C,NAME='h5ltget_attribute_info_c') IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - INTEGER(size_t) :: namelen ! length of name buffer - INTEGER(size_t) :: attrlen ! length of attr name buffer - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: attr_name ! name of the attribute - INTEGER(hsize_t),DIMENSION(*),INTENT(inout):: dims ! dimensions - INTEGER, INTENT(inout) :: type_class ! type class - INTEGER(size_t), INTENT(inout) :: type_size ! type size + INTEGER(hid_t), INTENT(in) :: loc_id + INTEGER(size_t) :: namelen + INTEGER(size_t) :: attrlen + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: obj_name + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: attr_name + INTEGER(hsize_t),DIMENSION(*),INTENT(inout):: dims + INTEGER, INTENT(inout) :: type_class + INTEGER(size_t), INTENT(inout) :: type_size END FUNCTION h5ltget_attribute_info_c END INTERFACE - namelen = LEN(dset_name) + namelen = LEN(obj_name) attrlen = LEN(attr_name) - errcode = h5ltget_attribute_info_c(loc_id,namelen,dset_name,attrlen,attr_name,dims,type_class,type_size) + errcode = h5ltget_attribute_info_c(loc_id,namelen,obj_name,attrlen,attr_name,dims,type_class,type_size) END SUBROUTINE h5ltget_attribute_info_f - !------------------------------------------------------------------------- - ! Function: h5ltpath_valid_f - ! - ! Purpose: Validates a path - ! - ! Return: Success: 0, Failure: -1 - ! - ! Programmer: M. Scot Breitenfeld - ! - ! Date: February 18, 2012 - ! - ! Comments: - ! - ! Modifications: - ! - !------------------------------------------------------------------------- - + !> + !! \ingroup FH5LT + !! + !! \brief Determines whether an HDF5 path is valid and, optionally, whether the path resolves to an HDF5 object. + !! + !! \param loc_id Identifier of an object in the file. + !! \param path The path to the object to check; links in path may be of any type. + !! \param check_object_valid Indicates whether to check if the final component of the path resolves to a valid object. + !! \param path_valid Object status. + !! \param errcode \fortran_error + !! SUBROUTINE h5ltpath_valid_f(loc_id, path, check_object_valid, path_valid, errcode) IMPLICIT NONE - INTEGER(hid_t) , INTENT(IN) :: loc_id ! An identifier of an object in the file. - CHARACTER(LEN=*), INTENT(IN) :: path ! Path to the object to check, relative to loc_id. - LOGICAL , INTENT(IN) :: check_object_valid ! Indicates whether to check if the final component - ! of the path resolves to a valid object - LOGICAL , INTENT(OUT) :: path_valid ! Object status - INTEGER , INTENT(OUT) :: errcode ! Error code: 0 on success and -1 on failure + INTEGER(hid_t) , INTENT(IN) :: loc_id + CHARACTER(LEN=*), INTENT(IN) :: path + LOGICAL , INTENT(IN) :: check_object_valid + LOGICAL , INTENT(OUT) :: path_valid + INTEGER , INTENT(OUT) :: errcode INTEGER(size_t) :: pathlen INTEGER :: check_object_valid_c @@ -1871,7 +1808,11 @@ CONTAINS END SUBROUTINE h5ltpath_valid_f +#ifdef H5_DOXYGEN_FORTRAN +END MODULE H5LT +#else END MODULE H5LT_CONST +#endif diff --git a/hl/fortran/src/H5TBff.F90 b/hl/fortran/src/H5TBff.F90 index 82f34a8..52af33f 100644 --- a/hl/fortran/src/H5TBff.F90 +++ b/hl/fortran/src/H5TBff.F90 @@ -1,3 +1,14 @@ +!> @defgroup FH5TB Fortran High Level Table (H5TB) Interface +!! +!! @see H5TB, C-HL API +!! +!! @see @ref H5TB_UG, User Guide +!! + +!> @ingroup FH5TB +!! +!! @brief This module contains Fortran interfaces for H5TB. +! ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ! Copyright by The HDF Group. * ! Copyright by the Board of Trustees of the University of Illinois. * @@ -10,13 +21,6 @@ ! If you do not have access to either file, you may request a copy from * ! help@hdfgroup.org. * ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * -! -! -! This file contains FORTRAN interfaces for H5TB functions -! -! -! NOTES -! ! _____ __ __ _____ ____ _____ _______ _ _ _______ ! |_ _| \/ | __ \ / __ \| __ \__ __|/\ | \ | |__ __| ! **** | | | \ / | |__) | | | | |__) | | | / \ | \| | | | **** @@ -29,38 +33,64 @@ ! This is needed for Windows based operating systems. ! #include "H5config_f.inc" - -MODULE h5tb_CONST +#ifdef H5_DOXYGEN_FORTRAN + MODULE H5TB +#else + MODULE H5TB_CONST +#endif USE, INTRINSIC :: ISO_C_BINDING USE h5fortran_types USE hdf5 INTERFACE h5tbwrite_field_name_f +#ifdef H5_DOXYGEN_FORTRAN + MODULE PROCEDURE h5tbwrite_field_name_f +#else MODULE PROCEDURE h5tbwrite_field_name_f_int MODULE PROCEDURE h5tbwrite_field_name_f_string +#endif END INTERFACE INTERFACE h5tbread_field_name_f +#ifdef H5_DOXYGEN_FORTRAN + MODULE PROCEDURE h5tbread_field_name_f +#else MODULE PROCEDURE h5tbread_field_name_f_int MODULE PROCEDURE h5tbread_field_name_f_string +#endif END INTERFACE INTERFACE h5tbwrite_field_index_f +#ifdef H5_DOXYGEN_FORTRAN + MODULE PROCEDURE h5tbwrite_field_index_f +#else MODULE PROCEDURE h5tbwrite_field_index_f_int MODULE PROCEDURE h5tbwrite_field_index_f_string +#endif END INTERFACE INTERFACE h5tbread_field_index_f +#ifdef H5_DOXYGEN_FORTRAN + MODULE PROCEDURE h5tbread_field_index_f +#else MODULE PROCEDURE h5tbread_field_index_f_int MODULE PROCEDURE h5tbread_field_index_f_string +#endif END INTERFACE INTERFACE h5tbinsert_field_f +#ifdef H5_DOXYGEN_FORTRAN + MODULE PROCEDURE h5tbinsert_field_f +#else MODULE PROCEDURE h5tbinsert_field_f_int MODULE PROCEDURE h5tbinsert_field_f_string +#endif END INTERFACE + +#ifndef H5_DOXYGEN_FORTRAN + INTERFACE h5tbmake_table_f MODULE PROCEDURE h5tbmake_table_f90 MODULE PROCEDURE h5tbmake_table_ptr_f @@ -144,7 +174,6 @@ MODULE h5tb_CONST END FUNCTION h5tbread_field_index_c END INTERFACE - INTERFACE INTEGER FUNCTION h5tbinsert_field_c(loc_id,namelen,dset_name,namelen1,field_name,& field_type,field_index,buf) & @@ -153,8 +182,8 @@ MODULE h5tb_CONST IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: field_name ! name of the field + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: field_name ! name of the field INTEGER(hid_t), INTENT(in) :: field_type ! field type INTEGER, INTENT(in) :: field_index ! field_index TYPE(C_PTR), VALUE :: buf ! data buffer @@ -163,26 +192,36 @@ MODULE h5tb_CONST END FUNCTION h5tbinsert_field_c END INTERFACE -CONTAINS +#endif -!------------------------------------------------------------------------- -! Function: h5tbmake_table_f90 -! -! Purpose: Make a table -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 06, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- +CONTAINS - SUBROUTINE h5tbmake_table_f90(table_title,& +!> +!! \ingroup FH5TB +!! +!! \brief Creates (DOES NOT WRITE) a dataset named \p dset_name attached to the object specified by the identifier \p loc_id. +!! +!! \note \fortran_obsolete +!! +!! \param table_title The title of the table. +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to create. +!! \param nfields The number of fields. +!! \param nrecords The number of records. +!! \param type_size The size in bytes of the structure associated with the table. Obtained with sizeof or storage_size. +!! \param field_names An array containing the names of the fields. +!! \param field_offset An array containing the offsets of the fields. +!! \param field_types An array containing the type of the fields. +!! \param chunk_size The chunk size. +!! \param compress Flag that turns compression on or off. +!! \param errcode \fortran_error +!! +#ifdef H5_DOXYGEN_FORTRAN + SUBROUTINE h5tbmake_table_f(& +#else + SUBROUTINE h5tbmake_table_f90(& +#endif + table_title,& loc_id,& dset_name,& nfields,& @@ -196,20 +235,20 @@ CONTAINS errcode ) IMPLICIT NONE - CHARACTER(LEN=*), INTENT(in) :: table_title ! name of the dataset - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in) :: nfields ! fields - INTEGER(hsize_t), INTENT(in) :: nrecords ! records - INTEGER(size_t), INTENT(in) :: type_size ! type size - CHARACTER(LEN=*), DIMENSION(1:nfields), INTENT(in) :: field_names ! field names - INTEGER(size_t), DIMENSION(1:nfields), INTENT(in) :: field_offset ! field offset - INTEGER(hid_t), DIMENSION(1:nfields), INTENT(in) :: field_types ! field types - INTEGER(hsize_t), INTENT(in) :: chunk_size ! chunk size - INTEGER, INTENT(in) :: compress ! compress + CHARACTER(LEN=*), INTENT(in) :: table_title + INTEGER(hid_t) , INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(in) :: nfields + INTEGER(hsize_t), INTENT(in) :: nrecords + INTEGER(size_t) , INTENT(in) :: type_size + CHARACTER(LEN=*), DIMENSION(1:nfields), INTENT(in) :: field_names + INTEGER(size_t) , DIMENSION(1:nfields), INTENT(in) :: field_offset + INTEGER(hid_t), DIMENSION(1:nfields), INTENT(in) :: field_types + INTEGER(hsize_t), INTENT(in) :: chunk_size + INTEGER, INTENT(in) :: compress + INTEGER :: errcode INTEGER(size_t) :: namelen ! name length INTEGER(size_t) :: namelen1 ! name length - INTEGER :: errcode ! error code INTEGER(size_t), DIMENSION(1:nfields) :: char_len_field_names ! field name lengths INTEGER(size_t) :: max_char_size_field_names ! character len of field names INTEGER(hsize_t) :: i ! general purpose integer @@ -234,21 +273,21 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: table_title ! name of the dataset - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in) :: nfields ! fields - INTEGER(hsize_t), INTENT(in) :: nrecords ! records - INTEGER(size_t), INTENT(in) :: type_size ! type size - CHARACTER(KIND=C_CHAR), DIMENSION(nfields), INTENT(in) :: field_names ! field names - INTEGER(size_t), DIMENSION(nfields), INTENT(in) :: field_offset ! field offset - INTEGER(hid_t), DIMENSION(nfields), INTENT(in) :: field_types ! field types - INTEGER(hsize_t), INTENT(in) :: chunk_size ! chunk size - INTEGER, INTENT(in) :: compress ! compress - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: namelen1 ! name length - INTEGER(size_t), DIMENSION(nfields) :: char_len_field_names ! field name's lengths - INTEGER(size_t) :: max_char_size_field_names ! character len of field names + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: table_title + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(in) :: nfields + INTEGER(hsize_t), INTENT(in) :: nrecords + INTEGER(size_t), INTENT(in) :: type_size + CHARACTER(KIND=C_CHAR), DIMENSION(nfields), INTENT(in) :: field_names + INTEGER(size_t), DIMENSION(nfields), INTENT(in) :: field_offset + INTEGER(hid_t), DIMENSION(nfields), INTENT(in) :: field_types + INTEGER(hsize_t), INTENT(in) :: chunk_size + INTEGER, INTENT(in) :: compress + INTEGER(size_t) :: namelen + INTEGER(size_t) :: namelen1 + INTEGER(size_t), DIMENSION(nfields) :: char_len_field_names + INTEGER(size_t) :: max_char_size_field_names END FUNCTION h5tbmake_table_c END INTERFACE @@ -266,9 +305,40 @@ CONTAINS type_size, field_offset, field_types, chunk_size, compress, char_len_field_names, & max_char_size_field_names, field_names) +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5tbmake_table_f +#else END SUBROUTINE h5tbmake_table_f90 - - SUBROUTINE h5tbmake_table_ptr_f(table_title,& +#endif + +!> +!! \ingroup FH5TB +!! +!! \brief Creates and writes a dataset named \p dset_name attached to the object specified by the identifier \p loc_id. +!! +!! \note \fortran_approved +!! +!! \param table_title The title of the table +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to create +!! \param nfields The number of fields +!! \param nrecords The number of records +!! \param type_size The size in bytes of the structure associated with the table; This value is obtained with sizeof(). +!! \param field_names An array containing the names of the fields +!! \param field_offset An array containing the offsets of the fields +!! \param field_types An array containing the type of the fields +!! \param chunk_size The chunk size +!! \param fill_data Fill values data +!! \param compress Flag that turns compression on or off +!! \param data Buffer with data to be written to the table +!! \param errcode \fortran_error +!! +#ifdef H5_DOXYGEN_FORTRAN + SUBROUTINE h5tbmake_table_f(& +#else + SUBROUTINE h5tbmake_table_ptr_f(& +#endif + table_title,& loc_id,& dset_name,& nfields,& @@ -285,22 +355,22 @@ CONTAINS USE ISO_C_BINDING IMPLICIT NONE - CHARACTER(LEN=*), INTENT(in) :: table_title ! name of the dataset - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in) :: nfields ! fields - INTEGER(hsize_t), INTENT(in) :: nrecords ! records - INTEGER(size_t), INTENT(in) :: type_size ! type size - CHARACTER(LEN=*), DIMENSION(1:nfields), INTENT(in) :: field_names ! field names - INTEGER(size_t), DIMENSION(1:nfields), INTENT(in) :: field_offset ! field offset - INTEGER(hid_t), DIMENSION(1:nfields), INTENT(in) :: field_types ! field types - INTEGER(hsize_t), INTENT(in) :: chunk_size ! chunk size - TYPE(C_PTR), INTENT(in) :: fill_data ! Fill values data - INTEGER, INTENT(in) :: compress ! compress - TYPE(C_PTR), INTENT(in) :: data ! Buffer with data to be written to the table + CHARACTER(LEN=*), INTENT(in) :: table_title + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(in) :: nfields + INTEGER(hsize_t), INTENT(in) :: nrecords + INTEGER(size_t), INTENT(in) :: type_size + CHARACTER(LEN=*), DIMENSION(1:nfields), INTENT(in) :: field_names + INTEGER(size_t), DIMENSION(1:nfields), INTENT(in) :: field_offset + INTEGER(hid_t), DIMENSION(1:nfields), INTENT(in) :: field_types + INTEGER :: errcode + INTEGER(hsize_t), INTENT(in) :: chunk_size + TYPE(C_PTR), INTENT(in) :: fill_data + INTEGER, INTENT(in) :: compress + TYPE(C_PTR), INTENT(in) :: data INTEGER(size_t) :: namelen ! name length INTEGER(size_t) :: namelen1 ! name length - INTEGER :: errcode ! error code INTEGER(size_t), DIMENSION(1:nfields) :: char_len_field_names ! field name lengths INTEGER(size_t) :: max_char_size_field_names ! character len of field names INTEGER(hsize_t) :: i ! general purpose integer @@ -327,22 +397,22 @@ CONTAINS IMPORT :: C_CHAR, C_PTR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: table_title ! name of the dataset - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in) :: nfields ! fields - INTEGER(hsize_t), INTENT(in) :: nrecords ! records - INTEGER(size_t), INTENT(in) :: type_size ! type size - CHARACTER(KIND=C_CHAR), DIMENSION(nfields), INTENT(in) :: field_names ! field names - INTEGER(size_t), DIMENSION(nfields), INTENT(in) :: field_offset ! field offset - INTEGER(hid_t), DIMENSION(nfields), INTENT(in) :: field_types ! field types - INTEGER(hsize_t), INTENT(in) :: chunk_size ! chunk size - TYPE(C_PTR), INTENT(in), VALUE :: fill_data ! Fill values data - INTEGER, INTENT(in) :: compress ! compress - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: namelen1 ! name length - INTEGER(size_t), DIMENSION(nfields) :: char_len_field_names ! field name's lengths - INTEGER(size_t) :: max_char_size_field_names ! character len of field names + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: table_title + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(in) :: nfields + INTEGER(hsize_t), INTENT(in) :: nrecords + INTEGER(size_t), INTENT(in) :: type_size + CHARACTER(KIND=C_CHAR), DIMENSION(nfields), INTENT(in) :: field_names + INTEGER(size_t), DIMENSION(nfields), INTENT(in) :: field_offset + INTEGER(hid_t), DIMENSION(nfields), INTENT(in) :: field_types + INTEGER(hsize_t), INTENT(in) :: chunk_size + TYPE(C_PTR), INTENT(in), VALUE :: fill_data + INTEGER, INTENT(in) :: compress + INTEGER(size_t) :: namelen + INTEGER(size_t) :: namelen1 + INTEGER(size_t), DIMENSION(nfields) :: char_len_field_names + INTEGER(size_t) :: max_char_size_field_names TYPE(C_PTR), INTENT(in), VALUE :: data END FUNCTION h5tbmake_table_ptr_c END INTERFACE @@ -361,28 +431,44 @@ CONTAINS type_size, field_offset, field_types, chunk_size, fill_data, compress, char_len_field_names, & max_char_size_field_names, field_names, data) - END SUBROUTINE h5tbmake_table_ptr_f - - SUBROUTINE h5tbread_table_f(loc_id, table_name, nfields, dst_size, dst_offset, & +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5tbmake_table_f +#else + END SUBROUTINE h5tbmake_table_ptr_f +#endif +!> +!! \ingroup FH5TB +!! +!! \brief Reads a table. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to read +!! \param nfields Number of fields, i.e., size of dst_offset and dst_sizes arrays. +!! \param dst_size The size of the structure type, as calculated by sizeof or storage_size +!! \param dst_offset An array containing the offsets of the fields. These offsets can be calculated with H5OFFSETOF. +!! \param dst_sizes An array containing the sizes of the fields. These sizes can be calculated with sizeof or storage_size. +!! \param dst_buf Pointer to buffer with data. +!! \param errcode \fortran_error +!! + SUBROUTINE h5tbread_table_f(loc_id, dset_name, nfields, dst_size, dst_offset, & dst_sizes, dst_buf, errcode) USE ISO_C_BINDING IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! An array containing the sizes of the fields - CHARACTER(LEN=*), INTENT(in) :: table_name ! The name of the dataset to read - INTEGER(hsize_t), INTENT(in) :: nfields ! number of fields - INTEGER(size_t), INTENT(in) :: dst_size ! The size of the structure type - INTEGER(size_t), DIMENSION(1:nfields), INTENT(in) :: dst_offset ! An array containing the offsets of the fields - INTEGER(size_t), DIMENSION(1:nfields), INTENT(in) :: dst_sizes ! An array containing the sizes of the fields - TYPE(C_PTR) :: dst_buf ! Buffer with data !! do not use INTENT, causes NAG - ! to segfault in C APIs - INTEGER :: errcode ! error code - - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(in) :: nfields + INTEGER(size_t), INTENT(in) :: dst_size + INTEGER(size_t), DIMENSION(1:nfields), INTENT(in) :: dst_offset + INTEGER(size_t), DIMENSION(1:nfields), INTENT(in) :: dst_sizes + TYPE(C_PTR) :: dst_buf !!! do not use INTENT, causes NAG to segfault in C APIs + INTEGER :: errcode + + INTEGER(size_t) :: namelen ! name length INTERFACE INTEGER FUNCTION h5tbread_table_c(loc_id,& - table_name,& + dset_name,& namelen,& nfields,& dst_size,& @@ -393,22 +479,22 @@ CONTAINS IMPORT :: C_PTR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=1), INTENT(in) :: table_name ! name of the dataset + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=1), INTENT(in) :: dset_name INTEGER(hsize_t), INTENT(in) :: nfields - INTEGER(size_t), INTENT(in) :: dst_size ! type size - INTEGER(size_t), DIMENSION(1:nfields), INTENT(in) :: dst_offset ! An array containing the sizes of the fields - INTEGER(size_t), DIMENSION(1:nfields), INTENT(in) :: dst_sizes ! An array containing the sizes of the fields - INTEGER(size_t) :: namelen ! name length + INTEGER(size_t), INTENT(in) :: dst_size + INTEGER(size_t), DIMENSION(1:nfields), INTENT(in) :: dst_offset + INTEGER(size_t), DIMENSION(1:nfields), INTENT(in) :: dst_sizes + INTEGER(size_t) :: namelen TYPE(C_PTR), VALUE :: dst_buf END FUNCTION h5tbread_table_c END INTERFACE - namelen = LEN(table_name) + namelen = LEN(dset_name) errcode = h5tbread_table_c(loc_id,& - table_name,& + dset_name,& namelen, & nfields, & dst_size,& @@ -416,25 +502,28 @@ CONTAINS dst_sizes, & dst_buf) - END SUBROUTINE h5tbread_table_f -!------------------------------------------------------------------------- -! Function: h5tbwrite_field_name_f_int -! -! Purpose: Writes one field -! -! Programmer: Pedro Vicente -! -! Date: October 12, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - - SUBROUTINE h5tbwrite_field_name_f_int(loc_id,& +#ifdef H5_DOXYGEN_FORTRAN +!> +!! \ingroup FH5TB +!! +!! \brief Overwrites field. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to overwrite +!! \param field_name The names of the fields to write +!! \param start The zero index record to start writing +!! \param nrecords The number of records to write +!! \param type_size The size of the structure type, as calculated by sizeof or storage_size. +!! \param buf Buffer with data. +!! \param errcode \fortran_error +!! + SUBROUTINE h5tbwrite_field_name_f(& +#else + SUBROUTINE h5tbwrite_field_name_f_int(& +#endif + loc_id,& dset_name,& field_name,& start,& @@ -444,16 +533,20 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: field_name ! name of the field - INTEGER(hsize_t), INTENT(in) :: start ! start record - INTEGER(hsize_t), INTENT(in) :: nrecords ! records - INTEGER(size_t), INTENT(in) :: type_size ! type size - INTEGER, INTENT(in), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: namelen1 ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + CHARACTER(LEN=*), INTENT(in) :: field_name + INTEGER(hsize_t), INTENT(in) :: start + INTEGER(hsize_t), INTENT(in) :: nrecords + INTEGER(size_t), INTENT(in) :: type_size +#ifdef H5_DOXYGEN_FORTRAN + TYPE(TYPE), INTENT(in), DIMENSION(*) :: buf +#else + INTEGER, INTENT(in), DIMENSION(*), TARGET :: buf +#endif + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: namelen1 ! name length TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1)) @@ -462,10 +555,11 @@ CONTAINS errcode = h5tbwrite_field_name_c(loc_id,namelen,dset_name,namelen1,field_name,& start,nrecords,type_size,f_ptr) - +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5tbwrite_field_name_f +#else END SUBROUTINE h5tbwrite_field_name_f_int - SUBROUTINE h5tbwrite_field_name_f_string(loc_id,& dset_name,& field_name,& @@ -498,24 +592,28 @@ CONTAINS start,nrecords,type_size,f_ptr) END SUBROUTINE h5tbwrite_field_name_f_string - - -!------------------------------------------------------------------------- -! Function: h5tbread_field_name_f_int -! -! Purpose: Reads one field -! -! Programmer: Pedro Vicente -! -! Date: October 12, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - - SUBROUTINE h5tbread_field_name_f_int(loc_id,& +#endif + +#ifdef H5_DOXYGEN_FORTRAN +!> +!! \ingroup FH5TB +!! +!! \brief Reads one or several fields. The fields are identified by name. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to read. +!! \param field_name An array containing the names of the fields to read. +!! \param start The start record to read from. +!! \param nrecords The number of records to read. +!! \param type_size The size in bytes of the structure associated with the table. Obtained with sizeof or storage_size. +!! \param buf Buffer with data +!! \param errcode \fortran_error +!! + SUBROUTINE h5tbread_field_name_f(& +#else + SUBROUTINE h5tbread_field_name_f_int(& +#endif + loc_id,& dset_name,& field_name,& start,& @@ -526,19 +624,23 @@ CONTAINS IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: field_name ! name of the field - INTEGER(hsize_t), INTENT(in) :: start ! start record - INTEGER(hsize_t), INTENT(in) :: nrecords ! records - INTEGER(size_t), INTENT(in) :: type_size ! type size - INTEGER, INTENT(INOUT), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: namelen1 + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + CHARACTER(LEN=*), INTENT(in) :: field_name + INTEGER(hsize_t), INTENT(in) :: start + INTEGER(hsize_t), INTENT(in) :: nrecords + INTEGER(size_t), INTENT(in) :: type_size +#ifdef H5_DOXYGEN_FORTRAN + TYPE(TYPE), INTENT(INOUT), DIMENSION(*):: buf +#else + INTEGER, INTENT(INOUT), DIMENSION(*), TARGET :: buf +#endif + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: namelen1 ! name length TYPE(C_PTR) :: f_ptr - f_ptr = C_LOC(buf(1)) ! name length + f_ptr = C_LOC(buf(1)) namelen = LEN(dset_name) namelen1 = LEN(field_name) @@ -546,6 +648,9 @@ CONTAINS errcode = h5tbread_field_name_c(loc_id,namelen,dset_name,namelen1,field_name,& start,nrecords,type_size,f_ptr) +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5tbread_field_name_f +#else END SUBROUTINE h5tbread_field_name_f_int SUBROUTINE h5tbread_field_name_f_string(loc_id,& @@ -558,16 +663,16 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: field_name ! name of the field - INTEGER(hsize_t), INTENT(in) :: start ! start record - INTEGER(hsize_t), INTENT(in) :: nrecords ! records - INTEGER(size_t), INTENT(in) :: type_size ! type size - CHARACTER(LEN=*), INTENT(INOUT), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: namelen1 ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + CHARACTER(LEN=*), INTENT(in) :: field_name + INTEGER(hsize_t), INTENT(in) :: start + INTEGER(hsize_t), INTENT(in) :: nrecords + INTEGER(size_t), INTENT(in) :: type_size + CHARACTER(LEN=*), INTENT(INOUT), DIMENSION(*), TARGET :: buf + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: namelen1 ! name length TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1)(1:1)) @@ -579,24 +684,28 @@ CONTAINS start,nrecords,type_size,f_ptr) END SUBROUTINE h5tbread_field_name_f_string - - -!------------------------------------------------------------------------- -! Function: h5tbwrite_field_index_f_int -! -! Purpose: Writes one field -! -! Programmer: Pedro Vicente -! -! Date: October 12, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - - SUBROUTINE h5tbwrite_field_index_f_int(loc_id,& +#endif + +#ifdef H5_DOXYGEN_FORTRAN +!> +!! \ingroup FH5TB +!! +!! \brief Overwrites a field. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to overwrite. +!! \param field_index The indexe of the fields to write. +!! \param start The zero based index record to start writing. +!! \param nrecords The number of records to write. +!! \param type_size The size of the structure type, as calculated by sizeof or storage_size. +!! \param buf Buffer with data. +!! \param errcode \fortran_error +!! + SUBROUTINE h5tbwrite_field_index_f(& +#else + SUBROUTINE h5tbwrite_field_index_f_int(& +#endif + loc_id,& dset_name,& field_index,& start,& @@ -606,15 +715,19 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: field_index ! index - INTEGER(hsize_t), INTENT(in) :: start ! start record - INTEGER(hsize_t), INTENT(in) :: nrecords ! records - INTEGER(size_t), INTENT(in) :: type_size ! type size - INTEGER, INTENT(in), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: field_index + INTEGER(hsize_t), INTENT(in) :: start + INTEGER(hsize_t), INTENT(in) :: nrecords + INTEGER(size_t), INTENT(in) :: type_size +#ifdef H5_DOXYGEN_FORTRAN + INTEGER, INTENT(in), DIMENSION(*) :: buf +#else + INTEGER, INTENT(in), DIMENSION(*), TARGET :: buf +#endif + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1)) @@ -624,6 +737,9 @@ CONTAINS errcode = h5tbwrite_field_index_c(loc_id,namelen,dset_name,field_index,& start,nrecords,type_size,f_ptr) +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5tbwrite_field_index_f +#else END SUBROUTINE h5tbwrite_field_index_f_int SUBROUTINE h5tbwrite_field_index_f_string(loc_id,& @@ -636,15 +752,15 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: field_index ! index - INTEGER(hsize_t), INTENT(in) :: start ! start record - INTEGER(hsize_t), INTENT(in) :: nrecords ! records - INTEGER(size_t), INTENT(in) :: type_size ! type size - CHARACTER(LEN=*), INTENT(in), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: field_index + INTEGER(hsize_t), INTENT(in) :: start + INTEGER(hsize_t), INTENT(in) :: nrecords + INTEGER(size_t), INTENT(in) :: type_size + CHARACTER(LEN=*), INTENT(in), DIMENSION(*), TARGET :: buf + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1)(1:1)) @@ -654,24 +770,28 @@ CONTAINS start,nrecords,type_size,f_ptr) END SUBROUTINE h5tbwrite_field_index_f_string - - -!------------------------------------------------------------------------- -! Function: h5tbread_field_index_f_int -! -! Purpose: Reads one field -! -! Programmer: Pedro Vicente -! -! Date: October 12, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - - SUBROUTINE h5tbread_field_index_f_int(loc_id,& +#endif + +#ifdef H5_DOXYGEN_FORTRAN +!> +!! \ingroup FH5TB +!! +!! \brief Reads field. The fields are identified by index. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to read. +!! \param field_index The indexes of the fields to read. +!! \param start The start record to read from. +!! \param nrecords The number of records to read. +!! \param type_size The size in bytes of the structure associated with the table. Obtained with sizeof or storage_size. +!! \param buf Buffer with data. +!! \param errcode \fortran_error +!! + SUBROUTINE h5tbread_field_index_f(& +#else + SUBROUTINE h5tbread_field_index_f_int(& +#endif + loc_id,& dset_name,& field_index,& start,& @@ -681,15 +801,19 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: field_index ! index - INTEGER(hsize_t), INTENT(in) :: start ! start record - INTEGER(hsize_t), INTENT(in) :: nrecords ! records - INTEGER(size_t), INTENT(in) :: type_size ! type size - INTEGER, INTENT(INOUT), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: field_index + INTEGER(hsize_t), INTENT(in) :: start + INTEGER(hsize_t), INTENT(in) :: nrecords + INTEGER(size_t), INTENT(in) :: type_size +#ifdef H5_DOXYGEN_FORTRAN + TYPE(TYPE), INTENT(INOUT), DIMENSION(*) :: buf +#else + INTEGER, INTENT(INOUT), DIMENSION(*), TARGET :: buf +#endif + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1)) @@ -697,7 +821,9 @@ CONTAINS errcode = h5tbread_field_index_c(loc_id,namelen,dset_name,field_index,& start,nrecords,type_size,f_ptr) - +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5tbread_field_index_f +#else END SUBROUTINE h5tbread_field_index_f_int SUBROUTINE h5tbread_field_index_f_string(loc_id,& @@ -710,15 +836,15 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER, INTENT(in) :: field_index ! index - INTEGER(hsize_t), INTENT(in) :: start ! start record - INTEGER(hsize_t), INTENT(in) :: nrecords ! records - INTEGER(size_t), INTENT(in) :: type_size ! type size - CHARACTER(LEN=*), INTENT(INOUT), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER, INTENT(in) :: field_index + INTEGER(hsize_t), INTENT(in) :: start + INTEGER(hsize_t), INTENT(in) :: nrecords + INTEGER(size_t), INTENT(in) :: type_size + CHARACTER(LEN=*), INTENT(INOUT), DIMENSION(*), TARGET :: buf + INTEGER :: errcode + INTEGER(size_t) :: namelen TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1)(1:1)) @@ -728,39 +854,48 @@ CONTAINS start,nrecords,type_size,f_ptr) END SUBROUTINE h5tbread_field_index_f_string - -!------------------------------------------------------------------------- -! Function: h5tbinsert_field_f -! -! Purpose: Inserts one field -! -! Programmer: Pedro Vicente -! -! Date: October 13, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - - SUBROUTINE h5tbinsert_field_f_int(loc_id,& +#endif + +#ifdef H5_DOXYGEN_FORTRAN +!> +!! \ingroup FH5TB +!! +!! \brief Insert a new field into a table. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the table. +!! \param field_name The name of the field to insert. +!! \param field_type The data type of the field. +!! \param position The zero based index position where to insert the field. +!! \param buf Buffer with data. +!! \param errcode \fortran_error +!! + SUBROUTINE h5tbinsert_field_f(& +#else + SUBROUTINE h5tbinsert_field_f_int(& +#endif + loc_id,& dset_name,& field_name,& field_type,& - field_index,& + position,& buf,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: field_name ! name of the field - INTEGER(hid_t), INTENT(in) :: field_type ! field type - INTEGER, INTENT(in) :: field_index ! field_index - INTEGER, INTENT(in), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: namelen1 ! name length - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + CHARACTER(LEN=*), INTENT(in) :: field_name + INTEGER(hid_t), INTENT(in) :: field_type + INTEGER, INTENT(in) :: position +#ifdef H5_DOXYGEN_FORTRAN + TYPE(TYPE), INTENT(in), DIMENSION(*) :: buf +#else + INTEGER, INTENT(in), DIMENSION(*), TARGET :: buf +#endif + INTEGER :: errcode + + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: namelen1 ! name length TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1)) @@ -769,27 +904,31 @@ CONTAINS namelen1 = LEN(field_name) errcode = h5tbinsert_field_c(loc_id,namelen,dset_name,namelen1,field_name,& - field_type,field_index,f_ptr) + field_type,position,f_ptr) +#ifdef H5_DOXYGEN_FORTRAN + END SUBROUTINE h5tbinsert_field_f +#else END SUBROUTINE h5tbinsert_field_f_int SUBROUTINE h5tbinsert_field_f_string(loc_id,& dset_name,& field_name,& field_type,& - field_index,& + position,& buf,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: field_name ! name of the field - INTEGER(hid_t), INTENT(in) :: field_type ! field type - INTEGER, INTENT(in) :: field_index ! field_index - CHARACTER(LEN=*), INTENT(in), DIMENSION(*), TARGET :: buf ! data buffer - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: namelen1 ! name length - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + CHARACTER(LEN=*), INTENT(in) :: field_name + INTEGER(hid_t), INTENT(in) :: field_type + INTEGER, INTENT(in) :: position + CHARACTER(LEN=*), INTENT(in), DIMENSION(*), TARGET :: buf + INTEGER :: errcode + + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: namelen1 ! name length TYPE(C_PTR) :: f_ptr f_ptr = C_LOC(buf(1)(1:1)) @@ -798,36 +937,33 @@ CONTAINS namelen1 = LEN(field_name) errcode = h5tbinsert_field_c(loc_id,namelen,dset_name,namelen1,field_name,& - field_type,field_index,f_ptr) + field_type,position,f_ptr) END SUBROUTINE h5tbinsert_field_f_string - -!------------------------------------------------------------------------- -! Function: h5tbdelete_field_f -! -! Purpose: Inserts one field -! -! Programmer: Pedro Vicente -! -! Date: October 13, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +#endif + +!> +!! \ingroup FH5TB +!! +!! \brief Deletes a field from a table. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the table. +!! \param field_name The name of the field to delete. +!! \param errcode \fortran_error +!! SUBROUTINE h5tbdelete_field_f(loc_id,& dset_name,& field_name,& errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - CHARACTER(LEN=*), INTENT(in) :: field_name ! name of the field - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: namelen1 ! name length - INTEGER :: errcode ! error code + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + CHARACTER(LEN=*), INTENT(in) :: field_name + INTEGER :: errcode + + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t) :: namelen1 ! name length INTERFACE @@ -836,11 +972,11 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(HID_T), INTENT(IN) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: dset_name ! name of the dataset - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: field_name ! name of the field - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: namelen1 ! name length length + INTEGER(HID_T), INTENT(IN) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: dset_name + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(IN) :: field_name + INTEGER(size_t) :: namelen + INTEGER(size_t) :: namelen1 END FUNCTION h5tbdelete_field_c END INTERFACE @@ -850,24 +986,17 @@ CONTAINS errcode = h5tbdelete_field_c(loc_id,namelen,dset_name,namelen1,field_name) END SUBROUTINE h5tbdelete_field_f - -!------------------------------------------------------------------------- -! Function: h5tbget_table_info_f -! -! Purpose: Gets the number of records and fields of a table -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 13, 2004 -! -! Comments: -! -! Modifications: -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5TB +!! +!! \brief Gets the table dimensions. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to read. +!! \param nfields The number of fields. +!! \param nrecords The number of records. +!! \param errcode \fortran_error +!! SUBROUTINE h5tbget_table_info_f(loc_id,& dset_name,& nfields,& @@ -875,12 +1004,12 @@ CONTAINS errcode ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(inout):: nfields ! nfields - INTEGER(hsize_t), INTENT(inout):: nrecords ! nrecords - INTEGER :: errcode ! error code - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(inout):: nfields + INTEGER(hsize_t), INTENT(inout):: nrecords + INTEGER :: errcode + INTEGER(size_t) :: namelen ! name length INTERFACE INTEGER FUNCTION h5tbget_table_info_c(loc_id,namelen,dset_name,nfields,nrecords) & @@ -888,11 +1017,11 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(inout):: nfields ! nfields - INTEGER(hsize_t), INTENT(inout):: nrecords ! nrecords - INTEGER(size_t) :: namelen ! name length + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(inout):: nfields + INTEGER(hsize_t), INTENT(inout):: nrecords + INTEGER(size_t) :: namelen END FUNCTION h5tbget_table_info_c END INTERFACE @@ -901,26 +1030,22 @@ CONTAINS END SUBROUTINE h5tbget_table_info_f - -!------------------------------------------------------------------------- -! Function: h5tbget_field_info_f -! -! Purpose: Get information about fields -! -! Return: Success: 0, Failure: -1 -! -! Programmer: Pedro Vicente -! -! Date: October 13, 2004 -! -! Comments: -! -! Modifications: -! Added optional parameter for returning the maximum character length -! in the field name array. March 3, 2011 -! -!------------------------------------------------------------------------- - +!> +!! \ingroup FH5TB +!! +!! \brief Gets information about a table. +!! +!! \param loc_id Location identifier. The identifier may be that of a file or group. +!! \param dset_name The name of the dataset to read. +!! \param nfields The number of fields. +!! \param field_names An array containing the names of the fields. +!! \param field_sizes An array containing the size of the fields. +!! \param field_offsets An array containing the offsets of the fields. +!! \param type_size The size of the HDF5 datatype associated with the table +!! (i.e., the size in bytes of the HDF5 compound datatype used to define a row, or record, in the table). +!! \param errcode \fortran_error +!! \param maxlen_out Maximum character length of the field names. +!! SUBROUTINE h5tbget_field_info_f(loc_id,& dset_name,& nfields,& @@ -931,18 +1056,18 @@ CONTAINS errcode, maxlen_out ) IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(LEN=*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in) :: nfields ! nfields - CHARACTER(LEN=*), DIMENSION(nfields), INTENT(inout) :: field_names ! field names - INTEGER(size_t), DIMENSION(nfields), INTENT(inout) :: field_sizes ! field sizes - INTEGER(size_t), DIMENSION(nfields), INTENT(inout) :: field_offsets ! field offsets - INTEGER(size_t), INTENT(inout):: type_size ! type size - INTEGER :: errcode ! error code - INTEGER(size_t), OPTIONAL :: maxlen_out ! maximum character len of the field names - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t), DIMENSION(nfields) :: namelen2 ! name lengths - INTEGER(hsize_t) :: i ! general purpose integer + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(LEN=*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(in) :: nfields + CHARACTER(LEN=*), DIMENSION(nfields), INTENT(inout) :: field_names + INTEGER(size_t), DIMENSION(nfields), INTENT(inout) :: field_sizes + INTEGER(size_t), DIMENSION(nfields), INTENT(inout) :: field_offsets + INTEGER(size_t), INTENT(inout):: type_size + INTEGER :: errcode + INTEGER(size_t), OPTIONAL :: maxlen_out + INTEGER(size_t) :: namelen ! name length + INTEGER(size_t), DIMENSION(nfields) :: namelen2 ! name lengths + INTEGER(hsize_t) :: i INTEGER(size_t) :: maxlen INTEGER(size_t) :: c_maxlen_out @@ -953,17 +1078,17 @@ CONTAINS IMPORT :: C_CHAR IMPORT :: HID_T, SIZE_T, HSIZE_T IMPLICIT NONE - INTEGER(hid_t), INTENT(in) :: loc_id ! file or group identifier - CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name ! name of the dataset - INTEGER(hsize_t), INTENT(in):: nfields ! nfields - CHARACTER(KIND=C_CHAR), DIMENSION(1:nfields), INTENT(inout) :: field_names ! field names - INTEGER(size_t), DIMENSION(1:nfields), INTENT(inout) :: field_sizes ! field sizes - INTEGER(size_t), DIMENSION(1:nfields), INTENT(inout) :: field_offsets ! field offsets - INTEGER(size_t), INTENT(inout):: type_size ! type size - INTEGER(size_t) :: namelen ! name length - INTEGER(size_t) :: maxlen ! maximum length of input field names - INTEGER(size_t), DIMENSION(1:nfields) :: namelen2 ! name lengths - INTEGER(size_t) :: c_maxlen_out ! maximum character length of a field array element + INTEGER(hid_t), INTENT(in) :: loc_id + CHARACTER(KIND=C_CHAR), DIMENSION(*), INTENT(in) :: dset_name + INTEGER(hsize_t), INTENT(in):: nfields + CHARACTER(KIND=C_CHAR), DIMENSION(1:nfields), INTENT(inout) :: field_names + INTEGER(size_t), DIMENSION(1:nfields), INTENT(inout) :: field_sizes + INTEGER(size_t), DIMENSION(1:nfields), INTENT(inout) :: field_offsets + INTEGER(size_t), INTENT(inout):: type_size + INTEGER(size_t) :: namelen + INTEGER(size_t) :: maxlen + INTEGER(size_t), DIMENSION(1:nfields) :: namelen2 + INTEGER(size_t) :: c_maxlen_out END FUNCTION h5tbget_field_info_c END INTERFACE @@ -981,7 +1106,11 @@ CONTAINS END SUBROUTINE h5tbget_field_info_f +#ifdef H5_DOXYGEN_FORTRAN +END MODULE H5TB +#else END MODULE H5TB_CONST +#endif diff --git a/hl/src/H5DOpublic.h b/hl/src/H5DOpublic.h index 13b2422..20f4c98 100644 --- a/hl/src/H5DOpublic.h +++ b/hl/src/H5DOpublic.h @@ -18,7 +18,11 @@ extern "C" { #endif -/**\defgroup H5DO Optimizations +/** \page H5DO_UG The HDF5 High Level Optimizations + * @todo Under Construction + */ + +/**\defgroup H5DO HDF5 Optimizations APIs (H5DO) * * Bypassing default HDF5 behavior in order to optimize for specific * use cases (H5DO) diff --git a/hl/src/H5DSpublic.h b/hl/src/H5DSpublic.h index e34535d..4fcf681 100644 --- a/hl/src/H5DSpublic.h +++ b/hl/src/H5DSpublic.h @@ -31,7 +31,11 @@ typedef herr_t (*H5DS_iterate_t)(hid_t dset, unsigned dim, hid_t scale, void *vi extern "C" { #endif -/**\defgroup H5DS Dimension Scales +/** \page H5DS_UG The HDF5 High Level Dimension Scales + * @todo Under Construction + */ + +/**\defgroup H5DS HDF5 Dimension Scales APIs (H5DS) * * Creating and manipulating HDF5 datasets that are associated with * the dimension of another HDF5 dataset (H5DS) diff --git a/hl/src/H5IMpublic.h b/hl/src/H5IMpublic.h index b5426d6..bccf3c4 100644 --- a/hl/src/H5IMpublic.h +++ b/hl/src/H5IMpublic.h @@ -18,7 +18,11 @@ extern "C" { #endif -/**\defgroup H5IM Images +/** \page H5IM_UG The HDF5 High Level Images + * @todo Under Construction + */ + +/**\defgroup H5IM HDF5 Images API (H5IM) * * Creating and manipulating HDF5 datasets intended to be * interpreted as images (H5IM) @@ -27,7 +31,7 @@ extern "C" { * document: \ref IMG * This version of the API is primarily concerned with two dimensional raster * data similar to HDF4 Raster Images. - * The HDF5 Images API uses the \ref H5LT HDF5 API. + * The HDF5 Images API uses the \ref H5LT. * * \note \Bold{Programming hints:} * \note To use any of these functions or subroutines, diff --git a/hl/src/H5LTpublic.h b/hl/src/H5LTpublic.h index 6e25afa..15cd845 100644 --- a/hl/src/H5LTpublic.h +++ b/hl/src/H5LTpublic.h @@ -35,7 +35,11 @@ typedef enum H5LT_lang_t { extern "C" { #endif -/**\defgroup H5LT Lite +/** \page H5LT_UG The HDF5 High Level Lite + * @todo Under Construction + */ + +/**\defgroup H5LT HDF5 Lite APIs (H5LT,H5LD) * Functions used to simplify creating and manipulating datasets, * attributes and other features (H5LT, H5LD) * diff --git a/hl/src/H5PTpublic.h b/hl/src/H5PTpublic.h index 185e4a4..6552aa9 100644 --- a/hl/src/H5PTpublic.h +++ b/hl/src/H5PTpublic.h @@ -18,7 +18,11 @@ extern "C" { #endif -/**\defgroup H5PT Packet Table +/** \page H5PT_UG The HDF5 High Level Packet Table + * @todo Under Construction + */ + +/**\defgroup H5PT HDF5 Packet Table APIs (H5PT) * * Creating and manipulating HDF5 datasets to support append- * and read-only operations on table data (H5PT) diff --git a/hl/src/H5TBpublic.h b/hl/src/H5TBpublic.h index dc0e31a..44b122c 100644 --- a/hl/src/H5TBpublic.h +++ b/hl/src/H5TBpublic.h @@ -18,7 +18,11 @@ extern "C" { #endif -/**\defgroup H5TB Table +/** \page H5TB_UG The HDF5 High Level Table + * @todo Under Construction + */ + +/**\defgroup H5TB HDF5 Table APIs (H5TB) * * Creating and manipulating HDF5 datasets intended to be * interpreted as tables (H5TB) diff --git a/java/src/hdf/hdf5lib/H5.java b/java/src/hdf/hdf5lib/H5.java index e701be3..ec9ba04 100644 --- a/java/src/hdf/hdf5lib/H5.java +++ b/java/src/hdf/hdf5lib/H5.java @@ -247,6 +247,10 @@ import hdf.hdf5lib.structs.H5O_token_t; * This code is the called by Java programs to access the entry points of the HDF5 library. Each routine wraps * a single HDF5 entry point, generally with the arguments and return codes analogous to the C interface. * + * @see H5, C-API + * + * @see @ref H5_UG, User Guide + * */ public class H5 implements java.io.Serializable { /** @@ -585,6 +589,8 @@ public class H5 implements java.io.Serializable { throws HDF5LibraryException; /** + * @ingroup JH5 + * * H5export_attribute is a utility function to save data in a file. * * @param file_export_name @@ -2447,6 +2453,10 @@ public class H5 implements java.io.Serializable { // //////////////////////////////////////////////////////////// /** * @defgroup JH5D Java Datasets (H5D) Interface + * + * @see H5D, C-API + * + * @see @ref H5D_UG, User Guide **/ /** @@ -4227,6 +4237,10 @@ public class H5 implements java.io.Serializable { /** * * @defgroup JH5E Java Error (H5E) Interface + * + * @see H5E, C-API + * + * @see @ref H5E_UG, User Guide */ /** @@ -4645,6 +4659,10 @@ public class H5 implements java.io.Serializable { /** * * @defgroup JH5F Java File (H5F) Interface + * + * @see H5F, C-API + * + * @see @ref H5F_UG, User Guide */ /** @@ -5389,6 +5407,10 @@ public class H5 implements java.io.Serializable { // //////////////////////////////////////////////////////////// /** * @defgroup JH5G Java Group (H5G) Interface + * + * @see H5G, C-API + * + * @see @ref H5G_UG, User Guide **/ /** @@ -6000,6 +6022,10 @@ public class H5 implements java.io.Serializable { // //////////////////////////////////////////////////////////// /** * @defgroup JH5I Java Identifier (H5I) Interface + * + * @see H5I, C-API + * + * @see @ref H5I_UG, User Guide **/ /** @@ -6265,6 +6291,10 @@ public class H5 implements java.io.Serializable { // ////////////////////////////////////////////////////////////////// /** * @defgroup JH5L Java Link (H5L) Interface + * + * @see H5L, C-API + * + * @see @ref H5L_UG, User Guide **/ /** @@ -6800,6 +6830,10 @@ public class H5 implements java.io.Serializable { // //////////////////////////////////////////////////////////// /** * @defgroup JH5O Java Object (H5O) Interface + * + * @see H5O, C-API + * + * @see @ref H5O_UG, User Guide **/ /** @@ -7344,6 +7378,8 @@ public class H5 implements java.io.Serializable { public synchronized static native void H5Oincr_refcount(long object_id) throws HDF5LibraryException; /** + * @ingroup JH5O + * * H5Oopen_by_token opens a group, dataset, or named datatype using its object token within an HDF5 file. * * @param loc_id @@ -7529,14 +7565,20 @@ public class H5 implements java.io.Serializable { /** * @ingroup JH5O * - * H5Oget_native_info_by_name retrieves the native HDF5-specific metadata for an HDF5 object, identifying - * the object by location and relative name. Native HDF5-specific metadata includes things like object - * header information and object storage layout information. + * H5Oget_native_info_by_idx retrieves the native HDF5-specific metadata for an HDF5 object, identifying + * the object by an index position. Native HDF5-specific metadata includes things like object header + * information and object storage layout information. * * @param loc_id - * IN: File or group identifier specifying location of group in which object is located - * @param name - * IN: Relative name of group + * IN: File or group identifier + * @param group_name + * IN: Name of group, relative to loc_id, in which object is located + * @param idx_type + * IN: Type of index by which objects are ordered + * @param order + * IN: Order of iteration within index + * @param n + * IN: Object to open * @param lapl_id * IN: Access property list identifier for the link pointing to the object (Not currently used; * pass as H5P_DEFAULT.) @@ -7548,23 +7590,31 @@ public class H5 implements java.io.Serializable { * @exception NullPointerException * name is null. **/ - public static H5O_native_info_t H5Oget_native_info_by_name(long loc_id, String name, long lapl_id) + public static H5O_native_info_t H5Oget_native_info_by_idx(long loc_id, String group_name, int idx_type, + int order, long n, long lapl_id) throws HDF5LibraryException, NullPointerException { - return H5Oget_native_info_by_name(loc_id, name, HDF5Constants.H5O_NATIVE_INFO_ALL, lapl_id); + return H5Oget_native_info_by_idx(loc_id, group_name, idx_type, order, n, + HDF5Constants.H5O_NATIVE_INFO_ALL, lapl_id); } /** * @ingroup JH5O * - * H5Oget_native_info_by_name retrieves the native HDF5-specific metadata for an HDF5 object, identifying - * the object by location and relative name. Native HDF5-specific metadata includes things like object - * header information and object storage layout information. + * H5Oget_native_info_by_idx retrieves the native HDF5-specific metadata for an HDF5 object, identifying + * the object by an index position. Native HDF5-specific metadata includes things like object header + * information and object storage layout information. * * @param loc_id - * IN: File or group identifier specifying location of group in which object is located - * @param name - * IN: Relative name of group + * IN: File or group identifier + * @param group_name + * IN: Name of group, relative to loc_id, in which object is located + * @param idx_type + * IN: Type of index by which objects are ordered + * @param order + * IN: Order of iteration within index + * @param n + * IN: Object to open * @param fields * IN: Object fields to select * @param lapl_id @@ -7578,27 +7628,21 @@ public class H5 implements java.io.Serializable { * @exception NullPointerException * name is null. **/ - public synchronized static native H5O_native_info_t H5Oget_native_info_by_name(long loc_id, String name, - int fields, long lapl_id) + public synchronized static native H5O_native_info_t H5Oget_native_info_by_idx( + long loc_id, String group_name, int idx_type, int order, long n, int fields, long lapl_id) throws HDF5LibraryException, NullPointerException; /** * @ingroup JH5O * - * H5Oget_native_info_by_idx retrieves the native HDF5-specific metadata for an HDF5 object, identifying - * the object by an index position. Native HDF5-specific metadata includes things like object header - * information and object storage layout information. + * H5Oget_native_info_by_name retrieves the native HDF5-specific metadata for an HDF5 object, identifying + * the object by location and relative name. Native HDF5-specific metadata includes things like object + * header information and object storage layout information. * * @param loc_id - * IN: File or group identifier - * @param group_name - * IN: Name of group, relative to loc_id, in which object is located - * @param idx_type - * IN: Type of index by which objects are ordered - * @param order - * IN: Order of iteration within index - * @param n - * IN: Object to open + * IN: File or group identifier specifying location of group in which object is located + * @param name + * IN: Relative name of group * @param lapl_id * IN: Access property list identifier for the link pointing to the object (Not currently used; * pass as H5P_DEFAULT.) @@ -7610,31 +7654,23 @@ public class H5 implements java.io.Serializable { * @exception NullPointerException * name is null. **/ - public static H5O_native_info_t H5Oget_native_info_by_idx(long loc_id, String group_name, int idx_type, - int order, long n, long lapl_id) + public static H5O_native_info_t H5Oget_native_info_by_name(long loc_id, String name, long lapl_id) throws HDF5LibraryException, NullPointerException { - return H5Oget_native_info_by_idx(loc_id, group_name, idx_type, order, n, - HDF5Constants.H5O_NATIVE_INFO_ALL, lapl_id); + return H5Oget_native_info_by_name(loc_id, name, HDF5Constants.H5O_NATIVE_INFO_ALL, lapl_id); } /** * @ingroup JH5O * - * H5Oget_native_info_by_idx retrieves the native HDF5-specific metadata for an HDF5 object, identifying - * the object by an index position. Native HDF5-specific metadata includes things like object header - * information and object storage layout information. + * H5Oget_native_info_by_name retrieves the native HDF5-specific metadata for an HDF5 object, identifying + * the object by location and relative name. Native HDF5-specific metadata includes things like object + * header information and object storage layout information. * * @param loc_id - * IN: File or group identifier - * @param group_name - * IN: Name of group, relative to loc_id, in which object is located - * @param idx_type - * IN: Type of index by which objects are ordered - * @param order - * IN: Order of iteration within index - * @param n - * IN: Object to open + * IN: File or group identifier specifying location of group in which object is located + * @param name + * IN: Relative name of group * @param fields * IN: Object fields to select * @param lapl_id @@ -7648,8 +7684,8 @@ public class H5 implements java.io.Serializable { * @exception NullPointerException * name is null. **/ - public synchronized static native H5O_native_info_t H5Oget_native_info_by_idx( - long loc_id, String group_name, int idx_type, int order, long n, int fields, long lapl_id) + public synchronized static native H5O_native_info_t H5Oget_native_info_by_name(long loc_id, String name, + int fields, long lapl_id) throws HDF5LibraryException, NullPointerException; // /////// unimplemented //////// @@ -7665,6 +7701,13 @@ public class H5 implements java.io.Serializable { // //////////////////////////////////////////////////////////// // /////// Generic property list routines /////// + /** + * @defgroup JH5P Java Property List (H5P) Interface + * + * @see H5P, C-API + * + * @see @ref H5P_UG, User Guide + **/ /** * @ingroup JH5P @@ -11768,6 +11811,10 @@ public class H5 implements java.io.Serializable { // //////////////////////////////////////////////////////////// /** * @defgroup JH5PL Java Plugin (H5PL) Interface + * + * @see H5PL, C-API + * + * @see @ref H5PL_UG, User Guide **/ /** @@ -11921,6 +11968,10 @@ public class H5 implements java.io.Serializable { /** * @defgroup JH5R Java Reference (H5R) Interface + * + * @see H5R, C-API + * + * @see @ref H5R_UG, User Guide **/ private synchronized static native int H5Rcreate(byte[] ref, long loc_id, String name, int ref_type, @@ -11956,9 +12007,9 @@ public class H5 implements java.io.Serializable { { /* These sizes are correct for HDF5.1.2 */ int ref_size = 8; - if (ref_type == HDF5Constants.H5R_DATASET_REGION) { + if (ref_type == HDF5Constants.H5R_DATASET_REGION) ref_size = 12; - } + byte rbuf[] = new byte[ref_size]; /* will raise an exception if fails */ @@ -12025,14 +12076,12 @@ public class H5 implements java.io.Serializable { * @return Returns the length of the name if successful, returning 0 (zero) if no name is associated with * the identifier. Otherwise returns a negative value. * - * * @exception HDF5LibraryException * Error from the HDF5 Library. * @exception NullPointerException * size is null. * @exception IllegalArgumentException * Argument is illegal. - * **/ public synchronized static native long H5Rget_name(long loc_id, int ref_type, byte[] ref, String[] name, long size) @@ -12081,9 +12130,9 @@ public class H5 implements java.io.Serializable { * @exception HDF5LibraryException * Error from the HDF5 Library. * @exception NullPointerException - * array is null. + * an input array is null. * @exception IllegalArgumentException - * array is invalid. + * an input array is invalid. **/ public synchronized static native int H5Rget_obj_type(long loc_id, int ref_type, byte ref[]) throws HDF5LibraryException, NullPointerException, IllegalArgumentException; @@ -12117,9 +12166,9 @@ public class H5 implements java.io.Serializable { * @exception HDF5LibraryException * Error from the HDF5 Library. * @exception NullPointerException - * output array is null. + * an input array is null. * @exception IllegalArgumentException - * output array is invalid. + * an input array is invalid. **/ public static long H5Rget_region(long loc_id, int ref_type, byte[] ref) throws HDF5LibraryException, NullPointerException, IllegalArgumentException @@ -12525,6 +12574,14 @@ public class H5 implements java.io.Serializable { // //////////////////////////////////////////////////////////// /** * @defgroup JH5S Java Dataspace (H5S) Interface + * + * @see H5S, C-API + * + * @see @ref H5S_UG, User Guide + **/ + + /** + * @defgroup JH5S Java Dataspace (H5S) Interface **/ /**************** Operations on dataspaces ********************/ @@ -13507,6 +13564,14 @@ public class H5 implements java.io.Serializable { // //////////////////////////////////////////////////////////// /** * @defgroup JH5T Java Datatype (H5T) Interface + * + * @see H5T, C-API + * + * @see @ref H5T_UG, User Guide + **/ + + /** + * @defgroup JH5T Java Datatype (H5T) Interface **/ /** @@ -15233,6 +15298,15 @@ public class H5 implements java.io.Serializable { // H5VL: VOL Interface Functions // // // // //////////////////////////////////////////////////////////// + + /** + * @defgroup JH5VL Java VOL Connector (H5VL) Interface + * + * @see H5VL, C-API + * + * @see @ref H5VL_UG, User Guide + **/ + /** * @defgroup JH5VL Java VOL Connector (H5VL) Interface **/ @@ -15401,6 +15475,10 @@ public class H5 implements java.io.Serializable { // //////////////////////////////////////////////////////////// /** * @defgroup JH5Z Java Filter (H5Z) Interface + * + * @see H5Z, C-API + * + * @see @ref H5Z_UG, User Guide **/ /** diff --git a/src/H5ACpublic.h b/src/H5ACpublic.h index 42bc090..f9da6f6 100644 --- a/src/H5ACpublic.h +++ b/src/H5ACpublic.h @@ -563,7 +563,7 @@ typedef struct H5AC_cache_config_t { * The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to * start in the serial case. In the parallel case, a larger value is needed * -- see the overview of the metadata cache in the - * “Metadata Caching in HDF5” section of the -- HDF5 User’s Guide + * “Metadata Caching in HDF5” section of the -- \ref UG * for details. */ size_t max_size; @@ -760,7 +760,7 @@ typedef struct H5AC_cache_image_config_t { * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX (100). * * \ref H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE means that no limit is - * imposed on number of times a prefeteched entry can appear in subsequent + * imposed on number of times a prefetched entry can appear in subsequent * cache images. * * A value of 0 prevents prefetched entries from being included in cache diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index d39e2c6..db628a3 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -360,7 +360,7 @@ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t d * -------------------------------------------------------------------------- * \ingroup H5D * - * \brief Creates a new dataset and links it into the file + * \brief Opens an existing dataset * * \fgdta_loc_id * \param[in] name Name of the dataset to open diff --git a/src/H5Emodule.h b/src/H5Emodule.h index 5abdb6a..c827d70 100644 --- a/src/H5Emodule.h +++ b/src/H5Emodule.h @@ -84,24 +84,24 @@ * an error stack ID is needed as a parameter, \ref H5E_DEFAULT can be used to indicate the library’s default * stack. The first error record of the error stack, number #000, is produced by the API function itself and * is usually sufficient to indicate to the application what went wrong. - * - * - * - * + * + *
Example: An Error Message
- *

If an application calls \ref H5Tclose on a + * + * + * + * - * - *
Example: An Error Message
+ *

If an application calls \ref H5Tclose on a * predefined datatype then the following message is * printed on the standard error stream. This is a * simple error that has only one component, the API * function; other errors may have many components. - * 

+ *         
  * HDF5-DIAG: Error detected in HDF5 (1.10.9) thread 0.
  *    #000: H5T.c line ### in H5Tclose(): predefined datatype
  *       major: Function argument
  *       minor: Bad value
- *       

- *
+ * + *

* In the example above, we can see that an error record has a major message and a minor message. A major * message generally indicates where the error happens. The location can be a dataset or a dataspace, for * example. A minor message explains further details of the error. An example is “unable to open file”. diff --git a/src/H5Imodule.h b/src/H5Imodule.h index 1ad9f1b..71b8f7d 100644 --- a/src/H5Imodule.h +++ b/src/H5Imodule.h @@ -29,6 +29,10 @@ #define H5_MY_PKG_ERR H5E_ATOM #define H5_MY_PKG_INIT NO +/** \page H5I_UG The HDF5 Identifiers + * @todo Under Construction + */ + /** * \defgroup H5I Identifiers (H5I) * diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h index f61b891..f373ba1 100644 --- a/src/H5Lmodule.h +++ b/src/H5Lmodule.h @@ -29,6 +29,10 @@ #define H5_MY_PKG_ERR H5E_LINK #define H5_MY_PKG_INIT YES +/** \page H5L_UG The HDF5 Links + * @todo Under Construction + */ + /** * \defgroup H5L Links (H5L) * diff --git a/src/H5Omodule.h b/src/H5Omodule.h index 977861b..0c482c5 100644 --- a/src/H5Omodule.h +++ b/src/H5Omodule.h @@ -29,6 +29,10 @@ #define H5_MY_PKG_ERR H5E_OHDR #define H5_MY_PKG_INIT YES +/** \page H5O_UG The HDF5 Objects + * @todo Under Construction + */ + /** * \defgroup H5O Objects (H5O) * diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h index 84d3583..66a24fd 100644 --- a/src/H5PLmodule.h +++ b/src/H5PLmodule.h @@ -27,6 +27,10 @@ #define H5_MY_PKG_ERR H5E_PLUGIN #define H5_MY_PKG_INIT YES +/** \page H5PL_UG The HDF5 Plugins + * @todo Under Construction + */ + /** * \defgroup H5PL Dynamically-loaded Plugins (H5PL) * diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 1f4503d..8990922 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -829,7 +829,7 @@ H5_DLL htri_t H5Pexist(hid_t plist_id, const char *name); */ H5_DLL herr_t H5Pget(hid_t plist_id, const char *name, void *value); /** - *\ingroup PLCR + * \ingroup PLCR * * \brief Returns the property list class identifier for a property list * diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h index c561058..eb69466 100644 --- a/src/H5Rmodule.h +++ b/src/H5Rmodule.h @@ -25,6 +25,10 @@ #define H5_MY_PKG_ERR H5E_REFERENCE #define H5_MY_PKG_INIT YES +/** \page H5R_UG The HDF5 References + * @todo Under Construction + */ + /** * \defgroup H5R References (H5R) * diff --git a/src/H5VLmodule.h b/src/H5VLmodule.h index fa03e85..1ad0c8d 100644 --- a/src/H5VLmodule.h +++ b/src/H5VLmodule.h @@ -53,13 +53,13 @@ * * * * *
- * \image html V_fig1.gif "The VOL Architecture" + * \image html vol_architecture.png "The VOL Architecture" *
* * Not all public HDF5 API calls pass through the VOL. Only calls which require manipulating storage go - * through the VOL and require a VOL connector authorto implement the appropriate callback. Dataspace, + * through the VOL and require a VOL connector author to implement the appropriate callback. Dataspace, * property list, error stack, etc. calls have nothing to do with storage manipulation or querying and * do not use the VOL. This may be confusing when it comes to property list calls, since many of those * calls set properties for storage. Property lists are just collections of key-value pairs, though, so diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h index b3a52fd..fddfd7f 100644 --- a/src/H5Zmodule.h +++ b/src/H5Zmodule.h @@ -29,6 +29,10 @@ #define H5_MY_PKG_ERR H5E_PLINE #define H5_MY_PKG_INIT YES +/** \page H5Z_UG The HDF5 Filters + * @todo Under Construction + */ + /** * \defgroup H5Z Filters (H5Z) * diff --git a/src/H5public.h b/src/H5public.h index 3103298..ca06025 100644 --- a/src/H5public.h +++ b/src/H5public.h @@ -694,7 +694,7 @@ H5_DLL herr_t H5get_libversion(unsigned *majnum, unsigned *minnum, unsigned *rel * currently linked. If this check fails, H5check_version() causes the * application to abort (by means of a standard C abort() call) and * prints information that is usually useful for debugging. This - * precaution is is taken to avoid the risks of data corruption or + * precaution is taken to avoid the risks of data corruption or * segmentation faults. * * The most common cause of this failure is that an application was -- cgit v0.12