diff options
Diffstat (limited to 'doc/html/Tutor/mount.html')
| -rw-r--r-- | doc/html/Tutor/mount.html | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/doc/html/Tutor/mount.html b/doc/html/Tutor/mount.html new file mode 100644 index 0000000..9d0e494 --- /dev/null +++ b/doc/html/Tutor/mount.html @@ -0,0 +1,304 @@ +<HTML><HEAD> +<TITLE>HDF5 Tutorial - Mounting Files +</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">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 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 "mount point" in the first file (parent). The "mount point" in + HDF5 is a group ( it can also be the root group ). + +<LI>Use the HDF5 API function H5Fmount to mount the second file (child) in + the first one. + +<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 the H5Funmount function 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 with a group in it, and another +file with 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 picture +illustrates this concept. +<PRE> + + 'FILE1' 'FILE2' + +-------------------- -------------------- +! ! ! ! +! / ! ! / ! +! | ! ! | ! +! | ! ! | ! +! V ! ! V ! +! -------- ! ! ---------- ! +! ! Group ! ! ! ! Dataset! ! +! --------- ! ! ---------- ! +!------------------! !------------------! +</PRE> +After mounting the second file, 'FILE2', under the group in the file, 'FILE1', +the parent has the following structure: +<PRE> + + 'FILE1' + + -------------------- + ! ! + ! / ! + ! | ! + ! | ! + ! V ! + ! -------- ! + ! ! Group ! ! + ! --------- ! + ! | ! + ! | ! + ! V ! + ! ----------- ! + ! ! Dataset ! ! + ! !---------- ! + ! ! + !------------------! + +</PRE> +[ <A HREF="examples/h5_mount.c">Download h5_mount.c</A> ] +<PRE> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +#include<hdf5.h> + +#define FILE1 "mount1.h5" +#define FILE2 "mount2.h5" + +#define RANK 2 +#define NX 4 +#define NY 5 + +int main(void) +{ + + hid_t fid1, fid2, gid; /* Files and group identifiers */ + hid_t did, tid, sid; /* Dataset and datatype identifiers */ + + herr_t status; + hsize_t dims[] = {NX,NY}; /* Dataset dimensions */ + + int i, j; + int bm[NX][NY], bm_out[NX][NY]; /* Data buffers */ + + /* + * Initialization of buffer matrix "bm" + */ + for(i =0; i < NX; i++) { + for(j = 0; j < NY; j++) + bm[i][j] = i + j; + } + + /* + * Create first file and a group in it. + */ + fid1 = H5Fcreate(FILE1, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + gid = H5Gcreate(fid1, "/G", 0); + + /* + * Close group and file + */ + H5Gclose(gid); + H5Fclose(fid1); + + /* + * Create second file and dataset "D" in it. + */ + fid2 = H5Fcreate(FILE2, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + dims[0] = NX; + dims[1] = NY; + sid = H5Screate_simple(RANK, dims, NULL); + did = H5Dcreate(fid2, "D", H5T_NATIVE_INT, sid, H5P_DEFAULT); + + /* + * Write data to the dataset. + */ + status = H5Dwrite(did, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, bm); + + /* + * Close all identifiers. + */ + H5Sclose(sid); + H5Dclose(did); + H5Fclose(fid2); + + /* + * Reopen both files + */ + fid1 = H5Fopen(FILE1, H5F_ACC_RDONLY, H5P_DEFAULT); + fid2 = H5Fopen(FILE2, H5F_ACC_RDONLY, H5P_DEFAULT); + + /* + * Mount second file under G in the first file. + */ + H5Fmount(fid1, "/G", fid2, H5P_DEFAULT); + + /* + * Access dataset D in the first file under /G/D name. + */ + did = H5Dopen(fid1,"/G/D"); + tid = H5Dget_type(did); + status = H5Dread(did, tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, bm_out); + + /* + * Print out the data. + */ + for(i=0; i < NX; i++){ + for(j=0; j < NY; j++) + printf(" %d", bm_out[i][j]); + printf("\n"); + } + + /* + * Close all identifers + */ + H5Tclose(tid); + H5Dclose(did); + + /* + * Unmounting second file + */ + H5Funmount(fid1, "/G"); + + /* + * Close both files + */ + H5Fclose(fid1); + H5Fclose(fid2); + + return 0; +} +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +</PRE> +<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 with the H5F_ACC_RDONLY access flag since no + objects will be modified. The child should be opened with H5F_ACC_RDWR if + the dataset is to be modified. +<P> +<LI> The second file is mounted in the first using the H5Fmount function. +<PRE> + herr_t H5Fmount(hid_t loc_id, const char *name, hid_t file_id, hid_t plist_id) +</PRE> +<UL> + <LI> The first two arguments specify the location of the "mount point" + ( a group ). In this example the "mount point" is a group "/G" in the + file specified by its handle <I>fid1</I>. Since group G is in the root + group of the first file, one can also use just "G" to identify it. +<P> + Below is a description of another scenario:<BR> + Suppose group G was a member of group D in the first file (<I>fid1</I>). + Then mounting point G can be specified in two different ways: +<P> +<UL> + <LI> <I>loc_id</I> is <I>fid1</I><BR> + <I>name</I> is "D/G" +<P> + <LI> <I>loc_id</I> is an identifier of the group "D"<BR> + <I>name</I> is just "G" +</UL> + <P> + <LI> The third argument is an identifier of the file which will be mounted. + Only one file can be mounted per "mount point". +<P> + <LI> The fourth argument is an identifier of the property list to be used. + Currently, only the default property list, H5P_DEFAULT, can be used. +</UL> +<P> +<LI> In this example we just read data from the dataset D. One can modify + data also. If the dataset is modified while the file is mounted, it becomes + modified in the original file too after the file is unmounted. +<P> +<LI> The file is unmounted with the H5Funmount function: +<PRE> + herr_t H5Funmount(hid_t loc_id, const char *name) +</PRE> + Arguments to this function specify the location of the "mount point". + In our example <I>loc_id</I> is an identifier of the first file, and + <I>name</I> is the name of group G, "/G". One could also use "G" + instead of "/G" since G is a member of the root group in the file + <I>fid1</I>. Notice that H5Funmount does not close files. They are closed + with the respective calls to the H5Fclose function. Closing the parent + automatically unmounts the child. +<P> +<LI>The h5dump utility cannot display files in memory, therefore no output + of FILE1 after FILE2 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="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> <H6>Last Modified: August 27, 1999</H6><BR> +<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +</FONT> +<BR> +<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> + +</BODY> +</HTML> + + + |