From 3c5a088df0afced706a07c92df46494741a2c9ae Mon Sep 17 00:00:00 2001 From: Neil Fortner Date: Fri, 21 Aug 2015 16:12:57 -0500 Subject: [svn-r27547] Fill in public function descriptions from RM entries. Tested: ummon --- src/H5Pdapl.c | 39 +++++++++++++++++++++++++++++---- src/H5Pdcpl.c | 70 +++++++++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 94 insertions(+), 15 deletions(-) diff --git a/src/H5Pdapl.c b/src/H5Pdapl.c index 5574fa9..94ae0b4 100644 --- a/src/H5Pdapl.c +++ b/src/H5Pdapl.c @@ -316,7 +316,16 @@ done: /*------------------------------------------------------------------------- * Function: H5Pset_virtual_view * - * Purpose: VDSINC + * Purpose: Takes the access property list for the virtual dataset, + * dapl_id, and the flag, view, and sets the VDS view + * according to the flag value. The view will include all + * data before the first missing mapped data found if the + * flag is set to H5D_VDS_FIRST_MISSING or to include all + * available mapped data if the flag is set to + * H5D_VDS_LAST_AVAIALBLE. Missing mapped data will be + * filled with the fill value according to the VDS creation + * property settings. For VDS with unlimited mappings, the + * view defines the extent. * * Return: Non-negative on success/Negative on failure * @@ -354,7 +363,10 @@ done: /*------------------------------------------------------------------------- * Function: H5Pget_virtual_view * - * Purpose: VDSINC + * Purpose: Takes the access property list for the virtual dataset, + * dapl_id, and gets the flag, view, set by the + * H5Pset_virtual_view call. The possible values of view are + * H5D_VDS_FIRST_MISSING or H5D_VDS_LAST_AVAIALBLE. * * Return: Success: H5D_VDS_FIRST_MISSING or * H5D_VDS_LAST_AVAILABLE @@ -462,7 +474,22 @@ H5P__dacc_vds_view_dec(const void **_pp, void *_value) /*------------------------------------------------------------------------- * Function: H5Pset_virtual_printf_gap * - * Purpose: VDSINC + * Purpose: Sets the access property list for the virtual dataset, + * dapl_id, to instruct the library to stop looking for the + * mapped data stored in the files and/or datasets with the + * printf-style names after not finding gap_size files and/or + * datasets. The found source files and datasets will + * determine the extent of the unlimited VDS with the printf + * -style mappings. + * + * For example, if regularly spaced blocks of VDS are mapped + * to datasets with the names d-1, d-2, d-3, ..., d-N, ..., + * and d-2 dataset is missing and gap_size is set to 0, then + * VDS will contain only data found in d-1. If d-2 and d-3 + * are missing and gap_size is set to 2, then VDS will + * contain the data from d-1, d-3, ..., d-N, .... The blocks + * that are mapped to d-2 and d-3 will be filled according to + * the VDS fill value setting. * * Return: Non-negative on success/Negative on failure * @@ -500,7 +527,11 @@ done: /*------------------------------------------------------------------------- * Function: H5Pget_virtual_printf_gap * - * Purpose: VDSINC + * Purpose: Gets the maximum number of missing printf-style files + * and/or datasets for determining the extent of the + * unlimited VDS, gap_size, using the access property list + * for the virtual dataset, dapl_id. The default library + * value for gap_size is 0. * * Return: Non-negative on success/Negative on failure * diff --git a/src/H5Pdcpl.c b/src/H5Pdcpl.c index ebc3919..16577e7 100644 --- a/src/H5Pdcpl.c +++ b/src/H5Pdcpl.c @@ -1785,7 +1785,12 @@ done: /*------------------------------------------------------------------------- * Function: H5Pset_virtual * - * Purpose: VDSINC + * Purpose: Maps elements of the virtual dataset described by the + * virtual dataspace identifier vspace_id to the elements of + * the source dataset described by the source dataset + * dataspace identifier src_space_id. The source dataset is + * identified by the name of the file where it is located, + * src_file_name, and the name of the dataset, src_dset_name. * * As a side effect, the layout method is changed to * H5D_VIRTUAL. @@ -1981,7 +1986,9 @@ done: /*------------------------------------------------------------------------- * Function: H5Pget_virtual_count * - * Purpose: VDSINC + * Purpose: Gets the number of mappings for the virtual dataset that + * has a creation property list specified by the dcpl_id + * parameter. * * Return: Non-negative on success/Negative on failure * @@ -2023,9 +2030,13 @@ done: /*------------------------------------------------------------------------- * Function: H5Pget_virtual_vspace * - * Purpose: VDSINC + * Purpose: Takes the dataset creation property list for the virtual + * dataset, dcpl_id, and the mapping index, index, and + * returns a dataspace identifier for the selection within + * the virtual dataset used in the mapping. * - * Return: VDSINC + * Return: Returns a dataspace identifier if successful; otherwise + * returns a negative value. * * Programmer: Neil Fortner * Friday, February 13, 2015 @@ -2077,9 +2088,13 @@ done: /*------------------------------------------------------------------------- * Function: H5Pget_virtual_srcspace * - * Purpose: VDSINC + * Purpose: Takes the dataset creation property list for the virtual + * dataset, dcpl_id, and the mapping index, index, and + * returns a dataspace identifier for the selection within + * the source dataset used in the mapping. * - * Return: VDSINC + * Return: Returns a dataspace identifier if successful; otherwise + * returns a negative value. * * Programmer: Neil Fortner * Saturday, February 14, 2015 @@ -2165,9 +2180,26 @@ done: /*------------------------------------------------------------------------- * Function: H5Pget_virtual_filename * - * Purpose: VDSINC + * Purpose: Takes the dataset creation property list for the virtual + * dataset, dcpl_id, and the mapping index, index, and + * retrieves a name of a file for a source dataset used in + * the mapping. * - * Return: VDSINC + * Up to size characters of the filename are returned in + * name; additional characters, if any, are not returned to + * the user application. + * + * If the length of the filename, which determines the + * required value of size, is unknown, a preliminary call to + * H5Pget_virtual_filename with the last two parameters set + * to NULL can be made. The return value of this call will + * be the size in bytes of the filename. That value, plus 1 + * for a NULL terminator, is then assigned to size for a + * second H5Pget_virtual_filename call, which will retrieve + * the actual filename. + * + * Return: Returns the length of the name if successful, otherwise + * returns a negative value. * * Programmer: Neil Fortner * Saturday, February 14, 2015 @@ -2212,9 +2244,25 @@ done: /*------------------------------------------------------------------------- * Function: H5Pget_virtual_dsetname * - * Purpose: VDSINC - * - * Return: VDSINC + * Purpose: Takes the dataset creation property list for the virtual + * dataset, dcpl_id, and the mapping index, index, and + * retrieves the name of a source dataset used in the mapping. + * + * Up to size characters of the name are returned in name; + * additional characters, if any, are not returned to the + * user application. + * + * If the length of the filename, which determines the + * required value of size, is unknown, a preliminary call to + * H5Pget_virtual_dsetname with the last two parameters set + * to NULL can be made. The return value of this call will + * be the size in bytes of the filename. That value, plus 1 + * for a NULL terminator, is then assigned to size for a + * second H5Pget_virtual_dsetname call, which will retrieve + * the actual filename. + * + * Return: Returns the length of the name if successful, otherwise + * returns a negative value. * * Programmer: Neil Fortner * Saturday, February 14, 2015 -- cgit v0.12