    		    Using HDF5 with OpenMP
    		    ----------------------

    1. Introduction to OpenMP
    -------------------------

        - For shared-memory parallelism
        - A combination of library and directives
        - Available for C/C++ and Fortran
        - SGI leading effort
        - Information at http://www.openmp.org and
          http://www.sgi.com/software/openmp

    2. Programming(SGI MPISpro compiler and C language)
    ---------------------------------------------------

        - Turn on compiler '-mp' option
        - Include 'omp.h' library in program
        - Use library functions, directives and environment variables

    3. Sample Programs
    ------------------

    Appendix A contains four OpenMP-HDF5 test programs.  (They are derived from
    the hdf5/examples/h5_write.c).  The purpose of these program is to
    test OpenMP parallelism with the HDF5 library.

    All tests were run on modi4 with SGI MPISpro compiler(cc) and make.
    Program 1 and Program 2 are the working programs.  Program 3 and Program 4
    work occasionally due to racing conditions.
    Follow the following steps to try the programs.

      a.  have your hdf5 library compiled,
      b.  go to hdf5/examples directory,
      c.  add -mp option to the end of the CFLAGS list in the Makefile.  If you
          have the compiled program in another directory, you should go to the
          examples in that directory.
      d.  modify the hdf5/examples/h5_write.c according to the program attached
          here.
      e.  use hdf5/tools/h5dump to examine the output file.

    4. Conclusion
    -------------

    It is not safe to invoke HDF5 library calls via multiple threads in an
    OpenMP program.  But if one serializes HDF5 calls as illustrated in Program 1,
    the HDF5 library works correctly with the OpenMP programs.

    The serialization of HDF5 calls will slow down the OpenMP program unnecessarily.
    Future study is needed to check possible ways to "un-seralize" the HDF5 calls.
    One possibility is that the HDF5 library has a beta-version of Thread-safe
    implmentation though it is for Pthreads environment.  One can check on the
    feasibility of running OpenMP programs with this version of HDF5 Thread-safe
    library.

    Appendix A: OpenMP-HDF5 Programs

    -------
    Updated: 2000/11/28
    Contact: hdfhelp@ncsa.uiuc.edu