Page tree

The license could not be verified: License Certificate has expired!

 

JAVA

FORTRAN

C++

C

 

Link

H5P_GET_METADATA_READ_ATTEMPTS

Retrieves the number of read attempts from a file access property list

Motivation:

On a system that is not atomic, the library might possibly read inconsistent metadata with checksum when performing single-writer/multiple-reader (SWMR) operations for an HDF5 file. Upon encountering such situations, the library will try reading the metadata again to obtain consistent data. This routine provides the means to set the number of read attempts other than the library default.

 

Procedure:

H5P_GET_METADATA_READ_ATTEMPTS ( plist_id, attempts )

Signature:

herr_t  H5Pget_metadata_read_attempts(
              hid_t  plist_id,
              unsigned *attempts
        )
    

Parameters:
hid_t plist_id IN: Identifier for a file access property list
unsigned *attempts   OUT: The number of read attempts

Description:

H5Pget_metadata_read_attempts retrieves the number of read attempts that is set in the file access property list plist_id.

For a default file access property list, the value retrieved will depend on whether the user sets the number of attempts via H5Pset_metadata_read_attempts:

  • If the number of attempts is set to N, the value returned will be N.
  • If the number of attempts is not set, the value returned will be the default for non-SWMR access (1). SWMR is short for single-writer/multiple-reader.

For the file access property list of a specified HDF5 file, the value retrieved will depend on how the file is opened and whether the user sets the number of read attempts via H5Pset_metadata_read_attempts:

  • For a file opened with SWMR access:
    • If the number of attempts is set to N, the value returned will be N.
    • If the number of attempts is not set, the value returned will be the default for SWMR access (100).
  • For a file opened without SWMR access, the value retrieved will always be the default for non-SWMR access (1). The value set via H5Pset_metadata_read_attempts does not have any effect on non-SWMR access.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Failure Modes:

When the input property list is not a file access property list.

When the library is unable to retrieve the number of read attempts from the file access property list.

 

Example:

The first example illustrates the two cases for retrieving the number of read attempts from a default file access property list.


/* Get a copy of file access property list */ fapl = H5Pcreate(H5P_FILE_ACCESS); /* Retrieve the # of read attempts from the file access property list */ H5Pget_metadata_read_attempts(fapl, &attempts); /* * The value returned in "attempts" will be 1 (default for non-SWMR access). */ /* Set the # of read attempts to 20 */ H5Pset_metadata_read_attempts(fapl, 20); /* Retrieve the # of read attempts from the file access property list */ H5Pget_metadata_read_attempts(fapl, &attempts); /* * The value returned in "attempts" will be 20 as set. */ /* Close the property list */ H5Pclose(fapl);

 

The second example illustrates the two cases for retrieving the number of read attempts from the file access property list of a file opened with SWMR acccess.


 /* Open the file with SWMR access and default file access property list */ fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), H5P_DEFAULT); /* Get the file's file access roperty list */ file_fapl = H5Fget_access_plist(fid); /* Retrieve the # of read attempts from the file's file access property list */ H5Pget_metadata_read_attempts(file_fapl, &attempts); /* * The value returned in "attempts" will be 100 (default for SWMR access). */ /* Close the property list */ H5Pclose(file_fapl); /* Close the file */ H5Fclose(fid); /* Create a copy of file access property list */ fapl = H5Pcreate(H5P_FILE_ACCESS); /* Set the # of read attempts */ H5Pset_metadata_read_attempts(fapl, 20); /* Open the file with SWMR access and the non-default file access property list */ fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), fapl); /* Get the file's file access roperty list */ file_fapl = H5Fget_access_plist(fid); /* Retrieve the # of read attempts from the file's file access property list */ H5Pget_metadata_read_attempts(file_fapl, &attempts); /* * The value returned in "attempts" will be 20. */ /* Close the property lists */ H5Pclose(file_fapl); H5Pclose(fapl); /* Close the file */ H5Fclose(fid);

 

The third example illustrates the two cases for retrieving the number of read attempts from the file access property list of a file opened with non-SWMR acccess.

 

    /* Open the file with non-SWMR access and default file access property list */
    fid = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT);

    /* Get the file's file access roperty list */
    file_fapl = H5Fget_access_plist(fid);

    /* Retrieve the # of read attempts from the file's file access property list */
    H5Pget_metadata_read_attempts(file_fapl, &attempts);

    /*
     *  The value returned in "attempts" will be 1 (default for non-SWMR access).
     */

    /* Close the property list */	    
    H5Pclose(file_fapl);

    /* Close the file */
    H5Fclose(fid);

    /* Create a copy of file access property list */
    fapl = H5Pcreate(H5P_FILE_ACCESS);

    /* Set the # of read attempts */
    H5Pset_metadata_read_attempts(fapl, 20);

    /* Open the file with non-SWMR access and the non-default file access property list */
    fid = H5Fopen(FILE, H5F_ACC_RDONLY, fapl);

    /* Get the file's file access roperty list */
    file_fapl = H5Fget_access_plist(fid);

    /* Retrieve the # of read attempts from the file's file access property list */
    H5Pget_metadata_read_attempts(file_fapl, &attempts);

    /*
     *  The value returned in "attempts" will be 1 (default for non-SWMR access).
     */

    /* Close the property lists */	    
    H5Pclose(file_fapl);
    H5Pclose(fapl);

    /* Close the file */
    H5Fclose(fid);

History:
Release    Change
1.10.0C function introduced with this release.

--- Last Modified: January 03, 2018 | 02:32 PM