mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-21 01:04:10 +08:00
345e07fc11
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.]
322 lines
12 KiB
HTML
322 lines
12 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - Creating an HDF5 File
|
|
</TITLE>
|
|
</HEAD>
|
|
|
|
<body bgcolor="#ffffff">
|
|
|
|
<!-- BEGIN MAIN BODY -->
|
|
|
|
<A HREF="http://www.ncsa.uiuc.edu/"><img border=0
|
|
src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif"
|
|
width=78 height=27 alt="NCSA"><P></A>
|
|
|
|
[ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ]
|
|
<H1>
|
|
<BIG><BIG><BIG><FONT COLOR="#c101cd">Creating an HDF5 File</FONT>
|
|
</BIG></BIG></BIG></H1>
|
|
|
|
<hr noshade size=1>
|
|
|
|
<BODY>
|
|
<H2>Contents:</H2>
|
|
<UL>
|
|
<LI> <A HREF="#def">What is an HDF5 file</A>?
|
|
<LI>Programming Example
|
|
<UL>
|
|
<LI> <A HREF="#desc">Description</A>
|
|
<LI> <A HREF="#rem">Remarks</A>
|
|
<LI> <A HREF="#fc">File Contents</A>
|
|
<LI> <A HREF="#ddl">File Definition in DDL</A>
|
|
</UL>
|
|
</UL>
|
|
<HR>
|
|
<A NAME="def">
|
|
<H2>What is an HDF5 file?</h2>
|
|
<P>
|
|
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, an application must specify a filename, file
|
|
access mode, file creation property list, and file access property list.
|
|
<P>
|
|
<UL>
|
|
<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.
|
|
The user-block may be used to store
|
|
any data or information found to be useful to applications.
|
|
<P>
|
|
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>
|
|
The file access property list is used to control different methods of
|
|
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 the file.
|
|
<LI> Close the file and close the property lists, if necessary.
|
|
</OL>
|
|
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 <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.
|
|
|
|
<A NAME="rem">
|
|
<H3><U>Remarks</U></H3>
|
|
<UL>
|
|
<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><code>H5Fcreate</code>/<code>h5fcreate_f</code> creates
|
|
an HDF5 file and returns the file identifier.
|
|
<PRE>
|
|
<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 <I>name</I> parameter specifies the name of the file to be created.
|
|
<P>
|
|
<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 <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 <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,
|
|
<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
|
|
always <code>/</code>.
|
|
</UL>
|
|
<A NAME="fc">
|
|
<H3><U>File Contents</U></H3>
|
|
The HDF team has developed tools for examining the contents of HDF5 files.
|
|
The tool used in this tutorial is the HDF5 dumper, <code>h5dump</code>,
|
|
which displays the file contents in human-readable form.
|
|
The output of <code>h5dump</code> is an ASCII display formatted according
|
|
to the HDF5 DDL grammar.
|
|
This grammar is defined, using Backus-Naur Form, in the
|
|
<a href="../ddl.html">DDL in BNF for HDF5</a>.
|
|
<p>
|
|
To view the file contents, type:
|
|
<PRE>
|
|
<B>h5dump <filename></B>
|
|
</PRE>
|
|
|
|
Figure 4.1 describes the file contents of <code>file.h5</code> (<code>filef.h5</code>)
|
|
using a directed graph.
|
|
The directed graphs in this tutorial use an oval to represent an HDF5 group
|
|
and a rectangle to represent an HDF5 dataset (none in this example).
|
|
Arrows indicate the inclusion direction of the contents (none in this example).
|
|
|
|
<P>
|
|
<B>Fig. 4.1</B> <I>Contents of <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 <code>file.h5</code>, as generated by
|
|
<code>h5dump</code>. The HDF5 file called <code>file.h5</code> contains
|
|
a group called <code>/</code>, or the <I>root group</I>.
|
|
(The file called <code>filef.h5</code>,
|
|
created by the FORTRAN version of the example, has the same output except
|
|
that the filename shown is <code>filef.h5</code>.)
|
|
<P>
|
|
<B> Fig. 4.2</B> <I><code>file.h5</code> in DDL</I>
|
|
<PRE>
|
|
|
|
HDF5 "file.h5" {
|
|
GROUP "/" {
|
|
}
|
|
}
|
|
|
|
</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
|
|
<a href="../ddl.html">DDL in BNF for HDF5</a>, a section of the
|
|
<cite>HDF5 User's Guide</cite>.
|
|
<P>
|
|
<B> Fig. 4.3</B> <I>HDF5 File Definition</I>
|
|
<P>
|
|
The following symbol definitions are used in the DDL:
|
|
<PRE>
|
|
|
|
::= defined as
|
|
<tname> a token with the name <I>tname</I>
|
|
<a> | <b> one of <a> or <b>
|
|
<a>* zero or more occurrences of <a>
|
|
</PRE>
|
|
The simplified DDL for file definition is as follows:
|
|
<PRE>
|
|
<file> ::= HDF5 "<file_name>" { <root_group> }
|
|
|
|
<root_group> ::= GROUP "/" { <group_attribute>* <group_member>* }
|
|
|
|
<group_attribute> ::= <attribute>
|
|
|
|
<group_member> ::= <group> | <dataset>
|
|
</PRE>
|
|
<!-- BEGIN FOOTER INFO -->
|
|
|
|
<P><hr noshade size=1>
|
|
<font face="arial,helvetica" size="-1">
|
|
<a href="http://www.ncsa.uiuc.edu/"><img border=0
|
|
src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif"
|
|
width=78 height=27 alt="NCSA"><br>
|
|
The National Center for Supercomputing Applications</A><br>
|
|
<a href="http://www.uiuc.edu/">University of Illinois
|
|
at Urbana-Champaign</a><br>
|
|
<br>
|
|
<!-- <A HREF="helpdesk.mail.html"> -->
|
|
<A HREF="mailto:hdfhelp@ncsa.uiuc.edu">
|
|
hdfhelp@ncsa.uiuc.edu</A>
|
|
<br>
|
|
Describes HDF5 Release 1.2.2, June 2000
|
|
<BR> <H6>Last Modified: April 5, 2000</H6><BR>
|
|
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
|
|
<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu -->
|
|
</FONT>
|
|
|
|
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
|
|
|
|
</BODY>
|
|
</HTML>
|