256 lines
8.7 KiB
HTML
256 lines
8.7 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - Mounting Files
|
|
</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">Mounting Files</FONT>
|
|
</BIG></BIG></BIG></H1>
|
|
|
|
<hr noshade size=1>
|
|
|
|
<BODY>
|
|
<H2>Contents:</H2>
|
|
<UL>
|
|
<LI> <A HREF="#def">Mounting Files</A>
|
|
<LI> Programming Example
|
|
<UL>
|
|
<LI> <A HREF="#desc">Description</A>
|
|
<LI> <A HREF="#rem">Remarks</A>
|
|
<!--
|
|
<LI> <A HREF="#fc">File Contents</A>
|
|
-->
|
|
</UL>
|
|
</UL>
|
|
<HR>
|
|
<A NAME="def">
|
|
<H2>Mounting Files</H2>
|
|
|
|
HDF5 allows you to combine two or more HDF5 files in memory
|
|
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. The following steps are involved:
|
|
<OL>
|
|
<LI>Open the files.
|
|
|
|
<LI>Choose the <strong>mount point</strong> in the first file
|
|
(the parent file). The mount point in
|
|
HDF5 is a group, which CANNOT be the root group.
|
|
|
|
<LI>Use the HDF5 routine <CODE>H5Fmount</CODE> / <CODE>h5fmount_f</CODE>
|
|
to mount the second file (the child file) in the first file.
|
|
|
|
<LI>Work with the objects in the second file as if they were members of
|
|
the mount point group in the first file. The previous contents of
|
|
the mount point group are temporarily hidden.
|
|
|
|
<LI>Unmount the second file using <CODE>H5Funmount</CODE> /
|
|
<CODE>h5funmount_f</CODE> when the work is done.
|
|
</OL>
|
|
|
|
<H2> Programming Example</H2>
|
|
<A NAME="desc">
|
|
<H3><U>Description</U></H3>
|
|
|
|
In the following example, we create one file containing a group and
|
|
another file containing a dataset.
|
|
Mounting is used to access the dataset from the second
|
|
file as a member of a group in the first file.
|
|
The following figures illustrate this concept.
|
|
<PRE>
|
|
|
|
FILE1 FILE2
|
|
|
|
-------------------- --------------------
|
|
! ! ! !
|
|
! / ! ! / !
|
|
! | ! ! | !
|
|
! | ! ! | !
|
|
! V ! ! V !
|
|
! -------- ! ! ---------- !
|
|
! ! Group ! ! ! ! Dataset! !
|
|
! --------- ! ! ---------- !
|
|
!------------------! !------------------!
|
|
</PRE>
|
|
After mounting <code>FILE2</code> under the group in <code>FILE1</code>,
|
|
the parent file has the following structure:
|
|
<PRE>
|
|
|
|
FILE1
|
|
|
|
--------------------
|
|
! !
|
|
! / !
|
|
! | !
|
|
! | !
|
|
! V !
|
|
! -------- !
|
|
! ! Group ! !
|
|
! --------- !
|
|
! | !
|
|
! | !
|
|
! V !
|
|
! ----------- !
|
|
! ! Dataset ! !
|
|
! !---------- !
|
|
! !
|
|
!------------------!
|
|
|
|
</PRE>
|
|
[ <A HREF="examples/h5_mount.c">C program</A> ]
|
|
- <code>h5_mount.c</code><BR>
|
|
[ <A HREF="examples/mountexample.f90">FORTRAN program</A> ]
|
|
- <code>mountexample.f90</code>
|
|
<P>
|
|
|
|
<B>NOTE:</B> To download a tar file 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> The first part of the program creates a group in one file and creates
|
|
and writes a dataset to another file.
|
|
<P>
|
|
<LI> Both files are reopened and the second file is mounted in the first
|
|
using <CODE>H5Fmount</CODE> / <CODE>h5fmount_f</CODE>.
|
|
If no objects will be modified, the
|
|
files can be opened with <CODE>H5F_ACC_RDONLY</CODE>
|
|
(<CODE>H5F_ACC_RDONLY_F</CODE> in FORTRAN).
|
|
If the data is to be modified, the files should be opened with
|
|
<CODE>H5F_ACC_RDWR</CODE> (<CODE>H5F_ACC_RDWR_F</CODE> in FORTRAN).
|
|
<P>
|
|
<I><B>C:</B></I>
|
|
<pre>
|
|
herr_t H5Fmount (hid_t loc_id, const char *dsetname,
|
|
hid_t file_id, hid_t access_prp)
|
|
</pre>
|
|
<P>
|
|
<I><B>FORTRAN:</B></I>
|
|
<pre>
|
|
h5fmount_f (loc_id, dsetname, file_id, hdferr, access_prp)
|
|
|
|
loc_id IN: INTEGER (HID_T)
|
|
dsetname IN: CHARACTER (LEN=*)
|
|
file_id IN: INTEGER (HID_T)
|
|
hdferr OUT: INTEGER
|
|
access_prp IN: INTEGER (HID_T), OPTIONAL
|
|
(Default value: H5P_DEFAULT_F)
|
|
</pre>
|
|
<P>
|
|
<UL>
|
|
<LI> The <em>loc_id</em> and <em>dsetname</em> arguments
|
|
specify the location of the mount point.
|
|
In this example, the mount point is a group <code>/G</code> in the
|
|
specified file. Since the group <code>/G</code> is in the root
|
|
group of the first file, one can also use just <code>G</code> to
|
|
identify it.
|
|
<P>
|
|
Below is a description of another scenario:
|
|
<p>
|
|
Suppose the group <code>G</code> were a member of
|
|
the group <code>H</code> in the first file.
|
|
Then the mount point <code>G</code> can be specified in
|
|
two different ways:
|
|
<P>
|
|
<UL>
|
|
<LI> <em>loc_id</em> is the file identifier for the first file.<BR>
|
|
<em>dsetname</em> is <code>H/G</code>.
|
|
<P>
|
|
<LI> <em>loc_id</em> is the identifier for the group <code>H</code>.<BR>
|
|
<em>dsetname</em> is <code>G</code>.
|
|
</UL>
|
|
<P>
|
|
<LI> The <em>file_id</em> argument is the identifier for the file
|
|
which will be mounted.
|
|
Only one file can be mounted per mount point.
|
|
<P>
|
|
<LI> The <I>access_prp</I> argument is the identifier for the property list
|
|
to be used. Currently, only the default property list,
|
|
<CODE>H5P_DEFAULT</CODE>, can be used in C.
|
|
In FORTRAN, this argument can be omitted or
|
|
<CODE>H5P_DEFAULT_F</CODE> can be used.
|
|
<P>
|
|
<LI> The C function <CODE>H5Fmount</CODE> returns a non-negative
|
|
value if successful and a negative value otherwise.
|
|
With the FORTRAN routine, <CODE>h5fmount_f</CODE>,
|
|
the return value of the call is returned in <em>hdferr</em>:
|
|
0 if successful and -1 otherwise.
|
|
</UL>
|
|
<P>
|
|
<LI>In this example, we only read data from the dataset <code>D</code>.
|
|
One can also modify data.
|
|
If the dataset is modified while the file is mounted, it is
|
|
modified in the original file after the file is unmounted.
|
|
<P>
|
|
<LI> The file is unmounted with <CODE>H5Funmount</CODE> /
|
|
<CODE>h5funmount_f</CODE>:
|
|
<P>
|
|
<I><B>C:</B></I>
|
|
<pre>
|
|
herr_t H5Funmount (hid_t loc_id, const char *dsetname)
|
|
</pre>
|
|
<P>
|
|
<I><B>FORTRAN:</B></I>
|
|
<pre>
|
|
h5funmount_f (loc_id, dsetname, hdferr)
|
|
|
|
loc_id IN: INTEGER (HID_T)
|
|
dsetname IN: CHARACTER (LEN=*)
|
|
hdferr OUT: INTEGER
|
|
</pre>
|
|
<P>
|
|
<ul>
|
|
<li>The <I>loc_id</I> and <I>dsetname</I> arguments specify the location
|
|
of the mount point.
|
|
In our example <I>loc_id</I> is the first file's file identifier
|
|
and <I>dsetname</I> is the name of group <code>/G</code>.
|
|
</ul>
|
|
<P>
|
|
<li>Note that <CODE>H5Funmount</CODE> / <CODE>h5funmount_f</CODE>
|
|
does not close files. Files are closed with the respective calls to
|
|
the <CODE>H5Fclose</CODE> / <CODE>h5fclose_f</CODE> function.
|
|
<P>
|
|
<li>Closing the parent file automatically unmounts the child file.
|
|
<P>
|
|
<LI>The <code>h5dump</code> utility cannot display files in memory.
|
|
Therefore, no output of <code>FILE1</code> after <code>FILE2</code>
|
|
was mounted is provided.
|
|
</UL>
|
|
</UL>
|
|
|
|
|
|
<!-- 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>
|
|
<BR>
|
|
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
|
|
|
|
</BODY>
|
|
</HTML>
|
|
|
|
|
|
|