From 345e07fc11458901632c697ae794d91962eed817 Mon Sep 17 00:00:00 2001 From: Barbara Jones Date: Thu, 8 Mar 2001 11:47:44 -0500 Subject: [svn-r3563] Add changes to tutorial for Fortran Purpose: [is this a bug fix? feature? ...] Description: [describe the bug, or describe the new feature, etc] Solution: [details about the changes, algorithm, etc...] [Please as detail as you can since your own explanation is better than others guessing it from the code.] Platforms tested: [machines you have tested the changed version. This is absolute important. Test it out on at least two or three different platforms such as Big-endian-32bit (SUN/IRIX), little-endian-32(LINUX) and 64-bit (IRIX64/UNICOS/DEC-ALPHA) would be good.] --- doc/html/Tutor/Contents.html | 9 +- doc/html/Tutor/ContentsAdd.html | 64 +--- doc/html/Tutor/ContentsAdv.html | 68 +--- doc/html/Tutor/ContentsFull.html | 37 +-- doc/html/Tutor/ContentsIntro.html | 55 +--- doc/html/Tutor/Copyright.html | 42 ++- doc/html/Tutor/answers.html | 436 +++++++++++++++---------- doc/html/Tutor/api.html | 57 ++-- doc/html/Tutor/compound.html | 93 +++--- doc/html/Tutor/crtatt.html | 320 +++++++++++------- doc/html/Tutor/crtdat.html | 437 +++++++++++++++++-------- doc/html/Tutor/crtfile.html | 261 ++++++++++----- doc/html/Tutor/crtgrp.html | 131 +++++--- doc/html/Tutor/crtgrpar.html | 165 +++++----- doc/html/Tutor/crtgrpd.html | 198 +++++------- doc/html/Tutor/extend.html | 374 ++++++++++----------- doc/html/Tutor/fileorg.html | 27 +- doc/html/Tutor/glossary.html | 37 ++- doc/html/Tutor/intro.html | 39 ++- doc/html/Tutor/iterate.html | 327 +++++++++---------- doc/html/Tutor/mount.html | 345 +++++++++----------- doc/html/Tutor/property.html | 169 ++++++++++ doc/html/Tutor/questions.html | 141 ++++---- doc/html/Tutor/rdwt.html | 386 +++++++++++++++------- doc/html/Tutor/references.html | 7 +- doc/html/Tutor/reftoobj.html | 570 ++++++++++++--------------------- doc/html/Tutor/reftoreg.html | 659 ++++++++++++++------------------------ doc/html/Tutor/select.html | 319 ++++++------------ doc/html/Tutor/selectc.html | 381 ++++++++++------------ doc/html/Tutor/software.html | 87 +++++ doc/html/Tutor/title.html | 30 +- doc/html/Tutor/util.html | 4 +- 32 files changed, 3266 insertions(+), 3009 deletions(-) create mode 100644 doc/html/Tutor/property.html create mode 100644 doc/html/Tutor/software.html diff --git a/doc/html/Tutor/Contents.html b/doc/html/Tutor/Contents.html index 49c4a32..d2584e5 100644 --- a/doc/html/Tutor/Contents.html +++ b/doc/html/Tutor/Contents.html @@ -2,6 +2,7 @@ + - Tutorial Title Page
@@ -56,11 +57,11 @@ Remove (or comment out) when served from HDF web server. Advanced Topics +Introductory Topics
-Advanced Topics - +Advanced Topics
+ + Additional Information -
HDF5 Utilities -- h5ls and h5dump -
Glossary -
References -
Example Programs +
-
Full TOC -

-
Copyright, Etc.
diff --git a/doc/html/Tutor/ContentsAdv.html b/doc/html/Tutor/ContentsAdv.html index b2ac014..ac27c0e 100644 --- a/doc/html/Tutor/ContentsAdv.html +++ b/doc/html/Tutor/ContentsAdv.html @@ -10,6 +10,7 @@ Remove (or comment out) when served from HDF web server.
Return to HDF5 Doc Set
+

@@ -18,85 +19,36 @@ Remove (or comment out) when served from HDF web server. --> (Short TOC) -

Tutorial Title Page -
-
-Introductory Topics - - +Introductory Topics
+ + Advanced Topics -
-Compound Data Types -
-Selections Using H5Sselect_hyperslab -
-Selections Using H5Sselect_elements and H5Scopy -
+Compound Datatypes +Dataspace Selection - hyperslab +Dataspace Selection - Individual Points References to Objects -
References to Dataset Regions -
Chunking and Extendible Datasets -
Mounting Files -
Group Iteration +
-
Additional Information - +
-
Full TOC -
+
-
-
Copyright, Etc.
diff --git a/doc/html/Tutor/ContentsFull.html b/doc/html/Tutor/ContentsFull.html index 09cd5b9..d873f82 100644 --- a/doc/html/Tutor/ContentsFull.html +++ b/doc/html/Tutor/ContentsFull.html @@ -10,6 +10,7 @@ Remove (or comment out) when served from HDF web server.
Return to HDF5 Doc Set
+

@@ -19,79 +20,49 @@ Remove (or comment out) when served from HDF web server. (Short TOC) -

Tutorial Title Page -

Introductory Topics -
Introduction -
HDF5 File Organization -
The HDF5 API -
Creating an HDF5 File -
Creating a Dataset -
Reading from and Writing to a Dataset -
Creating an Attribute -
Creating a Group -
Creating Groups Using Absolute and Relative Names -
Creating Datasets in a Group
-
Quiz Questions -
Quiz Answers
Advanced Topics -
-Compound Data Types -
-Selections Using H5Sselect_hyperslab -
-Selections Using H5Sselect_elements and H5Scopy -
+Compound Datatypes +Dataspace Selection - Hyperslab +Dataspace Selection - Individual Points References to Objects -
References to Dataset Regions -
Chunking and Extendible Datasets -
Mounting Files -
Group Iteration
Additional Information -
HDF5 Utilities -- h5ls and h5dump -
Glossary -
References -
Example Programs -
-(Short TOC) -
-
Copyright, Etc.
diff --git a/doc/html/Tutor/ContentsIntro.html b/doc/html/Tutor/ContentsIntro.html index 5b974d1..96bd716 100644 --- a/doc/html/Tutor/ContentsIntro.html +++ b/doc/html/Tutor/ContentsIntro.html @@ -10,6 +10,7 @@ Remove (or comment out) when served from HDF web server.
Return to HDF5 Doc Set
+

@@ -19,85 +20,41 @@ Remove (or comment out) when served from HDF web server. (Short TOC) -

Tutorial Title Page -
-
+ Introductory Topics -
Introduction -
HDF5 File Organization -
The HDF5 API -
Creating an HDF5 File -
Creating a Dataset -
Reading from and Writing to a Dataset -
Creating an Attribute -
Creating a Group -
Creating Groups Using Absolute and Relative Names -
Creating Datasets in a Group
-
Quiz Questions -
Quiz Answers +
-
Advanced Topics - +
-
Additional Information - +
-
Full TOC -
+
-
-
Copyright, Etc.
diff --git a/doc/html/Tutor/Copyright.html b/doc/html/Tutor/Copyright.html index b22c16c..358ae02 100644 --- a/doc/html/Tutor/Copyright.html +++ b/doc/html/Tutor/Copyright.html @@ -21,7 +21,7 @@ NCSA HDF5 (Hierarchical Data Format 5) Software Library and Utilities NCSA HDF5 (Hierarchical Data Format 5) Software Library and Utilities
-Copyright 1998, 1999 by the Board of Trustees of the University of Illinois +Copyright 1998, 1999, 2000 by the Board of Trustees of the University of Illinois
All rights reserved.

@@ -67,13 +67,51 @@ the possibility of such damage. + + +


+Portions of HDF5 were developed with support from the University of +California, Lawrence Livermore National Laboratory (UC LLNL). +The following statment applies to those portions of the product +and must be retained in any redistribution of source code, binaries, +documentation, and/or accompanying materials: + + +This work was partially produced at the University of California, +Lawrence Livermore National Laboratory (UC LLNL) under contract no. +W-7405-ENG-48 (Contract 48) between the U.S. Department of Energy (DOE) +and The Regents of the University of California (University) for the +operation of UC LLNL. +

+DISCLAIMER: +This work was prepared as an account of work sponsored by an agency of the +United States Government. Neither the United States Government nor the +University of California nor any of their employees, makes any warranty, +express or implied, or assumes any liability or responsibility for the +accuracy, completeness, or usefulness of any information, apparatus, +product, or process disclosed, or represents that its use would not +infringe privately-owned rights. Reference herein to any specific +commercial products, process, or service by trade name, trademark, +manufacturer, or otherwise, does not necessarily constitute or imply its +endorsement, recommendation, or favoring by the United States Government +or the University of California. The views and opinions of authors +expressed herein do not necessarily state or reflect those of the United +States Government or the University of California, and shall not be used +for advertising or product endorsement purposes. +

+ + + +
HDF Help Desk +
+Last modified: 7 June 2000
-Last modified: 13 October 1999 +Describes HDF5 Release 1.2.2, June 2000 diff --git a/doc/html/Tutor/answers.html b/doc/html/Tutor/answers.html index 6bc239b..986b2f5 100644 --- a/doc/html/Tutor/answers.html +++ b/doc/html/Tutor/answers.html @@ -1,5 +1,5 @@ -HDF5 Tutorial - Introductory Topics Questions with Answers +<TITLE>HDF5 Tutorial - Introductory Topics Quiz with Answers @@ -13,182 +13,290 @@ width=78 height=27 alt="NCSA">

[ HDF5 Tutorial Top ]

-Introductory Topics Questions with -Answers +Introductory Topics Quiz + with Answers


-
 
 
-Section 2: HDF File Organization
-================================
-
-1. Name and describe the two primary objects that can be stored in an HDF5
-   file:
-
-Answer: 
-Group: A grouping structure containing zero or more HDF5 objects, together
-       with supporting metadata.
-
-Dataset: A multidimensional array of data elements, together with
-         supporting metadata.
-
-2. What is an attribute?
-
-Answer: An HDF attribute is a user-defined HDF5 structure that provides extra
-        information about an HDF5 object.
-
-3. Give the path name for an object called "harry" that is a member of a
-   group called "dick," which in turn is a member of the root group.
-
-Answer: /dick/harry
-
-Section 3: The HDF5 API
-=======================
-
-Describe the purpose of each of the following HDF5 APIs:
-
-H5A, H5D, H5E, F5F, H5G, H5T, H5Z
-
-H5A: Attribute access and manipulation routines.
-H5D: Dataset access and manipulation routines.
-H5E: Error handling routines.
-F5F: File access routines.
-H5G: Routines for creating and operating on groups.
-H5T: Routines for creating and manipulating the datatypes of dataset elements.
-H5Z: Data compression routines.
-
-
-Section 4: Creating an HDF File
-===============================
-
-1. What two HDF5 routines must be called in order to create an HDF5 file?
-
-Answer: H5Fcreate and H5Fclose.
-
-2. What include file must be included in any file that uses the HDF5 library.
-
-Answer: hdf5.h must be included because it contains definitions and
-        declarations used by the library.
-
-3. An HDF5 file is never completely empty because as soon as an HDF5 file
-   is created, it automatically contains a certain primary object.  What is
-   that object?
-
-Answer: The root group.
-
-
-Section 5: Creating a Dataset
-=============================
-
-1. Name and describe two major datatype categories.
-
-Answer: atomic datatype - An atomic datatype cannot be decomposed into
-                          smaller units at the API level.
-        compound datatype - A compound datatype is a collection of atomic/  
-                            compound datatypes, or small arrays of such types.
-
-2. List the HDF5 atomic datatypes. Give an example of a predefined datatype.
-
-Answer: There are six HDF5 atomic datatypes: integer, floating point,
-        date and time, character string, bit field, opaque.
-        H5T_IEEE_F32LE - 4-byte little-endian, IEEE floating point,
-        H5T_NATIVE_INT - native integer  
-
-3. What does the dataspace describe? What are the major characteristics of the
-   simple dataspace? 
-
-Answer: The dataspace describes the dimensionality of the dataset. It is 
-        characterized by its rank and dimension sizes.  
+

Section 2: HDF File Organization

+
    + +
  1. Name and describe the two primary objects that can be stored in an HDF5 + file. + +
    +
    Answers: +
    Group: A grouping structure containing zero or more + HDF5 objects, together with supporting metadata. +
    Dataset: A multidimensional array of data elements, + together with supporting metadata. +
    + +

    +

  2. What is an attribute? + +
    +
    Answer: +
    An HDF5 attribute is a user-defined HDF5 structure that provides extra + information about an HDF5 object. +
    + +

    +

  3. Give the path name for an object called harry that is + a member of a group called dick, which, in turn, is a + member of the root group. + +
    +
    Answer: +
    /dick/harry +
    + + +
+

Section 3: The HDF5 API

+
    + +
  1. Describe the purpose of each of the following HDF5 APIs: + + + H5A, H5D, H5E, H5F, H5G, H5T, H5Z + + +
    +
    Answers: + + 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 +
    +
    + + +
+

Section 4: Creating an HDF5 File

+
    + +
  1. What two HDF5 routines must be called to create an HDF5 file? + +
    +
    Answer: +
    H5Fcreate and H5Fclose. +
    + +

    +

  2. What include file must be included in any file that uses the HDF5 library? + +
    +
    Answer: +
    hdf5.h must be included because it contains definitions + and declarations used by the library. +
    + +

    +

  3. An HDF5 file is never completely empty because as soon as it is created, + it automatically contains a certain primary object. What is that object? + +
    +
    Answer: +
    The root group. +
    + + +
+

Section 5: Creating a Dataset

+
    + +
  1. Name and describe two major datatype categories. + +
    +
    Answers: +
    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. List the HDF5 atomic datatypes. Give an example of a predefined datatype. + +
    +
    Answers: +
    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: + + H5T_IEEE_F32LE + - 4-byte little-endian, IEEE floating point
    + H5T_NATIVE_INT + - native integer +
    +
    + +

    +

  3. What does the dataspace describe? What are the major characteristics of + the simple dataspace? + +
    +
    Answers: +
    The dataspace describes the dimensionality of the dataset. + A simple dataspace is characterized by its rank and dimension sizes. +
    -4. What information needs to be passed to the H5Dcreate function, i.e. +

    +

  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: dataset location, name, dataspace, datatype, and creation properties. +
    +
    Answer: +
    The dataset location, name, dataspace, datatype, and dataset + creation property list. +
    -Section 6: Reading from/Writing to a Dataset -============================================ +
+

Section 6: Reading from and Writing to a Dataset

+
    -1. What are six pieces of information which need to be specified for +
  1. What are six pieces of information which need to be specified for reading and writing a dataset? -Answer: A dataset, a dataset's datatype and dataspace in memory, the - dataspace in the file, the transfer properties and data buffer. - -2. Why are both the memory dataspace and file dataspace needed for - read/write operations, but only the memory datatype is specified for the - datatype? - -Answer: A dataset's file datatype is specified at creation time and cannot be - changed. Both file and memory dataspaces are needed for performing - subsetting and partial I/O operations. - -3. What does the line DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } in Fig 6.1 - means? - -Answer: It means that the dataset "dset" has a simple dataspace with the - current dimensions (4,6) and the maximum size of the dimensions (4,6). - - -Section 7: Creating an Attribute -================================ - -1. What is an attribute? - -Answer: An attribute is a dataset attached to an object. It describes the - nature and/or the intended usage of the object. - -2. Can partial I/O operations be performed on attributes? - -Answer: No - - -Section 8: Creating a Group -=========================== - -What are the two primary objects that can be included in -a group? - -Answer: A group and a dataset - - -Section 9: Creating Groups using Absolute/Relative Names -======================================================== - -1. Group names can be specified in two "ways". What are these - two types of group names that you can specify? - -Answer: relative and absolute - -2. You have a dataset named "moo" in the group "boo", which is - in the group "foo", which in turn, is in the root group. How would - you specify an absolute name to access this dataset? - -Answer: /foo/boo/moo - -Section 10: Creating Datasets in Groups -======================================= - -Describe a way to access the dataset "moo" described in the previous section -(Section 9, question 2), using a relative and absolute pathname. - -Answers: 1. Access the group, "/foo", and get the group ID. - Access the group "boo" using the group ID obtained in Step 1. - Access the dataset "moo" using the group ID in Step 2. - gid = H5Gopen (file_id, "/foo", 0); /* absolute path */ - gid1 = H5Gopen (gid, "boo", 0); /* relative path */ - did = H5Dopen (gid1, "moo"); /* relative path */ +
    +
    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. 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. What does the line +
        + DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } +
    in Figure 6.1 mean? + +
    +
    Answer: +
    It means that the dataset dset has a simple dataspace + with the current dimensions (4,6) and the maximum size of the + dimensions (4,6). +
    + + +
+

Section 7: Creating an Attribute

+
    + +
  1. What is an attribute? + +
    +
    Answer: +
    An attribute is a dataset attached to an object. It describes the + nature and/or the intended usage of the object. +
    + +

    +

  2. Can partial I/O operations be performed on attributes? + +
    +
    Answer: +
    No. +
    + + +
+

Section 8: Creating a Group

+
    + +
  1. What are the two primary objects that can be included in a group? + +
    +
    Answer: +
    A group and a dataset. +
    + + +
+

Section 9: Creating Groups Using Absolute and Relative Names

+
    + +
  1. Group names can be specified in two ways. What are these two types + of group names? + +
    +
    Answer: +
    Relative and absolute. +
    + +

    +

  2. You have a dataset named moo in the group + boo, which is in the group foo, + which, in turn, is in the root group. + How would you specify an absolute name to access this dataset? + +
    +
    Answer: +
    /foo/boo/moo +
    + + +
+

Section 10: Creating Datasets in Groups

+
    + +
  1. Describe a way to access the dataset moo described in + the previous section (Section 9, question 2) using a + relative name. + Describe a way to access the same dataset using an absolute name. + +
    +
    Answers: +
      +
    1. Access the group /foo and get the group ID. + Access the group boo using the group ID obtained + in Step 1. + Access the dataset moo using the group ID obtained + in Step 2. +
      +gid = H5Gopen (file_id, "/foo", 0);       /* absolute path */
      +gid1 = H5Gopen (gid, "boo", 0);           /* relative path */
      +did = H5Dopen (gid1, "moo");              /* relative path */  
      - 2. Access the group, "/foo", and get the group ID. - Access the dataset "boo/moo", with the group ID just obtained. - gid = H5Gopen (file_id, "/foo", 0); /* absolute path */ - did = H5Dopen (gid, "boo/moo"); /* relative path */ +
    2. Access the group /foo and get the group ID. + Access the dataset boo/moo with the group ID + just obtained. +
      +gid = H5Gopen (file_id, "/foo", 0);       /* absolute path */
      +did = H5Dopen (gid, "boo/moo");           /* relative path */  
      - 3. Access the dataset with an absolute path. - did = H5Dopen (file_id, "/foo/boo/moo"); /* absolute path */ -
+
  • Access the dataset with an absolute path. +
    +did = H5Dopen (file_id, "/foo/boo/moo");  /* absolute path */  
    + + + + +


    @@ -203,7 +311,9 @@ Answers: 1. Access the group, "/foo", and get the group ID. hdfhelp@ncsa.uiuc.edu -
    Last Modified: August 2, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: January 13, 2000


    diff --git a/doc/html/Tutor/api.html b/doc/html/Tutor/api.html index 3ed0a84..ba186a7 100644 --- a/doc/html/Tutor/api.html +++ b/doc/html/Tutor/api.html @@ -21,11 +21,21 @@ width=78 height=27 alt="NCSA">

    -The HDF5 library provides several interfaces, and is currently implemented in -C. The APIs provide routines for accessing HDF5 files and creating and -manipulating HDF5 objects. All C routines in the HDF5 library begin with -a prefix of the form H5*, where * is a single letter indicating the object on -which the operation is to be performed. The APIs are listed below: +The HDF5 library provides several interfaces, or APIs. +These APIs provide routines for creating, accessing, and manipulating +HDF5 files and objects. +

    +The library itself is implemented in C. To facilitate the work of +FORTRAN90 and Java programmers, HDF5 function wrappers have been developed +in each of these languages. +At the time of this writing, a set of C++ wrappers is in development. +This tutorial discusses the use of the C functions and the FORTRAN wrappers. +

    +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. The APIs are listed below:

    @@ -40,76 +50,78 @@ which the operation is to be performed. The APIs are listed below: - + - + - + - + - + - + - + - + - + - + - + - +
    H5
    Library Functions: the general-purpose H5 functions.Library Functions: general-purpose H5 functions
    H5A
    Annotation Interface: attribute access and manipulating routines.Annotation Interface: attribute access and manipulation + routines
    H5D
    Dataset Interface: dataset access and manipulating routines. - Dataset Interface: dataset access and manipulation + routines
    H5E
    Error Interface: error handling routines.Error Interface: error handling routines
    H5F
    File Interface: file access routines.File Interface: file access routines
    H5G
    Group Interface: group creating and operating routines.Group Interface: group creation and operation routines
    H5I
    Identifier Interface: identifier routines.Identifier Interface: identifier routines
    H5P
    Property List Interface: object property list manipulating - routines.Property List Interface: object property list manipulation + routines
    H5R
    Reference Interface: reference routines.Reference Interface: reference routines
    H5S
    Dataspace Interface: routines for defining dataspaces.Dataspace Interface: dataspace definition and access + routines
    H5T
    Data type Interface: routines for creating and manipulating - the data type of dataset elements.Datatype Interface: datatype creation and manipulation + routines
    H5Z
    Compression Interface: compression routine(s).Compression Interface: compression routine(s)
    @@ -127,8 +139,11 @@ which the operation is to be performed. The APIs are listed below: hdfhelp@ncsa.uiuc.edu -

    Last Modified: July 30, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: December 10, 1999

    +
    diff --git a/doc/html/Tutor/compound.html b/doc/html/Tutor/compound.html index 7983bf4..d68d5a3 100644 --- a/doc/html/Tutor/compound.html +++ b/doc/html/Tutor/compound.html @@ -1,5 +1,5 @@ -HDF5 Tutorial - Compound Data Types +<TITLE>HDF5 Tutorial - Compound Datatypes @@ -13,7 +13,7 @@ width=78 height=27 alt="NCSA">

    [ HDF5 Tutorial Top ]

    -Compound Data Types +Compound Datatypes


    @@ -21,7 +21,7 @@ width=78 height=27 alt="NCSA">

    Contents:

    +Note: The FORTRAN API does not yet support compound datatypes.
    -

    Creating Compound Data Types

    -A compound data type is similar to a struct in C or a common block in -Fortran. It is a collection of one or more atomic types or small arrays of -such types. To create and use a compound data type you need to refer to -various properties of the data compound data type: +

    Creating 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 a compound datatype you need to be familiar +with various properties of the compound datatype:
      -
    • It is of class compound. +
    • It is of class compound.
    • It has a fixed total size, in bytes.
    • It consists of zero or more members (defined in any order) with - unique names and which occupy non-overlapping regions within the datum. -
    • Each member has its own data type. -
    • Each member is referenced by an index number between zero and N-1, - where N is the number of members in the compound data type. + unique names and occupying non-overlapping regions within the datum. +
    • Each member has its own datatype. +
    • Each member is referenced by an index number between zero and N-1, + where N is the number of members in the compound datatype.
    • Each member has a name which is unique among its siblings in a - compound data type. -
    • Each member has a fixed byte offset, which is the first byte - (smallest byte address) of that member in a compound data type. + compound datatype. +
    • Each member has a fixed byte offset, which locates the first byte + (smallest byte address) of that member in the compound datatype.
    • Each member can be a small array of up to four dimensions.
    -Properties of members of a compound data type are defined when the -member is added to the compound type and cannot be subsequently modified. +Properties of members of a compound datatype are defined when the +member is added to the compound datatype and cannot be subsequently modified.

    -Compound data types must be built out of other data types. First, one -creates an empty compound data type and specifies its total size. Then -members are added to the compound data type in any order. +Compound datatypes must be built out of other datatypes. First, one +creates an empty compound datatype and specifies its total size. Then +members are added to the compound datatype in any order.

    Programming Example

    Description

    -This example shows how to create a compound data type, write an array -to the file which uses the compound data type, and read back subsets of -the members.
    - -[
    Download h5_compound.c] +This example shows how to create a compound datatype, write an array +to the file which uses the compound datatype, and read back subsets of +the members. +

    +

     +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
     #include "hdf5.h"
    @@ -126,7 +131,7 @@ main(void)
         file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
     
         /*
    -     * Create the memory data type. 
    +     * Create the memory datatype. 
          */
         s1_tid = H5Tcreate (H5T_COMPOUND, sizeof(s1_t));
         H5Tinsert(s1_tid, "a_name", HOFFSET(s1_t, a), H5T_NATIVE_INT);
    @@ -159,7 +164,7 @@ main(void)
         dataset = H5Dopen(file, DATASETNAME);
     
         /* 
    -     * Create a data type for s2
    +     * Create a datatype for s2
          */
         s2_tid = H5Tcreate(H5T_COMPOUND, sizeof(s2_t));
     
    @@ -186,7 +191,7 @@ main(void)
         printf("\n");
     
         /* 
    -     * Create a data type for s3.
    +     * Create a datatype for s3.
          */
         s3_tid = H5Tcreate(H5T_COMPOUND, sizeof(float));
     
    @@ -235,33 +240,34 @@ Field b :
     
     

    Remarks

      -
    • H5Tcreate creates a new data type of the specified class with +
    • H5Tcreate creates a new datatype of the specified class with the specified number of bytes.
           hid_t H5Tcreate ( H5T_class_t class, size_t size ) 
       
        -
      • The class parameter specifies the data type to create. -Currently only the H5T_COMPOUND data type class is supported with this +
      • The class parameter specifies the datatype to create. +Currently only the H5T_COMPOUND datatype class is supported with this function.
      • The size parameter specifies the number of bytes in the -data type to create. +datatype to create.

      -

    • H5Tinsert adds a member to the compound data type specified by +
    • H5Tinsert adds a member to the compound datatype specified by type_id.
      -   herr_t H5Tinsert ( hid_t type_id, const char * name, off_t offset, hid_t field_id ) 
      +   herr_t H5Tinsert ( hid_t type_id, const char * name, off_t offset, 
      +                      hid_t field_id ) 
       
        -
      • The type_id parameter is the identifier of the compound data type +
      • The type_id parameter is the identifier of the compound datatype to modify.
      • The name parameter is the name of the field to insert. The new -member name must be unique within a compound data type. +member name must be unique within a compound datatype.
      • The offset parameter is the offset in the memory structure of the field to insert. -The library defines the HOFFSET macro to compute the offset of a member within +The library defines the HOFFSET macro to compute the offset of a member within a struct:
           HOFFSET ( s, m ) 
        @@ -269,15 +275,15 @@ a struct:
         This macro computes the offset of member m within a struct 
         variable s. 
         
        -
      • The field_id parameter is the data type identifier of the +
      • The field_id parameter is the datatype identifier of the field to insert.

      -

    • H5Tclose releases a data type. +
    • H5Tclose releases a datatype.
          herr_t H5Tclose ( hid_t type_id ) 
       
      -The type_id parameter is the identifier of the data type to release. +The type_id parameter is the identifier of the datatype to release.

    File Contents

    @@ -365,8 +371,11 @@ GROUP "/" {
    hdfhelp@ncsa.uiuc.edu -
    Last Modified: August 27, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: April 5, 2000

    +
    diff --git a/doc/html/Tutor/crtatt.html b/doc/html/Tutor/crtatt.html index 82de873..bc9498a 100644 --- a/doc/html/Tutor/crtatt.html +++ b/doc/html/Tutor/crtatt.html @@ -36,160 +36,212 @@ width=78 height=27 alt="NCSA">

    Attributes are small datasets that can be used to describe the nature and/or the intended usage of the object they are attached to. In this section, we -show how to create and read/write an attribute. +show how to create, read, and write an attribute.

    Creating an attribute

    - Creating an attribute is similar to the creation of a dataset. To create an - attribute the application must specify the object which the attribute is - attached to, the data type and space of the attribute data and the creation - properties. + Creating an attribute is similar to creating a dataset. To create an + attribute, the application must specify the object which the attribute is + attached to, the datatype and dataspace of the attribute data, + and the attribute creation property list.

    The steps to create an attribute are as follows:

    1. Obtain the object identifier that the attribute is to be attached to. -
    2. Define the characteristics of the attribute and specify creation - properties. +
    3. Define the characteristics of the attribute and specify the + attribute creation property list.
        -
      • Define the data type. +
      • Define the datatype.
      • Define the dataspace. -
      • Specify the creation properties. +
      • Specify the attribute creation property list.
    4. Create the attribute. -
    5. Close the attribute and data type, dataspace, and creation property - list if necessary. +
    6. Close the attribute and datatype, dataspace, and + attribute creation property list, if necessary.

    - To create an attribute, the calling program must contain the following calls: + To create and close an attribute, the calling program must use +H5Acreate/h5acreate_f and +H5Aclose/h5aclose_f. For example: +

    +C:

    -     attr_id = H5Acreate(loc_id, attr_name, type_id, space_id, create_plist);
    -     H5Aclose(attr_id);
    +     attr_id = H5Acreate (dset_id, attr_name, type_id, space_id, creation_prp);
    +     status = H5Aclose (attr_id);
     
    +FORTRAN: +
    +     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)
    +

    Reading/Writing an attribute

    - Attributes may only be read/written as an entire object. No partial I/O is - currently supported. Therefore, to perform I/O operations on an attribute, the + Attributes may only be read or written as an entire object; no partial I/O is + supported. Therefore, to perform I/O operations on an attribute, the application needs only to specify the attribute and the attribute's memory - data type. + datatype.

    - The steps to read/write an attribute are as follows. + The steps to read or write an attribute are as follows.

    1. Obtain the attribute identifier. -
    2. Specify the attribute's memory data type. +
    3. Specify the attribute's memory datatype.
    4. Perform the desired operation. -
    5. Close the memory data type if necessary. +
    6. Close the memory datatype if necessary.

    -To read/write an attribute, the calling program must contain the following - calls: +To read and/or write an attribute, the calling program must contain the +H5Aread/h5aread_f and/or +H5Awrite/h5awrite_f routines. For example: +

    +C:

    -    status = H5Aread(attr_id, mem_type_id, buf);
    +    status = H5Aread (attr_id, mem_type_id, buf);
    +    status = H5Awrite (attr_id, mem_type_id, buf);
     
    - or +FORTRAN:
    -    status = H5Awrite(attr_id, mem_type_id, buf);
    +    CALL h5awrite_f (attr_id, mem_type_id, buf, hdferr)  
    +    CALL h5aread_f (attr_id, mem_type_id, buf, hdferr)
     

    Programming Example

    Description

    This example shows how to create and write a dataset attribute. -It opens an existing file 'dset.h5', obtains the id of the dataset "/dset1", +It opens an existing file 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.
    -[
    Download h5_crtatt.c ] -
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -
    -#include <hdf5.h>
    -#define FILE "dset.h5"
    -
    -main() {
    -
    -   hid_t       file_id, dataset_id, attribute_id, dataspace_id;  /* identifiers
    -*/
    -   hsize_t     dims;
    -   int         attr_data[2];
    -   herr_t      status;
    -
    -   /* Initialize the attribute data. */
    -   attr_data[0] = 100;
    -   attr_data[1] = 200;
    -
    -   /* Open an existing file. */
    -   file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);
    -
    -   /* Open an existing dataset. */
    -   dataset_id = H5Dopen(file_id, "/dset");
    -
    -   /* Create the data space for the attribute. */
    -   dims = 2;
    -   dataspace_id = H5Screate_simple(1, &dims, NULL);
    -
    -   /* Create a dataset attribute. */
    -   attribute_id = H5Acreate(dataset_id, "attr", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT);
    -
    -   /* Write the attribute data. */
    -   status = H5Awrite(attribute_id, H5T_NATIVE_INT, attr_data);
    -
    -   /* Close the attribute. */
    -   status = H5Aclose(attribute_id);
    +
     
    -   /* Close the dataspace. */
    -   status = H5Sclose(dataspace_id);
    +NOTE: To download a tar file of the examples, including a Makefile,
    +please go to the References page.
     
    -   /* Close to the dataset. */
    -   status = H5Dclose(dataset_id);
    -
    -   /* Close the file. */
    -   status = H5Fclose(file_id);
    -}
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -

    Remarks

    The dimensions of a dataset can be fixed (unchanging), or they may be - unlimited, which means that they are extendible. A dataspace can also - describe portions of a dataset, making it possible to do partial I/O + unlimited, which means that they are extensible. A dataspace can also + describe a portion of a dataset, making it possible to do partial I/O operations on selections. -

    Dataset creation properties

    +

    Dataset Creation Property Lists

    - When creating a dataset, HDF5 allows users to specify how raw data is - organized on disk and how the raw data is compressed. This information is + When creating a dataset, HDF5 allows the user to specify how raw data is + organized and/or compressed on disk. This information is stored in a dataset creation property list and passed to the dataset interface. The raw data on disk can be stored contiguously (in the same - linear way that it is organized in memory), partitioned into chunks and - stored externally, etc. In this tutorial, we use the default creation - property list; that is, no compression and - contiguous storage layout is used. For more information about the creation - properties, see the HDF5 User's Guide. + linear way that it is organized in memory), partitioned into chunks, + stored externally, etc. In this tutorial, we use the + default dataset creation property list; that is, contiguous storage layout + and no compression are used. For more information about + dataset creation property lists, + see The Dataset Interface (H5D) + in the HDF5 User's Guide.

    -In HDF5, data types and spaces are independent objects, which are created -separately from any dataset that they might be attached to. Because of this the -creation of a dataset requires definitions of data type and dataspace. -In this tutorial, we use HDF5 predefined data types (integer) and consider +In HDF5, datatypes and dataspaces are independent objects which are created +separately from any dataset that they might be attached to. Because of this, +the creation of a dataset requires definition of the datatype and dataspace. +In this tutorial, we use HDF5 predefined datatypes (integer) and consider only simple dataspaces. Hence, only the creation of dataspace objects is needed.

    @@ -142,158 +208,250 @@ needed. To create an empty dataset (no data written) the following steps need to be taken:

      -
    1. Obtain the location id where the dataset is to be created. -
    2. Define the dataset characteristics and creation properties. +
    3. Obtain the location identifier where the dataset is to be created. +
    4. Define the dataset characteristics and the dataset creation property list.
        -
      • define a data type -
      • define a dataspace -
      • specify dataset creation properties +
      • Define a datatype. +
      • Define a dataspace. +
      • Specify the dataset creation property list.
    5. Create the dataset. -
    6. Close the data type, dataspace, and the property list if necessary. +
    7. Close the datatype, the dataspace, and the property list if necessary.
    8. Close the dataset.
    -To create a simple dataspace, the calling program must contain the following -calls: +To create a simple dataspace, the calling program must contain a +call to create and close the dataspace. For example: +

    +C: +

    +   space_id = H5Screate_simple (rank, dims, maxdims);
    +   status = H5Sclose (space_id );
    +
    +FORTRAN:
    -   dataspace_id = H5Screate_simple(rank, dims, maxdims);
    -   H5Sclose(dataspace_id );
    +   CALL h5screate_simple_f (rank, dims, space_id, hdferr, maxdims=max_dims)
    +        or
    +   CALL h5screate_simple_f (rank, dims, space_id, hdferr)
    +
    +   CALL h5sclose_f (space_id, hdferr)
     
    -To create a dataset, the calling program must contain the following calls: +To create a dataset, the calling program must contain calls to create +and close the dataset. For example: +

    +C:

    -   dataset_id = H5Dcreate(hid_t loc_id, const char *name, hid_t type_id,
    -                          hid_t space_id, hid_t create_plist_id);
    -   H5Dclose (dataset_id);
    +   dset_id = H5Dcreate (hid_t loc_id, const char *name, hid_t type_id,
    +                          hid_t space_id, hid_t creation_prp);
    +   status = H5Dclose (dset_id);
     
    +FORTRAN: +
    +   CALL h5dcreate_f (loc_id, name, type_id, space_id, dset_id, &
    +                     hdferr, creation_prp=creat_plist_id)
    +        or
    +   CALL h5dcreate_f (loc_id, name, type_id, space_id, dset_id, hdferr)
     
    +   CALL h5dclose_f (dset_id, hdferr)
    +
    +If using the pre-defined datatypes in FORTRAN, then a call must +be made to initialize and terminate access to the pre-defined datatypes: +
    +  CALL h5init_types_f (hdferr) 
    +  CALL h5close_types_f (hdferr)
    +
    +h5init_types_f must be called before any HDF5 library +subroutine calls are made; +h5close_types_f must be called after the final HDF5 library +subroutine call. +See the programming example below for an illustration of the use of +these calls.

    Programming Example

    Description

    The following example shows how to create an empty dataset. -It creates a file called 'dset.h5', defines the dataset dataspace, creates a +It creates a file called 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.
    -[
    Download h5_crtdat.c ] -
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -
    -#include <hdf5.h>
    -#define FILE "dset.h5"
    -
    -main() {
    -
    -   hid_t       file_id, dataset_id, dataspace_id;  /* identifiers */
    -   hsize_t     dims[2];
    -   herr_t      status;
    -
    -   /* Create a new file using default properties. */
    -   file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
    -
    -   /* Create the data 
    -                space for the dataset. */
    -   dims[0] = 4;
    -   dims[1] = 6;
    -   dataspace_id = H5Screate_simple(2, dims, NULL);
    -
    -   /* Create the dataset. */
    -   dataset_id = H5Dcreate(file_id, "/dset", H5T_STD_I32BE, dataspace_id, 
    -                H5P_DEFAULT);
    -
    -   /* End access to the dataset and release resources used by it. */
    -   status = H5Dclose(dataset_id);
    -
    -   /* Terminate access to the data space. */
    -   status = H5Sclose(dataspace_id);
    + 
     
    -   /* Close the file. */
    -   status = H5Fclose(file_id);
    -}
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -
    +NOTE: To download a tar file of the examples, including a Makefile, +please go to the References page of this tutorial.

    Remarks

      -
    • H5Screate_simple creates a new simple data space and returns a data space - identifier. +
    • H5Screate_simple/h5screate_simple_f +creates a new simple dataspace and returns a dataspace identifier.
      +C:
         hid_t H5Screate_simple (int rank, const hsize_t * dims, 
                                 const hsize_t * maxdims)
      +FORTRAN:
      +  h5screate_simple_f (rank, dims, space_id, hdferr, maxdims) 
      +
      +            rank        INTEGER
      +            dims(*)     INTEGER(HSIZE_T)
      +            space_id    INTEGER(HID_T)
      +            hdferr      INTEGER 
      +                        (Valid values: 0 on success and -1 on failure)
      +            maxdims(*)  INTEGER(HSIZE_T), OPTIONAL
       
        -
      • The first parameter specifies the rank of the dataset. - -
      • The second parameter specifies the size of the dataset. - -
      • The third parameter is for the upper limit on the size of the dataset. - If it is NULL, the upper limit is the same as the dimension - sizes specified by the second parameter. +
      • The rank parameter specifies the rank, i.e., the number of + dimensions, of the dataset. + +
      • The dims parameter specifies the size of the dataset. + +
      • The maxdims parameter specifies the upper limit on the + size of the dataset. + If this parameter is NULL in C (or not specified in FORTRAN), + then the upper limit is the same as the dimension + sizes specified by the dims parameter. +
      • The function returns the dataspace identifier in C if successful; + otherwise it returns a negative value. + In FORTRAN, the dataspace identifier + is returned in the space_id parameter. If the call is successul + then a 0 is returned in hdferr; otherwise a -1 is returned.

      -

    • H5Dcreate creates a dataset at the specified location and returns a - dataset identifier. +
    • H5Dcreate/h5dcreate_f creates a dataset +at the specified location and returns a dataset identifier.
      +C:
         hid_t H5Dcreate (hid_t loc_id, const char *name, hid_t type_id, 
      -                   hid_t space_id, hid_t create_plist_id) 
      +                   hid_t space_id, hid_t creation_prp) 
      +FORTRAN:
      +  h5dcreate_f (loc_id, name, type_id, space_id, dset_id, & 
      +               hdferr, creation_prp) 
      +
      +            loc_id        INTEGER(HID_T)
      +            name          CHARACTER(LEN=*)
      +            type_id       INTEGER(HID_T)
      +            space_id      INTEGER(HID_T)
      +            dset_id       INTEGER(HID_T)
      +            hdferr        INTEGER 
      +                          (Valid values: 0 on success and -1 on failure)
      +            creation_prp  INTEGER(HID_T), OPTIONAL
       
        -
      • The first parameter is the location identifier. +
      • The loc_id parameter is the location identifier. +

        +

      • The name parameter is the name of the dataset to create. -
      • The second parameter is the name of the dataset to create. +

        +

      • The type_id parameter specifies the datatype identifier. -
      • The third parameter is the data type identifier. H5T_STD_I32BE, a - 32-bit Big Endian integer, is an HDF atomic data type. +

        +

      • The space_id parameter is the dataspace identifier. -
      • The fourth parameter is the data space identifier. +

        +

      • The creation_prp parameter specifies the + dataset creation property list. + H5P_DEFAULT in C and H5P_DEFAULT_F in FORTRAN + specify the default dataset creation property list. + This parameter is optional in FORTRAN; if it is omitted, + the default dataset creation property list will be used. +

        +

      • The C function returns the dataset identifier if successful and + a negative value otherwise. The FORTRAN call returns the + dataset identifier in dset_id. If it is successful, then 0 is + returned in hdferr; otherwise a -1 is returned. -
      • The last parameter specifies the dataset creation property list. - H5P_DEFAULT specifies the default dataset creation property list.

      -

    • H5Dcreate creates an empty array and initializes the data to 0. +
    • H5Dcreate/h5dcreate_f creates an empty array +and initializes the data to 0.

      -

    • When a dataset is no longer accessed by a program, H5Dclose must be -called to release the resource used by the dataset. This call is mandatory. +
    • When a dataset is no longer accessed by a program, +H5Dclose/h5dclose_f must be called to release +the resource used by the dataset. This call is mandatory.
      -  hid_t H5Dclose (hid_t dataset_id)
      +C:
      +    hid_t H5Dclose (hid_t dset_id)
      +FORTRAN:
      +    h5dclose_f (dset_id, hdferr)
      +
      +            dset_id  INTEGER(HID_T)
      +            hdferr   INTEGER 
      +                     (Valid values: 0 on success and -1 on failure)
       

    File Contents

    -The file contents of 'dset.h5' are shown is Figure 5.4 and Figure 5.5. - +The contents of the file dset.h5 (dsetf.h5 +for FORTRAN) are shown in Figure 5.4 and Figures 5.5a +and 5.5b. +

    +

    +
    +Figure 5.4   Contents of dset.h5 ( dsetf.h5) +
    + +
    + + - - + + - - - +
    Figure 5.4   The Contents of 'dset.h5' - Figure 5.5   'dset.h5' in DDL Figure 5.5a   dset.h5 in DDL Figure 5.5b   dsetf.h5 in DDL
    -
          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
    -            }
    -         }
    +    
    +
    +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
           }
    +   }
    +}
    +}
    +
    +
    +
          
    +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
           }
    +   }
    +}
    +}
     
    +

    +Note in Figures 5.5a and 5.5b that +H5T_STD_I32BE, a 32-bit Big Endian integer, +is an HDF atomic datatype. @@ -302,12 +460,12 @@ The following is the simplified DDL dataset definition:

    Fig. 5.6   HDF5 Dataset Definition

    -      <dataset> ::= DATASET "<dataset_name>" { <data type>
    +      <dataset> ::= DATASET "<dataset_name>" { <datatype>
                                                    <dataspace>
                                                    <data>
                                                    <dataset_attribute>* }
     
    -      <data type> ::= DATATYPE { <atomic_type> }
    +      <datatype> ::= DATATYPE { <atomic_type> }
     
           <dataspace> ::= DATASPACE { SIMPLE <current_dims> / <max_dims> }
     
    @@ -329,8 +487,11 @@ The following is the simplified DDL dataset definition:
     
     
     hdfhelp@@ncsa.uiuc.edu
    -
    Last Modified: August 27, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: April 5, 2000

    +
    diff --git a/doc/html/Tutor/crtfile.html b/doc/html/Tutor/crtfile.html index 8786aab..a5db890 100644 --- a/doc/html/Tutor/crtfile.html +++ b/doc/html/Tutor/crtfile.html @@ -13,7 +13,7 @@ width=78 height=27 alt="NCSA">

    [ HDF5 Tutorial Top ]

    -Creating an HDF5 file +Creating an HDF5 File


    @@ -34,134 +34,228 @@ width=78 height=27 alt="NCSA">

    What is an HDF5 file?

    -An HDF5 file is a binary file which contains scientific data and supporting -metadata. The two primary objects stored in an HDF5 file are groups and -datasets. Groups and datasets will be discussed in the other sessions. +An HDF5 file is a binary file containing scientific data and supporting +metadata. The primary types of objects stored in an HDF5 file, groups and +datasets, will be discussed in other sections of this tutorial.

    -To create a file, the program application must specify a file name, file +To create a file, an application must specify a filename, file access mode, file creation property list, and file access property list.

    The steps to create and close an HDF5 file are as follows:

      -
    1. Specify the file creation and access property lists if necessary. -
    2. Create a file. -
    3. Close the file and close the property lists if necessary. +
    4. Specify the file creation and access property lists, if necessary. +
    5. Create the file. +
    6. Close the file and close the property lists, if necessary.
    -To create an HDF5 file, the calling program must contain the following calls: - -
    -   file_id = H5Fcreate(filename, access_mode, create_id, access_id);
    +To create an HDF5 file, the calling program must contain calls to 
    +create and close the file.  For example:
    +

    +C:

    +   file_id = H5Fcreate (filename, access_mode, create_id, access_id);
    +   status = H5Fclose (file_id); 
    +
    +FORTRAN:
    +   CALL h5fcreate_f (filename, access_mode, file_id, hdferr, &
    +            creation_prp=create_id, access_prp=access_id)
    +        or
    +   CALL h5fcreate_f (filename, access_mode, file_id, hdferr)
     
    -   H5Fclose(file_id); 
    +   CALL h5fclose_f (file_id, hdferr)
     
    +In FORTRAN, the file creation property list, creation_prp, +and file access property list, access_prp, +are optional parameters; +they can be omitted if the default values are to be used.

    Programming Example

    Description

    The following example demonstrates how to create and close an HDF5 file. -It creates a file called 'file.h5', and then closes the file.
    -[
    Download h5_crtfile.c ] -
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -
    -
    -#include <hdf5.h>
    -#define FILE "file.h5"
    -
    -main() {
    -
    -   hid_t       file_id;   /* file identifier */
    -   herr_t      status;
    -
    -   /* Create a new file using default properties. */
    -   file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
    +It creates a file called file.h5 in the C version,
    +filef.h5 in FORTRAN, and then closes the file.

    - /* Terminate access to the file. */ - status = H5Fclose(file_id); -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +

    +

    +NOTE: To download a tar file of all of the examples, including +a Makefile, please go to the References page. -

    Remarks

      -
    • The include file 'hdf5.h' contains definitions and declarations, and it must - be included in any file that uses the HDF5 library. +
    • 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.

      -

    • H5Fcreate creates an HDF5 file and returns the file identifier. +
    • H5Fcreate/h5fcreate_f creates + an HDF5 file and returns the file identifier.
      - hid_t H5Fcreate (const char *name, unsigned flags, hid_t create_id, 
      -                  hid_t access_id) 
      +C:       
      +  hid_t H5Fcreate (const char *name, unsigned access_mode, hid_t creation_prp, 
      +                   hid_t access_prp) 
      +FORTRAN: 
      +  h5fcreate_f (name, access_mode, file_id, hdferr, creation_prp, access_prp)
      +
      +           name          CHARACTER(LEN=*)
      +           access_flag   INTEGER 
      +                         (Valid values: H5F_ACC_RDWR_F, H5F_ACC_RDONLY_F, 
      +                         H5F_ACC_TRUNC_F, H5F_ACC_EXCL_F, H5F_ACC_DEBUG_F)
      +           file_id       INTEGER(HID_T)
      +           hdferr        INTEGER 
      +                         (Valid values: 0 on success and -1 on failure)
      +           creation_prp  INTEGER(HID_T), OPTIONAL
      +                         (Default value: H5P_DEFAULT_F)
      +           access_prp    INTEGER(HID_T), OPTIONAL
      +                         (Default value: H5P_DEFAULT_F) 
      +         
       
        -
      • The first parameter specifies the name of the file to be created. +
      • The name parameter specifies the name of the file to be created.

        -

      • The second parameter specifies the file access mode. H5F_ACC_TRUNC will - truncate a file if it already exists. +
      • The access_mode parameter specifies the file access mode. + H5F_ACC_TRUNC (H5F_ACC_TRUNC_F in FORTRAN) + will truncate a file if it already exists.

        -

      • The third parameter specifies the file creation property list. - H5P_DEFAULT indicates that the default file creation property list is - used. - +
      • The creation_prp parameter + specifies the file creation property list. + For C, using H5P_DEFAULT indicates that the + default file creation property list is to be used. + This option is optional in FORTRAN; if it is omitted, the default file + creation property list, H5P_DEFAULT_F, is used.

        -

      • The last parameter of H5Fcreate specifies the file access property list. - H5P_DEFAULT indicates that the default file access property list is used. +
      • The access_prp parameter + specifies the file access property list. + For C, using H5P_DEFAULT indicates that the + default file creation property list is to be used. + This option is optional in FORTRAN; if it is omitted, the default file + creation property list, H5P_DEFAULT_F, is used. +

        +

      • In C, this function returns the file identifier if successful and + a negative value otherwise. + In FORTRAN, the file identifier is returned in the + file_id parameter. If the call is successful, 0 (zero) is + passed back in the hdferr parameter. Otherwise, hdferr + will have a value of -1.

      -

    • When a file is no longer accessed by a program, H5Fclose must be called to - release the resource used by the file. This call is mandatory. +
    • When a file is no longer accessed by a program, + H5Fclose/h5fclose_f + must be called to release the resources used by the file. This call + is mandatory.
      +C:
           herr_t H5Fclose (hid_t file_id) 
      +
      +FORTRAN:
      +    h5fclose_f(file_id, hdferr)
       

    • The root group is automatically created when a file is created. - Every file has a root group and the path name of the root group is '/'. + Every file has a root group and the path name of the root group is + always /.

    File Contents

    -HDF has developed tools to examine the contents of HDF5 files. The tool used -in this tutorial is the HDF5 dumper, h5dump. h5dump is a tool that displays -the file contents in human readable form to an ASCII file in DDL. DDL (Data -Description Language) is a language that describes HDF5 objects in Backus-Naur -Form. To view the file contents, type: +The HDF team has developed tools for examining the contents of HDF5 files. +The tool used in this tutorial is the HDF5 dumper, 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 +
    DDL in BNF for HDF5. +

    +To view the file contents, type:

        h5dump <filename> 
     
    -Figure 4.1 describes the file contents of 'file.h5' using a directed graph. -Each HDF5 object is represented by a rectangle and the arrows indicate -the structure of the contents. In Fig. 4.2, 'file.h5' contains -a group object named '/' (the root group). + +Figure 4.1 describes the file contents of file.h5 (filef.h5) +using a directed graph. +The directed graphs in this tutorial use an oval to represent an HDF5 group +and a rectangle to represent an HDF5 dataset (none in this example). +Arrows indicate the inclusion direction of the contents (none in this example).

    -Fig. 4.1   Contents of 'file.h5' +Fig. 4.1   Contents of file.h5 (filef.h5)

     
     
    -Figure 4.2 is the text-description of 'file.h5' generated by h5dump. The HDF5 -file called 'file.h5' contains a group called '/'. + +Figure 4.2 is the text description of 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.)

    - Fig. 4.2   'file.h5' in DDL + Fig. 4.2   file.h5 in DDL

     
              HDF5 "file.h5" {
    @@ -171,15 +265,18 @@ file called 'file.h5' contains a group called '/'.
     
     
    +

    File Definition in DDL

    + Figure 4.3 is the simplified DDL file definition for creating an HDF5 file. For simplicity, a simplified DDL is used in this tutorial. A complete and -more rigorous DDL can be found in the HDF5 User's Guide. See the -
    References section of this tutorial. +more rigorous DDL can be found in the +DDL in BNF for HDF5, a section of the +HDF5 User's Guide.

    Fig. 4.3   HDF5 File Definition

    - The explanation of the symbols used in the DDL: + The following symbol definitions are used in the DDL:

     
             ::=               defined as
    @@ -187,7 +284,7 @@ more rigorous DDL can be found in the HDF5 User's Guide.  See the
             <a> | <b>         one of <a> or <b>
             <a>*              zero or more occurrences of <a>
     
    - The simplified DDL file definition: + The simplified DDL for file definition is as follows:
             <file> ::= HDF5 "<file_name>" { <root_group> }
     
    @@ -211,14 +308,14 @@ more rigorous DDL can be found in the HDF5 User's Guide.  See the
     
     
     hdfhelp@ncsa.uiuc.edu
    -
    Last Modified: August 27, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: April 5, 2000

    + -
    + - - - diff --git a/doc/html/Tutor/crtgrp.html b/doc/html/Tutor/crtgrp.html index 566fd2c..678f805 100644 --- a/doc/html/Tutor/crtgrp.html +++ b/doc/html/Tutor/crtgrp.html @@ -42,13 +42,25 @@ program must:
  • Create the group.
  • Close the group. -To create a group, the calling program must contain the following calls: +To create a group, the calling program must call +H5Gcreate/h5gcreate_f. +To close the group, H5Gclose/h5gclose_f +must be called. For example: +

    +C:

       group_id = H5Gcreate (loc_id, name, size_hint);
    -  H5Gclose (group_id);
    +  status = H5Gclose (group_id);
     
    +FORTRAN: +
    +  CALL h5gcreate_f (loc_id, name, group_id, error, size_hint=size)
    +       or
    +  CALL h5gcreate_f (loc_id, name, group_id, error)
     
     
    +  CALL h5gclose_f (group_id, error)
    +

    @@ -56,77 +68,102 @@ To create a group, the calling program must contain the following calls:

    Description

    The following example shows how to create and close a group. It creates a file -called 'group.h5', creates a group called MyGroup in the root group, +called group.h5 (groupf.h5 for FORTRAN), +creates a group called MyGroup in the root group, and then closes the group and file.
    -[
    Download h5_crtgrp.c ] -
    -
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -
    -#include <hdf5.h>
    -#define FILE "group.h5"
    -
    -main() {
    -
    -   hid_t       file_id, group_id;  /* identifiers */
    -   herr_t      status;
    -
    -   /* Create a new file using default properties. */
    -   file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
    -
    -   /* Create a group named "/MyGroup" in the file. */
    -   group_id = H5Gcreate(file_id, "/MyGroup", 0);
    -
    -   /* Close the group. */
    -   status = H5Gclose(group_id);
    +
    +NOTE: To download a tar file of the examples, including a Makefile,
    +please go to the References page.
     
    -   /* Terminate access to the file. */
    -   status = H5Fclose(file_id);
    -}
    -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
     

    Remarks

      -
    • H5Gcreate creates a new empty group and returns a group identifier. +
    • H5Gcreate/h5gcreate_f creates + a new empty group, named MyGroup and located in the + root group, and returns a group identifier. +

      +C:

         hid_t H5Gcreate (hid_t loc_id, const char *name, size_t size_hint) 
       
      +FORTRAN: +
      +  h5gcreate_f (loc_id, name, group_id, hdferr, size_hint)
      +
      +           loc_id     INTEGER(HID_T)
      +           name       CHARACTER(LEN=*)
      +           group_id   INTEGER(HID_T)
      +           hdferr     INTEGER
      +                      (Possible values: 0 on success and -1 on failure)
      +           size_hint  INTEGER(SIZE_T), OPTIONAL
      +                      (Default value: OBJECT_NAMELEN_DEFAULT_F)
      +         
      +
        -
      • The first parameter specifies the location to create the group. - -
      • The second parameter specifies the name of the group to be created. - -
      • The third parameter specifies how much file space to reserve to store the +
      • The loc_id parameter specifies the location at which + to create the group. +

        +

      • The name parameter specifies the name of the group to be created. +

        +

      • The size_hint parameter specifies how much file space to + reserve to store the names that will appear in the group. If a non-positive value is supplied, then a default size is used. Passing a value of zero is usually adequate since the library is able to dynamically resize the name heap. +

        +

      • In FORTRAN, the return value for the routine is passed in + hdferr: 0 if successful, -1 otherwise. The group identifier + is passed back in group_id. In C, the function returns a valid + group identifier if successful and a negative value otherwise. +

      -

    • H5Gcreate creates a group named MyGroup in the root group of the specified - file. +
    • H5Gclose/h5gclose_f closes the group. + This call is mandatory.

      -

    • H5Gclose closes the group. This call is mandatory. +C:
         herr_t H5Gclose (hid_t group_id) 
       
      +FORTRAN: +
      +  h5gclose_f (group_id, hdferr)
      +
      +           group_id  INTEGER(HID_T)
      +           hdferr    INTEGER
      +                     (Possible values: 0 on success and -1 on failure)
      +         
      +

    File Contents

    -The contents of 'group.h5' and the definition of the group are given in the -following: +The contents of group.h5 and the +definition of the group are shown below. (The FORTRAN program +creates the HDF5 file groupf.h5 and the resulting DDL shows +groupf.h5 in the first line.)

    - - -
    Fig. 8.1   The Contents of 'group.h5'. + + + + - + - - + +
    Fig. 8.1   The Contents of group.h5. +   Fig. 8.2   'group.h5' in DDL Fig. 8.2   group.h5 in DDL
    +  
           
     HDF5 "group.h5" {
     GROUP "/" {
    @@ -154,7 +191,9 @@ GROUP "/" {
     
     
     hdfhelp@ncsa.uiuc.edu
    -
    Last Modified: August 27, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: April 5, 2000


    diff --git a/doc/html/Tutor/crtgrpar.html b/doc/html/Tutor/crtgrpar.html index d5fbc66..2ad598a 100644 --- a/doc/html/Tutor/crtgrpar.html +++ b/doc/html/Tutor/crtgrpar.html @@ -1,5 +1,5 @@ -HDF5 Tutorial - Creating Groups using Absolute/Relative Names +<TITLE>HDF5 Tutorial - Creating Groups using Absolute and Relative Names @@ -13,8 +13,8 @@ width=78 height=27 alt="NCSA">

    [ HDF5 Tutorial Top ]

    -Creating Groups using -Absolute/Relative Names +Creating Groups Using +Absolute and Relative Names


    @@ -39,95 +39,103 @@ object is to be created. This location is determined by the identifier of an HDF object and the name of the object to be created. The name of the created object can be either an absolute name or a name relative to the specified identifier. -In Example 5, we used the file identifier and the absolute name "/MyGroup" to create a -group. The file identifier and the name "/" specifies the location where the group -"MyGroup" was created. +In the previous example, we used the file identifier and the absolute name +/MyGroup to create a group.

    -In this section, we discuss HDF5 names and show how to use absolute/relative -names by giving an example of creating groups in a file. +In this section, we discuss HDF5 names and show how to use absolute and +relative names.

    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 +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 name which begins with a -slash is an absolute name which is accessed beginning with the root group of the -file while all other relative names are accessed beginning with the specified -group. Multiple consecutive slashes in a full name are treated as single slashes -and trailing slashes are not significant. A special case is the name "/" (or +of the component names being the special name . (a dot or period). +A name which begins with a slash is an absolute name which is accessed +beginning with the root group of the file; +all other names are relative names and and the named object is +accessed beginning with the specified group. +Multiple consecutive slashes in a full name are treated as single slashes +and trailing slashes are not significant. A special case is the name / (or equivalent) which refers to the root group.

    -Functions which operate on names generally take a location identifier which -is either a file ID or a group ID and perform the lookup with respect to that -location. Some possibilities are: +Functions which operate on names generally take a location identifier, which +can be either a file identifier or a group identifier, and perform the lookup +with respect to that location. +Several possibilities are described in the following table: - +
    +
    - + - + - + - + - + - + - + - + - + - + - +
    Location Type Object Name Description
    File IDFile identifier -
    /foo/bar
    +
    /foo/bar
    The object bar in group foo in the root group. The object bar in group foo + in the root group.
    Group ID Group identifier -
    /foo/bar
    +
    /foo/bar
    The object bar in group foo in the root group of the file containing the - specified group. In other words, the group ID's only purpose is to supply - a file. The 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 IDFile identifier
    /
    The root group of the specified file.
    Group IDGroup identifier
    /
    The root group of the file containing the specified group.
    Group IDGroup identifier -
    foo/bar
    +
    foo/bar
    The object bar in group foo in the specified group.The object bar in group foo in + the specified group.
    File IDFile identifier -
    .
    +
    .
    The root group of the file.
    Group IDGroup identifier -
    .
    +
    .
    The specified group.
    Other IDOther identifier -
    .
    +
    .
    The specified object.
    +

    @@ -136,74 +144,51 @@ location. Some possibilities are:

    Description

    The following example code shows how to create groups using absolute and relative names. It creates three groups: the first two groups are -created using the file identifier and the group absolute names, and the -third group is created using a group identifier and the name relative +created using the file identifier and the group absolute names while the +third group is created using a group identifier and a name relative to the specified group.
    -[ Download h5_crtgrpar.c ] - -
    -
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -
    -#include <hdf5.h>
    -#define FILE "groups.h5"
    -
    -main() {
    -
    -   hid_t       file_id, group1_id, group2_id, group3_id;  /* identifiers */
    -   herr_t      status;
    -
    -   /* Create a new file using default properties. */
    -   file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
    -
    -   /* Create group "MyGroup" in the root group using absolute name. */
    -   group1_id = H5Gcreate(file_id, "/MyGroup", 0);
    -
    -   /* Create group "Group_A" in group "MyGroup" using absolute name. */
    -   group2_id = H5Gcreate(file_id, "/MyGroup/Group_A", 0);
    -
    -   /* Create group "Group_B" in group "MyGroup" using relative name. */
    -   group3_id = H5Gcreate(group1_id, "Group_B", 0);
    +
     
    -   /* Close groups. */
    -   status = H5Gclose(group1_id);
    -   status = H5Gclose(group2_id);
    -   status = H5Gclose(group3_id);
    -
    -   /* Close the file. */
    -   status = H5Fclose(file_id);
    -}
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -
    +NOTE: To download a tar file of the examples, including a Makefile, +please go to the References page.

    Remarks

      -
    • H5Gcreate creates a group at the location specified by a location ID and a - name. The location ID can be a file ID or a group ID and the name can be - relative or absolute. - -
    • The first H5Gcreate creates the group 'MyGroup' in the root group of the - specified file. - -
    • The second H5Gcreate creates the group 'Group_A' in the group 'MyGroup' - in the root group of the specified file. Note that the parent group (MyGroup) - already exists. - -
    • The third H5Gcreate creates the group 'Group_B' in the specified group. +
    • H5Gcreate/h5gcreate_f 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.

    File Contents

    The file contents are shown below:

    -Fig. 9.1   The Contents of 'groups.h5' +Fig. 9.1   The Contents of groups.h5 + (groupsf.h5 for FORTRAN)

    - Fig. 9.2   'groups.h5' in DDL + Fig. 9.2   groups.h5 in DDL + (for FORTRAN, the name in the first line is groupsf.h5)
     
           HDF5 "groups.h5" {
    @@ -233,7 +218,9 @@ The file contents are shown below:
     
     
     hdfhelp@ncsa.uiuc.edu
    -
    Last Modified: August 27, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: April 5, 2000


    diff --git a/doc/html/Tutor/crtgrpd.html b/doc/html/Tutor/crtgrpd.html index e92a101..c9c7129 100644 --- a/doc/html/Tutor/crtgrpd.html +++ b/doc/html/Tutor/crtgrpd.html @@ -32,13 +32,16 @@ width=78 height=27 alt="NCSA">


    Creating 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 -refers to a group, then the dataset is created in that group. +We have shown how to create groups, datasets, and attributes. +In this section, we show how to create datasets in groups. +Recall that H5Dcreate/h5dcreate_f +creates a dataset at the location specified by a location identifier and +a name. Similar to H5Gcreate/h5gcreate_f, +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.

    Programming Example

    @@ -46,127 +49,98 @@ refers to a group, then the dataset is created in that group.

    Description

    This example shows how to create a dataset in a particular group. It opens the file created in the previous example and creates two datasets.
    -[
    Download h5_crtgrpd.c ] -
    -
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -
    -#include <hdf5.h>
    -#define FILE "groups.h5"
    -
    -main() {
    -
    -   hid_t       file_id, group_id, dataset_id, dataspace_id;  /* identifiers */
    -   hsize_t     dims[2];
    -   herr_t      status;
    -   int         i, j, dset1_data[3][3], dset2_data[2][10];
    -
    -   /* Initialize the first dataset. */
    -   for (i = 0; i < 3; i++)
    -      for (j = 0; j < 3; j++)
    -         dset1_data[i][j] = j + 1;
    -
    -   /* Initialize the second dataset. */
    -   for (i = 0; i < 2; i++)
    -      for (j = 0; j < 10; j++)
    -         dset2_data[i][j] = j + 1;
    -
    -   /* Open an existing file. */
    -   file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);
    -
    -   /* Create the data space for the first dataset. */
    -   dims[0] = 3;
    -   dims[1] = 3;
    -   dataspace_id = H5Screate_simple(2, dims, NULL);
    -
    -   /* Create a dataset in group "MyGroup". */
    -   dataset_id = H5Dcreate(file_id, "/MyGroup/dset1", H5T_STD_I32BE, dataspace_id
    -,
    -                       H5P_DEFAULT);
    -
    -   /* Write the first dataset. */
    -   status = H5Dwrite(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT,
    -                     dset1_data);
    -
    -   /* Close the data space for the first dataset. */
    -   status = H5Sclose(dataspace_id);
    -
    -   /* Close the first dataset. */
    -   status = H5Dclose(dataset_id);
    -
    -   /* Open an existing group of the specified file. */
    -   group_id = H5Gopen(file_id, "/MyGroup/Group_A");
    -
    -   /* Create the data space for the second dataset. */
    -   dims[0] = 2;
    -   dims[1] = 10;
    -   dataspace_id = H5Screate_simple(2, dims, NULL);
    -
    -   /* Create the second dataset in group "Group_A". */
    -   dataset_id = H5Dcreate(group_id, "dset2", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT);
    -
    -   /* Write the second dataset. */
    -   status = H5Dwrite(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT,
    -                     dset2_data);
    -
    -   /* Close the data space for the second dataset. */
    -   status = H5Sclose(dataspace_id);
    -
    -   /* Close the second dataset */
    -   status = H5Dclose(dataset_id);
    -
    -   /* Close the group. */
    -   status = H5Gclose(group_id);
    -
    -   /* Close the file. */
    -   status = H5Fclose(file_id);
    -}
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -
    + +NOTE: To download a tar file of the examples, including a Makefile, +please go to the References page.

    File Contents

    -Fig. 10.1   The Contents of 'groups.h5' +Fig. 10.1   The Contents of groups.h5 + (groupsf.h5 for FORTRAN)

     
    - Fig. 10.2   'groups.h5' in DDL + Fig. 10.2a   groups.h5 in DDL
     
    -   HDF5 "groups.h5" {
    -      GROUP "/" {
    -         GROUP "MyGroup" {
    -            GROUP "Group_A" {
    -               DATASET "dset2" {
    -                  DATATYPE { H5T_STD_I32BE }
    -                  DATASPACE { SIMPLE ( 2, 10 ) / ( 2, 10 ) }
    -                  DATA {
    -                     1, 2, 3, 4, 5, 6, 7, 8, 9, 10,
    -                     1, 2, 3, 4, 5, 6, 7, 8, 9, 10
    -                  }
    -               }
    -            }
    -            GROUP "Group_B" {
    -            }
    -            DATASET "dset1" {
    -               DATATYPE { H5T_STD_I32BE }
    -               DATASPACE { SIMPLE ( 3, 3 ) / ( 3, 3 ) }
    -               DATA {
    -                  1, 2, 3,
    -                  1, 2, 3,
    -                  1, 2, 3
    -               }
    +HDF5 "groups.h5" {
    +GROUP "/" {
    +   GROUP "MyGroup" {
    +      GROUP "Group_A" {
    +         DATASET "dset2" {
    +            DATATYPE { H5T_STD_I32BE }
    +            DATASPACE { SIMPLE ( 2, 10 ) / ( 2, 10 ) }
    +            DATA {
    +               1, 2, 3, 4, 5, 6, 7, 8, 9, 10,
    +               1, 2, 3, 4, 5, 6, 7, 8, 9, 10
                 }
              }
           }
    +      GROUP "Group_B" {
           }
    +      DATASET "dset1" {
    +         DATATYPE { H5T_STD_I32BE }
    +         DATASPACE { SIMPLE ( 3, 3 ) / ( 3, 3 ) }
    +         DATA {
    +            1, 2, 3,
    +            1, 2, 3,
    +            1, 2, 3
    +         }
    +      }
    +   }
    +}
    +}
     
    + Fig. 10.2b   groupsf.h5 in DDL +
     
    -
    +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
    +         }
    +      }
    +   }
    +}
    +}
    +


    @@ -178,7 +152,9 @@ main() {
    hdfhelp@ncsa.uiuc.edu -
    Last Modified: August 27, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: April 5, 2000


    diff --git a/doc/html/Tutor/extend.html b/doc/html/Tutor/extend.html index 03b5972..2c7fb11 100644 --- a/doc/html/Tutor/extend.html +++ b/doc/html/Tutor/extend.html @@ -35,16 +35,19 @@ width=78 height=27 alt="NCSA">


    Creating an Extendible Dataset

    -An extendible dataset is one whose dimensions can grow. In HDF5, it is possible to define a dataset to have certain initial dimensions, then later -to increase the size of any of the initial dimensions. +An extendible dataset is one whose dimensions can grow. +HDF5 allows you to define a dataset to have certain initial dimensions, +then to later increase the size of any of the initial dimensions.

    -HDF5 requires you to use chunking in order to define extendible datasets. Chunking makes it possible to extend datasets efficiently, without -having to reorganize storage excessively. +HDF5 requires you to use chunking to define extendible datasets. +This makes it possible to extend datasets efficiently without +having to excessively reorganize storage.

    The following operations are required in order to write an extendible dataset:

    1. Declare the dataspace of the dataset to have unlimited dimensions for all dimensions that might eventually be extended. -
    2. Set dataset creation properties to enable chunking and create a dataset. +
    3. Set dataset creation properties to enable chunking. +
    4. Create the dataset.
    5. Extend the size of the dataset.

    Programming Example

    @@ -52,229 +55,197 @@ The following operations are required in order to write an extendible dataset:

    Description

    This example shows how to create a 3 x 3 extendible dataset, write to that dataset, extend the dataset to 10x3, and write to the dataset again. -[
    Download h5_extend.c] -
    -
    -/**************************************************************  
    - *
    - *   This example shows how to work with extendible datasets.
    - *   In the current version of the library a dataset MUST be
    - *   chunked in order to be extendible.  
    - *
    - *   This example is derived from the h5_extend_write.c and 
    - *   h5_read_chunk.c examples that are in the "Introduction 
    - *   to HDF5".
    - *   
    - *************************************************************/
    - 
    -#include "hdf5.h"
    -
    -#define FILE        "ext.h5"
    -#define DATASETNAME "ExtendibleArray" 
    -#define RANK         2
    -
    -int
    -main (void)
    -{
    -    hid_t       file;                          /* handles */
    -    hid_t       dataspace, dataset;  
    -    hid_t       filespace;                   
    -    hid_t       cparms;                     
    -    hid_t       memspace;
    -
    -    hsize_t      dims[2]  = { 3, 3};           /* dataset dimensions			
    -                                                  at creation time */
    -    hsize_t      dims1[2] = { 3, 3};           /* data1 dimensions */ 
    -    hsize_t      dims2[2] = { 7, 1};           /* data2 dimensions */  
    -
    -    hsize_t      maxdims[2] = {H5S_UNLIMITED, H5S_UNLIMITED};
    -    hsize_t      size[2];
    -    hssize_t     offset[2];
    -    hsize_t      i,j;
    -    herr_t       status, status_n;                             
    -    int          data1[3][3] = { {1, 1, 1},      /* data to write */
    -                                 {1, 1, 1},
    -                                 {1, 1, 1} };      
    -
    -    int          data2[7]    = { 2, 2, 2, 2, 2, 2, 2};
    -
    -    /* Variables used in reading data back */
    -    hsize_t      chunk_dims[2] ={2, 5};
    -    hsize_t      chunk_dimsr[2];
    -    hsize_t      dimsr[2];
    -    int          data_out[10][3];
    -    int          rank, rank_chunk;
    -
    -    /* Create the data space with unlimited dimensions. */
    -    dataspace = H5Screate_simple (RANK, dims, maxdims); 
    -
    -    /* Create a new file. If file exists its contents will be overwritten. */
    -    file = H5Fcreate (FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
    -
    -    /* Modify dataset creation properties, i.e. enable chunking  */
    -    cparms = H5Pcreate (H5P_DATASET_CREATE);
    -    status = H5Pset_chunk ( cparms, RANK, chunk_dims);
    -
    -    /* Create a new dataset within the file using cparms
    -       creation properties.  */
    -    dataset = H5Dcreate (file, DATASETNAME, H5T_NATIVE_INT, dataspace,
    -                         cparms);
    -
    -    /* Extend the dataset. This call assures that dataset is 3 x 3.*/
    -    size[0]   = 3; 
    -    size[1]   = 3; 
    -    status = H5Dextend (dataset, size);
    -
    -    /* Select a hyperslab  */
    -    filespace = H5Dget_space (dataset);
    -    offset[0] = 0;
    -    offset[1] = 0;
    -    status = H5Sselect_hyperslab (filespace, H5S_SELECT_SET, offset, NULL,
    -                                  dims1, NULL);  
    -
    -    /* Write the data to the hyperslab  */
    -    status = H5Dwrite (dataset, H5T_NATIVE_INT, dataspace, filespace,
    -                       H5P_DEFAULT, data1);
    -
    -    /* Extend the dataset. Dataset becomes 10 x 3  */
    -    dims[0]   = dims1[0] + dims2[0];
    -    size[0]   = dims[0];  
    -    size[1]   = dims[1]; 
    -    status = H5Dextend (dataset, size);
    -
    -    /* Select a hyperslab  */
    -    filespace = H5Dget_space (dataset);
    -    offset[0] = 3;
    -    offset[1] = 0;
    -    status = H5Sselect_hyperslab (filespace, H5S_SELECT_SET, offset, NULL,
    -                                  dims2, NULL);  
    -
    -    /* Define memory space */
    -    dataspace = H5Screate_simple (RANK, dims2, NULL); 
    -
    -    /* Write the data to the hyperslab  */
    -    status = H5Dwrite (dataset, H5T_NATIVE_INT, dataspace, filespace,
    -                       H5P_DEFAULT, data2);
    -
    -    /* Close resources */
    -    status = H5Dclose (dataset);
    -    status = H5Sclose (dataspace);
    -    status = H5Sclose (filespace);
    -    status = H5Fclose (file);
    -
    -/****************************************************************
    -    Read the data back 
    - ***************************************************************/
    -
    -    file = H5Fopen (FILE, H5F_ACC_RDONLY, H5P_DEFAULT);
    -    dataset = H5Dopen (file, DATASETNAME);
    -    filespace = H5Dget_space (dataset);
    -    rank = H5Sget_simple_extent_ndims (filespace);
    -    status_n = H5Sget_simple_extent_dims (filespace, dimsr, NULL);
    -
    -    cparms = H5Dget_create_plist (dataset);
    -    if (H5D_CHUNKED == H5Pget_layout (cparms))
    -    {
    -       rank_chunk = H5Pget_chunk (cparms, 2, chunk_dimsr);
    -    }
    -
    -    memspace = H5Screate_simple (rank,dimsr,NULL);
    -    status = H5Dread (dataset, H5T_NATIVE_INT, memspace, filespace,
    -                      H5P_DEFAULT, data_out);
    -    printf("\n");
    -    printf("Dataset: \n");
    -    for (j = 0; j < dimsr[0]; j++)
    -    {
    -       for (i = 0; i < dimsr[1]; i++)
    -           printf("%d ", data_out[j][i]);
    -       printf("\n");
    -    }
    +
    +NOTE: To download a tar file of the examples, including a Makefile,
    +please go to the References page.
     
    -    status = H5Pclose (cparms);
    -    status = H5Dclose (dataset);
    -    status = H5Sclose (filespace);
    -    status = H5Sclose (memspace);
    -    status = H5Fclose (file);
    -}     
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -

    Remarks

      -
    • The function H5Pcreate creates a new property as an instance of - a property list. The signature of this function is as follows: -
      -  hid_t H5Pcreate ( H5P_class_t type )
      -
      +
    • The routine H5Pcreate / h5pcreate_f +creates a new property as an instance of + a property list. The signature is as follows: +

      +C: +

      +    hid_t H5Pcreate (H5P_class_t classtype)
      +
      +

      +FORTRAN: +

      +    h5pcreate_f (classtype, prp_id, hdferr) 
      +
      +            classtype  IN: INTEGER 
      +            prp_id    OUT: INTEGER(HID_T)
      +            hdferr    OUT: INTEGER 
      +
      +

        -
      • The parameter type is the type of property list to create.
        - The class types are: H5P_FILE_CREATE, H5P_FILE_ACCESS, H5P_DATASET_CREATE, - H5P_DATASET_XFER, and H5P_MOUNT +
      • The parameter classtype is the type of property list to create. + Valid class types are as follows: +
        + + + + + + + + +
        CFORTRAN

        + H5P_FILE_CREATE
        + H5P_FILE_ACCESS
        + H5P_DATASET_CREATE
        + H5P_DATASET_XFER
        + H5P_MOUNT

        +

        + H5P_FILE_CREATE_F
        + H5P_FILE_ACCESS_F
        + H5P_DATASET_CREATE_F
        + H5P_DATASET_XFER_F
        + H5P_MOUNT_F

        +
        +
        +
      • In C, the property list identifier is returned if successful; +otherwise a negative value is returned, if not. +In FORTRAN, the property list identifier is returned in prp_id +and the return value for the call is returned in hdferr.

      -

    • The function H5Pset_chunk sets the size of the chunks used +
    • The routine H5Pset_chunk / h5pset_chunk_f +sets the size of the chunks used to store a chunked layout dataset. - The signature of this function is as follows: -
      -  herr_t H5Pset_chunk ( hid_t plist, int ndims, const hsize_t * dim ) 
      -
      + The signature of this routine is as follows: +

      +C: +

      +    herr_t H5Pset_chunk (hid_t prp_id, int ndims, 
      +                         const hsize_t * dims) 
      +
      +

      +FORTRAN: +

      +    h5pset_chunk_f (prp_id, ndims, dims, hdferr) 
      +
      +            prp_id    IN: INTEGER(HID_T)
      +            ndims     IN: INTEGER
      +            dims      IN: INTEGER(HSIZE_T), DIMENSION(ndims) 
      +            hdferr   OUT: INTEGER
      +
      +
      +

        -
      • The first parameter, plist, is the identifier for the property +
      • The prp_id parameter is the identifier for the property list to query. -
      • The second parameter, ndims, is the number of dimensions of +
      • The ndims parameter is the number of dimensions of each chunk. -
      • The third parameter, dim, is an array containing the size of +
      • The dims parameter is an array containing the size of each chunk. +
      • In C, a non-negative value is returned if successful; otherwise a + negative value is returned. + In FORTRAN, the return value is returned in hdferr: 0 if + successful and -1 otherwise.

      -A non-negative value is returned if successful; otherwise a negative -value is returned. -

      -

    • The function H5Dextend extends a dataset that has an unlimited +
    • The H5Dextend / h5dextend_f routine +extends a dataset that has an unlimited dimension. The signature is as follows: -
      -  herr_t H5Dextend ( hid_t dataset_id, const hsize_t * size ) 
      -
      +

      +C: +

      +    herr_t H5Dextend (hid_t dset_id, const hsize_t * size) 
      +
      +

      +FORTRAN: +

      +    h5dextend_f (dset_id, size, hdferr) 
      +
      +            dset_id   IN: INTEGER(HID_T) 
      +            size         IN: INTEGER(HSIZE_T), DIMENSION(*)  
      +            hdferr      OUT: INTEGER
      +
      +

        -
      • The first parameter, dataset_id, is the identifier of - the dataset. -
      • The second parater, size, is an array containing the +
      • The dset_id parameter is the dataset identifier. +
      • The size parameter, is an array containing the new magnitude of each dimension. +
      • In C, this function returns a non-negative value if successful and + a negative value otherwise. + In FORTRAN, the return value is returned in hdferr: + 0 if successful and -1 otherwise.

      -This function returns a non-negative value if successful; otherwise -it returns a negative value. -

      -

    • The H5Dget_create_plist function returns an identifier for a +
    • The H5Dget_create_plist / h5dget_create_plist_f +routine returns an identifier for a copy of the dataset creation property list for a dataset.

      -

    • The H5Pget_layout function returns the layout of the raw data for a -dataset. Valid types are H5D_COMPACT, H5D_CONTIGUOUS, and H5D_CHUNKED. +
    • The C function, H5Pget_layout, returns the layout of the raw data for a +dataset. Valid types are H5D_CONTIGUOUS and +H5D_CHUNKED. +A FORTRAN routine for H5Pget_layout does not yet exist. +

      +

    • The H5Pget_chunk / h5pget_chunk_f +routine retrieves the size of chunks +for the raw data of a chunked layout dataset. +The signature is as follows: +

      +C: +

      +    int H5Pget_chunk (hid_t prp_id, int ndims, hsize_t * dims) 
      +
      +

      +FORTRAN: +

      +    h5pget_chunk_f (prp_id, ndims, dims, hdferr)
      +
      +            prp_id    IN: INTEGER(HID_T) 
      +            ndims     IN: INTEGER
      +            dims     OUT: INTEGER(HSIZE_T), DIMENSION(ndims) 
      +            hdferr   OUT: INTEGER 
      +

      -

    • The H5Pget_chunk function retrieves the size of chunks for the -raw data of a chunked layout dataset. -The signature of this function is: -
      -  int H5Pget_chunk ( hid_t plist, int max_ndims, hsize_t * dims ) 
      -
        -
      • The first parameter, plist, is the identifier of the + +
      • The prp_id parameter is the identifier of the property list to query. -
      • The second parameter, max_ndims, is the size of the dims +
      • The ndims parameter is the size of the dims array. -
      • The third parameter, dims, is the array to store the chunk - dimensions +
      • The dims parameter is the array in which to store the chunk + dimensions. +
      • In C, this function returns the chunk dimensionality if successful + and a negative value otherwise. + In FORTRAN, the return value is returned in hdferr: + the chunked rank if successful and -1 otherwise.

      -

    • The H5Pclose function terminates access to a property list. - The signature of this function is: -
      -  herr_t H5Pclose ( hid_t plist ) 
      -
      -where plist is the identifier of the property list to terminate -access to. +
    • The H5Pclose / h5pclose_f routine + terminates access to a property list. + The signature is as follows: +

      +C: +

      +    herr_t H5Pclose (hid_t prp_id) 
      +
      +

      +FORTRAN: +

      +    h5pclose_f (prp_id, hdferr) 
      +
      +            prp_id    IN: INTEGER(HID_T) 
      +            hdferr   OUT: INTEGER 
      +
      +

      +

        +
      • The prp_id parameter is the identifier of the property list + to terminate access to. +
    @@ -301,8 +272,11 @@ access to.
    hdfhelp@ncsa.uiuc.edu -
    Last Modified: August 27, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: January 19, 2000

    +
    diff --git a/doc/html/Tutor/fileorg.html b/doc/html/Tutor/fileorg.html index 03c2c29..afc0cba 100644 --- a/doc/html/Tutor/fileorg.html +++ b/doc/html/Tutor/fileorg.html @@ -21,28 +21,28 @@ width=78 height=27 alt="NCSA">

    -An HDF5 file is a container for storing a variety of scientific data, and the -two primary HDF5 objects are groups and datasets. +An HDF5 file is a container for storing a variety of scientific data +is composed of two primary types of objects: groups and datasets.

    • HDF5 group: a grouping structure containing zero or more HDF5 - objects, together with supporting metadata. + objects, together with supporting metadata
    • HDF5 dataset: a multidimensional array of data elements, together - with supporting metadata. + 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 +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 group members (datasets for example) is similar in many +Working with groups and datasets is similar in many ways to working with directories and files in UNIX. As with UNIX directories -and files, objects in an HDF5 file are often described by giving their full (or -absolute) path names. +and files, an HDF5 object in an HDF5 file is often referred to by its +full path name (also called an absolute path name).

      / signifies the root group.
      - /foo signifies a member of the root group called foo. + /foo signifies a member of the root group called foo.
      - /foo/zoo signifies a member of the group foo, which in + /foo/zoo signifies a member of the group foo, which in turn is a member of the root group.

    @@ -90,8 +90,11 @@ The tutorial ends with a glossary and references. hdfhelp@ncsa.uiuc.edu -

    Last Modified: July 30, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: December 10, 1999

    +
    diff --git a/doc/html/Tutor/glossary.html b/doc/html/Tutor/glossary.html index 84a938d..82757b8 100644 --- a/doc/html/Tutor/glossary.html +++ b/doc/html/Tutor/glossary.html @@ -44,8 +44,8 @@ number of entries in symbol tables (used to store groups) and additional version manner, called a complex dataspace.

    -

    DATA TYPE -
    An HDF5 Data Type is an object that describes the type of the +
    DATATYPE +
    An HDF5 Datatype is an object that describes the type of the element in an HDF5 multi-dimensional array. There are two categories of datatypes: atomic and compound data types. An atomic type is a type which cannot be decomposed into smaller @@ -181,6 +181,13 @@ A hyperslab is a portion of a dataset. A hyperslab selection can be a logically contiguous collection of points in a dataspace, or it can be a regular pattern of points or blocks in a dataspace.

    +

    MOUNTING FILES +
    +HDF5 allows you to combine two or more HDF5 files in a manner similar +to mounting files in UNIX. The group structure and metadata +from one file appear as though they exist in another file. +

    +

    NAMES
    HDF5 object names are a slash-separated list of components. A name which begins with a slash is an absolute name which is accessed @@ -192,6 +199,28 @@ can be a regular pattern of points or blocks in a dataspace. MPI (Message Passing Interface).

    +

    REFERENCE +
    +OBJECT REFERENCE:
    + A reference to an entire object in the current HDF5 file. +

    + An object + reference points to an entire object in the current HDF5 file by storing + the relative file address (OID) of the object header for the object + pointed to. The relative file address of an object header is constant + for the life of the object. An object reference is of a fixed size in + the file. +

    +DATASET REGION REFERENCE:
    + Reference to a specific dataset region. +

    + A dataset region reference points to a region of a dataset in the + current HDF5 file by storing the OID of the dataset and the global + heap offset of the region referenced. The region referenced is + located by retrieving the coordinates of the areas in the region + from the global heap. A dataset region reference is of a variable + size in the file. +

    THREADSAFE (HDF5)
    A "thread-safe" version of HDF-5 (TSHDF5) is one that can be called from any thread of a multi-threaded program. Any calls to HDF can be made in any order, and each individual HDF call will perform correctly. A calling program does not have to explicitly lock the HDF @@ -221,7 +250,9 @@ library as regular HDF-5 library, with additional code to synchronize access to hdfhelp@ncsa.uiuc.edu -
    Last Modified: September 1, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: January 5, 2000


    diff --git a/doc/html/Tutor/intro.html b/doc/html/Tutor/intro.html index abf664c..0cca74a 100644 --- a/doc/html/Tutor/intro.html +++ b/doc/html/Tutor/intro.html @@ -22,27 +22,39 @@ width=78 height=27 alt="NCSA">

    Welcome to the HDF5 Tutorial provided by the HDF User Support Group.

    HDF5 is a file format and library for storing scientific data. -HDF5 was designed and implemented to address the deficiencies of HDF4.x. -It has a more powerful and flexible data model, supports files larger than 2 GB, -supports parallel I/O, and is thread-safe. For a short overview presentation -of the HDF5 data model, library and tools see: +It was designed and implemented + to meet growing and ever-changing scientific data-storage + and data-handling needs, + to take advantage of the power and features of today's + computing systems, and + to address the deficiencies of HDF4.x. +HDF5 has a powerful and flexible data model, + supports files larger than 2 GB (the limit of HDF4.x files), and + supports parallel I/O. +Thread-safety is designed and is to be implemented in the near future. +For a short overview of the HDF5 data model, library, and tools, see +the slide presentation at the following URL:

    -   http://hdf.ncsa.uiuc.edu/HDF5/HDF5_overview/index.htm
    +   http://hdf.ncsa.uiuc.edu/HDF5/papers/HDF5_overview/index.htm
     
    This tutorial covers the basic HDF5 data objects and file structure, -the HDF5 programming model and the API functions necessary for creating and -modifying data objects. It also introduces the available HDF5 tools to access +the HDF5 programming model, and the API functions necessary for creating and +modifying data objects. It also introduces the available HDF5 tools for accessing HDF5 files.

    -The examples used in this tutorial, along with a Makefile to compile them +The examples used in this tutorial, along with a Makefile to compile them, can be found in ./examples/. You can also download a tar -file with the examples and Makefile. In -order to use the Makefile you may have to edit it and update the +file with the examples and Makefile. +To use the Makefile, you may have to edit it and update the compiler and compiler options, as well as the path for the HDF5 binary distribution. +The Java examples can be found in +a subdirectory of the ./examples/ directory called java/. The java/ +directory contains a Makefile and shell scripts for running the java +programs.

    -Please check the References for where to find +Please check the References for pointers to other examples of HDF5 Programs.

    We hope that the step-by-step examples and instructions will give you a quick @@ -68,8 +80,11 @@ Please send your comments and suggestions to hdfhelp@ncsa.uiuc.edu. hdfhelp@ncsa.uiuc.edu -

    Last Modified: October 8, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: April 5, 2000

    +
    diff --git a/doc/html/Tutor/iterate.html b/doc/html/Tutor/iterate.html index 4cb0475..e051764 100644 --- a/doc/html/Tutor/iterate.html +++ b/doc/html/Tutor/iterate.html @@ -21,11 +21,13 @@ width=78 height=27 alt="NCSA">

    Contents:

    + +

    Reading or Writing Data

    + +The Data Transfer property list, H5P_DATASET_XFER, is used to control +various aspects of I/O, such as caching hints or collective I/O information. +

    +The following code sets the maximum size for the type conversion buffer +and background buffer: +

    +   plist_xfer = H5Pcreate (H5P_DATASET_XFER);
    +   H5Pset_buffer(plist_xfer, (hsize_t)NX*NY*NZ, NULL, NULL);
    +   status = H5Dread (dataset, H5T_NATIVE_UCHAR, memspace, dataspace,
    +                      plist_xfer);
    +
    +See:
    + [
    C program ] + - h5_xfer.c
    + + + + +


    + + NCSA
    + The National Center for Supercomputing Applications

    + University of Illinois + at Urbana-Champaign
    +
    + + +hdfhelp@ncsa.uiuc.edu +
    +
    Last Modified: February 12, 2001

    + +
    +
    + + + + + + + diff --git a/doc/html/Tutor/questions.html b/doc/html/Tutor/questions.html index 26153f3..92d9d36 100644 --- a/doc/html/Tutor/questions.html +++ b/doc/html/Tutor/questions.html @@ -1,5 +1,5 @@ -HDF5 Tutorial - Introductory Topics Questions +<TITLE>HDF5 Tutorial - Introductory Topics Quiz @@ -13,106 +13,125 @@ width=78 height=27 alt="NCSA">

    [ HDF5 Tutorial Top ]

    -Introductory Topics Questions +Introductory Topics Quiz


    -
     
     
    -Section 2: HDF File Organization
    -================================
    +

    Section 2: HDF File Organization

    -1. Name and describe the two primary objects that can be stored in an HDF5 - file: +
      +
    1. Name and describe the two primary objects that can be stored in an HDF5 + file. -2. What is an attribute? +

      +

    2. What is an attribute? -3. Give the path name for an object called "harry" that is a member of a - group called "dick," which in turn is a member of the root group. +

      +

    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. +
    -Section 3: The HDF5 API -======================= +

    Section 3: The HDF5 API

    -Describe the purpose of each of the following HDF5 APIs: +
      +
    1. Describe the purpose of each of the following HDF5 APIs: + + H5A, H5D, H5E, H5F, H5G, H5T, H5Z + +
    -H5A, H5D, H5E, F5F, H5G, H5T, H5Z +

    Section 4: Creating an HDF5 File

    +
      +
    1. What two HDF5 routines must be called to create an HDF5 file? -Section 4: Creating an HDF File -=============================== +

      +

    2. What include file must be included in any file that uses the HDF5 library? -1. What two HDF5 routines must be called in order to create an HDF5 file? +

      +

    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? +
    -2. What include file must be included in any file that uses the HDF5 library. -3. An HDF5 file is never completely empty because as soon as an HDF5 file - is created, it automatically contains a certain primary object. What is - that object? +

    Section 5: Creating a Dataset

    +
      +
    1. Name and describe two major datatype categories. +

      +

    2. List the HDF5 atomic datatypes. Give an example of a predefined datatype. -Section 5: Creating a Dataset -============================= +

      +

    3. What does the dataspace describe? What are the major characteristics of + the simple dataspace? -1. Name and describe two major datatype categories. +

      +

    4. What information needs to be passed to the H5Dcreate + function, i.e., what information is needed to describe a dataset at + creation time? +
    -2. List the HDF5 atomic datatypes. Give an example of a predefined datatype. -3. What does the dataspace describe? What are the major characteristics of the - simple dataspace? +

    Section 6: Reading from and Writing to a Dataset

    -4. What information needs to be passed to the H5Dcreate function, i.e. - what information is needed to describe a dataset at creation time? - - -Section 6: Reading from/Writing to a Dataset -============================================ - -1. What are six pieces of information which need to be specified for +
      +
    1. What are six pieces of information which need to be specified for reading and writing a dataset? -2. Why are both the memory dataspace and file dataspace needed for - read/write operations, but only the memory datatype is specified for the - datatype? +

      +

    2. Why are both the memory dataspace and file dataspace needed for + read/write operations, while only the memory datatype is required? -3. What does the line DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } in Fig 6.1 - means? +

      +

    3. What does the line +
          + DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } +
      in Figure 6.1 mean? +
    -Section 7: Creating an Attribute -================================ +

    Section 7: Creating an Attribute

    -1. What is an attribute? +
      +
    1. What is an attribute? -2. Can partial I/O operations be performed on attributes? +

      +

    2. Can partial I/O operations be performed on attributes? +
    -Section 8: Creating a Group -=========================== +

    Section 8: Creating a Group

    -What are the two primary objects that can be included in -a group? +
      +
    1. What are the two primary objects that can be included in a group? +
    -Section 9: Creating Groups using Absolute/Relative Names -======================================================== +

    Section 9: Creating Groups Using Absolute and Relative Names

    -1. Group names can be specified in two "ways". What are these - two types of group names that you can specify? +
      +
    1. Group names can be specified in two ways. What are these two types + of group names? -2. You have a dataset named "moo" in the group "boo", which is - in the group "foo", which in turn, is in the root group. How would - you specify an absolute name to access this dataset? +

      +

    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? +
    -Section 10: Creating Datasets in Groups -======================================= +

    Section 10: Creating Datasets in Groups

    -Describe a way to access the dataset "moo" described in the previous section -(Section 9, question 2), using a relative and absolute pathname. +
      +
    1. Describe a way to access the dataset moo described in the +previous section (Section 9, question 2) using a relative name. +Describe a way to access the same dataset using an absolute name. +
    @@ -129,7 +148,9 @@ Describe a way to access the dataset "moo" described in the previous section hdfhelp@ncsa.uiuc.edu -
    Last Modified: August 2, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: January 13, 2000


    diff --git a/doc/html/Tutor/rdwt.html b/doc/html/Tutor/rdwt.html index 1eb1a84..445bdf2 100644 --- a/doc/html/Tutor/rdwt.html +++ b/doc/html/Tutor/rdwt.html @@ -1,5 +1,5 @@ -HDF5 Tutorial - Reading to/Writing from a Dataset +<TITLE>HDF5 Tutorial - Reading from and Writing to a Dataset @@ -13,7 +13,7 @@ width=78 height=27 alt="NCSA">

    [ HDF5 Tutorial Top ]

    -Reading to/Writing from a Dataset +Reading from and Writing to a Dataset


    @@ -21,7 +21,7 @@ width=78 height=27 alt="NCSA">

    Contents:

    +FORTRAN:
    -   H5Dwrite(dataset_id, mem_type_id, mem_space_id, file_space_id,
    -            xfer_plist_id, buf);
    +   CALL h5dread_f(dset_id, mem_type_id, buf, error, &
    +                     mem_space_id=mspace_id, file_space_id=fspace_id, &
    +                     xfer_prp=xfer_plist_id)
    +        or
    +   CALL h5dread_f(dset_id, mem_type_id, buf, error)
    +
    +
    +   CALL h5dwrite_f(dset_id, mem_type_id, buf, error, &
    +                     mem_space_id=mspace_id, file_space_id=fspace_id, &
    +                     xfer_prp=xfer_plist_id)
    +        or
    +   CALL h5dwrite_f(dset_id, mem_type_id, buf, error)
     
    @@ -88,130 +108,241 @@ To read to/write from a dataset, the calling program must contain the following

    Description

    The following example shows how to read and write an existing dataset. It opens the file created in the previous example, obtains the dataset -identifier, -/dset, writes the dataset to the file, then reads the dataset back from +identifier for the dataset /dset, +writes the dataset to the file, then reads the dataset back from memory. It then closes the dataset and file.
    -[
    Download h5_rdwt.c ] - -
    -
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    -
    -#include <hdf5.h>
    -#define FILE "dset.h5"
    -
    -main() {
    -
    -   hid_t       file_id, dataset_id;  /* identifiers */
    -   herr_t      status;
    -   int         i, j, dset_data[4][6];
    -
    -   /* Initialize the dataset. */
    -   for (i = 0; i < 4; i++)
    -      for (j = 0; j < 6; j++)
    -         dset_data[i][j] = i * 6 + j + 1;
    -
    -   /* Open an existing file. */
    -   file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);
    -
    -   /* Open an existing dataset. */
    -
    -   dataset_id = H5Dopen(file_id, "/dset");
    -
    -   /* Write the dataset. */
    -   status = H5Dwrite(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT,
    -                     dset_data);
    -
    -   status = H5Dread(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT,
    -                    dset_data);
    +
     
    -   /* Close the dataset. */
    -   status = H5Dclose(dataset_id);
    +NOTE: To download a tar file of the examples, including a Makefile,
    +please go to the References page.
     
    -   /* Close the file. */
    -   status = H5Fclose(file_id);
    -}
    -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
     

    Remarks

    + +

    File Contents

    +

    +HDF5 File Created by C Example +

    +Fig. A   REF_REG.h5 in DDL

    -HDF5 "trefer2.h5" {
    +
    +HDF5 "REF_REG.h5" {
     GROUP "/" {
    -   DATASET "Dataset1" {
    +   DATASET "MATRIX" {
    +      DATATYPE { H5T_STD_I32BE }
    +      DATASPACE { SIMPLE ( 2, 9 ) / ( 2, 9 ) }
    +      DATA {
    +         1, 1, 2, 3, 3, 4, 5, 5, 6,
    +         1, 2, 2, 3, 4, 4, 5, 6, 6
    +      }
    +   }
    +   DATASET "REGION_REFERENCES" {
           DATATYPE { H5T_REFERENCE }
    -      DATASPACE { SIMPLE ( 4 ) / ( 4 ) }
    +      DATASPACE { SIMPLE ( 2 ) / ( 2 ) }
           DATA {
    -         DATASET 0:744 {(2,2)-(7,7)}, DATASET 0:744 {(6,9), (2,2), (8,4), (1,6),
    -          (2,8), (3,2), (0,4), (9,0), (7,1), (3,3)}, NULL, NULL
    +         DATASET 0:744 {(0,3)-(1,5)}, DATASET 0:744 {(0,0), (1,6), (0,8)}
           }
        }
    -   DATASET "Dataset2" {
    -      DATATYPE { H5T_STD_U8LE }
    -      DATASPACE { SIMPLE ( 10, 10 ) / ( 10, 10 ) }
    +}
    +}
    +
    +
    +HDF5 File Created by FORTRAN Example: +

    +Fig. B   FORTRAN.h5 in DDL +

    +
    +HDF5 "FORTRAN.h5" {
    +GROUP "/" {
    +   DATASET "MATRIX" {
    +      DATATYPE { H5T_STD_I32BE }
    +      DATASPACE { SIMPLE ( 9, 2 ) / ( 9, 2 ) }
           DATA {
    -         0, 3, 6, 9, 12, 15, 18, 21, 24, 27,
    -         30, 33, 36, 39, 42, 45, 48, 51, 54, 57,
    -         60, 63, 66, 69, 72, 75, 78, 81, 84, 87,
    -         90, 93, 96, 99, 102, 105, 108, 111, 114, 117,
    -         120, 123, 126, 129, 132, 135, 138, 141, 144, 147,
    -         150, 153, 156, 159, 162, 165, 168, 171, 174, 177,
    -         180, 183, 186, 189, 192, 195, 198, 201, 204, 207,
    -         210, 213, 216, 219, 222, 225, 228, 231, 234, 237,
    -         240, 243, 246, 249, 252, 255, 255, 255, 255, 255,
    -         255, 255, 255, 255, 255, 255, 255, 255, 255, 255
    +         1, 1,
    +         1, 2,
    +         2, 2,
    +         3, 3,
    +         3, 4,
    +         4, 4,
    +         5, 5,
    +         5, 6,
    +         6, 6
    +      }
    +   }
    +   DATASET "REGION_REFERENCES" {
    +      DATATYPE { H5T_REFERENCE }
    +      DATASPACE { SIMPLE ( 2 ) / ( 2 ) }
    +      DATA {
    +         DATASET 0:744 {(3,0)-(5,1)}, DATASET 0:744 {(0,0), (6,1), (8,0)}
           }
        }
     }
     }
     
    -Notice how raw data of the dataset with the dataset regions is displayed. + +Notice how the raw data in the dataset with the dataset regions is displayed. Each element of the raw data consists of a reference to the dataset (DATASET number1:number2) and its selected region. If the selection is a hyperslab, the corner coordinates of the hyperslab are displayed. For the point selection, the coordinates of each point are displayed. + @@ -532,8 +354,11 @@ Output of this program is :
    hdfhelp@ncsa.uiuc.edu -
    Last Modified: August 27, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: January 19, 2000

    +
    diff --git a/doc/html/Tutor/select.html b/doc/html/Tutor/select.html index 76ef846..2ea4119 100644 --- a/doc/html/Tutor/select.html +++ b/doc/html/Tutor/select.html @@ -1,5 +1,5 @@ -HDF5 Tutorial - Selections using H5Sselect_hyperslab +<TITLE>HDF5 Tutorial - Hyperslab Selections @@ -13,7 +13,7 @@ width=78 height=27 alt="NCSA">

    [ HDF5 Tutorial Top ]

    -Selections using H5Sselect_hyperslab +Hyperslab Selections


    @@ -34,18 +34,21 @@ width=78 height=27 alt="NCSA">


    Selecting a Portion of a Dataspace

    -Hyperslabs are portions of datasets. A hyperslab selection can be a logically contiguous collection of points in a dataspace, or it +Hyperslabs are portions of datasets. A hyperslab selection can be a +logically contiguous collection of points in a dataspace, or it can be a regular pattern of points or blocks in a dataspace. -You can select a hyperslab to write to/read from with the function -H5Sselect_hyperslab. +You can select a hyperslab to write to or read from with the function +H5Sselect_hyperslab / h5sselect_hyperslab_f.

    Programming Example

    Description

    -This example creates a 5 x 6 integer array in a -file called sds.h5. It selects a 3 x 4 hyperslab from the dataset, -as follows (Dimension 0 is offset by 1 and Dimension 1 is offset by 2): +This example creates a 5 x 6 integer array in a file called sds.h5 +(sdsf.h5 in FORTRAN). It +selects a 3 x 4 hyperslab from the dataset as follows (Dimension 0 is +offset by 1 and Dimension 1 is offset by 2):

    +5 x 6 array: @@ -171,245 +174,100 @@ follows (with Dimension 0 offset by 3):
       

    -[ Download h5_hyperslab.c ] -

     
    -/************************************************************
    -  
    -  This example shows how to write and read a hyperslab.  It 
    -  is derived from the h5_read.c and h5_write.c examples in 
    -  the "Introduction to HDF5".
    -
    - ************************************************************/
    - 
    -#include "hdf5.h"
    -
    -#define FILE        "sds.h5"
    -#define DATASETNAME "IntArray" 
    -#define NX_SUB  3                      /* hyperslab dimensions */ 
    -#define NY_SUB  4 
    -#define NX 7                           /* output buffer dimensions */ 
    -#define NY 7 
    -#define NZ  3 
    -#define RANK         2
    -#define RANK_OUT     3
    -
    -#define X     5                        /* dataset dimensions */
    -#define Y     6
    -
    -int
    -main (void)
    -{
    -    hsize_t     dimsf[2];              /* dataset dimensions */
    -    int         data[X][Y];            /* data to write */
    -
    -    /* 
    -     * Data  and output buffer initialization. 
    -     */
    -    hid_t       file, dataset;         /* handles */
    -    hid_t       dataspace;   
    -    hid_t       memspace; 
    -    hsize_t     dimsm[3];              /* memory space dimensions */
    -    hsize_t     dims_out[2];           /* dataset dimensions */      
    -    herr_t      status;                             
    -
    -    int         data_out[NX][NY][NZ ]; /* output buffer */
    -   
    -    hsize_t     count[2];              /* size of the hyperslab in the file */
    -    hssize_t    offset[2];             /* hyperslab offset in the file */
    -    hsize_t     count_out[3];          /* size of the hyperslab in memory */
    -    hssize_t    offset_out[3];         /* hyperslab offset in memory */
    -    int         i, j, k, status_n, rank;
    -
    -
    -
    -/*********************************************************  
    -   This writes data to the HDF5 file.  
    - *********************************************************/  
    - 
    -    /* 
    -     * Data  and output buffer initialization. 
    -     */
    -    for (j = 0; j < X; j++) {
    -	for (i = 0; i < Y; i++)
    -	    data[j][i] = i + j;
    -    }     
    -    /*
    -     * 0 1 2 3 4 5 
    -     * 1 2 3 4 5 6
    -     * 2 3 4 5 6 7
    -     * 3 4 5 6 7 8
    -     * 4 5 6 7 8 9
    -     */
    -
    -    /*
    -     * Create a new file using H5F_ACC_TRUNC access,
    -     * the default file creation properties, and the default file
    -     * access properties.
    -     */
    -    file = H5Fcreate (FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
    -
    -    /*
    -     * Describe the size of the array and create the data space for fixed
    -     * size dataset. 
    -     */
    -    dimsf[0] = X;
    -    dimsf[1] = Y;
    -    dataspace = H5Screate_simple (RANK, dimsf, NULL); 
    -
    -    /*
    -     * Create a new dataset within the file using defined dataspace and
    -     * default dataset creation properties.
    -     */
    -    dataset = H5Dcreate (file, DATASETNAME, H5T_STD_I32BE, dataspace,
    -                         H5P_DEFAULT);
    -
    -    /*
    -     * Write the data to the dataset using default transfer properties.
    -     */
    -    status = H5Dwrite (dataset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL,
    -                      H5P_DEFAULT, data);
    -
    -    /*
    -     * Close/release resources.
    -     */
    -    H5Sclose (dataspace);
    -    H5Dclose (dataset);
    -    H5Fclose (file);
    - 
    -
    -/*************************************************************  
    -
    -  This reads the hyperslab from the sds.h5 file just 
    -  created, into a 2-dimensional plane of the 3-dimensional 
    -  array.
    -
    - ************************************************************/  
    -
    -    for (j = 0; j < NX; j++) {
    -	for (i = 0; i < NY; i++) {
    -	    for (k = 0; k < NZ ; k++)
    -		data_out[j][i][k] = 0;
    -	}
    -    } 
    - 
    -    /*
    -     * Open the file and the dataset.
    -     */
    -    file = H5Fopen (FILE, H5F_ACC_RDONLY, H5P_DEFAULT);
    -    dataset = H5Dopen (file, DATASETNAME);
    -
    -    dataspace = H5Dget_space (dataset);    /* dataspace handle */
    -    rank      = H5Sget_simple_extent_ndims (dataspace);
    -    status_n  = H5Sget_simple_extent_dims (dataspace, dims_out, NULL);
    -    printf("\nRank: %d\nDimensions: %lu x %lu \n", rank,
    -	   (unsigned long)(dims_out[0]), (unsigned long)(dims_out[1]));
    -
    -    /* 
    -     * Define hyperslab in the dataset. 
    -     */
    -    offset[0] = 1;
    -    offset[1] = 2;
    -    count[0]  = NX_SUB;
    -    count[1]  = NY_SUB;
    -    status = H5Sselect_hyperslab (dataspace, H5S_SELECT_SET, offset, NULL, 
    -                                  count, NULL);
    -
    -    /*
    -     * Define the memory dataspace.
    -     */
    -    dimsm[0] = NX;
    -    dimsm[1] = NY;
    -    dimsm[2] = NZ;
    -    memspace = H5Screate_simple (RANK_OUT, dimsm, NULL);   
    -
    -    /* 
    -     * Define memory hyperslab. 
    -     */
    -    offset_out[0] = 3;
    -    offset_out[1] = 0;
    -    offset_out[2] = 0;
    -    count_out[0]  = NX_SUB;
    -    count_out[1]  = NY_SUB;
    -    count_out[2]  = 1;
    -    status = H5Sselect_hyperslab (memspace, H5S_SELECT_SET, offset_out, NULL, 
    -                                  count_out, NULL);
    -
    -    /*
    -     * Read data from hyperslab in the file into the hyperslab in 
    -     * memory and display.
    -     */
    -    status = H5Dread (dataset, H5T_NATIVE_INT, memspace, dataspace,
    -                      H5P_DEFAULT, data_out);
    -    printf ("Data:\n ");
    -    for (j = 0; j < NX; j++) {
    -	for (i = 0; i < NY; i++) printf("%d ", data_out[j][i][0]);
    -	printf("\n ");
    -    }
    -	printf("\n");
    -    /*
    -     * 0 0 0 0 0 0 0
    -     * 0 0 0 0 0 0 0
    -     * 0 0 0 0 0 0 0
    -     * 3 4 5 6 0 0 0  
    -     * 4 5 6 7 0 0 0
    -     * 5 6 7 8 0 0 0
    -     * 0 0 0 0 0 0 0
    -     */
    -
    -    /*
    -     * Close and release resources.
    -     */
    -    H5Dclose (dataset);
    -    H5Sclose (dataspace);
    -    H5Sclose (memspace);
    -    H5Fclose (file);
    +To obtain the example, download:
    +
    +NOTE: To download a tar file of the examples, including a Makefile,
    +please go to the References page.
    +

    -} -

    Remarks

      -
    • H5Sselect_hyperslab selects a hyperslab region to add to the current -selected region for a specified dataspace. -
      -  herr_t H5Sselect_hyperslab (hid_t space_id, H5S_seloper_t op, 
      -         const hssize_t *start, const hsize_t *stride, 
      -         const hsize_t *count, const hsize_t *block ) 
      -
      +
    • H5Sselect_hyperslab / h5sselect_hyperslab_f +selects a hyperslab region to +add to the current selected region for a specified dataspace. +

      +C: +

      +    herr_t H5Sselect_hyperslab (hid_t space_id, H5S_seloper_t operator,
      +        const hssize_t *start, const hsize_t *stride,
      +        const hsize_t *count, const hsize_t *block ) 
      +
      +

      +FORTRAN: +

      +    h5sselect_hyperslab_f (space_id, operator, start, count, &
      +                           hdferr, stride, block)
      +
      +            space_id    IN: INTEGER(HID_T) 
      +            operator    IN: INTEGER 
      +            start       IN: INTEGER(HSSIZE_T), DIMENSION(*)
      +            count       IN: INTEGER(HSIZE_T), DIMENSION(*)
      +            hdferr     OUT: INTEGER
      +            stride      IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL
      +            block       IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL 
      +
      +

        -
      • The first parameter, space_id, is the dataspace identifier for the +
      • The parameter space_id is the dataspace identifier for the specified dataspace. -
      • The second parameter, op, can only be set to H5S_SELECT_SET - in the current release. It replaces the existing selection with the - parameters from this call. Overlapping blocks are not supported. -
      • The start array determines the starting coordinates of the hyperslab to select. +

        +

      • The parameter operator can be set to one of the following: +
        +
        H5S_SELECT_SET (H5S_SELECT_SET_F in FORTRAN) +
        Replace the existing selection with the parameters from this call. + Overlapping blocks are not supported with this operator. + +
        H5S_SELECT_OR (H5S_SELECT_OR_F in FORTRAN) +
        Add the new selection to the existing selection. +
        + +

        +

      • The start array determines the starting coordinates of the +hyperslab to select. +

      • The stride array indicates which elements along a dimension are to be selected. +

      • The count array determines how many positions to select from the dataspace in each dimension. +

      • The block array determines the size of the element block selected by the dataspace. +

        +

      • In C, a non-negative value is returned if successful, and a negative +value otherwise. In FORTRAN, the return value is returned in hdferr: +0 if successful and -1 otherwise.

      The start, stride, count, and block arrays must be the same size as the rank of the dataspace.

      -

    • This example introduces the following H5Dget_* functions: -
        - H5Dget_space: returns an identifier for a copy of the dataspace - of a dataset.
        - H5Dget_type: returns an identifier for a copy of the data type - of a dataset.
        -
      +
    • The examples introduce the following call: +
      +
      H5Dget_space / h5dget_space_f: +
      Returns an identifier for a copy of the dataspace of a dataset.

      +

      +
    • The C example also introduces the following calls: +
      +
      H5Sget_simple_extent_dims: +
      Returns the size and maximum size of each dimension of a dataspace. +
      H5Sget_simple_extent_ndims: +
      Determines the dimensionality (or rank) of a dataspace. +

      -

    • This example introduces the following H5Sget_* functions used to -obtain information about selections: -
        - H5Sget_simple_extent_dims: returns the size and maximum sizes - of each dimension of a dataspace.
        - H5Sget_simple_extent_ndims: determines the dimensionality - (or rank) of a dataspace.
        +The FORTRAN example does not use these calls, though they +are available as h5sget_simple_extent_dims_f and +h5sget_simple_extent_ndims_f. +
    @@ -439,8 +297,11 @@ obtain information about selections:
    hdfhelp@ncsa.uiuc.edu -
    Last Modified: August 27, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: April 5, 2000

    +
    diff --git a/doc/html/Tutor/selectc.html b/doc/html/Tutor/selectc.html index e01d9db..4edef82 100644 --- a/doc/html/Tutor/selectc.html +++ b/doc/html/Tutor/selectc.html @@ -1,5 +1,5 @@ -HDF5 Tutorial - Selections using H5Sselect_elements and H5Scopy +<TITLE>HDF5 Tutorial - Selecting Individual Points and Copying a Dataspace @@ -13,7 +13,8 @@ width=78 height=27 alt="NCSA">

    [ HDF5 Tutorial Top ]

    -Selections using H5Sselect_elements and H5SCopy +Selecting Individual Points and Copying +a Dataspace


    @@ -21,7 +22,7 @@ width=78 height=27 alt="NCSA">

    Contents:

    @@ -231,42 +160,83 @@ by the number of elements to be selected, num_elem.

    File Contents

    Following is the DDL for copy1.h5 and copy2.h5, as viewed with -the commands "h5dump copy1.h5" and "h5dump copy2.h5". +the following commands:
    +             +h5dump copy1.h5
    +             +h5dump copy2.h5 +

    -Fig. S.1   'copy1.h5' in DDL +


    +C:

    +Fig. S.1a   copy1.h5 in DDL

    -HDF5 "copy1.h5" {
    -GROUP "/" {
    -   DATASET "Copy1" {
    -      DATATYPE { H5T_STD_I32BE }
    -      DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) }
    -      DATA {
    -         0, 59, 0, 53,
    -         0, 0, 0, 0,
    -         0, 0, 0, 0
    +   HDF5 "copy1.h5" {
    +   GROUP "/" {
    +      DATASET "Copy1" {
    +         DATATYPE { H5T_STD_I32BE }
    +         DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) }
    +         DATA {
    +            0, 59, 0, 53,
    +            0, 0, 0, 0,
    +            0, 0, 0, 0
    +         }
           }
        }
    -}
    -}
    +   }
     
    -Fig. S.2   'copy2.h5' in DDL +Fig. S.1b   copy2.h5 in DDL
    -HDF5 "copy2.h5" {
    -GROUP "/" {
    -   DATASET "Copy2" {
    -      DATATYPE { H5T_STD_I32BE }
    -      DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) }
    -      DATA {
    -         1, 59, 1, 53,
    -         1, 1, 1, 1,
    -         1, 1, 1, 1
    +   HDF5 "copy2.h5" {
    +   GROUP "/" {
    +      DATASET "Copy2" {
    +         DATATYPE { H5T_STD_I32BE }
    +         DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) }
    +         DATA {
    +            1, 59, 1, 53,
    +            1, 1, 1, 1,
    +            1, 1, 1, 1
    +         }
           }
        }
    -}
    -}
    -
    +   }
    +
    +
    +FORTRAN:

    +Fig. S.2a   copy1.h5 in DDL +

    +   HDF5 "copy1.h5" {
    +   GROUP "/" {
    +      DATASET "Copy1" {
    +         DATATYPE { H5T_STD_I32BE }
    +         DATASPACE { SIMPLE ( 4, 3 ) / ( 4, 3 ) }
    +         DATA {
    +            0, 0, 0,
    +            53, 0, 0,
    +            0, 0, 0,
    +            59, 0, 0
    +         }
    +      }
    +   }
    +   }
    +
    +Fig. S.2b   copy2.h5 in DDL +
    +   HDF5 "copy2.h5" {
    +   GROUP "/" {
    +      DATASET "Copy2" {
    +         DATATYPE { H5T_STD_I32BE }
    +         DATASPACE { SIMPLE ( 4, 3 ) / ( 4, 3 ) }
    +         DATA {
    +            1, 1, 1,
    +            53, 1, 1,
    +            1, 1, 1,
    +            59, 1, 1
    +         }
    +      }
    +   }
    +   }
     
    - @@ -283,8 +253,11 @@ GROUP "/" {
    hdfhelp@ncsa.uiuc.edu -
    Last Modified: August 27, 1999

    +
    +Describes HDF5 Release 1.2.2, June 2000 +
    Last Modified: April 5, 2000

    +
    diff --git a/doc/html/Tutor/software.html b/doc/html/Tutor/software.html new file mode 100644 index 0000000..03c0929 --- /dev/null +++ b/doc/html/Tutor/software.html @@ -0,0 +1,87 @@ + +HDF5 Tutorial - Obtaining HDF5 Software + + + + + + +NCSA

    + + [ HDF5 Tutorial Top ] +

    +Obtaining HDF5 Software +

    + +
    + + +If you will be compiling in: +
    +
    C: +
    You will need the HDF5 library. We provide pre-compiled binaries +for the platforms on which we tested at: +
            +ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/bin/ +

    +If using the pre-compiled binaries you must +also obtain the GZIP library, as they were compiled with GZIP included, but do +not include this library. We provide the GZIP library for the platforms on +which we tested at: +
            +ftp://ftp.ncsa.uiuc.edu/HDF/gzip/ +

    +You can build the HDF5 library yourself, if need be. The source code +can be obtained from: +
            +ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current/src/ +

    +For further information regarding HDF5, check the HDF5 home page: +
            +http://hdf.ncsa.uiuc.edu/HDF5/ +

    +

    FORTRAN90: +
    With HDF5-1.4-beta2, support for Fortran 90 is included as part of +the installation of the HDF5 library. Download the HDF5-1.4-beta2 source +code and compile it with the --enable-fortran flag. Read the instructions +in the +RELEASE +file for further details. + +

    +

    Java: +
    You will need the JHI5 code. Go to the +Java HDF5 web page +for information on the Java-HDF5 software. The Java Tutorial examples +are included with this tutorial: +
            + ./examples/java/ +
    + + + + +


    + + NCSA
    + The National Center for Supercomputing Applications

    + University of Illinois + at Urbana-Champaign
    +
    + + +hdfhelp@@ncsa.uiuc.edu +
    Last Modified: January 10, 2001

    + + +
    +
    + + + + + diff --git a/doc/html/Tutor/title.html b/doc/html/Tutor/title.html index 35283b7..4076196 100644 --- a/doc/html/Tutor/title.html +++ b/doc/html/Tutor/title.html @@ -19,8 +19,6 @@ width=78 height=27 alt="NCSA">


    - - +

    + +          +NOTE:   +This tutorial does NOT include the software needed to +
                  +              +compile the examples. You will need to +obtain it first. +

    Contents:

    Introductory Topics

      @@ -42,11 +50,11 @@ width=78 height=27 alt="NCSA">

    1. The HDF5 API
    2. Creating an HDF5 File
    3. Creating a Dataset -
    4. Reading from/Writing to a Dataset +
    5. Reading from or Writing to a Dataset
    6. Creating an Attribute
    7. Creating a Group -
    8. Creating Groups using Absolute/Relative -Names +
    9. Creating Groups Using Absolute and + Relative Names
    10. Creating Datasets in Groups
      @@ -55,9 +63,9 @@ Names

    Advanced Topics