From 031768b5e286493204fb2c52e1a6188277fe6379 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Thu, 6 Jul 2000 11:28:38 -0500 Subject: [svn-r2426] RM_H5P.html: Minor copy-editing and formatting fixes. H5Pget_chunk: Changed max_ndims parameter description to IN. H5Pget/set_gc_references: Corrected signature errors, added missing parameter description and values. H5Pget/set_family: Removed. These are not implemented. H5Pget/set_hyper_cache: Corrected signature and parameter expressions, added missing parameter description. H5Pset_buffer: Added units for parameter 'size'.RM_H5P.html H5Pget/set_split: Corrected misnamed parameters. H5Pset_alignment and H5_set_core: Edited for clarity. Added statement regarding "special case" effect of setting 'threshold' to 0 (zero). Stated clearly that 'threshold' is non-negative and 'alignment' and 'increment' are both positive. H5Pget/set_vlen_mem_manager: Corrected cross-ref to H5Dvlen_reclaim. Minor clarification regarding circumstances under which contents of a parameter are ignored. H5Pget_cache: Removed redundant material. --- doc/html/RM_H5P.html | 143 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 89 insertions(+), 54 deletions(-) diff --git a/doc/html/RM_H5P.html b/doc/html/RM_H5P.html index ef80062..b732d01 100644 --- a/doc/html/RM_H5P.html +++ b/doc/html/RM_H5P.html @@ -99,8 +99,10 @@ many different parameters to be easily manipulated.
  • H5Pget_core
  • H5Pset_mpi   ||
  • H5Pget_mpi   || +
  • H5Pset_cache
  • H5Pget_cache
  • H5Pset_split @@ -111,6 +113,10 @@ many different parameters to be easily manipulated.
     
      +
      +
      +
      +
     
    ||  Available only in the parallel HDF5 library. @@ -634,7 +640,7 @@ facilitate moving easily between them.
    Parameters:
    hid_t plist -
    IN: Identifier of property list to modify +
    IN: Identifier of property list to modify.
    MPI_Comm comm
    IN: MPI communicator to be used for file open as defined in MPI_FILE_OPEN of MPI-2. This function does not make a @@ -1108,7 +1114,7 @@ facilitate moving easily between them.
    hid_t plist
    IN: Identifier of property list to query.
    int max_ndims -
    OUT: Size of the dims array. +
    IN: Size of the dims array.
    hsize_t * dims
    OUT: Array to store the chunk dimensions.
    @@ -1138,14 +1144,16 @@ facilitate moving easily between them.
    Description:
    H5Pset_alignment sets the alignment properties of a file access property list - so that any file object >= THRESHOLD bytes will be aligned on - an address which is a multiple of ALIGNMENT. The addresses + 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. + multiple of alignment.

    - Default values for THRESHOLD and ALIGNMENT are one, implying + Default values for threshold and + alignment are one, implying no alignment. Generally the default values will result in the best performance for single-process access to the file. For MPI-IO and other parallel systems, choose an alignment @@ -1155,9 +1163,14 @@ facilitate moving easily between them.

    hid_t plist
    IN: Identifier for a file access property list.
    hsize_t threshold -
    IN: Threshold value. +
    IN: Threshold value. + Must be non-negative. + Note that setting the threshold value to 0 (zero) has + the effect of a special case, forcing everything + to be aligned.
    hsize_t alignment -
    IN: Alignment value. +
    IN: Alignment value. + Must be a positive value.
    Returns:
    Returns a non-negative value if successful; @@ -1269,7 +1282,7 @@ facilitate moving easily between them.
    Name: H5Pget_external_count
    Signature: -
    int H5Pget_external_count(hid_t plist, +
    int H5Pget_external_count(hid_t plist )
    Purpose:
    Returns the number of external files for a dataset. @@ -1511,7 +1524,7 @@ facilitate moving easily between them.
    IN: Bit vector specifying certain general properties of the filter.
    size_t cd_nelmts -
    IN: Number of elements in cd_values +
    IN: Number of elements in cd_values.
    const unsigned int cd_values[]
    IN: Auxiliary data for the filter.
    @@ -1633,7 +1646,7 @@ facilitate moving easily between them.
    OUT: Bit vector specifying certain general properties of the filter.
    size_t *cd_nelmts -
    IN/OUT: Number of elements in cd_values +
    IN/OUT: Number of elements in cd_values.
    unsigned int *cd_values
    OUT: Auxiliary data for the filter.
    size_t namelen @@ -1659,7 +1672,7 @@ facilitate moving easily between them.
    Name: H5Pget_driver
    Signature: -
    H5F_driver_t H5Pget_driver(hid_t plist, +
    H5F_driver_t H5Pget_driver(hid_t plist )
    Purpose:
    Returns a low-level file driver identifier. @@ -1761,7 +1774,7 @@ facilitate moving easily between them.
    Name: H5Pset_sec2
    Signature: -
    herr_t H5Pset_sec2(hid_t plist, +
    herr_t H5Pset_sec2(hid_t plist )
    Purpose:
    Sets the low-level file driver to use the declared functions. @@ -1837,7 +1850,7 @@ facilitate moving easily between them. This driver is restricted to temporary files which are not larger than the amount of virtual memory available. The increment argument determines the file block size - and memory will be allocated in multiples of INCREMENT bytes. + and memory will be allocated in multiples of increment bytes. A liberal increment results in fewer calls to realloc() and probably less memory fragmentation.
    Parameters: @@ -1845,7 +1858,8 @@ facilitate moving easily between them.
    hid_t plist
    IN: Identifier of a file access property list.
    size_t increment -
    IN: File block size in bytes. +
    IN: File block size in bytes. + Must be a positive value.
    Returns:
    Returns a non-negative value if successful; @@ -1918,11 +1932,11 @@ facilitate moving easily between them. raw data in another file. The meta file will have a name which is formed by adding meta_extension (recommended default value: .meta) to the end of the base name - and will be accessed according to the meta_properties. + and will be accessed according to the meta_plist. The raw file will have a name which is formed by appending raw_extension (recommended default value: .raw) to the base name and will be accessed according - to the raw_properties. + to the raw_plist. Additional parameters may be added to this function in the future.
    Parameters:
    @@ -1960,10 +1974,10 @@ facilitate moving easily between them.
    herr_t H5Pget_split(hid_t plist, size_t meta_ext_size, char *meta_ext, - hid_t *meta_properties, + hid_t *meta_plist, size_t raw_ext_size, char *raw_ext, - hid_t *raw_properties + hid_t *raw_plist )
    Purpose:
    Determines whether the file access property list is set @@ -1972,7 +1986,7 @@ facilitate moving easily between them.
    H5Pget_split checks to determine whether the file access property list is set to the split driver. On successful return, - meta_properties and raw_properties will + meta_plist and raw_plist will point to copies of the meta and raw access property lists which should be closed by calling H5Pclose() when the application is finished with them, but if the meta and/or @@ -1996,14 +2010,14 @@ facilitate moving easily between them. copied to the meta_ext buffer.
    char *meta_ext
    OUT: Meta file extension. -
    hid_t *meta_properties +
    hid_t *meta_plist
    OUT: Pointer to a copy of the meta file access property list.
    size_t raw_ext_size
    IN: Number of characters of the raw file extension to be copied to the raw_ext buffer.
    char *raw_ext
    OUT: Raw file extension. -
    hid_t *raw_properties +
    hid_t *raw_plist
    OUT: Pointer to a copy of the raw file access property list.
    Returns: @@ -2025,7 +2039,7 @@ facilitate moving easily between them.
    Name: H5Pset_gc_references
    Signature: -
    herr_t H5Pset_split(hid_t plist, +
    herr_t H5Pset_gc_reference(hid_t plist, unsigned gc_ref )
    Purpose: @@ -2050,7 +2064,8 @@ facilitate moving easily between them.
    hid_t plist
    IN: File access property list identifier.
    unsigned gc_ref -
    IN: +
    IN: Flag setting reference garbage collection to + on (1) or off (0).
    Returns:
    Returns a non-negative value if successful; @@ -2069,7 +2084,7 @@ facilitate moving easily between them.
    Name: H5Pget_gc_references
    Signature: -
    herr_t H5Pget_split(hid_t plist, +
    herr_t H5Pget_gc_references(hid_t plist, unsigned *gc_ref )
    Purpose: @@ -2085,7 +2100,10 @@ facilitate moving easily between them.
    hid_t plist
    IN: File access property list identifier.
    unsigned gc_ref -
    OUT: +
    OUT: Flag returning the state of reference garbage collection. + A returned value of 1 indicates that + garbage collection is on while + 0 indicates that garbage collection is off.
    Returns:
    Returns a non-negative value if successful; @@ -2101,6 +2119,7 @@ facilitate moving easily between them.
    + @@ -2198,15 +2213,13 @@ facilitate moving easily between them.
    Returns a non-negative value if the file access property list is set to the family driver. Otherwise returns a negative value. - +-->
    @@ -2285,8 +2298,8 @@ facilitate moving easily between them.
    Description:
    Retrieves the maximum possible number of elements in the meta data cache and raw data chunk cache, the maximum possible number of - bytes in the raw data chunk cache, and the preemption policy value, - rdcc_w0. + bytes in the raw data chunk cache, and the preemption policy value. +

    Any (or all) arguments may be null pointers, in which case the corresponding datum is not returned.

    Parameters: @@ -2331,11 +2344,21 @@ facilitate moving easily between them. indicates whether to cache hyperslab blocks during I/O, a process which can significantly increase I/O speeds.

    + When working with hyperslab selections, it is possible to + significantly speed up I/O operations by retrieving an + entire hyperslab from the file in one operation and + caching it in memory. + The cache parameter specifies whether to turn + caching on for hyperslab I/O operations. + If cache is set to 1, + caching is turned on; + if set to 0, caching is turned off. +

    The parameter limit sets the maximum size of the hyperslab block to cache. If a block is smaller than that limit, it may still not be cached if no memory is available. - Setting the limit to 0 (zero) indicates no limitation on the size of - block to attempt to cache. + Setting limit to 0 (zero) indicates + no limitation on the size of block to attempt to cache.

    The default is to cache blocks with no limit on block size for serial I/O and to not cache blocks for parallel I/O. @@ -2344,7 +2367,8 @@ facilitate moving easily between them.

    hid_t plist
    IN: Dataset transfer property list identifier.
    unsigned cache -
    IN: +
    IN: A flag indicating whether caching is to be + set to on (1) or off (0).
    unsigned limit
    IN: Maximum size of the hyperslab block to cache. 0 (zero) indicates no limit. @@ -2368,8 +2392,8 @@ facilitate moving easily between them.
    Name: H5Pget_hyper_cache
    Signature:
    herr_t H5Pget_hyper_cache(hid_t plist, - unsigned cache, - unsigned limit + unsigned *cache, + unsigned *limit )
    Purpose:
    Returns information regarding the caching of hyperslab blocks during I/O. @@ -2381,9 +2405,10 @@ facilitate moving easily between them.
    hid_t plist
    IN: Dataset transfer property list identifier. -
    unsigned cache -
    OUT: -
    unsigned limit +
    unsigned *cache +
    OUT: A flag indicating whether caching is + set to on (1) or off (0). +
    unsigned *limit
    OUT: Maximum size of the hyperslab block to cache. 0 (zero) indicates no limit.
    @@ -2535,7 +2560,7 @@ facilitate moving easily between them.
    hid_t plist
    IN: Identifier for the dataset transfer property list.
    size_t size -
    IN: Size for the type conversion and background buffers. +
    IN: Size, in bytes, of the type conversion and background buffers.
    void tconv
    IN: Pointer to application-allocated type conversion buffer.
    void bkg @@ -2580,7 +2605,7 @@ facilitate moving easily between them. background buffer.
    Returns: -
    Returns buffer size if successful; +
    Returns buffer size, in bytes, if successful; otherwise 0 on failure.