Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Content Layer
id1195548671
Content Column
width50.00001%
id1195578110
classrm_pagetree_col mobile-hide
Content Block
id1195578111
 
Content Column
width50.00001%
id1195548673
classhdf-rm-main-column
Content Block
id1195548672

Include Content
render-without-blockstrue
page.rm-navbar
HTML Wrap
classhdf-print-only

Page Title

HTML Wrap
classhdf-rm-summary-block

Hdf rm anchor
AnchorNamesummary

Excerpt

Sets the number of read attempts in a file access property list

HTML Wrap
classhdf-rm-content-block
Note

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.

Hdf rm anchor
AnchorNameprocedure

Procedure:
HTML Wrap
classhdf-rm-section
HTML Wrap
classhdf_procedure

H5P_SET_METADATA_READ_ATTEMPTS ( plist_id, attempts )

Hdf rm anchor
AnchorNamesignature

Signature:
HTML Wrap
classhdf-rm-section
HTML Wrap
classhdf-togglebox hdf-c

HTML Add Class
hdf-togglebutton-visible
hdf-togglebutton-visible
selector.hdf-togglebutton.hdf-c

HTML
<pre><code class="language-c">herr_t H5Pset_metadata_read_attempts(
        hid_t plist_id, 
        unsigned attempts
        )
    </code></pre>

Hdf rm anchor
AnchorNameparameters

Parameters:
HTML Wrap
classhdf-rm-section
hid_t plist_idIN: Identifier for a file access property list
unsigned attempts   IN: The number of read attempts
Must be a value greater than 0

Hdf rm anchor
AnchorNamedescription

Description:
HTML Wrap
classhdf-rm-section

H5Pset

H5P_

metadata

SET_

read

METADATA_

attempts

READ_ATTEMPTS sets the number of reads that the library will try when reading checksummed metadata in an HDF5 file opened with SWMR access. When reading such metadata, the library will compare the checksum computed for the metadata just read with the checksum stored within the piece of checksum. When performing SWMR operations on a file, the checksum check might fail when the library reads data on a system that is not atomic. To remedy such situations, the library will repeatedly read the piece of metadata until the check passes or finally fails the read when the allowed number of attempts is reached.

The number of read attempts used by the library will depend on how the file is opened and whether the user sets the number of read attempts via this routine:

  • For a file opened with SWMR access:
    • If the user sets the number of attempts to N, the library will use N.
    • If the user does not set the number of attempts, the library will use the default for SWMR access (100).
  • For a file opened with non-SWMR access, the library will always use the default for non-SWMR access (1). The value set via this routine does not have any effect during non-SWMR access.

Hdf rm anchor
AnchorNamereturns

Returns:
HTML Wrap
classhdf-rm-section

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

Failure Modes:

When the user sets the number of read attempts to 0.

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

When the library is unable to set the number of read attempts in the file access property list.

Hdf rm anchor
AnchorNameexample

Example:
HTML Wrap
classhdf-rm-section

The first example illustrates the case in setting the number of read attempts for a file opened with SWMR access.

    /* 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.
     *  The library will use 20 as the number of read attempts
     *  when reading checksummed metadata in the file 
     */

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

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

The second example illustrates the case in setting the number of read attempts for a file opened with non-SWMR access. The value set in the file access property list does not have any effect.


 /* 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, 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). * The library will use 1 as the number of read attempts * when reading checksummed metadata in the file */ /* Close the property lists */ H5Pclose(fapl); H5Pclose(file_fapl); /* Close the file */ H5Fclose(fid);

Hdf rm anchor
AnchorNamehistory

History:
HTML Wrap
classhdf-rm-section
Release    Change
1.10.0C function introduced with this release.