philipp/hdf5
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[svn-r3659]

Browse Source 
Added html files with references to the fortran 90 files.
(under examples/)
This commit is contained in:
Barbara Jones
2001-03-19 09:26:47 -05:00
parent 380eb42bc5
commit f11cef2c56
30 changed files with 2967 additions and 3139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

262
doc/html/Tutor/crtfile.html
View File

@@ -13,7 +13,7 @@ width=78 height=27 alt="NCSA"><P></A>
[ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ]
<H1>
<BIG><BIG><BIG><FONT COLOR="#c101cd">Creating an HDF5 file</FONT>
<BIG><BIG><BIG><FONT COLOR="#c101cd">Creating an HDF5 File</FONT>
</BIG></BIG></BIG></H1>
<hr noshade size=1>
@@ -34,134 +34,228 @@ width=78 height=27 alt="NCSA"><P></A>
<A NAME="def">
<H2>What is an HDF5 file?</h2>
<P>
An HDF5 file is a binary file which contains scientific data and supporting
metadata. The two primary objects stored in an HDF5 file are groups and
datasets. Groups and datasets will be discussed in the other sessions.
An HDF5 file is a binary file containing scientific data and supporting
metadata. The primary types of objects stored in an HDF5 file, groups and
datasets, will be discussed in other sections of this tutorial.
<P>
To create a file, the program application must specify a file name, file
To create a file, an application must specify a filename, file
access mode, file creation property list, and file access property list.
<P>
<UL>
<LI><B> File Creation Property List:</B><BR>
<LI><B> File access mode:</B><BR>
When creating a file, the file access mode specifies the action to
take if the file already exists:
<UL>
<LI><code>H5F_ACC_TRUNC</code> specifies that if the file already exists,
the current contents will be deleted so that the application can rewrite
the file with new data.
<LI><code>H5F_ACC_EXCL</code> specifies that the open is to fail if
the file already exists.
<LI>If the file does not already exist, the file access parameter is
ignored.
<LI>In all cases, the application has both read and write access to
a successfully created file.
</UL>
<P>
Note that there are two different access modes for opening exisitng files:
<UL>
<LI><code>H5F_ACC_RDONLY</code> specifies that the application has
read access but will not be allowed to write any data.
<LI><code>H5F_ACC_RDWR</code> specifies that the application has
read and write access.
</UL>
<P>
For further information, see
<a href="../Files.html">The File Interface (H5F)</a> section of the
<cite>HDF5 User's Guide</cite> and
the <a href="../RM_H5F.html#File-Create">H5F: File Interface</a>
section of the <cite>HDF5 Reference Manual</cite>.
<P>
<LI><B> File creation property list:</B><BR>
The file creation property list is used to control the file metadata.
File metadata contains information about the size of the user-block, the
size of various file data structures used by the HDF5 library, etc.
In this tutorial, the default file creation property list,
<code>H5P_DEFAULT</code>, is used.
<P>
The user-block is a fixed length block of data located at the beginning
of the file which is ignored by the HDF5 library and may be used to store
any data information found to be useful to applications.
The user-block is a fixed-length block of data located at the beginning
of the file which is ignored by the HDF5 library.
The user-block may be used to store
any data or information found to be useful to applications.
<P>
For more details, see the HDF5 documentation. In this tutorial,
the default file metadata is used.
For further information, see
<a href="../Files.html">The File Interface (H5F)</a> section of the
<cite>HDF5 User's Guide</cite>.
<P>
<LI><B> File Access Property List:</B><BR>
<LI><B> File access property list:</B><BR>
The file access property list is used to control different methods of
performing I/O on files. See the HDF5 User's Guide for details. The default
file access property is used in this tutorial.
performing I/O on files.
The default file access property list, <code>H5P_DEFAULT</code>,
is used in this tutorial.
<P>
For further information, see
<a href="../Files.html">The File Interface (H5F)</a> section of the
<cite>HDF5 User's Guide</cite>.
</UL>
<P>
The steps to create and close an HDF5 file are as follows:
<OL>
<LI> Specify the file creation and access property lists if necessary.
<LI> Create a file.
<LI> Close the file and close the property lists if necessary.
<LI> Specify the file creation and access property lists, if necessary.
<LI> Create the file.
<LI> Close the file and close the property lists, if necessary.
</OL>
To create an HDF5 file, the calling program must contain the following calls:
<PRE>
file_id = H5Fcreate(filename, access_mode, create_id, access_id);
H5Fclose(file_id);
To create an HDF5 file, the calling program must contain calls to
create and close the file. For example:
<P>
<I>C</I>:<PRE>
file_id = H5Fcreate (filename, access_mode, create_id, access_id);
status = H5Fclose (file_id);
</PRE>
<I>FORTRAN</I>:<PRE>
CALL h5fcreate_f (filename, access_mode, file_id, hdferr, &
creation_prp=create_id, access_prp=access_id)
<i>or</i>
CALL h5fcreate_f (filename, access_mode, file_id, hdferr)
CALL h5fclose_f (file_id, hdferr)
</PRE>
In FORTRAN, the file creation property list, <code>creation_prp</code>,
and file access property list, <code>access_prp</code>,
are optional parameters;
they can be omitted if the default values are to be used.
<P>
<H2>Programming Example</H2>
<A NAME="desc">
<H3><U>Description</U></H3>
The following example demonstrates how to create and close an HDF5 file.
It creates a file called 'file.h5', and then closes the file.<BR>
[ <A HREF="examples/h5_crtfile.c">Download h5_crtfile.c</A> ]
<PRE>
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
It creates a file called <code>file.h5</code> in the C version,
<code>filef.h5</code> in FORTRAN, and then closes the file.<P>
<UL>
[ <A HREF="examples/h5_crtfile.c" target="ExternalWin">C Example</A> ]
-- <code>h5_crtfile.c</code> <BR>
[ <A HREF="examples/fileexample.f90" target="ExternalWin">FORTRAN Example</A> ]
-- <code>fileexample.f90</code><BR>
[ <A HREF="examples/java/CreateFile.java" target="ExternalWin">Java Example</A> ] -- <code>CreateFile.java</code>
</UL>
<P>
<B>NOTE:</B> To download a tar file of all of the examples, including
a Makefile, please go to the <A HREF="references.html">References</A> page.
#include &lt;hdf5.h&gt;
#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);
/* Terminate access to the file. */
status = H5Fclose(file_id);
}
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
</PRE>
<A NAME="rem">
<H3><U>Remarks</U></H3>
<UL>
<LI>The include file 'hdf5.h' contains definitions and declarations, and it must
be included in any file that uses the HDF5 library.
<LI><B>In C:</B>
The include file <code>hdf5.h</code> contains definitions and declarations
and must be included in any program that uses the HDF5 library.
<BR><B>In FORTRAN:</B>
The module <code>HDF5</code> contains definitions and declarations
and must be used in any program that uses the HDF5 library.
<P>
<LI>H5Fcreate creates an HDF5 file and returns the file identifier.
<LI><code>H5Fcreate</code>/<code>h5fcreate_f</code> creates
an HDF5 file and returns the file identifier.
<PRE>
hid_t H5Fcreate (const char *name, unsigned flags, hid_t create_id,
hid_t access_id)
<I>C</I>:
hid_t H5Fcreate (const char *name, unsigned access_mode, hid_t creation_prp,
hid_t access_prp)
<I>FORTRAN</I>:
h5fcreate_f (name, access_mode, file_id, hdferr, creation_prp, access_prp)
name CHARACTER(LEN=*)
access_flag INTEGER
(Valid values: H5F_ACC_RDWR_F, H5F_ACC_RDONLY_F,
H5F_ACC_TRUNC_F, H5F_ACC_EXCL_F, H5F_ACC_DEBUG_F)
file_id INTEGER(HID_T)
hdferr INTEGER
(Valid values: 0 on success and -1 on failure)
creation_prp INTEGER(HID_T), OPTIONAL
(Default value: H5P_DEFAULT_F)
access_prp INTEGER(HID_T), OPTIONAL
(Default value: H5P_DEFAULT_F)
</PRE>
<UL>
<LI> The first parameter specifies the name of the file to be created.
<LI> The <I>name</I> parameter specifies the name of the file to be created.
<P>
<LI> The second parameter specifies the file access mode. H5F_ACC_TRUNC will
truncate a file if it already exists.
<LI> The <I>access_mode</I> parameter specifies the file access mode.
<code>H5F_ACC_TRUNC</code> (<code>H5F_ACC_TRUNC_F</code> in FORTRAN)
will truncate a file if it already exists.
<P>
<LI> The third parameter specifies the file creation property list.
H5P_DEFAULT indicates that the default file creation property list is
used.
<LI> The <I>creation_prp</I> parameter
specifies the file creation property list.
For C, using <code>H5P_DEFAULT</code> indicates that the
default file creation property list is to be used.
This option is optional in FORTRAN; if it is omitted, the default file
creation property list, <code>H5P_DEFAULT_F</code>, is used.
<P>
<LI> The last parameter of H5Fcreate specifies the file access property list.
H5P_DEFAULT indicates that the default file access property list is used.
<LI> The <I>access_prp</I> parameter
specifies the file access property list.
For C, using <code>H5P_DEFAULT</code> indicates that the
default file creation property list is to be used.
This option is optional in FORTRAN; if it is omitted, the default file
creation property list, <code>H5P_DEFAULT_F</code>, is used.
<P>
<LI> In C, this function returns the file identifier if successful and
a negative value otherwise.
In FORTRAN, the file identifier is returned in the
<I>file_id</I> parameter. If the call is successful, 0 (zero) is
passed back in the <I>hdferr</I> parameter. Otherwise, <I>hdferr</I>
will have a value of -1.
</UL>
<P>
<LI> When a file is no longer accessed by a program, H5Fclose must be called to
release the resource used by the file. This call is mandatory.
<LI> When a file is no longer accessed by a program,
<code>H5Fclose</code>/<code>h5fclose_f</code>
must be called to release the resources used by the file. This call
is mandatory.
<PRE>
<I>C</I>:
herr_t H5Fclose (hid_t file_id)
<I>FORTRAN</I>:
h5fclose_f(file_id, hdferr)
</PRE>
<P>
<LI>The root group is automatically created when a file is created.
Every file has a root group and the path name of the root group is '/'.
Every file has a root group and the path name of the root group is
always <code>/</code>.
</UL>
<A NAME="fc">
<H3><U>File Contents</U></H3>
HDF has developed tools to examine the contents of HDF5 files. The tool used
in this tutorial is the HDF5 dumper, h5dump. h5dump is a tool that displays
the file contents in human readable form to an ASCII file in DDL. DDL (Data
Description Language) is a language that describes HDF5 objects in Backus-Naur
Form. To view the file contents, type:
The HDF team has developed tools for examining the contents of HDF5 files.
The tool used in this tutorial is the HDF5 dumper, <code>h5dump</code>,
which displays the file contents in human-readable form.
The output of <code>h5dump</code> is an ASCII display formatted according
to the HDF5 DDL grammar.
This grammar is defined, using Backus-Naur Form, in the
<a href="../ddl.html">DDL in BNF for HDF5</a>.
<p>
To view the file contents, type:
<PRE>
<B>h5dump &lt;filename&gt</B>
</PRE>
Figure 4.1 describes the file contents of 'file.h5' using a directed graph.
Each HDF5 object is represented by a rectangle and the arrows indicate
the structure of the contents. In Fig. 4.2, 'file.h5' contains
a group object named '/' (the root group).
Figure 4.1 describes the file contents of <code>file.h5</code> (<code>filef.h5</code>)
using a directed graph.
The directed graphs in this tutorial use an oval to represent an HDF5 group
and a rectangle to represent an HDF5 dataset (none in this example).
Arrows indicate the inclusion direction of the contents (none in this example).
<P>
<B>Fig. 4.1</B> &nbsp; <I>Contents of 'file.h5'</I>
<B>Fig. 4.1</B> &nbsp; <I>Contents of <code>file.h5</code> (<code>filef.h5</code>)</I>
<PRE>
<!--
<IMG src="fileh5.jpg" width="205" height="208"></PRE> -->
<IMG src="img001.gif"></PRE>
Figure 4.2 is the text-description of 'file.h5' generated by h5dump. The HDF5
file called 'file.h5' contains a group called '/'.
Figure 4.2 is the text description of <code>file.h5</code>, as generated by
<code>h5dump</code>. The HDF5 file called <code>file.h5</code> contains
a group called <code>/</code>, or the <I>root group</I>.
(The file called <code>filef.h5</code>,
created by the FORTRAN version of the example, has the same output except
that the filename shown is <code>filef.h5</code>.)
<P>
<B> Fig. 4.2</B> &nbsp; <I>'file.h5' in DDL</I>
<B> Fig. 4.2</B> &nbsp; <I><code>file.h5</code> in DDL</I>
<PRE>
HDF5 "file.h5" {
@@ -171,15 +265,18 @@ file called 'file.h5' contains a group called '/'.
</PRE>
<A NAME="ddl">
<h3><U>File Definition in DDL</U></H3>
Figure 4.3 is the simplified DDL file definition for creating an HDF5 file.
For simplicity, a simplified DDL is used in this tutorial. A complete and
more rigorous DDL can be found in the HDF5 User's Guide. See the
<A HREF="references.html">References</A> section of this tutorial.
more rigorous DDL can be found in the
<a href="../ddl.html">DDL in BNF for HDF5</a>, a section of the
<cite>HDF5 User's Guide</cite>.
<P>
<B> Fig. 4.3</B> &nbsp; <I>HDF5 File Definition</I>
<P>
The explanation of the symbols used in the DDL:
The following symbol definitions are used in the DDL:
<PRE>
::= defined as
@@ -187,7 +284,7 @@ more rigorous DDL can be found in the HDF5 User's Guide. See the
&lt;a&gt | &lt;b&gt one of &lt;a&gt or &lt;b&gt
&lt;a&gt;* zero or more occurrences of &lt;a&gt
</PRE>
The simplified DDL file definition:
The simplified DDL for file definition is as follows:
<PRE>
&lt;file&gt ::= HDF5 "&lt;file_name&gt;" { &lt;root_group&gt }
@@ -211,14 +308,13 @@ more rigorous DDL can be found in the HDF5 User's Guide. See the
<!-- <A HREF="helpdesk.mail.html"> -->
<A HREF="mailto:hdfhelp@ncsa.uiuc.edu">
hdfhelp@ncsa.uiuc.edu</A>
<BR> <H6>Last Modified: August 27, 1999</H6><BR>
<br>
<BR> <H6>Last Modified: March 9, 2001</H6><BR>
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu -->
</FONT>
<BR>
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
</BODY>
</HTML>