diff --git a/src/include/H5.f90 b/src/include/H5.f90 index eb14205..9a56399 100644 --- a/src/include/H5.f90 +++ b/src/include/H5.f90 @@ -7,103 +7,194 @@ ! License: see file COPYING in top level of source distribution. ! INTERFACE - + !> \ingroup h5hut_f90_api + !! \addtogroup h5hut_file_f + !! @{ + !> - !! \ingroup h5hut_file_f - !! Create file property. See \ref H5CreateProp - !! \return 0 on success or -2 on error - !< + !! Create a new, empty file property list. + !! + !! File property lists are used to control optional behavior like file + !! creation, file access, dataset creation, dataset transfer. File + !! property lists are attached to file handles while opened with \ref + !! h5_openfile(). + !! + !! \return empty file property list + !! \return \c H5_FAILURE on error + !! + !! \see h5_setprop_file_mpio() + !! \see h5_setprop_file_mpio_collective() + !! \see h5_setprop_file_mpio_independent() + !! \see h5_setprop_file_mpio_posix() (HDF5 <= 1.8.12 only) + !! \see h5_setprop_file_corevfd() + !! \see h5_setprop_file_align() + !! \see h5_setprop_file_throttle() + INTEGER*8 FUNCTION h5_createprop_file () END FUNCTION h5_createprop_file !> - !! \ingroup h5hut_file_f - !! Store MPI IO comminicator information in file property list. - !! See \ref H5SetPropFileMPIO - !! \return 0 on success or -2 on error - !< + !! Stores MPI IO communicator information to given file property list. If used in + !! \ref h5_openfile(), MPI collective IO will be used. + !! + !! \note This function deprecated. Use h5_setprop_file_mpio_collective() instead. + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + !! + !! \see h5_setprop_file_mpio_independent() + !! \see h5_setprop_file_mpio_posix() (HDF5 <= 1.8.12 only) + !! \see h5_setprop_file_corevfd() + INTEGER*8 FUNCTION h5_setprop_file_mpio (prop, comm) INTEGER*8, INTENT(IN) :: prop !< property INTEGER, INTENT(IN) :: comm !< the MPI communicator used by the program END FUNCTION h5_setprop_file_mpio !> - !! \ingroup h5hut_file_f - !! Store MPI IO comminicator information in file property list. - !! See \ref H5SetPropFileMPIOCollective - !! \return 0 on success or -2 on error - !< + !! Stores MPI IO communicator information to given file property list. If used in + !! \ref h5_openfile(), MPI collective IO will be used. + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + !! + !! \note This function deprecates h5_setprop_file_mpio(). + !! + !! \see h5_setprop_file_mpio_independent() + !! \see h5_setprop_file_mpio_posix() (HDF5 <= 1.8.12 only) + !! \see h5_setprop_file_corevfd() + INTEGER*8 FUNCTION h5_setprop_file_mpio_collective (prop, comm) INTEGER*8, INTENT(IN) :: prop !< property INTEGER, INTENT(IN) :: comm !< the MPI communicator used by the program END FUNCTION h5_setprop_file_mpio_collective !> - !! \ingroup h5hut_file_f - !! Store MPI IO comminicator information in file property list. - !! See \ref H5SetPropFileMPIOIndependent - !! \return 0 on success or -2 on error - !< + !! Stores MPI IO communicator information to given file property list. If used in + !! \ref h5_openfile(), MPI independent IO will be used. + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + !! + !! \see h5_setprop_file_mpio_collective() + !! \see h5_setprop_file_mpio_posix() (HDF5 <= 1.8.12 only) + !! \see h5_setprop_file_corevfd() + INTEGER*8 FUNCTION h5_setprop_file_mpio_independent (prop, comm) INTEGER*8, INTENT(IN) :: prop !< property INTEGER, INTENT(IN) :: comm !< the MPI communicator used by the program END FUNCTION h5_setprop_file_mpio_independent !> - !! \ingroup h5hut_file_f - !! Store MPI IO comminicator information in file property list. - !! See \ref H5SetPropFileMPIOPosix - !! \return 0 on success or -2 on error - !< + !! Stores MPI IO communicator information to given file property list. If used in + !! \ref h5_openfile(), MPI POSIX IO will be used. + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + !! + !! \note This function is available only, if H5hut has been compiled with + !! HDF5 1.8.12 or older. + !! + !! \see h5_setprop_file_mpio_collective() + !! \see h5_setprop_file_mpio_independent() + !! \see h5_setprop_file_corevfd() + INTEGER*8 FUNCTION h5_setprop_file_mpio_posix (prop, comm) INTEGER*8, INTENT(IN) :: prop !< property INTEGER, INTENT(IN) :: comm !< the MPI communicator used by the program END FUNCTION h5_setprop_file_mpio_posix !> - !! \ingroup h5hut_file_f - !! Use the core virtual file driver. - !! See \ref H5SetPropCoreVFD - !! \return 0 on success or -2 on error - !< + !! Modifies the file property list to use the \c H5FD_CORE driver. The + !! \c H5FD_CORE driver enables an application to work with a file in memory. + !! File contents are stored only in memory until the file is closed. + !! + !! The increment by which allocated memory is to be increased each time more + !! memory is required, must be specified with \c increment. + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + INTEGER*8 FUNCTION h5_setprop_file_corevfd (prop) INTEGER*8, INTENT(IN) :: prop !< property END FUNCTION h5_setprop_file_corevfd !> - !! \ingroup h5hut_file_f - !! Set alignment. See \ref H5SetPropFileAlign - !! \return 0 on success or -2 on error - !< + !! Sets alignment properties of a file property list so that any file + !! object greater than or equal in size to threshold bytes will be + !! aligned on an address which is a multiple of alignment. The + !! addresses are relative to the end of the user block; the alignment + !! is calculated by subtracting the user block size from the absolute + !! file address and then adjusting the address to be a multiple of + !! alignment. + !! + !! Default values for alignment is one, implying no + !! alignment. Generally the default value result in the best + !! performance for single-process access to the file. For MPI IO and + !! other parallel systems, choose an alignment which is a multiple of + !! the disk block size. + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + !! + !! \see h5_setprop_file_corevfd() + INTEGER*8 FUNCTION h5_setprop_file_align (prop, align) INTEGER*8, INTENT(IN) :: prop !< property INTEGER*8, INTENT(IN) :: align !< alignment END FUNCTION h5_setprop_file_align !> - !! \ingroup h5hut_file_f - !! Set throttle. See \ref H5SetPropFileThrottle - !! \return 0 on success or -2 on error - !< + !! Set the `throttle` factor, which causes HDF5 write and read + !! calls to be issued in that number of batches. + !! + !! This can prevent large concurrency parallel applications that + !! use independent writes from overwhelming the underlying + !! parallel file system. + !! + !! Throttling only works with the H5_VFD_MPIO_POSIX or + !! H5_VFD_MPIO_INDEPENDENT drivers and is only available in + !! the parallel library. + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + INTEGER*8 FUNCTION h5_setprop_file_throttle (prop, throttle) INTEGER*8, INTENT(IN) :: prop !< property - INTEGER*8, INTENT(IN) :: throttle !< throttle + INTEGER*8, INTENT(IN) :: throttle !< throttle factor END FUNCTION h5_setprop_file_throttle !> - !! \ingroup h5hut_file_f - !! Close property. See \ref H5CloseProp - !! \return 0 on success or -2 on error - !< + !! Close file property list. + INTEGER*8 FUNCTION h5_closeprop (prop) INTEGER*8, INTENT(IN) :: prop !< property END FUNCTION h5_closeprop !> - !! \ingroup h5hut_file_f - !! Opens a file for reading. See \ref H5OpenFile - !! \return 0 on success or error code - !< + !! Open file with name \c filename. + !! + !! File mode flags are: + !! - \c H5_O_RDONLY: Only reading allowed + !! - \c H5_O_WRONLY: create new file, dataset must not exist + !! - \c H5_O_APPENDONLY: allows to append new data to an existing file + !! - \c H5_O_RDWR: dataset may exist + !! - \c H5_FS_LUSTRE - enable optimizations for the Lustre file system + !! - \c H5_VFD_MPIO_POSIX - use the HDF5 MPI-POSIX virtual file driver + !! - \c H5_VFD_MPIO_INDEPENDENT - use MPI-IO in indepedent mode + !! + !! The file is opened with the properties set in the file property list + !! \c prop. This argument can also be set to \c H5_PROP_DEFAULT to use + !! reasonable default values. In this case \c MPI_COMM_WORLD will be + !! used as MPI communicator in a parallel execution environment. + !! + !! The typical file extension is \c .h5. + !! + !! \return File handle + !! \return \c H5_FAILURE on error + !! + !! \see h5_createprop_file() + INTEGER*8 FUNCTION h5_openfile (fname, mode, props) CHARACTER(LEN=*), INTENT(IN) :: fname !< the filename to open for reading INTEGER*8, INTENT(IN) :: mode !< file mode @@ -111,71 +202,167 @@ END FUNCTION h5_openfile !> - !! \ingroup h5hut_file_f - !! Closes a file. See \ref H5CloseFile - !! \return 0 on success or error code + !! Close file and free all memory associated with the file handle. + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + INTEGER*8 FUNCTION h5_closefile (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open END FUNCTION h5_closefile !> - !! \ingroup h5hut_file_f - !! Checks that a file is valid. See \ref H5CheckFile - !! \return H5_SUCCESS or H5_FAILURE - !< + !! Verify that the passed file handle is a valid H5hut file handle. + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + INTEGER*8 FUNCTION h5_checkfile ( filehandle ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open END FUNCTION h5_checkfile !> - !! \ingroup h5hut_file_f - !! Flush file data to disk. - !! \return H5_SUCCESS or H5_FAILURE - !< + !! Flush all file data to disk. + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + INTEGER*8 FUNCTION h5_flushfile (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open END FUNCTION h5_flushfile !> - !! \ingroup h5hut_file_f !! Flush step data to disk. - !! \return H5_SUCCESS or H5_FAILURE - !< + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + INTEGER*8 FUNCTION h5_flushstep (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open END FUNCTION h5_flushstep !> - !! \ingroup h5hut_file_f - !! Close HDF5 library. See \ref H5Finalize - !! \return \c H5_SUCCESS or \c H5_FAILURE - !< + !! Close H5hut library. This function should be called before program exit. + !! + !! \return \c H5_SUCCESS on success + !! \return \c H5_FAILURE on error + INTEGER*8 FUNCTION h5_finalize () END FUNCTION h5_finalize + !> @} + + !> \ingroup h5hut_f90_api_error_handling_and_debugging + !! \addtogroup h5hut_verbosity_f + !! @{ + !> - !! \ingroup h5hut_error_f - !! See \ref H5SetVerbosityLevel - !! \return 0 on success or error code - !< + !! Set verbosity level to \c level. + !! + !! Verbosity levels are: + !! - \c H5_VERBOSE_NONE: be quiet + !! - \c H5_VERBOSE_ERROR: output error messages + !! - \c H5_VERBOSE_WARN: output error messages and warning + !! - \c H5_VERBOSE_INFO: output error messages, warnings and informational messages + !! + !! The default verbosity level ist \c H5_VERBOSE_ERROR. + !! + !! \return \c H5_SUCCESS + !! + !! \see h5_get_verbosity_level() + SUBROUTINE h5_set_verbosity_level ( level ) INTEGER*8, INTENT(IN) :: level !< the level from 0 (no output) to 5 (most detailed) END SUBROUTINE h5_set_verbosity_level !> - !! \ingroup h5hut_error_f - !! Abort program on error. - !! \return 0 on success or error code - !< - SUBROUTINE h5_abort_on_error () - END SUBROUTINE h5_abort_on_error + !! Get verbosity level. + !! + !! \return verbosity level + !! + !! \see h5_set_verbosity_level() + + INTEGER*8 FUNCTION h5_get_verbosity_level () + END FUNCTION h5_get_verbosity_level + + !> @} + + !> \addtogroup h5hut_debug_f + !! @{ + + !> + !! Set debug mask. The debug mask is an or'ed value of + !! + !! - \c H5_DEBUG_API: C-API calls + !! - \c H5_DEBUG_CORE_API: core API calls. The core API is used by the C- and Fortran API. + !! - \c H5_DEBUG_PRIV_API: private API calls + !! - \c H5_DEBUG_PRIV_FUNC: static functions + !! - \c H5_DEBUG_HDF5: HDF5 wrapper calls + !! - \c H5_DEBUG_MPI: MPI wrapper calls + !! - \c H5_DEBUG_MALLOC: memory allocation + !! - \c H5_DEBUG_ALL: enable all + !! + !! \return \c H5_SUCCESS + !! + !! \see h5_get_debug_mask() + + SUBROUTINE h5_set_debug_mask ( mask ) + INTEGER*9, INTEGER(IN) :: mask !< [in] debug mask + END SUBROUTINE h5_set_debug_mask !> - !! \ingroup h5hut_error_f - !! Get error number. - !! \return 0 on success or error code - !< - SUBROUTINE h5_get_error_number () - END SUBROUTINE h5_get_error_number + !! Get debug mask. + !! + !! \return debug mask + !! + !! \see h5_set_debug_mask() + INTEGER*8 FUNCTION h5_get_debug_mask () + END FUNCTION h5_get_debug_mask + + !> @} + + !> \addtogroup h5hut_error_f + !! @{ + + !> + !! Report error, do not abort program. The error must be handled in the programm. + + SUBROUTINE h5_report_on_error () + END SUBROUTINE h5_report_on_error + + !> + !! Abort program on error. + + SUBROUTINE h5_abort_on_error () + END SUBROUTINE h5_abort_on_error + + !> + !! Get last error code. + !! + !! Error codes are: + !! + !! - \c H5_ERR_BADF: Something is wrong with the file handle. + !! - \c H5_ERR_NOMEM: Out of memory. + !! - \c H5_ERR_INVAL: Invalid argument. + !! + !! - \c H5_ERR_VIEW: Something is wrong with the view. + !! - \c H5_ERR_NOENTRY: A lookup failed. + !! + !! - \c H5_ERR_MPI: A MPI error occured. + !! - \c H5_ERR_HDF5: A HDF5 error occured. + !! - \c H5_ERR_H5: Unspecified error in H5 module. + !! - \c H5_ERR_H5PART: Unspecified error in H5Part module. + !! - \c H5_ERR_H5BLOCK: Unspecified error in H5Block module. + !! - \c H5_ERR_H5FED: Unspecified error in H5Fed module. + !! + !! - \c H5_ERR_INTERNAL: Internal error. + !! - \c H5_ERR_NOT_IMPLEMENTED: Function not yet implemented. + !! + !! \return error code + + INTEGER*8 FUNCTION h5_get_error_number () + END FUNCTION h5_get_error_number + + !> @} END INTERFACE diff --git a/src/include/H5.h b/src/include/H5.h index 3ea0df7..ebeae2e 100644 --- a/src/include/H5.h +++ b/src/include/H5.h @@ -20,10 +20,21 @@ extern "C" { #endif /** - \ingroup h5hut_file + \ingroup h5hut_c_api + \addtogroup h5hut_file + @{ +*/ - Create a new, empty file property list. This list can be used in \ref H5OpenFile() - to set various properties like the file I/O layer. +/** + Create a new, empty file property list. + + File property lists are used to control optional behavior like file + creation, file access, dataset creation, dataset transfer. File + property lists are attached to file handles while opened with \ref + H5OpenFile(). + + \return empty file property list + \return \c H5_FAILURE on error \see H5SetPropFileMPIO() \see H5SetPropFileMPIOCollective() @@ -32,9 +43,6 @@ extern "C" { \see H5SetPropFileCoreVFD() \see H5SetPropFileAlign() \see H5SetPropFileThrottle() - - \return empty file property list - \return \c H5_FAILURE on error */ static inline h5_prop_t H5CreateFileProp ( @@ -45,19 +53,17 @@ H5CreateFileProp ( } /** - \ingroup h5hut_file - Stores MPI IO communicator information to given file property list. If used in \ref H5OpenFile(), MPI collective IO will be used. \note H5SetPropFileMPIO() is deprecated. Use H5SetPropFileMPIOCollective() instead. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + \see H5SetPropFileMPIOIndependent() \see H5SetPropFileMPIOPosix() (HDF5 <= 1.8.12 only) \see H5SetPropFileCoreVFD() - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error */ static inline h5_err_t H5SetPropFileMPIO ( @@ -69,23 +75,21 @@ H5SetPropFileMPIO ( } /** - \ingroup h5hut_file - Stores MPI IO communicator information to given file property list. If used in \ref H5OpenFile(), MPI collective IO will be used. - \note H5SetPropFileMPIOCollective() deprecates H5SetPropFileMPIO(). + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + + \note This function deprecates H5SetPropFileMPIO(). \see H5SetPropFileMPIOIndependent() \see H5SetPropFileMPIOPosix() (HDF5 <= 1.8.12 only) \see H5SetPropFileCoreVFD() - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error */ static inline h5_err_t H5SetPropFileMPIOCollective ( - h5_prop_t prop, ///> [in,out] identifier for file property list + h5_prop_t prop, ///< [in,out] identifier for file property list MPI_Comm* comm ///< [in] MPI communicator ) { H5_API_ENTER (h5_err_t, "prop=%p, comm=%p", (void*)prop, comm); @@ -93,22 +97,20 @@ H5SetPropFileMPIOCollective ( } /** - \ingroup h5hut_file - Stores MPI IO communicator information to given file property list. If used in \ref H5OpenFile(), MPI independent IO will be used. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + \see H5SetPropFileMPIOCollective() \see H5SetPropFileMPIOPosix() (HDF5 <= 1.8.12 only) \see H5SetPropFileCoreVFD() - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error */ static inline h5_err_t H5SetPropFileMPIOIndependent ( - h5_prop_t prop, ///> [in,out] identifier for file property list - MPI_Comm* comm ///> [in] MPI communicator + h5_prop_t prop, ///< [in,out] identifier for file property list + MPI_Comm* comm ///< [in] MPI communicator ) { H5_API_ENTER (h5_err_t, "prop=%p, comm=%p", (void*)prop, comm); H5_API_RETURN (h5_set_prop_file_mpio_independent (prop, comm)); @@ -116,25 +118,24 @@ H5SetPropFileMPIOIndependent ( #if H5_VERSION_LE(1,8,12) /** - \ingroup h5hut_file - Stores MPI IO communicator information to given file property list. If used in \ref H5OpenFile(), MPI POSIX IO will be used. + + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + \note This function is available only, if H5hut has been compiled with HDF5 1.8.12 or older. \see H5SetPropFileMPIOCollective() \see H5SetPropFileMPIOIndependent() \see H5SetPropFileCoreVFD() - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error */ static inline h5_err_t H5SetPropFileMPIOPosix ( - h5_prop_t prop, ///> [in,out] identifier for file property list - MPI_Comm* comm ///> [in] MPI communicator + h5_prop_t prop, ///< [in,out] identifier for file property list + MPI_Comm* comm ///< [in] MPI communicator ) { H5_API_ENTER (h5_err_t, "prop=%p, comm=%p", (void*)prop, comm); H5_API_RETURN (h5_set_prop_file_mpio_posix (prop, comm)); @@ -142,31 +143,26 @@ H5SetPropFileMPIOPosix ( #endif /** - \ingroup h5hut_file - Modifies the file property list to use the \c H5FD_CORE driver. The \c H5FD_CORE driver enables an application to work with a file in memory. File contents are stored only in memory until the file is closed. The increment by which allocated memory is to be increased each time more - memory is required, can be specified with \ref H5SetPropFileAlign(). - - \see H5SetPropFileAlign() + memory is required, must be specified with \c increment. \return \c H5_SUCCESS on success \return \c H5_FAILURE on error */ static inline h5_err_t H5SetPropFileCoreVFD ( - h5_prop_t prop ///> [in,out] identifier for file property list + h5_prop_t prop, ///< [in,out] identifier for file property list + h5_int64_t increment ///< [in] size, in bytes, of memory increments. ) { H5_API_ENTER (h5_err_t, "prop=%p", (void*)prop); - H5_API_RETURN (h5_set_prop_file_core_vfd (prop)); + H5_API_RETURN (h5_set_prop_file_core_vfd (prop, increment)); } /** - \ingroup h5hut_file - Sets alignment properties of a file property list so that any file object greater than or equal in size to threshold bytes will be aligned on an address which is a multiple of alignment. The @@ -181,23 +177,21 @@ H5SetPropFileCoreVFD ( other parallel systems, choose an alignment which is a multiple of the disk block size. - \see H5SetPropFileCoreVFD() - \return \c H5_SUCCESS on success \return \c H5_FAILURE on error + + \see H5SetPropFileCoreVFD() */ static inline h5_err_t H5SetPropFileAlign ( - h5_prop_t prop, ///> [in,out] identifier for file property list - h5_int64_t align ///> [in] alignment + h5_prop_t prop, ///< [in,out] identifier for file property list + h5_int64_t align ///< [in] alignment ) { H5_API_ENTER (h5_err_t, "prop=%p, align=%lld", (void*)prop, (long long int)align); H5_API_RETURN (h5_set_prop_file_align (prop, align)); } /** - \ingroup h5hut_file - Set the `throttle` factor, which causes HDF5 write and read calls to be issued in that number of batches. @@ -214,29 +208,25 @@ H5SetPropFileAlign ( */ static inline h5_err_t H5SetPropFileThrottle ( - h5_prop_t prop, ///> [in,out] identifier for file property list - h5_int64_t throttle ///> [in] throttle factor + h5_prop_t prop, ///< [in,out] identifier for file property list + h5_int64_t throttle ///< [in] throttle factor ) { H5_API_ENTER (h5_err_t, "prop=%p, throttle=%lld", (void*)prop, (long long int)throttle); H5_API_RETURN (h5_set_prop_file_throttle (prop, throttle)); } /** - \ingroup h5hut_file - Close file property list. */ static inline h5_err_t H5CloseProp ( - h5_prop_t prop ///> [in] identifier for file property list + h5_prop_t prop ///< [in] identifier for file property list ) { H5_API_ENTER (h5_err_t, "prop=%p", (void*)prop); H5_API_RETURN (h5_close_prop (prop)); } /** - \ingroup h5hut_file - Open file with name \c filename. File mode flags are: @@ -255,16 +245,16 @@ H5CloseProp ( The typical file extension is \c .h5. - \see H5CreateFileProp() - \return File handle \return \c H5_FAILURE on error + + \see H5CreateFileProp() */ static inline h5_file_t H5OpenFile ( - const char* filename, ///> [in] name of file - h5_int64_t mode, ///> [in] file mode - h5_prop_t props ///> [in] identifier for file property list + const char* filename, ///< [in] name of file + h5_int64_t mode, ///< [in] file mode + h5_prop_t props ///< [in] identifier for file property list ) { H5_API_ENTER (h5_file_t, "filename='%s', mode=%lld, props=%p", @@ -273,8 +263,6 @@ H5OpenFile ( } /** - \ingroup h5hut_file - Close file and free all memory associated with the file handle. \return \c H5_SUCCESS on success @@ -291,8 +279,6 @@ H5CloseFile ( } /** - \ingroup h5hut_file - Verify that the passed file handle is a valid H5hut file handle. \return \c H5_SUCCESS on success @@ -309,8 +295,6 @@ H5CheckFile ( } /** - \ingroup h5hut_file - Flush step data to disk. \return \c H5_SUCCESS on success @@ -327,8 +311,6 @@ H5FlushStep ( } /** - \ingroup h5hut_file - Flush all file data to disk. \return \c H5_SUCCESS on success @@ -345,8 +327,6 @@ H5FlushFile ( } /** - \ingroup h5hut_file - Close H5hut library. This function should be called before program exit. \return \c H5_SUCCESS on success @@ -360,26 +340,141 @@ H5Finalize ( H5_API_RETURN (h5_close_hdf5 ()); } -/** - \ingroup h5hut_error +///< @} + +/** + \ingroup h5hut_c_api_error_handling_and_debugging + \addtogroup h5hut_verbosity + @{ + */ + +/** Set verbosity level to \c level. + Verbosity levels are: + - \c H5_VERBOSE_NONE: be quiet + - \c H5_VERBOSE_ERROR: output error messages + - \c H5_VERBOSE_WARN: output error messages and warning + - \c H5_VERBOSE_INFO: output error messages, warnings and informational messages + + The default verbosity level ist \c H5_VERBOSE_ERROR. + \return \c H5_SUCCESS + + \see H5GetVerbosityLevel() */ static inline h5_err_t H5SetVerbosityLevel ( - const h5_id_t level ///< [in] verbosity/debug level. + const h5_id_t level ///< [in] verbosity level. ) { - return h5_set_debuglevel (level); + return h5_set_debuglevel (level & 0x03); } /** - \ingroup h5hut_error + Get verbosity level. + \return verbosity level + + \see H5SetVerbosityLevel() +*/ +static inline h5_id_t +H5GetVerbosityLevel ( + void + ) { + return h5_get_debuglevel (level) & 0x03; +} + +///< @} + +/** + \addtogroup h5hut_debug + @{ +*/ + +/** + Set debug mask. The debug mask is an or'ed value of + + - \c H5_DEBUG_API: C-API calls + - \c H5_DEBUG_CORE_API: core API calls. The core API is used by the C- and Fortran API. + - \c H5_DEBUG_PRIV_API: private API calls + - \c H5_DEBUG_PRIV_FUNC: static functions + - \c H5_DEBUG_HDF5: HDF5 wrapper calls + - \c H5_DEBUG_MPI: MPI wrapper calls + - \c H5_DEBUG_MALLOC: memory allocation + - \c H5_DEBUG_ALL: enable all + + \return \c H5_SUCCESS + + \see H5GetDebugMask() +*/ +static inline h5_err_t +H5SetDebugMask ( + const h5_id_t mask ///< [in] debug mask + ) { + return h5_set_debuglevel (mask & ~0x03); +} + +/** + Get debug mask. + + \return debug mask + + \see H5SetDebugMask() +*/ +static inline h5_id_t +H5GetDebugMask ( + void + ) { + return (h5_get_debuglevel () & ~0x03); +} +///< @} + +/** + \addtogroup h5hut_error + @{ +*/ + +/** + Report error, do not abort program. The error must be handled in the programm. + + \return \c H5_SUCCESS + + \see H5SetErrorHandler() + \see H5ReportErrorhandler() +*/ +static inline h5_err_t +H5ReportOnError ( + void + ) { + H5_API_ENTER (h5_err_t, "%s", ""); + H5_API_RETURN (h5_set_errorhandler (h5_report_errorhandler)); +} + +/** + Abort program on error. + + \return \c H5_SUCCESS + + \see H5SetErrorHandler() + \see H5AbortErrorhandler() +*/ +static inline h5_err_t +H5AbortOnError ( + void + ) { + H5_API_ENTER (h5_err_t, "%s", ""); + H5_API_RETURN (h5_set_errorhandler (h5_abort_errorhandler)); +} + +/** Set error handler to \c handler. \return \c H5_SUCCESS + + \see H5GetErrorHandler() + \see H5ReportErrorhandler() + \see H5AbortErrorhandler() */ static inline h5_err_t H5SetErrorHandler ( @@ -390,26 +485,13 @@ H5SetErrorHandler ( } /** - \ingroup h5hut_error - - Set the abort error handler. - - \return \c H5_SUCCESS -*/ -static inline h5_err_t -H5AbortOnError ( - void - ) { - H5_API_ENTER (h5_err_t, "%s", ""); - H5_API_RETURN (h5_set_errorhandler (h5_abort_errorhandler)); -} - -/** - \ingroup h5hut_error - Get current error handler. \return Pointer to error handler. + + \see H5SetErrorHandler() + \see H5ReportErrorhandler() + \see H5AbortErrorhandler() */ static inline h5_errorhandler_t H5GetErrorHandler ( @@ -421,12 +503,10 @@ H5GetErrorHandler ( /** - \ingroup h5hut_error - The report error handler writes a message to stderr, sets the error number and returns. - \return \c H5_FAILURE + \return \c H5_FAILURE */ static inline h5_err_t H5ReportErrorhandler ( @@ -437,8 +517,6 @@ H5ReportErrorhandler ( } /** - \ingroup h5hut_error - The abort error handler writes a message to stderr and exits the programm. \return does not return. @@ -452,10 +530,27 @@ H5AbortErrorhandler ( } /** - \ingroup h5hut_error - Get last error code. + Error codes are: + + - \c H5_ERR_BADF: Something is wrong with the file handle. + - \c H5_ERR_NOMEM: Out of memory. + - \c H5_ERR_INVAL: Invalid argument. + + - \c H5_ERR_VIEW: Something is wrong with the view. + - \c H5_ERR_NOENTRY: A lookup failed. + + - \c H5_ERR_MPI: A MPI error occured. + - \c H5_ERR_HDF5: A HDF5 error occured. + - \c H5_ERR_H5: Unspecified error in H5 module. + - \c H5_ERR_H5PART: Unspecified error in H5Part module. + - \c H5_ERR_H5BLOCK: Unspecified error in H5Block module. + - \c H5_ERR_H5FED: Unspecified error in H5Fed module. + + - \c H5_ERR_INTERNAL: Internal error. + - \c H5_ERR_NOT_IMPLEMENTED: Function not yet implemented. + \return error code */ static inline h5_err_t @@ -465,6 +560,8 @@ H5GetErrno ( return h5_get_errno (); } +///< @} + #ifdef __cplusplus } #endif diff --git a/src/include/H5Block.h b/src/include/H5Block.h index 2f94503..b513151 100644 --- a/src/include/H5Block.h +++ b/src/include/H5Block.h @@ -10,7 +10,7 @@ #ifndef __H5BLOCK_H #define __H5BLOCK_H -/*! +/** \ingroup h5block_model \note @@ -21,13 +21,9 @@ size of the layout. If the size of the layout doesn't match the size of the field, an error will be indicated. - \note - In write mode partitions are shrinked to make them non-overlaping. This - process may shrink the partitions more than required. - - \note - In read-mode partitions may not cross boundaries. This means, if the grid - size is (X, Y, Z), all partitions must fit into this grid. + \note In write mode views might be reduced to make them + non-overlaping, i.e. ghost-zones are eliminated. This may shrink + views in an unexpected way. \todo check whether layout is reasonable diff --git a/src/include/H5Block_attribs.f90 b/src/include/H5Block_attribs.f90 index 7afa123..844060f 100644 --- a/src/include/H5Block_attribs.f90 +++ b/src/include/H5Block_attribs.f90 @@ -7,7 +7,10 @@ ! License: see file COPYING in top level of source distribution. ! INTERFACE - + !> \ingroup h5block_f90_api + !! \addtogroup h5block_attrib_f + !! @{ + ! __ _ _ _ _ _ _ _ _ ! / _(_) ___| | __| | __ _| |_| |_ _ __(_) |__ _ _| |_ ___ ___ ! | |_| |/ _ \ |/ _` | / _` | __| __| '__| | '_ \| | | | __/ _ \/ __| @@ -22,20 +25,18 @@ ! |_| |___/ !> - !! \ingroup h5block_attrib_f !! See \ref H5BlockGetNumFieldAttribs !! \return number of attributes or error code - !< + INTEGER*8 FUNCTION h5bl_getnfieldattribs (filehandle, field_name) INTEGER*8, INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field END FUNCTION h5bl_getnfieldattribs !> - !! \ingroup h5block_attrib_f !! See \ref H5BlockGetFieldAttribInfo !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_getfieldattribinfo (filehandle, field_name, idx, attrib_name, attrib_nelems) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field @@ -52,10 +53,9 @@ ! |___/ !> - !! \ingroup h5block_attrib_f !! See \ref H5BlockWriteFieldAttribString !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_writefieldattrib_string (filehandle, field_name, attrib_name, attrib_value) INTEGER*8, INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field @@ -64,9 +64,8 @@ END FUNCTION h5bl_writefieldattrib_string !> - !! \ingroup h5block_attrib_f !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_readfieldattrib_string (filehandle, field_name, attrib_name, attrib_value) INTEGER*8, INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field @@ -81,11 +80,9 @@ ! |_/_/ \___/ |_| \___|\__,_|_| !> - !! \ingroup h5block_attrib_f - !! !! See \ref H5BlockWriteFieldAttribFloat64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_writefieldattrib_r8 (filehandle, field_name, attrib_name, attrib_value, attrib_nelems) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field @@ -95,10 +92,9 @@ END FUNCTION h5bl_writefieldattrib_r8 !> - !! \ingroup h5block_attrib_f !! See \ref H5BlockReadFieldAttribFloat64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_readfieldattrib_r8 ( filehandle, field_name, attrib_name, attrib_value ) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field @@ -107,10 +103,9 @@ END FUNCTION h5bl_readfieldattrib_r8 !> - !! \ingroup h5block_attrib_f !! See \ref H5BlockWriteFieldAttribFloat32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_writefieldattrib_r4 (filehandle, field_name, attrib_name, attrib_value, attrib_nelems) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field @@ -120,10 +115,9 @@ END FUNCTION h5bl_writefieldattrib_r4 !> - !! \ingroup h5block_attrib_f !! See \ref H5BlockReadFieldAttribFloat32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_readfieldattrib_r4 (filehandle, field_name, attrib_name, attrib_value) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field @@ -139,10 +133,9 @@ ! |___/ !> - !! \ingroup h5block_attrib_f !! See \ref H5BlockWriteFieldAttribInt64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_writefieldattrib_i8 (filehandle, field_name, attrib_name, attrib_value, attrib_nelems) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field @@ -152,10 +145,9 @@ END FUNCTION h5bl_writefieldattrib_i8 !!> - !! \ingroup h5block_attrib_f !! See \ref H5BlockReadFieldAttribInt64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_readfieldattrib_i8 (filehandle, field_name, attrib_name, attrib_value) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field @@ -164,10 +156,9 @@ END FUNCTION h5bl_readfieldattrib_i8 !> - !! \ingroup h5block_attrib_f !! See \ref H5BlockWriteFieldAttribInt32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_writefieldattrib_i4 (filehandle, field_name, attrib_name, attrib_value, attrib_nelems) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field @@ -177,10 +168,9 @@ END FUNCTION h5bl_writefieldattrib_i4 !> - !! \ingroup h5block_attrib_f !! See \ref H5BlockReadFieldAttribInt32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_readfieldattrib_i4 (filehandle, field_name, attrib_name, attrib_value) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: field_name !< name of field @@ -196,10 +186,9 @@ ! |_| |___/ !> - !! \ingroup h5block_attrib_f !! See \ref H5Block3dGetFieldSpacing !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_get_field_spacing (filehandle, name, x, y, z) INTEGER*8, INTENT(IN) :: filehandle CHARACTER(LEN=*), INTENT(IN) :: name @@ -209,10 +198,9 @@ END FUNCTION h5bl_3d_get_field_spacing !> - !! \ingroup h5block_attrib_f !! See \ref H5Block3dSetFieldSpacing !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_set_field_spacing (filehandle, name, x, y, z) INTEGER*8, INTENT(IN) :: filehandle CHARACTER(LEN=*), INTENT(IN) :: name @@ -229,10 +217,9 @@ ! |___/ !> - !! \ingroup h5block_attrib_f !! See \ref H5Block3dGetFieldOrigin !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_get_field_origin (filehandle, name, x, y, z) INTEGER*8, INTENT(IN) :: filehandle CHARACTER(LEN=*), INTENT(IN) :: name @@ -242,10 +229,9 @@ END FUNCTION h5bl_3d_get_field_origin !> - !! \ingroup h5block_attrib_f !! See \ref H5Block3dSetFieldOrigin !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_set_field_origin (filehandle, name, x, y, z) INTEGER*8, INTENT(IN) :: filehandle CHARACTER(LEN=*), INTENT(IN) :: name @@ -261,10 +247,9 @@ ! |_| |_|\___|_|\__,_| \___\___/ \___/|_| \__,_|___/ !> - !! \ingroup h5block_attrib_f !! See \ref H5Block3dSetFieldXCoords !! \return 0 on success -1 on error - !< + INTEGER*8 FUNCTION h5bl_set_fieldxcoords (filehandle, field_name, coords, n_coords) INTEGER*8, INTENT(IN) :: filehandle CHARACTER(LEN=*), INTENT(IN) :: field_name @@ -273,10 +258,9 @@ END FUNCTION h5bl_set_fieldxcoords !> - !! \ingroup h5block_attrib_f !! See \ref H5Block3dGetFieldXCoords !! \return 0 on success -1 on error - !< + INTEGER*8 FUNCTION h5bl_get_fieldxcoords (filehandle, field_name, coords, n_coords) INTEGER*8, INTENT(IN) :: filehandle CHARACTER(LEN=*), INTENT(IN) :: field_name @@ -285,10 +269,9 @@ END FUNCTION h5bl_get_fieldxcoords !> - !! \ingroup h5block_attrib_f !! See \ref H5Block3dSetFieldYCoords !! \return 0 on success -1 on error - !< + INTEGER*8 FUNCTION h5bl_set_fieldycoords (filehandle, field_name, coords, n_coords) INTEGER*8, INTENT(IN) :: filehandle CHARACTER(LEN=*), INTENT(IN) :: field_name @@ -297,10 +280,9 @@ END FUNCTION h5bl_set_fieldycoords !> - !! \ingroup h5block_attrib_f !! See \ref H5Block3dGetFieldYCoords !! \return 0 on success -1 on error - !< + INTEGER*8 FUNCTION h5bl_get_fieldycoords (filehandle, field_name, coords, n_coords) INTEGER*8, INTENT(IN) :: filehandle CHARACTER(LEN=*), INTENT(IN) :: field_name @@ -309,10 +291,9 @@ END FUNCTION h5bl_get_fieldycoords !> - !! \ingroup h5block_attrib_f !! See \ref H5Block3dSetFieldZCoords !! \return 0 on success -1 on error - !< + INTEGER*8 FUNCTION h5bl_set_fieldzcoords (filehandle, field_name, coords, n_coords) INTEGER*8, INTENT(IN) :: filehandle CHARACTER(LEN=*), INTENT(IN) :: field_name @@ -321,10 +302,9 @@ END FUNCTION h5bl_set_fieldzcoords !> - !! \ingroup h5block_attrib_f !! See \ref H5Block3dGetFieldZCoords !! \return 0 on success -1 on error - !< + INTEGER*8 FUNCTION h5bl_get_fieldzcoords (filehandle, field_name, coords, n_coords) INTEGER*8, INTENT(IN) :: filehandle CHARACTER(LEN=*), INTENT(IN) :: field_name diff --git a/src/include/H5Block_attribs.h b/src/include/H5Block_attribs.h index c49f9c9..e884038 100644 --- a/src/include/H5Block_attribs.h +++ b/src/include/H5Block_attribs.h @@ -162,14 +162,15 @@ H5BlockReadFieldAttribString ( } -/*! +/** \ingroup h5block_attrib \anchor H5BlockWriteFieldAttribFloat64 Write float64 \c values as attribute \c attrib_name of field \c field_name. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5BlockWriteFieldAttribFloat64 ( @@ -193,14 +194,15 @@ H5BlockWriteFieldAttribFloat64 ( nelems )); } -/*! +/** \ingroup h5block_attrib \anchor H5BlockReadFieldAttribFloat64 Read float64 values from attribute \c attrib_name of field \c field_name into a \c buffer. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5BlockReadFieldAttribFloat64 ( @@ -222,14 +224,15 @@ H5BlockReadFieldAttribFloat64 ( } -/*! +/** \ingroup h5block_attrib \anchor H5BlockWriteFieldAttribFloat32 Write float32 \c values as attribute \c attrib_name of field \c field_name. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5BlockWriteFieldAttribFloat32 ( @@ -253,14 +256,15 @@ H5BlockWriteFieldAttribFloat32 ( nelems )); } -/*! +/** \ingroup h5block_attrib \anchor H5BlockReadFieldAttribFloat32 Read float32 values from attribute \c attrib_name of field \c field_name into a \c buffer. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5BlockReadFieldAttribFloat32 ( @@ -281,14 +285,15 @@ H5BlockReadFieldAttribFloat32 ( buffer )); } -/*! +/** \ingroup h5block_attrib \anchor H5BlockWriteFieldAttribInt64 Write int64 \c values as attribute \c attrib_name of field \c field_name. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5BlockWriteFieldAttribInt64 ( @@ -311,14 +316,15 @@ H5BlockWriteFieldAttribInt64 ( nelems )); } -/*! +/** \ingroup h5block_attrib \anchor H5BlockReadFieldAttribInt64 Read int64 values from attribute \c attrib_name of field \c field_name into a \c buffer. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5BlockReadFieldAttribInt64 ( @@ -340,14 +346,15 @@ H5BlockReadFieldAttribInt64 ( } -/*! +/** \ingroup h5block_attrib \anchor H5BlockWriteFieldAttribInt32 Write int32 \c values as attribute \c attrib_name of field \c field_name. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5BlockWriteFieldAttribInt32 ( @@ -371,14 +378,15 @@ H5BlockWriteFieldAttribInt32 ( nelems )); } -/*! +/** \ingroup h5block_attrib \anchor H5BlockReadFieldAttribInt32 Read int32 values from attribute \c attrib_name of field \c field_name into a \c buffer. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5BlockReadFieldAttribInt32 ( @@ -398,13 +406,14 @@ H5BlockReadFieldAttribInt32 ( (void*)buffer )); } -/*! +/** \ingroup h5block_attrib \anchor H5Block3dGetFieldOrigin Get field origin. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dGetFieldOrigin ( @@ -433,13 +442,14 @@ H5Block3dGetFieldOrigin ( H5_API_RETURN (H5_SUCCESS); } -/*! +/** \ingroup h5block_attrib \anchor H5Block3dSetFieldOrigin Set field origin. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dSetFieldOrigin ( @@ -462,13 +472,14 @@ H5Block3dSetFieldOrigin ( 3)); } -/*! +/** \ingroup h5block_attrib \anchor H5Block3dGetFieldSpacing Get field spacing for field \c field_name in the current time step. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dGetFieldSpacing ( @@ -495,13 +506,14 @@ H5Block3dGetFieldSpacing ( H5_API_RETURN (H5_SUCCESS); } -/*! +/** \ingroup h5block_attrib \anchor H5Block3dSetFieldSpacing Set field spacing for field \c field_name in the current time step. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dSetFieldSpacing ( @@ -524,7 +536,7 @@ H5Block3dSetFieldSpacing ( 3)); } -/*! +/** \ingroup h5block_attrib \anchor H5Block3dSetFieldXCoords @@ -535,7 +547,8 @@ H5Block3dSetFieldSpacing ( By convention, the \c coords array should have the same length as the X dimension of the field, and a warning will be printed if not. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dSetFieldXCoords ( @@ -557,7 +570,7 @@ H5Block3dSetFieldXCoords ( } -/*! +/** \ingroup h5block_attrib \anchor H5Block3dGetFieldXCoords @@ -568,7 +581,8 @@ H5Block3dSetFieldXCoords ( By convention, the \c coords array should have the same length as the X dimension of the field, and a warning will be printed if they differ. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dGetFieldXCoords ( @@ -589,7 +603,7 @@ H5Block3dGetFieldXCoords ( coords, n_coords)); } -/*! +/** \ingroup h5block_attrib \anchor H5Block3dSetFieldYCoords @@ -600,7 +614,8 @@ H5Block3dGetFieldXCoords ( By convention, the \c coords array should have the same length as the Y dimension of the field, and a warning will be printed if not. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dSetFieldYCoords ( @@ -622,7 +637,7 @@ H5Block3dSetFieldYCoords ( } -/*! +/** \ingroup h5block_attrib \anchor H5Block3dGetFieldYCoords @@ -633,7 +648,8 @@ H5Block3dSetFieldYCoords ( By convention, the \c coords array should have the same length as the Y dimension of the field, and a warning will be printed if they differ. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dGetFieldYCoords ( @@ -654,7 +670,7 @@ H5Block3dGetFieldYCoords ( coords, n_coords)); } -/*! +/** \ingroup h5block_attrib \anchor H5Block3dSetFieldZCoords @@ -665,7 +681,8 @@ H5Block3dGetFieldYCoords ( By convention, the \c coords array should have the same length as the Z dimension of the field, and a warning will be printed if not. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dSetFieldZCoords ( @@ -687,7 +704,7 @@ H5Block3dSetFieldZCoords ( } -/*! +/** \ingroup h5block_attrib \anchor H5Block3dGetFieldZCoords @@ -698,7 +715,8 @@ H5Block3dSetFieldZCoords ( By convention, the \c coords array should have the same length as the Z dimension of the field, and a warning will be printed if they differ. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dGetFieldZCoords ( diff --git a/src/include/H5Block_io.f90 b/src/include/H5Block_io.f90 index 127a0fe..022e02d 100644 --- a/src/include/H5Block_io.f90 +++ b/src/include/H5Block_io.f90 @@ -7,14 +7,14 @@ ! License: see file COPYING in top level of source distribution. ! INTERFACE - !> \ingroup h5hut_f90_api - !! \addtogroup h5block_data_f + !> \ingroup h5block_f90_api + !! \addtogroup h5block_io_f !! @{ !> !! See \ref H5Block3dWriteScalarFieldFloat64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_write_scalar_field_r8 ( filehandle, name, buffer ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -24,7 +24,7 @@ !> !! See \ref H5Block3dReadScalarFieldFloat64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_read_scalar_field_r8 ( filehandle, name, buffer ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -34,7 +34,7 @@ !> !! See \ref H5Block3dWriteVector3dFieldFloat64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_write_vector3d_field_r8 ( filehandle, name, x, y, z ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -46,7 +46,7 @@ !> !! See \ref H5Block3dReadVector3dFieldFloat64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_read_vector3d_field_r8 ( filehandle, name, x, y, z ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -58,7 +58,7 @@ !> !! See \ref H5Block3dWriteScalarFieldFloat32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_write_scalar_field_r4 ( filehandle, name, buffer ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -68,7 +68,7 @@ !> !! See \ref H5Block3dReadScalarFieldFloat32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_read_scalar_field_r4 ( filehandle, name, buffer ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -78,7 +78,7 @@ !> !! See \ref H5Block3dWriteVector3dFieldFloat32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_write_vector3d_field_r4 ( filehandle, name, x, y, z ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -90,7 +90,7 @@ !> !! See \ref H5Block3dReadVector3dFieldFloat32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_read_vector3d_field_r4 ( filehandle, name, x, y, z ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -102,7 +102,7 @@ !> !! See \ref H5Block3dWriteScalarFieldInt64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_write_scalar_field_i8 ( filehandle, name, buffer ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -112,7 +112,7 @@ !> !! See \ref H5Block3dReadScalarFieldInt64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_read_scalar_field_i8 ( filehandle, name, buffer ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -122,7 +122,7 @@ !> !! See \ref H5Block3dWriteVector3dFieldInt64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_write_vector3d_field_i8 ( filehandle, name, x, y, z ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -134,7 +134,7 @@ !> !! See \ref H5Block3dReadVector3dFieldInt64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_read_vector3d_field_i8 ( filehandle, name, x, y, z ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -146,7 +146,7 @@ !> !! See \ref H5Block3dWriteScalarFieldInt32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_write_scalar_field_i4 ( filehandle, name, buffer ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -156,7 +156,7 @@ !> !! See \ref H5Block3dReadScalarFieldInt32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_read_scalar_field_i4 ( filehandle, name, buffer ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -166,7 +166,7 @@ !> !! See \ref H5Block3dWriteVector3dFieldInt32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_write_vector3d_field_i4 ( filehandle, name, x, y, z ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -178,7 +178,7 @@ !> !! See \ref H5Block3dReadVector3dFieldInt32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_read_vector3d_field_i4 ( filehandle, name, x, y, z ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned at file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset diff --git a/src/include/H5Block_io.h b/src/include/H5Block_io.h index 7e71d36..e8cf402 100644 --- a/src/include/H5Block_io.h +++ b/src/include/H5Block_io.h @@ -1,5 +1,5 @@ /* - Copyright (c) 2006-2015, The Regents of the University of California, + Copyright (c) 2006-2016, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy) and the Paul Scherrer Institut (Switzerland). All rights reserved. @@ -19,32 +19,35 @@ extern "C" { #endif -/*! +/** \ingroup h5block_io - \anchor H5Block3dWriteScalarFieldFloat64 - Write a 3-dimensional field \c name from the buffer starting at \c data - to the current time-step using the defined field layout. Values are - floating points (64-bit). + Attempts to write the 3-dimensional field \p name from the + buffer pointed to by \p buffer to the current step using the + previously defined field view. + + The data type is 64bit floating point (\c h5_float64_t). Ensure that + the number of items in the buffer matches the view. Use the FORTRAN + indexing scheme to store data in the buffer. You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dWriteScalarFieldFloat64 ( const h5_file_t f, ///< [in] file handle. const char* name, ///< [in] name of dataset to write. - const h5_float64_t* buffer ///< [in] pointer to write buffer. + const h5_float64_t* buffer ///< [in] pointer to buffer containing data to write. ) { - H5_API_ENTER (h5_err_t, "f=%p, name='%s', buffer=%p", (h5_file_p)f, name, buffer); H5_API_RETURN (h5b_write_scalar_data(f, name, (void*)buffer, H5T_NATIVE_DOUBLE )); } -/*! +/** \ingroup h5block_io \anchor H5Block3dReadScalarFieldFloat64 @@ -54,7 +57,8 @@ H5Block3dWriteScalarFieldFloat64 ( You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dReadScalarFieldFloat64 ( @@ -69,7 +73,7 @@ H5Block3dReadScalarFieldFloat64 ( H5_API_RETURN (h5b_read_scalar_data(f, name, (void*)buffer, H5T_NATIVE_DOUBLE)); } -/*! +/** \ingroup h5block_io \anchor H5Block3dWriteVector3dFieldFloat64 @@ -80,7 +84,8 @@ H5Block3dReadScalarFieldFloat64 ( You must use the Fortran indexing scheme to access items in \c x_buf. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dWriteVector3dFieldFloat64 ( @@ -98,7 +103,7 @@ H5Block3dWriteVector3dFieldFloat64 ( (void*)x_buf, (void*)y_buf, (void*)z_buf, H5T_NATIVE_DOUBLE)); } -/*! +/** \ingroup h5block_io \anchor H5Block3dReadVector3dFieldFloat64 @@ -109,7 +114,8 @@ H5Block3dWriteVector3dFieldFloat64 ( You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dReadVector3dFieldFloat64 ( @@ -128,7 +134,7 @@ H5Block3dReadVector3dFieldFloat64 ( } -/*! +/** \ingroup h5block_io \anchor H5Block3dWriteScalarFieldFloat32 @@ -138,7 +144,8 @@ H5Block3dReadVector3dFieldFloat64 ( You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dWriteScalarFieldFloat32 ( @@ -153,7 +160,7 @@ H5Block3dWriteScalarFieldFloat32 ( H5_API_RETURN (h5b_write_scalar_data(f, name, buffer, H5T_NATIVE_FLOAT )); } -/*! +/** \ingroup h5block_io \anchor H5Block3dReadScalarFieldFloat32 @@ -163,7 +170,8 @@ H5Block3dWriteScalarFieldFloat32 ( You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dReadScalarFieldFloat32 ( @@ -178,7 +186,7 @@ H5Block3dReadScalarFieldFloat32 ( H5_API_RETURN (h5b_read_scalar_data(f, name, buffer, H5T_NATIVE_FLOAT)); } -/*! +/** \ingroup h5block_io \anchor H5Block3dWriteVector3dFieldFloat32 @@ -189,7 +197,8 @@ H5Block3dReadScalarFieldFloat32 ( You must use the Fortran indexing scheme to access items in \c x_buf. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dWriteVector3dFieldFloat32 ( @@ -207,7 +216,7 @@ H5Block3dWriteVector3dFieldFloat32 ( x_buf, y_buf, z_buf, H5T_NATIVE_FLOAT)); } -/*! +/** \ingroup h5block_io \anchor H5Block3dReadVector3dFieldFloat32 @@ -218,7 +227,8 @@ H5Block3dWriteVector3dFieldFloat32 ( You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dReadVector3dFieldFloat32 ( @@ -237,7 +247,7 @@ H5Block3dReadVector3dFieldFloat32 ( } -/*! +/** \ingroup h5block_io \anchor H5Block3dWriteScalarFieldInt64 @@ -247,7 +257,8 @@ H5Block3dReadVector3dFieldFloat32 ( You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dWriteScalarFieldInt64 ( @@ -262,7 +273,7 @@ H5Block3dWriteScalarFieldInt64 ( H5_API_RETURN (h5b_write_scalar_data(f, name, buffer, H5T_NATIVE_INT64 )); } -/*! +/** \ingroup h5block_io \anchor H5Block3dReadScalarFieldInt64 @@ -272,7 +283,8 @@ H5Block3dWriteScalarFieldInt64 ( You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dReadScalarFieldInt64 ( @@ -288,7 +300,7 @@ H5Block3dReadScalarFieldInt64 ( } -/*! +/** \ingroup h5block_io \anchor H5Block3dWriteVector3dFieldInt64 @@ -299,7 +311,8 @@ H5Block3dReadScalarFieldInt64 ( You must use the Fortran indexing scheme to access items in \c x_buf. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dWriteVector3dFieldInt64 ( @@ -317,7 +330,7 @@ H5Block3dWriteVector3dFieldInt64 ( x_buf, y_buf, z_buf, H5T_NATIVE_INT64)); } -/*! +/** \ingroup h5block_io \anchor H5Block3dReadVector3dFieldInt64 @@ -328,7 +341,8 @@ H5Block3dWriteVector3dFieldInt64 ( You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dReadVector3dFieldInt64 ( @@ -347,7 +361,7 @@ H5Block3dReadVector3dFieldInt64 ( } -/*! +/** \ingroup h5block_io \anchor H5Block3dWriteScalarFieldInt32 @@ -357,7 +371,8 @@ H5Block3dReadVector3dFieldInt64 ( You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dWriteScalarFieldInt32 ( @@ -372,7 +387,7 @@ H5Block3dWriteScalarFieldInt32 ( H5_API_RETURN (h5b_write_scalar_data(f, name, buffer, H5T_NATIVE_INT32 )); } -/*! +/** \ingroup h5block_io \anchor H5Block3dReadScalarFieldInt32 @@ -382,7 +397,8 @@ H5Block3dWriteScalarFieldInt32 ( You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dReadScalarFieldInt32 ( @@ -398,7 +414,7 @@ H5Block3dReadScalarFieldInt32 ( } -/*! +/** \ingroup h5block_io \anchor H5Block3dWriteVector3dFieldInt32 @@ -409,7 +425,8 @@ H5Block3dReadScalarFieldInt32 ( You must use the Fortran indexing scheme to access items in \c x_buf. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dWriteVector3dFieldInt32 ( @@ -427,7 +444,7 @@ H5Block3dWriteVector3dFieldInt32 ( x_buf, y_buf, z_buf, H5T_NATIVE_INT32)); } -/*! +/** \ingroup h5block_io \anchor H5Block3dReadVector3dFieldInt32 @@ -438,7 +455,8 @@ H5Block3dWriteVector3dFieldInt32 ( You must use the Fortran indexing scheme to access items in \c data. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dReadVector3dFieldInt32 ( diff --git a/src/include/H5Block_model.f90 b/src/include/H5Block_model.f90 index e13f6b5..c9eabab 100644 --- a/src/include/H5Block_model.f90 +++ b/src/include/H5Block_model.f90 @@ -7,6 +7,10 @@ ! License: see file COPYING in top level of source distribution. ! INTERFACE + !> \ingroup h5block_f90_api + !! \addtogroup h5block_model_f + !! @{ + ! _ _ _ _ ! __| | __ _| |_ __ _ _ __ ___ ___ __| | ___| | ! / _` |/ _` | __/ _` | | '_ ` _ \ / _ \ / _` |/ _ \ | @@ -15,10 +19,9 @@ !> - !! \ingroup h5block_model_f - !! See \ref H5Block3dSetView + !! See \ref H5Block3dSetView() !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_setview ( filehandle, i_start, i_end, j_start, j_end, k_start, k_end ) INTEGER*8, INTENT(IN) :: filehandle INTEGER*8, INTENT(IN) :: i_start @@ -30,10 +33,9 @@ END FUNCTION h5bl_3d_setview !> - !! \ingroup h5block_model_f - !! See \ref H5Block3dGetView + !! See \ref H5Block3dGetView() !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_getview ( filehandle, i_start, i_end, j_start, j_end, k_start, k_end ) INTEGER*8, INTENT(IN) :: filehandle INTEGER*8, INTENT(OUT) :: i_start @@ -45,10 +47,9 @@ END FUNCTION h5bl_3d_getview !> - !! \ingroup h5block_model_f - !! See \ref H5Block3dGetReducedView + !! See \ref H5Block3dGetReducedView() !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_getreducedview ( filehandle, i_start, i_end, j_start, j_end, k_start, k_end ) INTEGER*8, INTENT(IN) :: filehandle INTEGER*8, INTENT(OUT) :: i_start @@ -60,19 +61,17 @@ END FUNCTION h5bl_3d_getreducedview !> - !! \ingroup h5block_model_f - !! See \ref H5Block3dHasView + !! See \ref H5Block3dHasView() !! \return rank of processor error code - !< + INTEGER*8 FUNCTION h5bl_3d_hasview ( filehandle ) INTEGER*8, INTENT(IN) :: filehandle END FUNCTION h5bl_3d_hasview !> - !! \ingroup h5block_model_f - !! See \ref H5Block3dSetChunk + !! See \ref H5Block3dSetChunkSize() !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_3d_setchunk ( filehandle, i, j, k ) INTEGER*8, INTENT(IN) :: filehandle INTEGER*8, INTENT(IN) :: i @@ -81,19 +80,17 @@ END FUNCTION h5bl_3d_setchunk !> - !! \ingroup h5block_model_f !! See \ref H5BlockGetNumFields !! \return number of fields or error code - !< + INTEGER*8 FUNCTION h5bl_getnumfields ( filehandle ) INTEGER*8, INTENT(IN) :: filehandle END FUNCTION h5bl_getnumfields !> - !! \ingroup h5block_model_f !! See \ref H5BlockGetFieldInfo !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5bl_getfieldinfo ( filehandle, idx, field_name, grid_rank, grid_dims, field_dims ) INTEGER*8, INTENT(IN) :: filehandle INTEGER*8, INTENT(IN) :: idx @@ -103,4 +100,6 @@ INTEGER*8, INTENT(OUT) :: field_dims END FUNCTION h5bl_getfieldinfo + !> @} + END INTERFACE diff --git a/src/include/H5Block_model.h b/src/include/H5Block_model.h index 9e768df..552cc7a 100644 --- a/src/include/H5Block_model.h +++ b/src/include/H5Block_model.h @@ -21,14 +21,15 @@ extern "C" { /********************** defining the layout **********************************/ -/*! +/** \ingroup h5block_model \anchor H5BlockHasFieldData Checks whether the current time-step has field data or not. - \return \c H5_SUCCESS if field data is available otherwise \c - H5_NOK. + \return \c H5_OK if field data is available + \return \c H5_NOK if no field data is available + \return \c H5_FAILURE on error */ static inline h5_err_t H5BlockHasFieldData ( @@ -40,15 +41,16 @@ H5BlockHasFieldData ( H5_API_RETURN (h5b_has_field_data (f)); } -/*! +/** \ingroup h5block_model \anchor H5Block3dHasView Tests whether a view has been set, either directly with \ref H5Block3dSetView or indirectly with \ref H5Block3dSetGrid. - \return \c 1 on true. - \return \c 0 on false. + \return \c H5_OK if field data is available + \return \c H5_NOK if no field data is available + \return \c H5_FAILURE on error */ static inline h5_int64_t H5Block3dHasView ( @@ -60,7 +62,7 @@ H5Block3dHasView ( H5_API_RETURN (h5b_3d_has_view (f)); } -/*! +/** \ingroup h5block_model \anchor H5Block3dSetView @@ -72,7 +74,8 @@ H5Block3dHasView ( use the same field dimensions, set the layout only once before the first timestep. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dSetView ( @@ -99,12 +102,13 @@ H5Block3dSetView ( k_start, k_end)); } -/*! +/** \ingroup h5block_model \anchor H5Block3dGetView Return the view of this processor. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dGetView ( @@ -128,13 +132,14 @@ H5Block3dGetView ( H5_API_RETURN (h5b_3d_get_view (f, i_start, i_end, j_start, j_end, k_start, k_end)); } -/*! +/** \ingroup h5block_model \anchor H5Block3dGetReducedView Return the reduced (ghost-zone free) view of this processor. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dGetReducedView ( @@ -158,14 +163,15 @@ H5Block3dGetReducedView ( H5_API_RETURN (h5b_3d_get_reduced_view(f, i_start, i_end, j_start, j_end, k_start, k_end)); } -/*! +/** \ingroup h5block_model \anchor H5Block3dSetChunkSize Define the chunk dimensions and enable chunking in the underlying HDF5 dataset. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dSetChunkSize ( @@ -183,13 +189,14 @@ H5Block3dSetChunkSize ( H5_API_RETURN (h5b_3d_set_chunk(f, i, j, k)); } -/*! +/** \ingroup h5block_model \anchor H5Block3dGetChunkSize Lookup the chunk dimensions of the underlying HDF5 dataset. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dGetChunkSize ( @@ -206,7 +213,7 @@ H5Block3dGetChunkSize ( } #ifdef PARALLEL_IO -/*! +/** \ingroup h5block_model \anchor H5Block3dSetGrid @@ -219,7 +226,8 @@ H5Block3dGetChunkSize ( The product of the dimensions must equal the size of the MPI communicator. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dSetGrid ( @@ -237,14 +245,15 @@ H5Block3dSetGrid ( H5_API_RETURN (h5b_3d_set_grid(f, i, j, k)); } -/*! +/** \ingroup h5block_model \anchor H5Block3dGetGridCoords Look up the index (\c i, \c j, \c k) in the grid belonging to MPI processor \c proc. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dGetGridCoords ( @@ -260,7 +269,7 @@ H5Block3dGetGridCoords ( H5_API_RETURN (h5b_3d_get_grid_coords(f, proc, i, j, k)); } -/*! +/** \ingroup h5block_model \anchor H5Block3dSetDims @@ -270,7 +279,8 @@ H5Block3dGetGridCoords ( A grid must be already set with \ref H5Block3dSetGrid, and all processors must specify the same dimensions. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dSetDims ( @@ -289,7 +299,7 @@ H5Block3dSetDims ( } #endif -/*! +/** \ingroup h5block_model \anchor H5Block3dSetHalo @@ -300,7 +310,8 @@ H5Block3dSetDims ( A grid with dimensions must already be set with \ref H5Block3dSetGrid and \ref H5Block3dSetDims, and all processors must specify the same halo radii. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5Block3dSetHalo ( @@ -318,7 +329,7 @@ H5Block3dSetHalo ( H5_API_RETURN (h5b_3d_set_halo(f, i, j, k)); } -/*! +/** \ingroup h5block_model \anchor H5BlockGetNumFields @@ -338,7 +349,7 @@ H5BlockGetNumFields ( } -/*! +/** \ingroup h5block_model \anchor H5BlockGetFieldInfo @@ -353,7 +364,8 @@ H5BlockGetNumFields ( minus one. The number of fields bound to the current time-step can be queried by calling the function \ref H5BlockGetNumFields. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5BlockGetFieldInfo ( @@ -386,14 +398,16 @@ H5BlockGetFieldInfo ( type)); } -/*! +/** \ingroup h5block_model \anchor H5BlockGetFieldInfoByName Get the rank and dimensions of the field specified by its name. - See \ref H5BlockGetFieldInfo. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error + + \see H5BlockGetFieldInfo. */ static inline h5_err_t H5BlockGetFieldInfoByName ( diff --git a/src/include/H5Fed_model.h b/src/include/H5Fed_model.h index d738bf0..2986f5a 100644 --- a/src/include/H5Fed_model.h +++ b/src/include/H5Fed_model.h @@ -19,17 +19,15 @@ extern "C" { #endif -/*! - Get number of meshes of given type. +/** + Get number of meshes of tetrahedral meshes in file. - \param[in] f File handle - \param[in] type_id Type of mesh we want the number of. - - \return Number of meshes of type \c type_id or error code. + \return number of tetrahedral meshes + \return \c H5_FAILURE */ static inline h5_ssize_t H5FedGetNumTetrahedralMeshes ( - const h5_file_t f + const h5_file_t f ///< file object ) { H5_API_ENTER (h5_err_t, "f=%p", @@ -47,131 +45,113 @@ H5FedGetNumTriangleMeshes ( H5_API_RETURN (h5t_get_num_trimeshes (f)); } -/*! +/** Get the number of hierarchical mesh levels. - \param[in] f File handle - \return Number of hierarchical mesh levels or error code. */ static inline h5_ssize_t H5FedGetNumLevels ( - h5t_mesh_t* const m + h5t_mesh_t* const m ///< [in] mesh object ) { H5_API_ENTER (h5_ssize_t, "m=%p", m); H5_API_RETURN (h5t_get_num_leaf_levels (m)); } -/*! +/** Get current mesh levels. - \param[in] f File handle - \return ID of current mesh levels or error code. */ static inline h5_lvl_idx_t H5FedGetLevel ( - h5t_mesh_t* const m + h5t_mesh_t* const m ///< [in] mesh object ) { H5_API_ENTER (h5_lvl_idx_t, "m=%p", m); H5_API_RETURN (h5t_get_level (m)); } -/*! +/** Returns the number of vertices used for defining the (sub-)mesh at current level on this compute node. - \param[in] f file handle - \return Number of vertices or error code. */ static inline h5_ssize_t H5FedGetNumVertices ( - h5t_mesh_t* const m /*!< file handle */ + h5t_mesh_t* const m ///< [in] mesh object ) { H5_API_ENTER (h5_ssize_t, "m=%p", m); H5_API_RETURN (h5t_get_num_vertices (m, -1)); } -/*! +/** Returns the number of vertices used for defining the (sub-)mesh at current level on compute node \c cnode. - \param[in] f file handle - \param[in] cnode compute node - \return Number of vertices or error code. */ static inline h5_ssize_t H5FedGetNumVerticesCnode ( - h5t_mesh_t* const m, - const int cnode + h5t_mesh_t* const m ///< [in] mesh object + const int cnode ///< [in] compute node to query ) { H5_API_ENTER (h5_ssize_t, "m=%p, cnode=%d", m, cnode); H5_API_RETURN (h5t_get_num_vertices (m, cnode)); } -/*! +/** Returns the number of vertices used for defining the (sub-)mesh at current level overl all compute nodes. - \param[in] f file handle - \return Total number of vertices or error code. */ static inline h5_ssize_t H5FedGetNumVerticesTotal ( - h5t_mesh_t* const m + h5t_mesh_t* const m ///< [in] mesh object ) { H5_API_ENTER (h5_ssize_t, "m=%p", m); H5_API_RETURN (h5t_get_num_vertices (m, -1)); } -/*! +/** Returns the number of elements present in the (sub-)mesh at current level on this compute node. - \param[in] f file handle - \return Number of elements or error code. */ static inline h5_ssize_t H5FedGetNumElements ( - h5t_mesh_t* const m + h5t_mesh_t* const m ///< [in] mesh object ) { H5_API_ENTER (h5_ssize_t, "m=%p", m); H5_API_RETURN (h5t_get_num_leaf_elems (m, -1)); } -/*! +/** Returns the number of elements present in the (sub-)mesh at current level on compute node \c cnode. - \param[in] f file handle - \param[in] cnode Compute node - \return Number of elements or error code. */ static inline h5_ssize_t H5FedGetNumElementsCnode ( - h5t_mesh_t* const m, - const int cnode + h5t_mesh_t* const m ///< [in] mesh object + const int cnode ///< [in] compute node to query ) { H5_API_ENTER (h5_ssize_t, "m=%p, cnode=%d", m, cnode); H5_API_RETURN (h5t_get_num_leaf_elems (m, cnode)); } -/*! +/** Returns the number of elements present in the mesh at current level over all compute nodes. - \param[in] f File handle. - \return Number of elements or error code. */ static inline h5_ssize_t H5FedGetNumElementsTotal ( - h5t_mesh_t* const m + h5t_mesh_t* const m ///< [in] mesh object ) { H5_API_ENTER (h5_ssize_t, "m=%p", m); H5_API_RETURN (h5t_get_num_leaf_elems (m, -1)); diff --git a/src/include/H5Fed_retrieve.h b/src/include/H5Fed_retrieve.h index 2f20628..c0f4bde 100644 --- a/src/include/H5Fed_retrieve.h +++ b/src/include/H5Fed_retrieve.h @@ -21,8 +21,7 @@ extern "C" { #endif - -/*! +/** Begin traverse over all entities on this compute node. Initialize internal data structures. @@ -30,16 +29,12 @@ extern "C" { Entities might be on processor boundaries! Therefore the same entity might be processed on several compute nodes. - \param[in] f file handle - \param[in] codim co-dimension of entity to traverse - \return H5_SUCCESS or error code */ - static inline h5t_iterator_p H5FedBeginTraverseEntities ( - h5t_mesh_t* const m, - const int codim + h5t_mesh_t* const m, ///< mesh object + const int codim ///< co-dimension of entity to traverse ) { H5_API_ENTER (h5t_iterator_p, "m=%p, codim=%d", m, codim); h5t_iterator_p iter; @@ -60,54 +55,45 @@ H5FedBeginTraverseBoundaryFaces ( H5_API_RETURN (iter); } -/*! +/** Get next local entity ID. - \param[in/out] iter iterator - \return Local entity ID \return -1, if done \return error code on error */ static inline h5_loc_id_t H5FedTraverseEntities ( - h5t_iterator_t* iter + h5t_iterator_t* iter ///< [in,out] entity iterator ) { H5_API_ENTER (h5_loc_id_t, "iter=%p", iter); H5_API_RETURN (h5t_iterate_entities (iter)); } -/*! +/** End of traversing. Release internal data structures. - \param[in/out] iter iterator - \return H5_SUCCESS or error code - */ static inline h5_err_t H5FedEndTraverseEntities ( - h5t_iterator_t* iter + h5t_iterator_t* iter ///< [in,out] entity iterator ) { H5_API_ENTER (h5_err_t, "iter=%p", iter); H5_API_RETURN (h5t_release_entity_iterator (iter)); } -/*! +/** Get coordinates of vertex given by local index - \param[in] f file handle - \param[in] vertex_idx local index of vertex - \param[out] P 3-dimensional coordinates - \return H5_SUCCESS or error code */ static inline h5_err_t H5FedGetVertexCoordsByIndex ( - h5t_mesh_t* const m, - h5_loc_idx_t vertex_index, - h5_float64_t P[3] + h5t_mesh_t* const m, ///< [in] mesh object + h5_loc_idx_t vertex_index, ///< [in] local index of vertex + h5_float64_t P[3] ///< [out] vertex coordinates ) { H5_API_ENTER (h5_err_t, "m=%p, vertex_index=%lld, P=%p", diff --git a/src/include/H5Fed_store.h b/src/include/H5Fed_store.h index 7b962b7..a7cc628 100644 --- a/src/include/H5Fed_store.h +++ b/src/include/H5Fed_store.h @@ -75,9 +75,6 @@ H5FedAddChunkedTriangleMesh ( real number of elements to add the level. If you want to refine \c n tetrahedra \c n*8 elements must be added. - \param[in] f File handle. - \param[in] num_elems_to_refine Number of elements which will be refined. - \return ID of new level. \note @@ -90,8 +87,8 @@ H5FedAddChunkedTriangleMesh ( */ static inline h5_err_t H5FedBeginStoreVertices ( - h5t_mesh_t* const m, - const h5_size_t num + h5t_mesh_t* const m, ///< [in] mesh object + const h5_size_t num ///< [in] store this number of vertices ) { H5_API_ENTER (h5_err_t, "m=%p, num=%llu", @@ -176,9 +173,9 @@ H5FedStoreElement ( static inline h5_loc_idx_t H5FedStoreWeightedElement ( - h5t_mesh_t* const m, /*!< file handle */ - const h5_loc_idx_t local_vids[], /*!< tuple with vertex id's */ - const h5_weight_t weights[] // tuple with weights + h5t_mesh_t* const m, ///< [in] mesh object + const h5_loc_idx_t local_vids[],///< tuple with vertex id's + const h5_weight_t weights[] ///< tuple with weights ) { H5_API_ENTER (h5_loc_idx_t, "m=%p, local_vids=%p", m, local_vids); if (h5t_get_level (m) != 0) { diff --git a/src/include/H5Fed_tags.h b/src/include/H5Fed_tags.h index 4f39884..e64a33e 100644 --- a/src/include/H5Fed_tags.h +++ b/src/include/H5Fed_tags.h @@ -130,39 +130,31 @@ H5FedCloseMTagset ( H5_API_RETURN (h5t_close_mtagset(tagset)); } -/*! +/** Remove tagset from mesh - \param[in] tagset tagset - \param[in] name name of tagset to remove - \return H5_SUCCESS or error code */ static inline h5_err_t H5FedRemoveMTagset ( - h5t_mesh_t* m, - const char name[] + h5t_mesh_t* m, ///< mesh object + const char name[] ///< [in] name of tagset to remove ) { H5_API_ENTER (h5_err_t, "m=%p, name='%s'", m, name); H5_API_RETURN (h5t_remove_mtagset (m, name)); } -/*! +/** Set tag for entity in current mesh. - \param[in] tagset ptr tagset - \param[in] entity_id id of entity - \param[in] size size of value - \param[in] val tag value - \return H5_SUCCESS or error code */ static inline h5_err_t H5FedSetTag ( - h5t_tagset_t* const tagset, - h5_loc_id_t entity_id, - const h5_size_t size, - void* val + h5t_tagset_t* const tagset, ///< [in,out] tagset object + h5_loc_id_t entity_id, ///< [in] entity the tag is assigned to + const h5_size_t size, ///< [in] byte-size of value + void* val ///< [in] value of tag ) { H5_API_ENTER (h5_err_t, "tagset=%p, entity_id=%lld, size=%lld, val=%p", diff --git a/src/include/H5Part_io.f90 b/src/include/H5Part_io.f90 index b9e03af..4e69adc 100644 --- a/src/include/H5Part_io.f90 +++ b/src/include/H5Part_io.f90 @@ -7,10 +7,14 @@ ! License: see file COPYING in top level of source distribution. ! INTERFACE + !> \ingroup h5part_f90_api + !! \addtogroup h5part_io_f + !! @{ + !> - !! \ingroup h5part_data_f !! See \ref H5PartWriteDataFloat64 !! \return 0 on success or error code + INTEGER*8 FUNCTION h5pt_writedata_r8 ( filehandle, name, data ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -18,9 +22,9 @@ END FUNCTION h5pt_writedata_r8 !> - !! \ingroup h5part_data_f !! See \ref H5PartWriteDataFloat32 !! \return 0 on success or error code + INTEGER*8 FUNCTION h5pt_writedata_r4 ( filehandle, name, data ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -28,9 +32,9 @@ END FUNCTION h5pt_writedata_r4 !> - !! \ingroup h5part_data_f !! See \ref H5PartWriteDataInt64 !! \return 0 on success or error code + INTEGER*8 FUNCTION h5pt_writedata_i8 ( filehandle, name, data ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -38,9 +42,9 @@ END FUNCTION h5pt_writedata_i8 !> - !! \ingroup h5part_data_f !! See \ref H5PartWriteDataInt32 !! \return 0 on success or error code + INTEGER*8 FUNCTION h5pt_writedata_i4 ( filehandle, name, data ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -49,9 +53,9 @@ !> - !! \ingroup h5part_data_f !! See \ref H5PartReadDataFloat64 !! \return 0 on success or error code + INTEGER*8 FUNCTION h5pt_readdata_r8 (filehandle,name,data) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -59,9 +63,9 @@ END FUNCTION h5pt_readdata_r8 !> - !! \ingroup h5part_data_f !! See \ref H5PartReadDataFloat32 !! \return 0 on success or error code + INTEGER*8 FUNCTION h5pt_readdata_r4 (filehandle,name,data) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -69,9 +73,9 @@ END FUNCTION h5pt_readdata_r4 !> - !! \ingroup h5part_data_f !! See \ref H5PartReadDataInt64 !! \return 0 on success or error code + INTEGER*8 FUNCTION h5pt_readdata_i8 (filehandle,name,data) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset @@ -79,13 +83,15 @@ END FUNCTION h5pt_readdata_i8 !> - !! \ingroup h5part_data_f !! See \ref H5PartReadDataInt32 !! \return 0 on success or error code + INTEGER*8 FUNCTION h5pt_readdata_i4 (filehandle,name,data) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open CHARACTER(LEN=*), INTENT(IN) :: name !< the name of the dataset INTEGER, INTENT(OUT) :: data(*) !< array to read int32 data into END FUNCTION h5pt_readdata_i4 + !> @} + END INTERFACE diff --git a/src/include/H5Part_io.h b/src/include/H5Part_io.h index 8c26c44..332416c 100644 --- a/src/include/H5Part_io.h +++ b/src/include/H5Part_io.h @@ -19,8 +19,8 @@ extern "C" { #endif -/*! - \ingroup h5part_data +/** + \ingroup h5part_io Write array of 64 bit floating point data to file. @@ -43,7 +43,8 @@ extern "C" { The data is committed to disk before the routine returns. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartWriteDataFloat64 ( @@ -57,14 +58,15 @@ H5PartWriteDataFloat64 ( H5_API_RETURN (h5u_write_data (f, name, (void*)data, H5T_NATIVE_DOUBLE)); } -/*! - \ingroup h5part_data +/** + \ingroup h5part_io Write array of 32 bit floating point data to file. - See \c H5PartWriteDataFloat64() for more details. + See \ref H5PartWriteDataFloat64() for more details. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartWriteDataFloat32 ( @@ -78,14 +80,15 @@ H5PartWriteDataFloat32 ( H5_API_RETURN (h5u_write_data(f, name, (void*)data, H5T_NATIVE_FLOAT)); } -/*! - \ingroup h5part_data +/** + \ingroup h5part_io Write array of 64 bit integer data to file. - See \c H5PartWriteDataFloat64() for more details. + See \ref H5PartWriteDataFloat64() for more details. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartWriteDataInt64 ( @@ -99,14 +102,15 @@ H5PartWriteDataInt64 ( H5_API_RETURN (h5u_write_data (f, name, (void*)data, H5T_NATIVE_INT64)); } -/*! - \ingroup h5part_data +/** + \ingroup h5part_io Write array of 32 bit integer data to file. - See \c H5PartWriteDataFloat64() for more details. + See \ref H5PartWriteDataFloat64() for more details. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartWriteDataInt32 ( @@ -120,14 +124,15 @@ H5PartWriteDataInt32 ( H5_API_RETURN (h5u_write_data (f, name, (void*)data, H5T_NATIVE_INT32)); } -/*! - \ingroup h5part_data +/** + \ingroup h5part_io Read array of 64 bit floating point data from file. - See \c H5PartWriteDataFloat64() for more details. + See \ref H5PartWriteDataFloat64() for more details. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartReadDataFloat64 ( @@ -141,14 +146,15 @@ H5PartReadDataFloat64 ( H5_API_RETURN (h5u_read_data (f, name, data, H5T_NATIVE_DOUBLE)); } -/*! - \ingroup h5part_data +/** + \ingroup h5part_io Read array of 32 bit floating point data from file. - See \c H5PartWriteDataFloat64() for more details. + See \ref H5PartWriteDataFloat64() for more details. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartReadDataFloat32 ( @@ -162,14 +168,15 @@ H5PartReadDataFloat32 ( H5_API_RETURN (h5u_read_data (f, name, data, H5T_NATIVE_FLOAT)); } -/*! - \ingroup h5part_data +/** + \ingroup h5part_io Read array of 64 bit integer data from file. - See \c H5PartWriteDataFloat64() for more details. + See \ref H5PartWriteDataFloat64() for more details. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartReadDataInt64 ( @@ -183,14 +190,15 @@ H5PartReadDataInt64 ( H5_API_RETURN (h5u_read_data (f, name, data, H5T_NATIVE_INT64)); } -/*! - \ingroup h5part_data +/** + \ingroup h5part_io Read array of 32 bit integer data from file. - See \c H5PartWriteDataFloat64() for more details. + See \ref H5PartWriteDataFloat64() for more details. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartReadDataInt32 ( diff --git a/src/include/H5Part_model.f90 b/src/include/H5Part_model.f90 index bdab318..92d3287 100644 --- a/src/include/H5Part_model.f90 +++ b/src/include/H5Part_model.f90 @@ -8,22 +8,23 @@ ! INTERFACE !> - !! \ingroup h5part_model_f - !! + !! \ingroup h5part_f90_api + !! \addtogroup h5part_model_f + !! @{ + + !> !! See \ref H5PartSetNumParticles !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5pt_setnpoints ( filehandle, npoints ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open INTEGER*8, INTENT(IN) :: npoints !< the number of particles on *this* processor END FUNCTION h5pt_setnpoints !> - !! \ingroup h5part_model_f - !! !! See \ref H5PartSetNumParticlesStrided !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5pt_setnpoints_strided ( filehandle, npoints, stride ) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open INTEGER*8, INTENT(IN) :: npoints !< the number of particles on *this* processor @@ -32,11 +33,9 @@ !> - !! \ingroup h5part_model_f - !! !! See \ref H5PartSetView !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5pt_setview (filehandle,start,end) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open INTEGER*8, INTENT(IN) :: start !< offset of the first particle in the view @@ -44,11 +43,9 @@ END FUNCTION h5pt_setview !> - !! \ingroup h5part_model_f - !! !! See \ref H5PartSetViewIndices !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5pt_setview_indices (filehandle,indices,nelem) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open INTEGER*8, INTENT(IN) :: indices(*) !< list of indicies to select in this view @@ -56,41 +53,33 @@ END FUNCTION h5pt_setview_indices !> - !! \ingroup h5part_model_f - !! !! See \ref H5PartSetCanonicalView !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5pt_setcanonicalview (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open END FUNCTION h5pt_setcanonicalview !> - !! \ingroup h5part_model_f - !! !! See \ref H5PartResetView !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5pt_resetview (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open END FUNCTION h5pt_resetview !> - !! \ingroup h5part_model_f - !! !! See \ref H5PartResetView !! \return 1 if true, 0 if false, or error code - !< + INTEGER*8 FUNCTION h5pt_hasview (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open END FUNCTION h5pt_hasview !> - !! \ingroup h5part_model_f - !! !! See \ref H5PartGetView !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5pt_getview (filehandle,start,end) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open INTEGER*8, INTENT(OUT) :: start !< buffer to store the offset of the first particle in the view @@ -98,21 +87,17 @@ END FUNCTION h5pt_getview !> - !! \ingroup h5part_model_f - !! !! See \ref H5PartGetNumDatasets !! \return the number of datasets or error code - !< + INTEGER*8 FUNCTION h5pt_getndatasets (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open END FUNCTION h5pt_getndatasets !> - !! \ingroup h5part_model_f - !! !! See \ref H5PartGetDatasetName !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5pt_getdatasetname (filehandle,index,name) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open INTEGER*8, INTENT(IN) :: index !< index of dataset to query (starting from 0) @@ -120,11 +105,9 @@ END FUNCTION h5pt_getdatasetname !> - !! \ingroup h5part_model_f - !! !! See \ref H5PartGetDatasetInfo !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5pt_getdatasetinfo (filehandle, idx, name, type, num_elems) INTEGER*8,INTENT(IN) :: filehandle !< file handle INTEGER*8,INTENT(IN) :: idx !< index of dataset being queried @@ -134,13 +117,13 @@ END FUNCTION h5pt_getdatasetinfo !> - !! \ingroup h5part_model_f - !! !! See \ref H5PartSetChunkSize !! \return 0 on success or -2 on error - !< + INTEGER*8 FUNCTION h5pt_getnpoints (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open END FUNCTION h5pt_getnpoints + !> @} + END INTERFACE diff --git a/src/include/H5Part_model.h b/src/include/H5Part_model.h index d623098..57ddc11 100644 --- a/src/include/H5Part_model.h +++ b/src/include/H5Part_model.h @@ -19,10 +19,10 @@ extern "C" { #endif -/*! +/** \ingroup h5part_model - Set the number of particles for the current time-step. + Set the number of points/particles for the current time-step. After you call this subroutine, all subsequent operations will assume this number of particles will be written. @@ -44,7 +44,8 @@ extern "C" { are arranged \f$ x_1,y_1,x_2,y_2\f$... than you need to setup striding (in this case with value 2) using \ref H5PartSetNumParticlesStrided. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartSetNumPoints ( @@ -58,6 +59,11 @@ H5PartSetNumPoints ( H5_API_RETURN (h5u_set_num_points (f, npoints, stride)); } +/** + \ingroup h5part_model + + \see H5PartSetNumPoints() +*/ static inline h5_err_t H5PartSetNumParticles ( const h5_file_t f, ///< [in] file handle. @@ -70,7 +76,7 @@ H5PartSetNumParticles ( H5_API_RETURN (h5u_set_num_points (f, nparticles, stride)); } -/*! +/** \ingroup h5part_model Set the number of particles for the current time-step. @@ -95,7 +101,8 @@ H5PartSetNumParticles ( such as \c x[] and \c y[], use \ref H5PartSetNumParticles(). - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartSetNumParticlesStrided ( @@ -111,7 +118,7 @@ H5PartSetNumParticlesStrided ( H5_API_RETURN (h5u_set_num_points (f, npoints, stride)); } -/*! +/** \ingroup h5part_model Define the chunk \c size and enables chunking in the underlying @@ -122,11 +129,12 @@ H5PartSetNumParticlesStrided ( On parallel filesystems that are sensitive to write alignment (e.g. lustre) it is recommended to set a reasonable chunk size when using the MPI-POSIX - or MPI-IO independent VFDs (see \ref H5OpenFile). + or MPI-IO independent VFDs (see \ref H5OpenFile()). For more details about chunking, please read the HDF5 documentation. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartSetChunkSize ( @@ -139,12 +147,13 @@ H5PartSetChunkSize ( H5_API_RETURN (h5u_set_chunk (f, size)); } -/*! +/** \ingroup h5part_model Get the number of datasets that are stored at the current time-step. - \return number of datasets in current timestep or \c H5_FAILURE. + \return number of datasets in current timestep + \return \c H5_FAILURE on error */ static inline h5_ssize_t H5PartGetNumDatasets ( @@ -156,7 +165,7 @@ H5PartGetNumDatasets ( H5_API_RETURN (h5u_get_num_datasets(f)); } -/*! +/** \ingroup h5part_model This reads the name of a dataset specified by it's index in the current @@ -164,7 +173,8 @@ H5PartGetNumDatasets ( If the number of datasets is \c n, the range of \c _index is \c 0 to \c n-1. - \result \c H5_SUCCESS + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartGetDatasetName ( @@ -183,7 +193,7 @@ H5PartGetDatasetName ( H5_API_RETURN (h5u_get_dataset_info(f, idx, name, len, NULL, NULL)); } -/*! +/** \ingroup h5part_model Gets the name, type and number of elements of a dataset based on its @@ -196,7 +206,8 @@ H5PartGetDatasetName ( - \c H5_INT64_T (for \c h5_int64_t) - \c H5_INT32_T (for \c h5_int32_t) - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartGetDatasetInfo ( @@ -220,7 +231,7 @@ H5PartGetDatasetInfo ( f, idx, name, len_name, type, nelems)); } -/*! +/** \ingroup h5part_model This function returns the number of particles in this processor's view, @@ -251,6 +262,11 @@ H5PartGetNumPoints ( H5_API_RETURN (h5u_get_num_points (f)); } +/** + \ingroup h5part_model + + \see H5PartGetNumPoints() +*/ static inline h5_ssize_t H5PartGetNumParticles ( const h5_file_t f ///< [in] file handle. @@ -261,12 +277,13 @@ H5PartGetNumParticles ( H5_API_RETURN (h5u_get_num_points (f)); } -/*! +/** \ingroup h5part_model Reset the view. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartResetView ( @@ -278,15 +295,15 @@ H5PartResetView ( H5_API_RETURN (h5u_reset_view (f)); } -/*! +/** \ingroup h5part_model Check whether a view has been set, either automatically with \ref H5PartSetNumParticles() or manually with \ref H5PartSetView or \ref H5PartSetViewIndices. - \return \c 1 if view has been set. - \return \c 0 otherwise. + \return \c H5_OK if view has been set. + \return \c H5_NOK if no view has been set. \return \c H5_FAILURE on error. */ static inline h5_err_t @@ -299,7 +316,7 @@ H5PartHasView ( H5_API_RETURN (h5u_has_view (f)); } -/*! +/** \ingroup h5part_model For parallel I/O or for subsetting operations on the datafile, @@ -318,7 +335,8 @@ H5PartHasView ( The range is \e inclusive: the end value is the last index of the data. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartSetView ( @@ -332,7 +350,7 @@ H5PartSetView ( H5_API_RETURN (h5u_set_view (f, start, end)); } -/*! +/** \ingroup h5part_model For parallel I/O or for subsetting operations on the datafile, @@ -353,7 +371,8 @@ H5PartSetView ( reads). However, after you set a view, it will return the number of particles contained in the view. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartSetViewIndices ( @@ -367,7 +386,7 @@ H5PartSetViewIndices ( H5_API_RETURN (h5u_set_view_indices (f, indices, nelems)); } -/*! +/** \ingroup h5part_model Allows you to query the current view. Start and End @@ -390,15 +409,16 @@ H5PartGetView ( H5_API_RETURN (h5u_get_view (f, start, end)); } -/*! +/** \ingroup h5part_model If it is too tedious to manually set the start and end coordinates - for a view, the \c H5SetCanonicalView() will automatically select an + for a view, \c H5SetCanonicalView() will automatically select an appropriate domain decomposition of the data arrays for the degree of parallelism and set the "view" accordingly. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_int64_t H5PartSetCanonicalView ( diff --git a/src/include/H5_attribs.f90 b/src/include/H5_attribs.f90 index f646350..034af25 100644 --- a/src/include/H5_attribs.f90 +++ b/src/include/H5_attribs.f90 @@ -7,6 +7,10 @@ ! License: see file COPYING in top level of source distribution. ! INTERFACE + !> + !! \ingroup \h5hut_f90_api + !! \addtogroup \h5hut_file_attribs_f + !! @{ ! __ _ _ _ _ _ _ _ ! / _(_) | ___ __ _| |_| |_ _ __(_) |__ _ _| |_ ___ ___ ! | |_| | |/ _ \ / _` | __| __| '__| | '_ \| | | | __/ _ \/ __| @@ -19,19 +23,17 @@ ! |_| |___/ !> - !! \ingroup h5hut_attrib_f !! See \ref H5GetNumFileAttribs !! \return number of attributes or error code - !< + INTEGER*8 FUNCTION h5_getnfileattribs (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< file handle END FUNCTION h5_getnfileattribs !> - !! \ingroup h5hut_attrib_f !! See \ref H5GetFileAttribInfo !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_getfileattribinfo (fhandle, idx, name, type, nelem) INTEGER*8,INTENT(IN) :: fhandle !< file handle INTEGER*8,INTENT(IN) :: idx !< index of attribute being queried @@ -41,10 +43,9 @@ END FUNCTION h5_getfileattribinfo !> - !! \ingroup h5hut_attrib_f !! See \ref H5GetFileAttribInfoByName !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_getfileattribinfo_by_name (fhandle, name, type, nelem) INTEGER*8,INTENT(IN) :: fhandle !< file handle CHARACTER(LEN=*), INTENT(IN):: name !< name of attribute @@ -65,10 +66,9 @@ ! |___/ !> - !! \ingroup h5hut_attrib_f !! See \ref H5WriteFileAttribString !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_writefileattrib_string (filehandle, attrib_name, attrib_value) INTEGER*8, INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: attrib_name !< name of attribute to write @@ -76,9 +76,8 @@ END FUNCTION h5_writefileattrib_string !> - !! \ingroup h5hut_attrib_f !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_readfileattrib_string (filehandle, attrib_name, attrib_value) INTEGER*8, INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: attrib_name !< name of the attribute to read @@ -97,10 +96,9 @@ ! |_/_/ \___/ |_| \___|\__,_|_| !> - !! \ingroup h5hut_attrib_f !! See \ref H5WriteFileAttribFloat64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_writefileattrib_r8 (filehandle, attrib_name, attrib_value, attrib_nelem) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: attrib_name !< name of attribute to read @@ -109,10 +107,9 @@ END FUNCTION h5_writefileattrib_r8 !> - !! \ingroup h5hut_attrib_f !! See \ref H5ReadFileAttribFloat64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_readfileattrib_r8 (filehandle, attrib_name, attrib_value) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: attrib_name !< name of attribute to read @@ -120,10 +117,9 @@ END FUNCTION h5_readfileattrib_r8 !> - !! \ingroup h5hut_attrib_f !! See \ref H5WriteFileAttribFloat32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_writefileattrib_r4 (filehandle, attrib_name, attrib_value, attrib_nelem) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: attrib_name !< name of attribute to read @@ -132,10 +128,9 @@ END FUNCTION h5_writefileattrib_r4 !> - !! \ingroup h5hut_attrib_f !! See \ref H5ReadFileAttribFloat32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_readfileattrib_r4 ( filehandle, attrib_name, attrib_value ) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: attrib_name !< name of attribute to read @@ -155,10 +150,9 @@ ! |___/ !> - !! \ingroup h5hut_attrib_f !! See \ref H5WriteFileAttribInt64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_writefileattrib_i8 (filehandle, attrib_name, attrib_value, attrib_nelem) INTEGER*8, INTENT(IN) :: filehandle !< file handle CHARACTER (LEN=*), INTENT(IN) :: attrib_name!< name of attribute to write @@ -167,10 +161,9 @@ END FUNCTION h5_writefileattrib_i8 !> - !! \ingroup h5hut_attrib_f !! See \ref H5ReadFileAttribInt64 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_readfileattrib_i8 (filehandle, attrib_name, attrib_value) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: attrib_name !< name of attribute to read @@ -178,10 +171,9 @@ END FUNCTION h5_readfileattrib_i8 !> - !! \ingroup h5hut_attrib_f !! See \ref H5WriteFileAttribInt32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_writefileattrib_i4 (filehandle, attrib_name, attrib_value, attrib_nelem) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER (LEN=*), INTENT(IN) :: attrib_name !< name of attribute to write @@ -190,16 +182,22 @@ END FUNCTION h5_writefileattrib_i4 !> - !! \ingroup h5hut_attrib_f !! See \ref H5ReadFileAttribInt32 !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_readfileattrib_i4 (filehandle, attrib_name, attrib_value) INTEGER*8,INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: attrib_name !< name of attribute to read INTEGER*4,INTENT(OUT):: attrib_value(*) !< attribute data will be read into this array END FUNCTION h5_readfileattrib_i4 + !> @} + + !> + !! \ingroup \h5hut_f90_api + !! \addtogroup \h5hut_step_attribs_f + !! @{ + ! _ _ _ _ _ _ ! ___| |_ ___ _ __ __ _| |_| |_ _ __(_) |__ _ _| |_ ___ ___ ! / __| __/ _ \ '_ \ / _` | __| __| '__| | '_ \| | | | __/ _ \/ __| @@ -213,19 +211,17 @@ ! |_| |___/ !> - !! \ingroup h5hut_attrib_f !! See \ref H5GetNumFileAttribs !! \return number of attributes or error code - !< + INTEGER*8 FUNCTION h5_getnstepattribs (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< file handle END FUNCTION h5_getnstepattribs !> - !! \ingroup h5hut_attrib_f !! See \ref H5GetFileAttribInfo !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_getstepattribinfo (filehandle, idx, name, type, nelem) INTEGER*8,INTENT(IN) :: filehandle !< file handle INTEGER*8,INTENT(IN) :: idx !< index of attribute being queried @@ -235,10 +231,9 @@ END FUNCTION h5_getstepattribinfo !> - !! \ingroup h5hut_attrib_f !! See \ref H5GetStepAttribInfoByName !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_getstepattribinfo_by_name (fhandle, name, type, nelem) INTEGER*8,INTENT(IN) :: fhandle !< file handle CHARACTER(LEN=*), INTENT(IN):: name !< name of attribute @@ -260,10 +255,9 @@ ! |___/ !> - !! \ingroup h5hut_attrib_f !! See \ref H5WriteStepAttribString !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_writestepattrib_string (filehandle, attrib_name, attrib_value) INTEGER*8, INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: attrib_name !< name of attribute to write @@ -271,10 +265,9 @@ END FUNCTION h5_writestepattrib_string !> - !! \ingroup h5hut_attrib_f !! See \ref H5ReadStepAttribString !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_readstepattrib_string (filehandle, attrib_name, attrib_value) INTEGER*8, INTENT(IN) :: filehandle !< file handle CHARACTER(LEN=*), INTENT(IN) :: attrib_name !< name of the attribute to read @@ -294,7 +287,6 @@ ! |_/_/ \___/ |_| \___|\__,_|_| !> - !! \ingroup h5hut_attrib_f !! See \ref H5WriteStepAttribFloat64 !! \return 0 on success or error code !< @@ -306,7 +298,6 @@ END FUNCTION h5_writestepattrib_r8 !> - !! \ingroup h5hut_attrib_f !! See \ref H5ReadStepAttribFloat64 !! \return 0 on success or error code !< @@ -317,7 +308,6 @@ END FUNCTION h5_readstepattrib_r8 !> - !! \ingroup h5hut_attrib_f !! See \ref H5WriteStepAttribFloat32 !! \return 0 on success or error code !< @@ -329,7 +319,6 @@ END FUNCTION h5_writestepattrib_r4 !> - !! \ingroup h5hut_attrib_f !! See \ref H5ReadStepAttribFloat32 !! \return 0 on success or error code !< @@ -353,7 +342,6 @@ ! |___/ !> - !! \ingroup h5hut_attrib_f !! See \ref H5WriteStepAttribInt64 !! \return 0 on success or error code !< @@ -365,7 +353,6 @@ END FUNCTION h5_writestepattrib_i8 !> - !! \ingroup h5hut_attrib_f !! See \ref H5ReadStepAttribInt64 !! \return 0 on success or error code !< @@ -376,7 +363,6 @@ END FUNCTION h5_readstepattrib_i8 !> - !! \ingroup h5hut_attrib_f !! See \ref H5WriteStepAttribInt32 !! \return 0 on success or error code !< @@ -388,7 +374,6 @@ END FUNCTION h5_writestepattrib_i4 !> - !! \ingroup h5hut_attrib_f !! See \ref H5ReadStepAttribInt32 !! \return 0 on success or error code !< @@ -398,4 +383,5 @@ INTEGER*4,INTENT(OUT):: attrib_value(*) !< attribute data will be read into this array END FUNCTION h5_readstepattrib_i4 + !> @} END INTERFACE diff --git a/src/include/H5_attribs.h b/src/include/H5_attribs.h index 3fae036..6d6f27e 100644 --- a/src/include/H5_attribs.h +++ b/src/include/H5_attribs.h @@ -35,12 +35,13 @@ extern "C" { |_| |___/ */ -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Gets the number of attributes in the file's root ("/"). - \return Number of attributes or \c H5_FAILURE.. + \return Number of attributes + \return \c H5_FAILURE on error */ static inline h5_int64_t H5GetNumFileAttribs ( @@ -52,8 +53,8 @@ H5GetNumFileAttribs ( H5_API_RETURN (h5_get_num_file_attribs (f)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Gets the name, type and number of elements of the file attribute specified by its index. @@ -63,7 +64,8 @@ H5GetNumFileAttribs ( one. The number of attributes bound to file \c f can be queried by calling \ref H5GetNumFileAttribs. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5GetFileAttribInfo ( @@ -92,13 +94,14 @@ H5GetFileAttribInfo ( nelems)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Get the type and number of elements of the file attribute specified by its name. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5GetFileAttribInfoByName ( @@ -134,13 +137,14 @@ H5GetFileAttribInfoByName ( |_/_/ \___/ */ -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Write an attribute \c name with the string \c value to the file root ("/"). - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5WriteFileAttribString ( @@ -159,13 +163,14 @@ H5WriteFileAttribString ( strlen(value) + 1 )); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Read a string into a \c buffer from an attribute \c name in the file root ("/"). - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5ReadFileAttribString ( @@ -183,13 +188,14 @@ H5ReadFileAttribString ( (void*)buffer)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Write an attribute \c name with float64 \c values to the file root ("/"). - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5WriteFileAttribFloat64 ( @@ -209,13 +215,14 @@ H5WriteFileAttribFloat64 ( nelems)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Read float64 values into a \c buffer from an attribute \c name in the file root ("/"). - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5ReadFileAttribFloat64 ( @@ -234,13 +241,14 @@ H5ReadFileAttribFloat64 ( } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Write an attribute \c name with float32 \c values to the file root ("/"). - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5WriteFileAttribFloat32 ( @@ -260,13 +268,14 @@ H5WriteFileAttribFloat32 ( nelems )); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Read float32 values into a \c buffer from an attribute \c name in the file root ("/"). - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5ReadFileAttribFloat32 ( @@ -284,13 +293,14 @@ H5ReadFileAttribFloat32 ( (void*)buffer)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Write an attribute \c name with int64 \c values to the file root ("/"). - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5WriteFileAttribInt64 ( @@ -310,13 +320,14 @@ H5WriteFileAttribInt64 ( nelems)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Read int64 values into a \c buffer from an attribute \c name in the file root ("/"). - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5ReadFileAttribInt64 ( @@ -334,13 +345,14 @@ H5ReadFileAttribInt64 ( (void*)buffer)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Write an attribute \c name with int32 \c values to the file root ("/"). - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5WriteFileAttribInt32 ( @@ -360,13 +372,14 @@ H5WriteFileAttribInt32 ( nelems)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_file_attribs Read int32 values into a \c buffer from an attribute \c name in the file root ("/"). - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5ReadFileAttribInt32 ( @@ -399,12 +412,13 @@ H5ReadFileAttribInt32 ( |_| |___/ */ -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Gets the number of attributes bound to the current step. - \return Number of attributes or \c H5_FAILURE.. + \return Number of attributes + \return \c H5_FAILURE on error */ static inline h5_int64_t H5GetNumStepAttribs ( @@ -416,8 +430,8 @@ H5GetNumStepAttribs ( H5_API_RETURN (h5_get_num_step_attribs (f)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Gets the name, type and number of elements of the step attribute specified by its index. @@ -427,7 +441,8 @@ H5GetNumStepAttribs ( minus one. The number of attributes bound to the current time-step can be queried by calling \ref H5GetNumStepAttribs. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5GetStepAttribInfo ( @@ -457,13 +472,14 @@ H5GetStepAttribInfo ( nelems)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Gets the type and number of elements of the step attribute specified by its name. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5GetStepAttribInfoByName ( @@ -500,13 +516,14 @@ H5GetStepAttribInfoByName ( |_/_/ \___/ */ -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Write an attribute \c name with the string \c value to the current timestep. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5WriteStepAttribString ( @@ -525,13 +542,14 @@ H5WriteStepAttribString ( strlen(value) + 1 )); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Read a string into a \c buffer from an attribute \c name in the current timestep. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5ReadStepAttribString ( @@ -549,13 +567,14 @@ H5ReadStepAttribString ( (void*)buffer)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Write an attribute \c name with float64 \c values to the current time step. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5WriteStepAttribFloat64 ( @@ -575,13 +594,14 @@ H5WriteStepAttribFloat64 ( nelems)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Read float64 values into a \c buffer from an attribute \c name in the current time step. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5ReadStepAttribFloat64 ( @@ -599,13 +619,14 @@ H5ReadStepAttribFloat64 ( (void*)buffer)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Write an attribute \c name with float32 \c values to the current time step. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5WriteStepAttribFloat32 ( @@ -625,13 +646,14 @@ H5WriteStepAttribFloat32 ( nelems )); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Read float32 values into a \c buffer from an attribute \c name in the current time step. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5ReadStepAttribFloat32 ( @@ -649,13 +671,14 @@ H5ReadStepAttribFloat32 ( (void*)buffer)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Write an attribute \c name with int64 \c values to the current time step. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5WriteStepAttribInt64 ( @@ -675,13 +698,14 @@ H5WriteStepAttribInt64 ( nelems)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Read int64 values into a \c buffer from an attribute \c name in the current time step. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5ReadStepAttribInt64 ( @@ -700,13 +724,14 @@ H5ReadStepAttribInt64 ( H5_API_RETURN (h5err); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Write an attribute \c name with int32 \c values to the current time step. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5WriteStepAttribInt32 ( @@ -726,13 +751,14 @@ H5WriteStepAttribInt32 ( nelems)); } -/*! - \ingroup h5hut_attrib +/** + \ingroup h5hut_step_attribs Read int32 values into a \c buffer from an attribute \c name in the current time step. - \return \c H5_SUCCESS or \c H5_FAILURE. + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5ReadStepAttribInt32 ( diff --git a/src/include/H5_const.f90 b/src/include/H5_const.f90 index d7d324a..006821e 100644 --- a/src/include/H5_const.f90 +++ b/src/include/H5_const.f90 @@ -30,6 +30,7 @@ INTEGER*8, PARAMETER :: H5_OK = H5_SUCCESS INTEGER*8, PARAMETER :: H5_NOK = -1 INTEGER*8, PARAMETER :: H5_FAILURE = -2 + INTEGER*8, PARAMETER :: H5_FAILED = H5_FAILED INTEGER*8, PARAMETER :: H5_ERR_BADF = -9 INTEGER*8, PARAMETER :: H5_ERR_NOMEM = -12 INTEGER*8, PARAMETER :: H5_ERR_INVAL = -22 @@ -66,4 +67,3 @@ INTEGER*8, PARAMETER :: H5_DEBUG_CLIB = 1024 INTEGER*8, PARAMETER :: H5_DEBUG_ALL = 2048-4 - diff --git a/src/include/H5_model.f90 b/src/include/H5_model.f90 index 69a7630..185906e 100644 --- a/src/include/H5_model.f90 +++ b/src/include/H5_model.f90 @@ -1,39 +1,50 @@ +! +! Copyright (c) 2006-2016, The Regents of the University of California, +! through Lawrence Berkeley National Laboratory (subject to receipt of any +! required approvals from the U.S. Dept. of Energy) and the Paul Scherrer +! Institut (Switzerland). All rights reserved.! +! +! License: see file COPYING in top level of source distribution. +! INTERFACE !> - !! \ingroup h5hut_model_f + !! \ingroup h5hut_f90_api + !! \addtogroup h5hut_model_f + !! @{ + + !> !! See \ref H5HasStep !! \return 0 on success or H5_FAILURE - !< + LOGICAL FUNCTION h5_hasstep (filehandle,step) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open INTEGER*8, INTENT(IN) :: step !< a timestep value >= 1 END FUNCTION h5_hasstep !> - !! \ingroup h5hut_model_f !! See \ref H5SetStep !! \return 0 on success or error code - !< + INTEGER*8 FUNCTION h5_setstep (filehandle,step) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open INTEGER*8, INTENT(IN) :: step !< a timestep value >= 1 END FUNCTION h5_setstep !> - !! \ingroup h5hut_model_f !! See \ref H5GetStep !! \return the the current step or \c H5_FAILURE - !< + INTEGER*8 FUNCTION h5_getstep (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open END FUNCTION h5_getstep !> - !! \ingroup h5hut_model_f !! See \ref H5GetNumSteps !! \return the number of steps or error code - !< + INTEGER*8 FUNCTION h5_getnsteps (filehandle) INTEGER*8, INTENT(IN) :: filehandle !< the handle returned during file open END FUNCTION h5_getnsteps + + !> @} END INTERFACE diff --git a/src/include/H5_model.h b/src/include/H5_model.h index 9329a44..5f29e07 100644 --- a/src/include/H5_model.h +++ b/src/include/H5_model.h @@ -19,7 +19,7 @@ extern "C" { #endif -/*! +/** \ingroup h5hut_model Define format of the step names. @@ -27,7 +27,8 @@ extern "C" { Example: ==H5SetStepNameFormat( f, "Step", 6 )== defines step names like ==Step#000042==. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5SetStepNameFormat ( @@ -41,12 +42,13 @@ H5SetStepNameFormat ( H5_API_RETURN (h5_set_stepname_fmt (f, name, width)); } -/*! +/** \ingroup h5hut_model Get format of the step names. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5GetStepNameFormat ( @@ -61,12 +63,13 @@ H5GetStepNameFormat ( H5_API_RETURN (h5_get_stepname_fmt (f, name, l_name, width)); } -/*! +/** \ingroup h5hut_model Set the current step. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5SetStep ( @@ -79,13 +82,13 @@ H5SetStep ( H5_API_RETURN (h5_set_step (f, step)); } -/*! +/** \ingroup h5hut_model Get current step. - \return Step index - \return H5_FAILURE on error + \return Step number + \return \c H5_FAILURE on error */ static inline h5_id_t H5GetStep ( @@ -97,13 +100,13 @@ H5GetStep ( H5_API_RETURN (h5_get_step (f)); } -/*! +/** \ingroup h5hut_model Get the number of processors. - \return Number of processors. - \return \c H5_FAILURE on error. + \return Number of processors. + \return \c H5_FAILURE on error. */ static inline int H5GetNumProcs ( @@ -115,7 +118,7 @@ H5GetNumProcs ( H5_API_RETURN (h5_get_num_procs(f)); } -/*! +/** \ingroup h5hut_model Get the number of time-steps that are currently stored in the file @@ -137,13 +140,13 @@ H5GetNumSteps ( H5_API_RETURN (h5_get_num_steps(f)); } -/*! +/** \ingroup h5hut_model Query whether a particular step already exists in the file. - \return \c 1 if step exists - \return \c 0 if step does not exist + \return \c H5_OK if step exists + \return \c H5NOK if step does not exist \return \c H5_FAILURE on error */ static inline h5_err_t @@ -157,14 +160,15 @@ H5HasStep ( H5_API_RETURN (h5_has_step (f, stepno)); } -/*! +/** \ingroup h5hut_model Start traversing steps. \note This function is not yet implemented! - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5StartTraverseSteps ( @@ -176,14 +180,15 @@ H5StartTraverseSteps ( H5_API_RETURN (h5_start_traverse_steps (f)); } -/*! +/** \ingroup h5hut_model Go to next step. \note This function is not yet implemented! - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5TraverseSteps ( @@ -195,13 +200,13 @@ H5TraverseSteps ( H5_API_RETURN (h5_traverse_steps (f)); } -/*! +/** \ingroup h5hut_model Return number of attached files. - \return number of attachments. - \return \c H5_FAILURE on error. + \return number of attachments. + \return \c H5_FAILURE on error. */ static inline h5_ssize_t H5GetNumAttachments ( @@ -213,13 +218,14 @@ H5GetNumAttachments ( H5_API_RETURN (h5_get_num_attachments (f)); } -/*! +/** \ingroup h5hut_model Get name and size of attachment given by index \c idx. Return the file name in \c fname and the original size in \c fsize. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5GetAttachmentInfoByIdx ( @@ -238,12 +244,13 @@ H5GetAttachmentInfoByIdx ( f, idx, fname, len_fname, fsize)); } -/*! +/** \ingroup h5hut_model Get size of attached file with name \c fname. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5GetAttachmentInfoByName ( @@ -256,12 +263,13 @@ H5GetAttachmentInfoByName ( f, fname, fsize)); } -/*! +/** \ingroup h5hut_model Attach file \c fname. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5AddAttachment ( @@ -272,13 +280,14 @@ H5AddAttachment ( H5_API_RETURN (h5_add_attachment (f, fname)); } -/*! +/** \ingroup h5hut_model Get attachment \c fname from H5hut file and write it to disk in the current working directory. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5GetAttachment ( @@ -289,12 +298,13 @@ H5GetAttachment ( H5_API_RETURN (h5_get_attachment (f, fname)); } -/*! +/** \ingroup h5hut_model Delete attachment \c fname. - \return \c H5_SUCCESS or \c H5_FAILURE + \return \c H5_SUCCESS on success + \return \c H5_FAILURE on error */ static inline h5_err_t H5DeleteAttachment ( diff --git a/src/include/h5core/h5.h b/src/include/h5core/h5.h index c247dea..4335c5d 100644 --- a/src/include/h5core/h5.h +++ b/src/include/h5core/h5.h @@ -63,7 +63,7 @@ h5_set_prop_file_mpio_posix ( h5_err_t h5_set_prop_file_core_vfd ( - h5_prop_t); + h5_prop_t, h5_int64_t); h5_err_t h5_close_prop (