diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 2005-07-19 17:28:56 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 2005-07-19 17:28:56 (GMT) |
| commit | 794ba0a251af47b8e3c60afa2fe92d267e2a6b55 (patch) | |
| tree | f24cea3b81ff02fa3f31c0a1c4e80fa10f4393c0 /doc/html/Tutor/crtfile.html | |
| parent | d2e92fd23610c3ccdddbbc55484e54a5a21a9252 (diff) | |
| download | hdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.zip hdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.tar.gz hdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.tar.bz2 | |
[svn-r11084]
Description:
All HDF5 user documentation has been moved to a separate hdf5doc/
repository, managed under Subversion.
With this 'cvs commit', all files are stripped from hdf5/doc/.
THIS CHANGE IS APPLIED ONLY TO THE HDF5 DEVELOPMENT BRANCH,
post Release 1.6.x; it is not applied to the release branches.
Diffstat (limited to 'doc/html/Tutor/crtfile.html')
| -rw-r--r-- | doc/html/Tutor/crtfile.html | 317 |
1 files changed, 0 insertions, 317 deletions
diff --git a/doc/html/Tutor/crtfile.html b/doc/html/Tutor/crtfile.html deleted file mode 100644 index fc235c4..0000000 --- a/doc/html/Tutor/crtfile.html +++ /dev/null @@ -1,317 +0,0 @@ -<HTML><HEAD> -<TITLE>HDF5 Tutorial - Creating an HDF5 File -</TITLE> -</HEAD> - -<body bgcolor="#ffffff"> - -<!-- BEGIN MAIN BODY --> - - - [ <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="footer-ncsalogo.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> -<BR> <H6>Last Modified: June 22, 2001</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> |