add ability to write HDF5 soft links

Author: scivision

CMakeLists.txt

@@ -5,7 +5,7 @@ include(cmake/compiler_find.cmake)
 
 project(h5fortran
   LANGUAGES C Fortran
-  VERSION 3.4.2
+  VERSION 3.4.3
   DESCRIPTION "thin, light object-oriented HDF5 Fortran interface"
   HOMEPAGE_URL https://github.com/geospace-code/h5fortran)
 

Examples.md

@@ -26,6 +26,18 @@ call h5f%write('/value1', 123.)
 call h5f%finalize()
 ```
 
+## create soft links to actual variable
+
+HDF5 soft link variables: arbitrarily many soft-linked variable names can point to an actual variable, which need not yet exist.
+
+```fortran
+call h5f%write("/x", 42)
+call h5f%softlink("/x", "/y")
+call h5f%softlink("/x", "/z")
+```
+
+/z and /y are soft links to /x, which need not yet exist.
+
 ## ensure all files are flushed to disk at end of program
 
 If your program opens lots of HDF5 files and you're worried about being sure they're all flushed to disk, make this call near the very end of the program.

README.md

@@ -40,6 +40,7 @@ as well as **character (string)**.
 * **Array slicing on read and write** is supported, that is, reading or writing part of a disk HDF5 array into a variable matching the slice shape.
 * Mismatched datatypes are coerced as per standard Fortran rules. For example, reading a float HDF5 variable into an integer Fortran variable:  42.3 => 42
 * Zlib (deflate) compression / decompression -- h5fortran will work without Zlib, but will save/load uncompressed data only.
+* create HDF5 soft link variables--arbitrarily many soft-linked variable names can point to an actual variable, which need not yet exist.
 
 Tested on systems with HDF5 1.8, 1.10 and 1.12 including:
 

meson.build

@@ -1,6 +1,6 @@
 project('h5fortran', 'fortran',
   meson_version : '>=0.52.0',
-  version : '3.4.2',
+  version : '3.4.3',
   default_options : ['default_library=static', 'buildtype=release', 'warning_level=3'])
 
 subdir('meson')

src/interface.f90

@@ -51,7 +51,8 @@ module h5fortran
   ndims => hdf_get_ndims, &
   shape => hdf_get_shape, layout => hdf_get_layout, chunks => hdf_get_chunk, &
   exist => hdf_check_exist, exists => hdf_check_exist, &
-  is_contig => hdf_is_contig, is_chunked => hdf_is_chunked
+  is_contig => hdf_is_contig, is_chunked => hdf_is_chunked, &
+  softlink => create_softlink
 
 !> below are procedure that need generic mapping (type or rank agnostic)
 
@@ -123,6 +124,24 @@ module subroutine hdf_create(self, dname, dtype, dims, sid, did, chunk_size, ist
 integer, intent(in), optional :: chunk_size(:), istart(:), iend(:), stride(:)
 !! keep istart, iend, stride for future slice shape check
 end subroutine hdf_create
+
+module subroutine hdf_open_group(self, gname, ierr)
+class(hdf5_file), intent(inout) :: self
+character(*), intent(in)        :: gname
+integer, intent(out), optional :: ierr
+end subroutine hdf_open_group
+
+module subroutine hdf_close_group(self, ierr)
+class(hdf5_file), intent(inout) :: self
+integer, intent(out), optional :: ierr
+end subroutine hdf_close_group
+
+module subroutine create_softlink(self, target, link)
+class(hdf5_file), intent(inout) :: self
+character(*), intent(in) :: target, &  !< target path to link
+                            link  !< soft link path to create
+end subroutine create_softlink
+
 end interface
 
 interface !< writer_lt.f90
@@ -399,19 +418,6 @@ module subroutine hdf_read_7d(self, dname, value, ierr, istart, iend, stride)
 end subroutine hdf_read_7d
 end interface
 
-interface
-module subroutine hdf_open_group(self, gname, ierr)
-class(hdf5_file), intent(inout) :: self
-character(*), intent(in)        :: gname
-integer, intent(out), optional :: ierr
-end subroutine hdf_open_group
-
-module subroutine hdf_close_group(self, ierr)
-class(hdf5_file), intent(inout) :: self
-integer, intent(out), optional :: ierr
-end subroutine hdf_close_group
-end interface
-
 
 interface  !< attributes.f90
 

src/tests/test_exist.f90

@@ -11,6 +11,9 @@ program exist_tests
 call test_exist()
 print *, 'OK: exist'
 
+call test_softlink()
+print *, "OK: softlink"
+
 call test_scratch()
 print *, 'OK: scratch'
 
@@ -59,6 +62,35 @@ subroutine test_exist()
 end subroutine test_exist
 
 
+subroutine test_softlink()
+type(hdf5_file) :: h
+character(*), parameter :: fn = 'soft.h5'
+integer :: y
+
+call h%initialize(fn, status="new")
+
+call h%write("/actual", 142)
+call h%softlink("/actual", "/additional")
+call h%read("/additional", y)
+
+if (.not.h%exist("/additional")) error stop "softlink not present"
+
+if (y /= 142) error stop "did not read softlink correctly"
+
+!> test dangling link
+
+call h%softlink("/not_here", "/not_yet")
+if (h%exist("/not_yet")) error stop "dangling softlink"
+
+call h%write("/not_here", 36)
+call h%read("/not_yet", y)
+if (y /= 36)  error stop "finalizing dangling link failed"
+
+call h%finalize()
+
+end subroutine test_softlink
+
+
 subroutine test_scratch()
 logical :: e
 type(hdf5_file) :: h

src/write.f90

@@ -4,7 +4,8 @@
 h5screate_f, H5S_SCALAR_F, &
 h5dcreate_f, &
 h5pset_chunk_f, h5pset_deflate_f, h5pset_shuffle_f, h5pset_fletcher32_f, h5pcreate_f, H5P_DATASET_CREATE_F, h5pclose_f, &
-h5gopen_f
+h5gopen_f, &
+H5Lcreate_soft_f
 
 use H5LT, only: h5ltmake_dataset_string_f, h5ltpath_valid_f
 
@@ -109,6 +110,19 @@
 end procedure hdf_create
 
 
+module procedure create_softlink
+!! HDF5 soft link -- to variables in same file
+!! target need not exist (dangling link)
+!! linking to external files requires an external link (different function required)
+
+integer :: ierr
+
+call H5Lcreate_soft_f(target, self%lid, link, ierr)
+if (check(ierr, self%filename)) return
+
+end procedure create_softlink
+
+
 subroutine set_deflate(self, dims, pid, ierr, chunk_size)
 class(hdf5_file), intent(inout) :: self
 integer(HSIZE_T), intent(in) :: dims(:)