summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorNeil Fortner <nfortne2@hdfgroup.org>2015-08-21 21:12:57 (GMT)
committerNeil Fortner <nfortne2@hdfgroup.org>2015-08-21 21:12:57 (GMT)
commit3c5a088df0afced706a07c92df46494741a2c9ae (patch)
tree3860f2ef3b971e9c41eba2833f9c301772916188 /src
parent32bf83f1cf00df5079d8a5e2f16422a28d1fa53d (diff)
downloadhdf5-3c5a088df0afced706a07c92df46494741a2c9ae.zip
hdf5-3c5a088df0afced706a07c92df46494741a2c9ae.tar.gz
hdf5-3c5a088df0afced706a07c92df46494741a2c9ae.tar.bz2
[svn-r27547] Fill in public function descriptions from RM entries.
Tested: ummon
Diffstat (limited to 'src')
-rw-r--r--src/H5Pdapl.c39
-rw-r--r--src/H5Pdcpl.c70
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