Mounting Files

Mounting Files

1. Open the files.
2. Choose the mount point in the first file (the parent file). The mount point in HDF5 is a group, which CANNOT be the root group.
3. Use the HDF5 routine H5Fmount / h5fmount_f to mount the second file (the child file) in the first file.
4. 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.
5. Unmount the second file using H5Funmount / h5funmount_f when the work is done.

Programming Example

Description

             FILE1                                   FILE2
  
      --------------------                   --------------------
      !                  !                   !                  !
      !      /           !                   !       /          !
      !       |          !                   !        |         !
      !       |          !                   !        |         !
      !       V          !                   !        V         !
      !     --------     !                   !     ----------   !
      !     ! Group !    !                   !     ! Dataset!   !
      !     ---------    !                   !     ----------   !
      !------------------!                   !------------------! 

 
                                FILE1                                 
  
                         --------------------                   
                         !                  !                  
                         !      /           !               
                         !       |          !            
                         !       |          !         
                         !       V          !    
                         !     --------     !              
                         !     ! Group !    !            
                         !     ---------    !           
                         !         |        !
                         !         |        !
                         !         V        !
                         !    -----------   !
                         !    ! Dataset !   !
                         !    !----------   !
                         !                  !
                         !------------------!                    

• The first part of the program creates a group in one file and creates and writes a dataset to another file.

• Both files are reopened and the second file is mounted in the first using H5Fmount / h5fmount_f. If no objects will be modified, the files can be opened with H5F_ACC_RDONLY (H5F_ACC_RDONLY_F in FORTRAN). If the data is to be modified, the files should be opened with H5F_ACC_RDWR (H5F_ACC_RDWR_F in FORTRAN).

  C:

      herr_t H5Fmount (hid_t loc_id, const char *dsetname, 
                       hid_t file_id, hid_t access_prp)  
  

  FORTRAN:

      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)  
  

  • The loc_id and dsetname arguments specify the location of the mount point. In this example, the mount point is a group /G in the specified file. Since the group /G is in the root group of the first file, one can also use just G to identify it.

    Below is a description of another scenario:

    Suppose the group G were a member of the group H in the first file. Then the mount point G can be specified in two different ways:

    • loc_id is the file identifier for the first file.
      dsetname is H/G.

    • loc_id is the identifier for the group H.
      dsetname is G.

  • The file_id argument is the identifier for the file which will be mounted. Only one file can be mounted per mount point.

  • The access_prp argument is the identifier for the property list to be used. Currently, only the default property list, H5P_DEFAULT, can be used in C. In FORTRAN, this argument can be omitted or H5P_DEFAULT_F can be used.

  • The C function H5Fmount returns a non-negative value if successful and a negative value otherwise. With the FORTRAN routine, h5fmount_f, the return value of the call is returned in hdferr: 0 if successful and -1 otherwise.

• In this example, we only read data from the dataset D. 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.

• The file is unmounted with H5Funmount / h5funmount_f:

  C:

      herr_t H5Funmount (hid_t loc_id, const char *dsetname)
  

  FORTRAN:

      h5funmount_f (loc_id, dsetname, hdferr)
  
              loc_id     IN: INTEGER (HID_T)
              dsetname   IN: CHARACTER (LEN=*)
              hdferr    OUT: INTEGER
  

  • The loc_id and dsetname arguments specify the location of the mount point. In our example loc_id is the first file's file identifier and dsetname is the name of group /G.

• Note that H5Funmount / h5funmount_f does not close files. Files are closed with the respective calls to the H5Fclose / h5fclose_f function.

• Closing the parent file automatically unmounts the child file.

• The h5dump utility cannot display files in memory. Therefore, no output of FILE1 after FILE2 was mounted is provided.