diff options
Diffstat (limited to 'doc/html/Tutor/crtfile.html')
| -rw-r--r-- | doc/html/Tutor/crtfile.html | 259 |
1 files changed, 177 insertions, 82 deletions
diff --git a/doc/html/Tutor/crtfile.html b/doc/html/Tutor/crtfile.html index 8786aab..b0bf50d 100644 --- a/doc/html/Tutor/crtfile.html +++ b/doc/html/Tutor/crtfile.html @@ -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); +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) - H5Fclose(file_id); + 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> -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - - -#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 <code>file.h5</code> in the C version, +<code>filef.h5</code> in FORTRAN, and then closes the file.<P> - /* Terminate access to the file. */ - status = H5Fclose(file_id); -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +<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. -</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 <filename></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> <I>Contents of 'file.h5'</I> +<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 '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> <I>'file.h5' in DDL</I> +<B> Fig. 4.2</B> <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> <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 <a> | <b> one of <a> or <b> <a>* zero or more occurrences of <a> </PRE> - The simplified DDL file definition: + The simplified DDL for file definition is as follows: <PRE> <file> ::= HDF5 "<file_name>" { <root_group> } @@ -211,14 +308,12 @@ 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> <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> -<BR> + <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> </BODY> </HTML> - - - |