summaryrefslogtreecommitdiffstats
path: root/doc/html/Tutor/mount.html
blob: 1094231866b542bc7847635dfd73efe6f03a38d7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
<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>