From 15df4a2679d261abdeb2ab2575b2a16077057f83 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Fri, 8 Dec 2000 14:50:33 -0500 Subject: [svn-r3104] Purpose: Finalize new API function descriptions Description: Edits to recently-added APIs: H5Pset_sieve_buf_size H5Pset_fapl_log H5P[sg]et_fapl_mpio H5Pset_fapl_multi H5P[sg]et_dxpl_multi H5Pset_fapl_split H5P[sg]et_fapl_gass H5Pset_fapl_dpss H5P[sg]et_fapl_srb Added H5P[sg]et_fapl_core. Addition of new APIs for R1.4 is now complete. Moved H5Pset_driver and H5Pget_driver_info to TechNotes. Platforms tested: IE 5 --- doc/html/RM_H5P.html | 304 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 213 insertions(+), 91 deletions(-) diff --git a/doc/html/RM_H5P.html b/doc/html/RM_H5P.html index f060b50..84e8346 100644 --- a/doc/html/RM_H5P.html +++ b/doc/html/RM_H5P.html @@ -57,7 +57,7 @@ many different parameters to be easily manipulated.
- General Property List Operations + General Property List
Operations -

Variable-length Datatype Properties -

- +
  +
  +
 
 
 
 
-||  Indicates functions available
-     only in the parallel HDF5 library. +||  Indicates functions
+     available only in the
+     parallel HDF5 library. 		       @@ -107,9 +105,9 @@ many different parameters to be easily manipulated.
  • H5Pset_fapl_stdio
  • H5Pset_fapl_stream
  • H5Pget_fapl_stream -
  • H5Pset_driver +
  • H5Pget_driver -
  • H5Pget_driver_info +
  • H5Pset_meta_block_size
  • H5Pget_meta_block_size
  • H5Pset_sieve_buf_size @@ -165,6 +163,8 @@ many different parameters to be easily manipulated.
  • H5Pget_hyper_cache
  • H5Pset_btree_ratios
  • H5Pget_btree_ratios +
  • H5Pset_vlen_mem_manager +
  • H5Pget_vlen_mem_manager
  • H5Pset_dxpl_mpio   ||
  • H5Pget_dxpl_mpio   ||
  • H5Pset_dxpl_multi @@ -1601,23 +1601,26 @@ facilitate moving easily between them.
    Name: H5Pset_sieve_buf_size
    Signature: -
    xxx H5Pset_sieve_buf_size( +
    herr_t H5Pset_sieve_buf_size( hid_t fapl_id, hsize_t size )
    Purpose: -
    +
    Sets the maximum size of the data sieve buffer.
    Description:
    H5Pset_sieve_buf_size sets size, - the maximum size in bytes of the data seive buffer, which is + the maximum size in bytes of the data sieve buffer, which is used by file drivers that are capable of using data sieving.

    - The data sieve buffer is used when performing I/O on datasets in the file. Using a buffer which is large anough to hold several pieces of the dataset being read in for hyperslab selections boosts performance by quite a bit. + The data sieve buffer is used when performing I/O on datasets + in the file. Using a buffer which is large anough to hold + several pieces of the dataset being read in for + hyperslab selections boosts performance by quite a bit.

    - The default value is set to 64KB, indicating that file I/O for raw data reads and writes will occur in at least 64KB blocks. Setting the value to 0 with this API function will turn off the data sieving, even if the VFL driver attempts to use that strategy. -

    - Need a conceptual understanding of data sieving to finish this. -- FB - + The default value is set to 64KB, indicating that file I/O for + raw data reads and writes will occur in at least 64KB blocks. + Setting the value to 0 with this API function will turn off the + data sieving, even if the VFL driver attempts to use that strategy.

    Parameters:
    hid_t fapl_id @@ -2641,18 +2644,38 @@ facilitate moving easily between them.
    Purpose:
    Sets up the use of the logging driver.
    Description: -
    H5Psget_fapl_log modifies the - file access property list to use the logging driver . - (H5FD_LOG ??) +
    H5Pset_fapl_log modifies the + file access property list to use the logging driver + H5FD_LOG. There are no driver-specific properties.

    logfile is the name of the file in which the logging entries are to be recorded.

    verbosity indicates the extent of the logging - activity intended, with a value of 0 indicating - no logging. - (Other values, range, ... ??) + activity intended. Valid values are as follows: +

    + + + + +
    + 0   + + Performs no logging. +
    + 1   + + Records where writes and reads occur in the file. +
    + 2   + + Records where writes and reads occur in the file and what + kind of data is written at each location: raw data or any of + several types of metadata (object headers, superblock, + B-tree data, local headers, or global headers). +
    +
    Parameters:
    @@ -2688,12 +2711,13 @@ facilitate moving easily between them. MPI_Info info )
    Purpose: -
    Stores MPIO communicator information to the file access property list. +
    Stores MPI IO communicator information to the file access property list.
    Description: -
    H5Pset_fapl_mpio stores the user supplied - MPIO communicator comm and info in - the file access property list fapl_id, - which can then be used to create and/or open the file. +
    H5Pset_fapl_mpio stores the user-supplied + MPI IO parameters comm, for communicator, and + info, for information, in + the file access property list fapl_id. + That property list can then be used to create and/or open the file.

    H5Pset_fapl_mpio is available only in the parallel HDF5 library and is not a collective function. @@ -2749,8 +2773,8 @@ facilitate moving easily between them.

    Purpose:
    Returns MPI communicator information.
    Description: -
    If the file access property list is set to the H5FD_MPIO driver, - H5Pget_fapl_mpio returns the MPI communicator and +
    If the file access property list is set to the H5FD_MPIO + driver, H5Pget_fapl_mpio returns the MPI communicator and information through the comm and info pointers, if those values are non-null.

    @@ -2886,6 +2910,17 @@ facilitate moving easily between them.

    H5Pset_fapl_multi sets the file access property list fapl_id to use the multi-file driver.

    + The multi-file driver enables different types of HDF5 data and + metadata to be written to separate files. These files are viewed + by the HDF5 library and the application as a single virtual HDF5 file + with a single HDF5 file address space. + The types of data that can be broken out into separate file include + raw data, the superblock, B-tree data, global heap data, + local heap data, and object headers. + At the programmer's discretion, two or more types of data can be + written the same file while other types of data are written to + separate files. +

    The array memb_map maps memory usage types to other memory usage types and is the mechanism that allows the caller to specify how many files are created. @@ -2903,7 +2938,9 @@ facilitate moving easily between them. name passed to H5FDopen(), usually from H5Fcreate() or H5Fopen()).

    - The array memb_addr .... + The array memb_addr specifies the offsets within the + virtual address space, from 0 (zero) to + HADDR_MAX, at wihch each type of data storage begins.

    If relax is set to TRUE (or 1), then opening an existing file for read-only access will not fail @@ -2924,17 +2961,17 @@ facilitate moving easily between them. where   X   is one of the following letters:

    - s for H5FD_MEM_SUPER + s    for H5FD_MEM_SUPER
    - b for H5FD_MEM_BTREE + b    for H5FD_MEM_BTREE
    - r for H5FD_MEM_DRAW + r    for H5FD_MEM_DRAW
    - g for H5FD_MEM_GHEAP + g    for H5FD_MEM_GHEAP
    - l for H5FD_MEM_LHEAP + l    for H5FD_MEM_LHEAP
    - o for H5FD_MEM_OHDR + o    for H5FD_MEM_OHDR
    memb_addr
    The default value is HADDR_UNDEF for each element. @@ -2951,7 +2988,9 @@ facilitate moving easily between them.
    const char **memb_name
    IN: Name generator for names of member files.
    const haddr_t *memb_addr -
    IN: +
    IN: The offsets within the virtual address space, + from 0 (zero) to HADDR_MAX, + at wihch each type of data storage begins.
    hbool_t relax
    IN: Allows read-only access to incomplete file sets when TRUE. @@ -3061,14 +3100,16 @@ facilitate moving easily between them.
    Description:
    H5Pset_dxpl_multi sets the data transfer property list dxpl_id to use the multi-file driver for each - memory usage type memb_dxpl[] - (after the usage map is applied). + memory usage type memb_dxpl[]. +

    + H5Pset_dxpl_multi can only be used after + the member map has been set with H5Pset_fapl_multi.

    Parameters:
    hid_t dxpl_id,
    IN: Data transfer property list identifier.
    const hid_t *memb_dxpl -
    IN: Array of memory usage types for ... +
    IN: Array of data access property lists.
    Returns:
    Returns a non-negative value if successful. @@ -3105,7 +3146,7 @@ facilitate moving easily between them.
    hid_t dxpl_id,
    IN: Data transfer property list identifier.
    const hid_t *memb_dxpl -
    OUT: Array of memory usage types for ... +
    OUT: Array of data access property lists.
    Returns:
    Returns a non-negative value if successful. @@ -3138,32 +3179,34 @@ facilitate moving easily between them.
    Description:
    H5Pset_fapl_split is a compatability function that enables the multi-file driver to emulate the split driver from - HDF5 Releases 1.0 and 1.2. + HDF5 Releases 1.0 and 1.2. + The split file driver stored metadata and raw data in separate files + but provide no mechanism for separating types of metadata.

    - fapl_id is .... + fapl_id is a file access property list identifier.

    - meta_ext is .... + meta_ext is the filename extension for the metadata file.

    - meta_plist_id is the file property list identifier for - the meta data file. + meta_plist_id is the file access property list identifier + for the metadata file.

    - raw_ext is .... + raw_ext is the filename extension for the raw data file.

    - raw_plist_id is the file property list identifier for - the raw data file. + raw_plist_id is the file access property list identifier + for the raw data file.

    Parameters:
    hid_t fapl_id, -
    IN: +
    IN: File access property list identifier.
    const char *meta_ext, -
    IN: +
    IN: Metadata filename extension.
    hid_t meta_plist_id, -
    IN: +
    IN: File access property list identifier for the metadata file.
    const char *raw_ext, -
    IN: +
    IN: Raw data filename extension.
    hid_t raw_plist_id -
    IN: +
    IN: File access property list identifier for the raw data file.
    Returns:
    Returns a non-negative value if successful. @@ -3184,13 +3227,13 @@ facilitate moving easily between them.
    Name: H5Pset_fapl_sec2
    Signature: -
    herr_t H5Psget_fapl_sec2( +
    herr_t H5Pset_fapl_sec2( hid_t fapl_id )
    Purpose:
    Sets the sec2 driver.
    Description: -
    H5Psget_fapl_sec2 modifies the file access property list +
    H5Pset_fapl_sec2 modifies the file access property list to use the H5FD_SEC2 driver.
    Parameters:
    @@ -3216,13 +3259,13 @@ facilitate moving easily between them.
    Name: H5Pset_fapl_stdio
    Signature: -
    herr_t H5Psget_fapl_stdio( +
    herr_t H5Pset_fapl_stdio( hid_t fapl_id )
    Purpose:
    Sets the standard I/O driver.
    Description: -
    H5Psget_fapl_stdio modifies the file access property list +
    H5Pset_fapl_stdio modifies the file access property list to use the standard I/O driver, H5FD_STDIO.
    Parameters:
    @@ -3363,6 +3406,8 @@ facilitate moving easily between them.
    + -
    +--> +
    @@ -3447,6 +3490,8 @@ facilitate moving easily between them.
    + -
    +--> +
    Name: H5Pset_fapl_gass
    Signature: -
    herr_t H5Psget_fapl_gass( +
    herr_t H5Pset_fapl_gass( hid_t fapl_id, GASS_Info info )
    Purpose:
    Stores user-supplied GASS information.
    Description: -
    H5Psget_fapl_gass stores user-supplied GASS information, +
    H5Pset_fapl_gass stores user-supplied GASS information, the GASS_Info struct data as passed in info, to the file access property list fapl_id. fapl_id can then be used to create and/or open the file. @@ -3516,23 +3559,20 @@ facilitate moving easily between them.

    Any modification to info after this function call returns may have undetermined effect to the access property list. - Users must call H5Psget_fapl_gass again to setup + Users must call H5Pset_fapl_gass again to setup the property list.

    Note: -
    H5Psget_fapl_gass is an experimental function. +
    H5Pset_fapl_gass is an experimental function. It is designed for use only when accessing files via the GASS facility of the Globus environment. - URL ?? + For further information, see + http//www.globus.org/.
    Parameters:
    hid_t fapl_id,
    IN: File access property list identifier.
    GASS_Info info
    IN: Pointer to the GASS information structure. - -

    - Need GASS_Info struct. -

    Returns:
    Returns a non-negative value if successful. @@ -3571,17 +3611,14 @@ facilitate moving easily between them.
    H5Pget_fapl_gass is an experimental function. It is designed for use only when accessing files via the GASS facility of the Globus environment. - URL ?? + For further information, see + http//www.globus.org/.
    Parameters:
    hid_t fapl_id,
    IN: File access property list identifier.
    GASS_Info *info
    OUT: Pointer to the GASS information structure. - -

    - Need GASS_Info struct. -

    Returns:
    Returns a non-negative value if successful. @@ -3615,13 +3652,15 @@ facilitate moving easily between them.
    H5Pget_fapl_dpss is an experimental function. It is designed for use only when accessing files via the DPSS facility of the Globus environment. - URL ?? + For further information, see + http//www.globus.org/.

    As of HDF5 Release 1.4 Beta, the Globus project has deprecated - the DPSS facility in favor of an FTP-based facility, which is still + the DPSS facility in favor of an FTP-based facility that is still under development. While the DPSS functionality is still available, - it may be unavailable in future Globus releases. + users must be aware that it was implemented purely for research purposes + and may be unavailable in future Globus releases.

    Parameters:
    hid_t fapl_id @@ -3664,8 +3703,8 @@ facilitate moving easily between them.
    Note:
    H5Pset_fapl_gass is an experimental function. It is designed for use only when accessing files via the - GASS facility of the Storage Resource Broker (SRB). - URL ?? + Storage Resource Broker (SRB). For further information, see + http//www.npaci.edu/Research/DI/srb/.
    Parameters:
    hid_t fapl_id @@ -3711,8 +3750,8 @@ facilitate moving easily between them.
    Note:
    H5Pset_fapl_gass is an experimental function. It is designed for use only when accessing files via the - GASS facility of the Storage Resource Broker (SRB). - URL ?? + Storage Resource Broker (SRB). For further information, see + http//www.npaci.edu/Research/DI/srb/.
    Parameters:
    @@ -3738,6 +3777,83 @@ facilitate moving easily between them.
    +
    Name: H5Pset_fapl_core +
    Signature: +
    herr_t H5Pset_fapl_core( + hid_t fapl_id, + size_t increment, + hbool_t backing_store + ) +
    Purpose: +
    Modifies the file access property list to use the + H5FD_CORE driver. +
    Description: +
    H5Pset_fapl_core modifies the file access property list + to use the H5FD_CORE driver. +

    + increment specifies the increment by which allocated memory + is to be increased each time more memory is required. + +

    Parameters: +
    +
    xxx xxx +
    IN: +
    OUT: +
    +
    Returns: +
    Returns a non-negative value if successful. + Otherwise returns a negative value. + + +
    + + +
    +
    +
    Name: H5Pget_fapl_core +
    Signature: +
    xxx H5Pget_fapl_core( + xxx xxx, + xxx xxx, + xxx xxx + ) +
    Purpose: +
    +
    Description: +
    H5Pget_fapl_core + +
    Parameters: +
    +
    xxx xxx +
    IN: +
    OUT: +
    +
    Returns: +
    Returns a non-negative value if successful. + Otherwise returns a negative value. + + +
    + + + + - + +
    -- cgit v0.12