summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDana Robinson <derobins@hdfgroup.org>2020-06-04 06:06:48 (GMT)
committerDana Robinson <derobins@hdfgroup.org>2020-06-04 06:06:48 (GMT)
commit1f37602ba10e58ee44afd187dc15b0911002f180 (patch)
tree0c8b3275c5654864918dbeb6c3c07c3e5d9d74aa
parent9c18bb99e893fe87e1359f55796f542e9961d27d (diff)
downloadhdf5-1f37602ba10e58ee44afd187dc15b0911002f180.zip
hdf5-1f37602ba10e58ee44afd187dc15b0911002f180.tar.gz
hdf5-1f37602ba10e58ee44afd187dc15b0911002f180.tar.bz2
Normalization of H5D.c with develop.
-rw-r--r--src/H5D.c516
1 files changed, 246 insertions, 270 deletions
diff --git a/src/H5D.c b/src/H5D.c
index 7030759..4828aaf 100644
--- a/src/H5D.c
+++ b/src/H5D.c
@@ -21,12 +21,12 @@
/***********/
/* Headers */
/***********/
-#include "H5private.h" /* Generic Functions */
-#include "H5CXprivate.h" /* API Contexts */
-#include "H5Dpkg.h" /* Datasets */
-#include "H5Eprivate.h" /* Error handling */
-#include "H5FLprivate.h" /* Free lists */
-#include "H5Iprivate.h" /* IDs */
+#include "H5private.h" /* Generic Functions */
+#include "H5CXprivate.h" /* API Contexts */
+#include "H5Dpkg.h" /* Datasets */
+#include "H5Eprivate.h" /* Error handling */
+#include "H5FLprivate.h" /* Free lists */
+#include "H5Iprivate.h" /* IDs */
/****************/
@@ -73,31 +73,28 @@ H5FL_BLK_EXTERN(type_conv);
/*-------------------------------------------------------------------------
- * Function: H5Dcreate2
+ * Function: H5Dcreate2
*
- * Purpose: Creates a new dataset named NAME at LOC_ID, opens the
- * dataset for access, and associates with that dataset constant
- * and initial persistent properties including the type of each
- * datapoint as stored in the file (TYPE_ID), the size of the
- * dataset (SPACE_ID), and other initial miscellaneous
- * properties (DCPL_ID).
+ * Purpose: Creates a new dataset named NAME at LOC_ID, opens the
+ * dataset for access, and associates with that dataset constant
+ * and initial persistent properties including the type of each
+ * datapoint as stored in the file (TYPE_ID), the size of the
+ * dataset (SPACE_ID), and other initial miscellaneous
+ * properties (DCPL_ID).
*
- * All arguments are copied into the dataset, so the caller is
- * allowed to derive new types, dataspaces, and creation
- * parameters from the old ones and reuse them in calls to
- * create other datasets.
+ * All arguments are copied into the dataset, so the caller is
+ * allowed to derive new types, dataspaces, and creation
+ * parameters from the old ones and reuse them in calls to
+ * create other datasets.
*
- * Return: Success: The object ID of the new dataset. At this
- * point, the dataset is ready to receive its
- * raw data. Attempting to read raw data from
- * the dataset will probably return the fill
- * value. The dataset should be closed when the
- * caller is no longer interested in it.
+ * Return: Success: The object ID of the new dataset. At this
+ * point, the dataset is ready to receive its
+ * raw data. Attempting to read raw data from
+ * the dataset will probably return the fill
+ * value. The dataset should be closed when the
+ * caller is no longer interested in it.
*
- * Failure: FAIL
- *
- * Programmer: Quincey Koziol
- * Thursday, April 5, 2007
+ * Failure: H5I_INVALID_HID
*
*-------------------------------------------------------------------------
*/
@@ -106,35 +103,39 @@ H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id,
hid_t lcpl_id, hid_t dcpl_id, hid_t dapl_id)
{
H5G_loc_t loc; /* Object location to insert dataset into */
- H5D_t *dset = NULL; /* New dataset's info */
+ H5D_t *dset = NULL; /* New dataset's info */
const H5S_t *space; /* Dataspace for dataset */
- hid_t ret_value; /* Return value */
+ hid_t ret_value = H5I_INVALID_HID; /* Return value */
- FUNC_ENTER_API(FAIL)
+ FUNC_ENTER_API(H5I_INVALID_HID)
H5TRACE7("i", "i*siiiii", loc_id, name, type_id, space_id, lcpl_id, dcpl_id,
dapl_id);
/* Check arguments */
+ if(!name)
+ HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, H5I_INVALID_HID, "name parameter cannot be NULL")
+ if(!*name)
+ HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, H5I_INVALID_HID, "name parameter cannot be an empty string")
if(H5G_loc(loc_id, &loc) < 0)
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location ID")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a location ID")
if(H5I_DATATYPE != H5I_get_type(type_id))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a datatype ID")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a datatype ID")
if(NULL == (space = (const H5S_t *)H5I_object_verify(space_id, H5I_DATASPACE)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataspace ID")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a dataspace ID")
- /* Get correct property list */
+ /* Get link creation property list */
if(H5P_DEFAULT == lcpl_id)
lcpl_id = H5P_LINK_CREATE_DEFAULT;
else
if(TRUE != H5P_isa_class(lcpl_id, H5P_LINK_CREATE))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not link creation property list")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "lcpl_id is not a link creation property list")
- /* Get correct property list */
+ /* Get dataset creation property list */
if(H5P_DEFAULT == dcpl_id)
dcpl_id = H5P_DATASET_CREATE_DEFAULT;
else
if(TRUE != H5P_isa_class(dcpl_id, H5P_DATASET_CREATE))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not dataset create property list ID")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "dcpl_id is not a dataset create property list ID")
/* Set the DCPL for the API context */
H5CX_set_dcpl(dcpl_id);
@@ -146,53 +147,52 @@ H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id,
if(H5CX_set_apl(&dapl_id, H5P_CLS_DACC, loc_id, TRUE) < 0)
HGOTO_ERROR(H5E_DATASET, H5E_CANTSET, H5I_INVALID_HID, "can't set access property list info")
- /* Create the new dataset & get its ID */
+ /* Create the dataset */
if(NULL == (dset = H5D__create_named(&loc, name, type_id, space, lcpl_id, dcpl_id, dapl_id)))
- HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, FAIL, "unable to create dataset")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, H5I_INVALID_HID, "unable to create dataset")
+
+ /* Get an ID for the dataset */
if((ret_value = H5I_register(H5I_DATASET, dset, TRUE)) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, FAIL, "unable to register dataset")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to register dataset")
done:
- if(ret_value < 0)
+ if(H5I_INVALID_HID == ret_value)
if(dset && H5D_close(dset) < 0)
- HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, FAIL, "unable to release dataset")
+ HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, H5I_INVALID_HID, "unable to release dataset")
FUNC_LEAVE_API(ret_value)
} /* end H5Dcreate2() */
/*-------------------------------------------------------------------------
- * Function: H5Dcreate_anon
+ * Function: H5Dcreate_anon
*
- * Purpose: Creates a new dataset named NAME at LOC_ID, opens the
- * dataset for access, and associates with that dataset constant
- * and initial persistent properties including the type of each
- * datapoint as stored in the file (TYPE_ID), the size of the
- * dataset (SPACE_ID), and other initial miscellaneous
- * properties (DCPL_ID).
+ * Purpose: Creates a new dataset named NAME at LOC_ID, opens the
+ * dataset for access, and associates with that dataset constant
+ * and initial persistent properties including the type of each
+ * datapoint as stored in the file (TYPE_ID), the size of the
+ * dataset (SPACE_ID), and other initial miscellaneous
+ * properties (DCPL_ID).
*
- * All arguments are copied into the dataset, so the caller is
- * allowed to derive new types, dataspaces, and creation
- * parameters from the old ones and reuse them in calls to
- * create other datasets.
+ * All arguments are copied into the dataset, so the caller is
+ * allowed to derive new types, dataspaces, and creation
+ * parameters from the old ones and reuse them in calls to
+ * create other datasets.
*
* The resulting ID should be linked into the file with
* H5Olink or it will be deleted when closed.
*
- * Return: Success: The object ID of the new dataset. At this
- * point, the dataset is ready to receive its
- * raw data. Attempting to read raw data from
- * the dataset will probably return the fill
- * value. The dataset should be linked into
- * the group hierarchy before being closed or
- * it will be deleted. The dataset should be
- * closed when the caller is no longer interested
- * in it.
- *
- * Failure: FAIL
+ * Return: Success: The object ID of the new dataset. At this
+ * point, the dataset is ready to receive its
+ * raw data. Attempting to read raw data from
+ * the dataset will probably return the fill
+ * value. The dataset should be linked into
+ * the group hierarchy before being closed or
+ * it will be deleted. The dataset should be
+ * closed when the caller is no longer interested
+ * in it.
*
- * Programmer: James Laird
- * Tuesday, January 24, 2006
+ * Failure: H5I_INVALID_HID
*
*-------------------------------------------------------------------------
*/
@@ -201,25 +201,25 @@ H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id,
hid_t dapl_id)
{
H5G_loc_t loc; /* Object location to insert dataset into */
- H5D_t *dset = NULL; /* New dataset's info */
+ H5D_t *dset = NULL; /* New dataset's info */
const H5S_t *space; /* Dataspace for dataset */
- hid_t ret_value; /* Return value */
+ hid_t ret_value = H5I_INVALID_HID; /* Return value */
- FUNC_ENTER_API(FAIL)
+ FUNC_ENTER_API(H5I_INVALID_HID)
H5TRACE5("i", "iiiii", loc_id, type_id, space_id, dcpl_id, dapl_id);
/* Check arguments */
if(H5G_loc(loc_id, &loc) < 0)
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location ID")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a location ID")
if(H5I_DATATYPE != H5I_get_type(type_id))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a datatype ID")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a datatype ID")
if(NULL == (space = (const H5S_t *)H5I_object_verify(space_id, H5I_DATASPACE)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataspace ID")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a dataspace ID")
if(H5P_DEFAULT == dcpl_id)
dcpl_id = H5P_DATASET_CREATE_DEFAULT;
else
if(TRUE != H5P_isa_class(dcpl_id, H5P_DATASET_CREATE))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not dataset create property list ID")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not dataset create property list ID")
/* Verify access property list and set up collective metadata if appropriate */
if(H5CX_set_apl(&dapl_id, H5P_CLS_DACC, loc_id, TRUE) < 0)
@@ -227,11 +227,11 @@ H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id,
/* build and open the new dataset */
if(NULL == (dset = H5D__create(loc.oloc->file, type_id, space, dcpl_id, dapl_id)))
- HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, FAIL, "unable to create dataset")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, H5I_INVALID_HID, "unable to create dataset")
/* Register the new dataset to get an ID for it */
if((ret_value = H5I_register(H5I_DATASET, dset, TRUE)) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, FAIL, "unable to register dataset")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to register dataset")
done:
/* Release the dataset's object header, if it was created */
@@ -240,36 +240,34 @@ done:
/* Get the new dataset's object location */
if(NULL == (oloc = H5D_oloc(dset)))
- HDONE_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "unable to get object location of dataset")
+ HDONE_ERROR(H5E_DATASET, H5E_CANTGET, H5I_INVALID_HID, "unable to get object location of dataset")
/* Decrement refcount on dataset's object header in memory */
if(H5O_dec_rc_by_loc(oloc) < 0)
- HDONE_ERROR(H5E_DATASET, H5E_CANTDEC, FAIL, "unable to decrement refcount on newly created object")
- } /* end if */
+ HDONE_ERROR(H5E_DATASET, H5E_CANTDEC, H5I_INVALID_HID, "unable to decrement refcount on newly created object")
+ }
/* Cleanup on failure */
- if(ret_value < 0)
+ if(H5I_INVALID_HID == ret_value)
if(dset && H5D_close(dset) < 0)
- HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, FAIL, "unable to release dataset")
+ HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, H5I_INVALID_HID, "unable to release dataset")
FUNC_LEAVE_API(ret_value)
} /* end H5Dcreate_anon() */
/*-------------------------------------------------------------------------
- * Function: H5Dopen2
+ * Function: H5Dopen2
*
- * Purpose: Finds a dataset named NAME at LOC_ID, opens it, and returns
- * its ID. The dataset should be close when the caller is no
- * longer interested in it.
+ * Purpose: Finds a dataset named NAME at LOC_ID, opens it, and returns
+ * its ID. The dataset should be close when the caller is no
+ * longer interested in it.
*
* Takes a dataset access property list
*
- * Return: Success: A new dataset ID
- * Failure: FAIL
+ * Return: Success: Object ID of the dataset
*
- * Programmer: James Laird
- * Thursday, July 27, 2006
+ * Failure: H5I_INVALID_HID
*
*-------------------------------------------------------------------------
*/
@@ -278,16 +276,18 @@ H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id)
{
H5D_t *dset = NULL;
H5G_loc_t loc; /* Object location of group */
- hid_t ret_value;
+ hid_t ret_value = H5I_INVALID_HID; /* Return value */
- FUNC_ENTER_API(FAIL)
+ FUNC_ENTER_API(H5I_INVALID_HID)
H5TRACE3("i", "i*si", loc_id, name, dapl_id);
/* Check args */
if(H5G_loc(loc_id, &loc) < 0)
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a location")
- if(!name || !*name)
- HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no name")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a location")
+ if(!name)
+ HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, H5I_INVALID_HID, "name parameter cannot be NULL")
+ if(!*name)
+ HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, H5I_INVALID_HID, "name parameter cannot be an empty string")
/* Verify access property list and set up collective metadata if appropriate */
if(H5CX_set_apl(&dapl_id, H5P_CLS_DACC, loc_id, FALSE) < 0)
@@ -295,16 +295,16 @@ H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id)
/* Open the dataset */
if(NULL == (dset = H5D__open_name(&loc, name, dapl_id)))
- HGOTO_ERROR(H5E_DATASET, H5E_CANTOPENOBJ, FAIL, "unable to open dataset")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTOPENOBJ, H5I_INVALID_HID, "unable to open dataset")
/* Register an atom for the dataset */
if((ret_value = H5I_register(H5I_DATASET, dset, TRUE)) < 0)
- HGOTO_ERROR(H5E_ATOM, H5E_CANTREGISTER, FAIL, "can't register dataset atom")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, H5I_INVALID_HID, "can't register dataset atom")
done:
- if(ret_value < 0)
+ if(H5I_INVALID_HID == ret_value)
if(dset && H5D_close(dset) < 0)
- HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, FAIL, "unable to release dataset")
+ HDONE_ERROR(H5E_DATASET, H5E_CLOSEERROR, H5I_INVALID_HID, "unable to release dataset")
FUNC_LEAVE_API(ret_value)
} /* end H5Dopen2() */
@@ -313,15 +313,12 @@ done:
/*-------------------------------------------------------------------------
* Function: H5Dclose
*
- * Purpose: Closes access to a dataset (DATASET_ID) and releases
- * resources used by it. It is illegal to subsequently use that
- * same dataset ID in calls to other dataset functions.
+ * Purpose: Closes access to a dataset and releases resources used by
+ * it. It is illegal to subsequently use that same dataset
+ * ID in calls to other dataset functions.
*
* Return: Non-negative on success/Negative on failure
*
- * Programmer: Robb Matzke
- * Thursday, December 4, 1997
- *
*-------------------------------------------------------------------------
*/
herr_t
@@ -334,10 +331,9 @@ H5Dclose(hid_t dset_id)
/* Check args */
if(NULL == H5I_object_verify(dset_id, H5I_DATASET))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset ID")
- /*
- * Decrement the counter on the dataset. It will be freed if the count
+ /* Decrement the counter on the dataset. It will be freed if the count
* reaches zero.
*/
if(H5I_dec_app_ref_always_close(dset_id) < 0)
@@ -349,36 +345,34 @@ done:
/*-------------------------------------------------------------------------
- * Function: H5Dget_space
+ * Function: H5Dget_space
*
- * Purpose: Returns a copy of the file dataspace for a dataset.
+ * Purpose: Returns a copy of the file dataspace for a dataset.
*
- * Return: Success: ID for a copy of the dataspace. The data
- * space should be released by calling
- * H5Sclose().
+ * Return: Success: ID for a copy of the dataspace. The data
+ * space should be released by calling
+ * H5Sclose().
*
- * Failure: FAIL
- *
- * Programmer: Robb Matzke
- * Wednesday, January 28, 1998
+ * Failure: H5I_INVALID_HID
*
*-------------------------------------------------------------------------
*/
hid_t
H5Dget_space(hid_t dset_id)
{
- H5D_t *dset = NULL;
- hid_t ret_value;
+ H5D_t *dset = NULL;
+ hid_t ret_value = H5I_INVALID_HID; /* Return value */
FUNC_ENTER_API(H5I_INVALID_HID)
H5TRACE1("i", "i", dset_id);
/* Check args */
if(NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a dataset")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "invalid dataset identifier")
+ /* Get the dataspace */
if((ret_value = H5D__get_space(dset)) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, H5I_INVALID_HID, "unable to get dataspace")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, H5I_INVALID_HID, "unable to get dataspace")
done:
FUNC_LEAVE_API(ret_value)
@@ -386,35 +380,30 @@ done:
/*-------------------------------------------------------------------------
- * Function: H5Dget_space_status
- *
- * Purpose: Returns the status of dataspace allocation.
- *
- * Return:
- * Success: Non-negative
+ * Function: H5Dget_space_status
*
- * Failture: Negative
+ * Purpose: Returns the status of dataspace allocation.
*
- * Programmer: Raymond Lu
+ * Return: Non-negative on success/Negative on failure
*
*-------------------------------------------------------------------------
*/
herr_t
H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation)
{
- H5D_t *dset = NULL;
- herr_t ret_value = SUCCEED;
+ H5D_t *dset = NULL;
+ herr_t ret_value = SUCCEED; /* Return value */
FUNC_ENTER_API(FAIL)
H5TRACE2("e", "i*Ds", dset_id, allocation);
- /* Check arguments */
+ /* Check args */
if(NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid dataset identifier")
- /* Read dataspace address and return */
+ /* Get dataspace status */
if(H5D__get_space_status(dset, allocation) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, FAIL, "unable to get space status")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "unable to get space status")
done:
FUNC_LEAVE_API(ret_value)
@@ -422,18 +411,15 @@ done:
/*-------------------------------------------------------------------------
- * Function: H5Dget_type
+ * Function: H5Dget_type
*
- * Purpose: Returns a copy of the file datatype for a dataset.
+ * Purpose: Returns a copy of the file datatype for a dataset.
*
- * Return: Success: ID for a copy of the datatype. The data
- * type should be released by calling
- * H5Tclose().
+ * Return: Success: ID for a copy of the datatype. The data
+ * type should be released by calling
+ * H5Tclose().
*
- * Failure: FAIL
- *
- * Programmer: Robb Matzke
- * Tuesday, February 3, 1998
+ * Failure: H5I_INVALID_HID
*
*-------------------------------------------------------------------------
*/
@@ -441,17 +427,18 @@ hid_t
H5Dget_type(hid_t dset_id)
{
H5D_t *dset; /* Dataset */
- hid_t ret_value; /* Return value */
+ hid_t ret_value = H5I_INVALID_HID; /* Return value */
- FUNC_ENTER_API(FAIL)
+ FUNC_ENTER_API(H5I_INVALID_HID)
H5TRACE1("i", "i", dset_id);
/* Check args */
if(NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "invalid dataset identifier")
+ /* Get the datatype */
if((ret_value = H5D__get_type(dset)) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, FAIL, "unable to get dataspace")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, H5I_INVALID_HID, "unable to get datatype")
done:
FUNC_LEAVE_API(ret_value)
@@ -459,18 +446,18 @@ done:
/*-------------------------------------------------------------------------
- * Function: H5Dget_create_plist
+ * Function: H5Dget_create_plist
*
- * Purpose: Returns a copy of the dataset creation property list.
+ * Purpose: Returns a copy of the dataset creation property list.
*
- * Return: Success: ID for a copy of the dataset creation
- * property list. The template should be
- * released by calling H5P_close().
+ * Return: Success: ID for a copy of the dataset creation
+ * property list. The template should be
+ * released by calling H5P_close().
*
- * Failure: FAIL
+ * Failure: H5I_INVALID_HID
*
- * Programmer: Robb Matzke
- * Tuesday, February 3, 1998
+ * Programmer: Robb Matzke
+ * Tuesday, February 3, 1998
*
*-------------------------------------------------------------------------
*/
@@ -478,17 +465,18 @@ hid_t
H5Dget_create_plist(hid_t dset_id)
{
H5D_t *dataset; /* Dataset structure */
- hid_t ret_value; /* Return value */
+ hid_t ret_value = H5I_INVALID_HID; /* Return value */
FUNC_ENTER_API(H5I_INVALID_HID)
H5TRACE1("i", "i", dset_id);
/* Check args */
if(NULL == (dataset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "not a dataset")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "invalid dataset identifier")
+ /* Get the dataset creation property list */
if((ret_value = H5D_get_create_plist(dataset)) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, H5I_INVALID_HID, "Can't get creation plist")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, H5I_INVALID_HID, "unable to get dataset creation properties")
done:
FUNC_LEAVE_API(ret_value)
@@ -496,35 +484,35 @@ done:
/*-------------------------------------------------------------------------
- * Function: H5Dget_access_plist
+ * Function: H5Dget_access_plist
*
- * Purpose: Returns a copy of the dataset creation property list.
+ * Purpose: Returns a copy of the dataset access property list.
*
* Description: H5Dget_access_plist returns the dataset access property
- * list identifier of the specified dataset.
+ * list identifier of the specified dataset.
*
- * The chunk cache parameters in the returned property lists will be
- * those used by the dataset. If the properties in the file access
- * property list were used to determine the dataset’s chunk cache
- * configuration, then those properties will be present in the
- * returned dataset access property list. If the dataset does not
- * use a chunked layout, then the chunk cache properties will be set
- * to the default. The chunk cache properties in the returned list
- * are considered to be “set”, and any use of this list will override
- * the corresponding properties in the file’s file access property
- * list.
+ * The chunk cache parameters in the returned property lists will be
+ * those used by the dataset. If the properties in the file access
+ * property list were used to determine the dataset’s chunk cache
+ * configuration, then those properties will be present in the
+ * returned dataset access property list. If the dataset does not
+ * use a chunked layout, then the chunk cache properties will be set
+ * to the default. The chunk cache properties in the returned list
+ * are considered to be “set”, and any use of this list will override
+ * the corresponding properties in the file’s file access property
+ * list.
*
- * All link access properties in the returned list will be set to the
- * default values.
+ * All link access properties in the returned list will be set to the
+ * default values.
*
- * Return: Success: ID for a copy of the dataset access
- * property list. The template should be
- * released by calling H5Pclose().
+ * Return: Success: ID for a copy of the dataset access
+ * property list. The template should be
+ * released by calling H5Pclose().
*
- * Failure: FAIL
+ * Failure: H5I_INVALID_HID
*
- * Programmer: Neil Fortner
- * Wednesday, October 29, 2008
+ * Programmer: Neil Fortner
+ * Wednesday, October 29, 2008
*
*-------------------------------------------------------------------------
*/
@@ -532,17 +520,18 @@ hid_t
H5Dget_access_plist(hid_t dset_id)
{
H5D_t *dset; /* Dataset structure */
- hid_t ret_value; /* Return value */
+ hid_t ret_value = H5I_INVALID_HID; /* Return value */
- FUNC_ENTER_API(FAIL)
+ FUNC_ENTER_API(H5I_INVALID_HID)
H5TRACE1("i", "i", dset_id);
/* Check args */
- if (NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+ if(NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "invalid dataset identifier")
+ /* Get the dataset access property list */
if((ret_value = H5D_get_access_plist(dset)) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "Can't get access plist")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, H5I_INVALID_HID, "unable to get dataset access properties")
done:
FUNC_LEAVE_API(ret_value)
@@ -550,20 +539,17 @@ done:
/*-------------------------------------------------------------------------
- * Function: H5Dget_storage_size
- *
- * Purpose: Returns the amount of storage that is required for the
- * dataset. For chunked datasets this is the number of allocated
- * chunks times the chunk size.
+ * Function: H5Dget_storage_size
*
- * Return: Success: The amount of storage space allocated for the
- * dataset, not counting meta data. The return
- * value may be zero if no data has been stored.
+ * Purpose: Returns the amount of storage that is required for the
+ * dataset. For chunked datasets this is the number of allocated
+ * chunks times the chunk size.
*
- * Failure: Zero
+ * Return: Success: The amount of storage space allocated for the
+ * dataset, not counting meta data. The return
+ * value may be zero if no data has been stored.
*
- * Programmer: Robb Matzke
- * Wednesday, April 21, 1999
+ * Failure: Zero
*
*-------------------------------------------------------------------------
*/
@@ -571,18 +557,18 @@ hsize_t
H5Dget_storage_size(hid_t dset_id)
{
H5D_t *dset; /* Dataset to query */
- hsize_t ret_value; /* Return value */
+ hsize_t ret_value = 0; /* Return value */
FUNC_ENTER_API(0)
H5TRACE1("h", "i", dset_id);
/* Check args */
if(NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, 0, "not a dataset")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, 0, "invalid dataset identifier")
- /* Set return value */
+ /* Get the storage size */
if(H5D__get_storage_size(dset, &ret_value) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, 0, "can't get size of dataset's storage")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, 0, "unable to get storage size")
done:
FUNC_LEAVE_API(ret_value)
@@ -590,16 +576,13 @@ done:
/*-------------------------------------------------------------------------
- * Function: H5Dget_offset
+ * Function: H5Dget_offset
*
- * Purpose: Returns the address of dataset in file.
+ * Purpose: Returns the address of dataset in file.
*
- * Return: Success: the address of dataset
+ * Return: Success: The address of dataset
*
- * Failure: HADDR_UNDEF
- *
- * Programmer: Raymond Lu
- * November 6, 2002
+ * Failure: HADDR_UNDEF (can also be a valid return value!)
*
*-------------------------------------------------------------------------
*/
@@ -607,7 +590,7 @@ haddr_t
H5Dget_offset(hid_t dset_id)
{
H5D_t *dset; /* Dataset to query */
- haddr_t ret_value; /* Return value */
+ haddr_t ret_value = HADDR_UNDEF; /* Return value */
FUNC_ENTER_API(HADDR_UNDEF)
H5TRACE1("a", "i", dset_id);
@@ -616,7 +599,7 @@ H5Dget_offset(hid_t dset_id)
if(NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, HADDR_UNDEF, "not a dataset")
- /* Set return value */
+ /* Get the offset */
ret_value = H5D__get_offset(dset);
done:
@@ -625,9 +608,9 @@ done:
/*-------------------------------------------------------------------------
- * Function: H5Diterate
+ * Function: H5Diterate
*
- * Purpose: This routine iterates over all the elements selected in a memory
+ * Purpose: This routine iterates over all the elements selected in a memory
* buffer. The callback function is called once for each element selected
* in the dataspace. The selection in the dataspace is modified so
* that any elements already iterated over are removed from the selection
@@ -674,11 +657,11 @@ done:
* indicating failure. The iterator can be restarted at the next
* element.
*
- * Return: Returns the return value of the last operator if it was non-zero,
+ * Return: Returns the return value of the last operator if it was non-zero,
* or zero if all elements were processed. Otherwise returns a
* negative value.
*
- * Programmer: Quincey Koziol
+ * Programmer: Quincey Koziol
* Friday, June 11, 1999
*
*-------------------------------------------------------------------------
@@ -771,9 +754,9 @@ done:
/*-------------------------------------------------------------------------
- * Function: H5Dvlen_get_buf_size
+ * Function: H5Dvlen_get_buf_size
*
- * Purpose: This routine checks the number of bytes required to store the VL
+ * Purpose: This routine checks the number of bytes required to store the VL
* data from the dataset, using the space_id for the selection in the
* dataset on disk and the type_id for the memory representation of the
* VL data, in memory. The *size value is modified according to how many
@@ -787,16 +770,15 @@ done:
* Kinda kludgy, but easier than the other method of trying to figure out
* the sizes without actually reading the data in... - QAK
*
- * Return: Non-negative on success, negative on failure
+ * Return: Non-negative on success, negative on failure
*
- * Programmer: Quincey Koziol
+ * Programmer: Quincey Koziol
* Wednesday, August 11, 1999
*
*-------------------------------------------------------------------------
*/
herr_t
-H5Dvlen_get_buf_size(hid_t dataset_id, hid_t type_id, hid_t space_id,
- hsize_t *size)
+H5Dvlen_get_buf_size(hid_t dataset_id, hid_t type_id, hid_t space_id, hsize_t *size)
{
H5D_vlen_bufsize_t vlen_bufsize = {0, 0, 0, 0, 0, 0};
H5D_t *dset; /* Dataset for operation */
@@ -816,7 +798,7 @@ H5Dvlen_get_buf_size(hid_t dataset_id, hid_t type_id, hid_t space_id,
H5I_DATATYPE != H5I_get_type(type_id) || size == NULL)
HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid argument")
if(NULL == (dset = (H5D_t *)H5I_object(dataset_id)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
if(NULL == (type = (H5T_t *)H5I_object_verify(type_id, H5I_DATATYPE)))
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not an valid base datatype")
if(NULL == (space = (H5S_t *)H5I_object_verify(space_id, H5I_DATASPACE)))
@@ -872,20 +854,17 @@ done:
vlen_bufsize.vl_tbuf = H5FL_BLK_FREE(vlen_vl_buf, vlen_bufsize.vl_tbuf);
FUNC_LEAVE_API(ret_value)
-} /* end H5Dvlen_get_buf_size() */
+} /* end H5Dvlen_get_buf_size() */
/*-------------------------------------------------------------------------
- * Function: H5Dset_extent
+ * Function: H5Dset_extent
*
- * Purpose: Modifies the dimensions of a dataset.
- * Can change to a smaller dimension.
+ * Purpose: Modifies the dimensions of a dataset.
+ * Can change to a smaller dimension.
*
* Return: Non-negative on success, negative on failure
*
- * Programmer: Pedro Vicente, pvn@ncsa.uiuc.edu
- * April 9, 2002
- *
*-------------------------------------------------------------------------
*/
herr_t
@@ -899,17 +878,17 @@ H5Dset_extent(hid_t dset_id, const hsize_t size[])
/* Check args */
if(NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "dset_id parameter is not a valid dataset identifier")
if(!size)
- HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "no size specified")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "size array cannot be NULL")
/* Set up collective metadata if appropriate */
if(H5CX_set_loc(dset_id) < 0)
HGOTO_ERROR(H5E_DATASET, H5E_CANTSET, FAIL, "can't set collective metadata read info")
- /* Private function */
+ /* Set the extent */
if(H5D__set_extent(dset, size) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, FAIL, "unable to set extend dataset")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTSET, FAIL, "unable to set dataset extent")
done:
FUNC_LEAVE_API(ret_value)
@@ -923,9 +902,6 @@ done:
*
* Return: Non-negative on success, negative on failure
*
- * Programmer: Mike McGreevy
- * May 19, 2010
- *
*-------------------------------------------------------------------------
*/
herr_t
@@ -947,7 +923,7 @@ H5Dflush(hid_t dset_id)
/* Flush dataset information cached in memory */
if(H5D__flush(dset, dset_id) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTFLUSH, FAIL, "unable to flush cached dataset info")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTFLUSH, FAIL, "unable to flush dataset")
done:
FUNC_LEAVE_API(ret_value)
@@ -961,29 +937,26 @@ done:
*
* Return: Non-negative on success, negative on failure
*
- * Programmer: Mike McGreevy
- * July 21, 2010
- *
*-------------------------------------------------------------------------
*/
herr_t
H5Drefresh(hid_t dset_id)
{
H5D_t *dset; /* Dataset to refresh */
- herr_t ret_value = SUCCEED; /* return value */
+ herr_t ret_value = SUCCEED; /* Return value */
FUNC_ENTER_API(FAIL)
H5TRACE1("e", "i", dset_id);
/* Check args */
if(NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "dset_id parameter is not a valid dataset identifier")
/* Set up collective metadata if appropriate */
if(H5CX_set_loc(dset_id) < 0)
HGOTO_ERROR(H5E_DATASET, H5E_CANTSET, FAIL, "can't set collective metadata read info")
- /* Call private function to refresh the dataset object */
+ /* Refresh the dataset object */
if((H5D__refresh(dset_id, dset)) < 0)
HGOTO_ERROR(H5E_DATASET, H5E_CANTLOAD, FAIL, "unable to refresh dataset")
@@ -996,10 +969,11 @@ done:
* Function: H5Dformat_convert (Internal)
*
* Purpose: For chunked:
- * Convert the chunk indexing type to version 1 B-tree if not
- * For compact/contiguous:
- * Downgrade layout version to 3 if greater than 3
- * For virtual: no conversion
+ * Convert the chunk indexing type to version 1 B-tree if not
+ * For compact/contiguous:
+ * Downgrade layout version to 3 if greater than 3
+ * For virtual:
+ * No conversion
*
* Return: Non-negative on success, negative on failure
*
@@ -1012,7 +986,7 @@ herr_t
H5Dformat_convert(hid_t dset_id)
{
H5D_t *dset; /* Dataset to refresh */
- herr_t ret_value = SUCCEED; /* return value */
+ herr_t ret_value = SUCCEED; /* Return value */
FUNC_ENTER_API(FAIL)
H5TRACE1("e", "i", dset_id);
@@ -1112,23 +1086,23 @@ herr_t
H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hsize_t *chunk_nbytes)
{
H5D_t *dset = NULL;
- herr_t ret_value = SUCCEED;
+ herr_t ret_value = SUCCEED; /* Return value */
FUNC_ENTER_API(FAIL)
H5TRACE3("e", "i*h*h", dset_id, offset, chunk_nbytes);
/* Check arguments */
if(NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
- if( NULL == offset )
- HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid argument (null)")
- if( NULL == chunk_nbytes )
- HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid argument (null)")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "dset_id parameter is not a valid dataset identifier")
+ if(NULL == offset)
+ HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "offset parameter cannot be NULL")
+ if(NULL == chunk_nbytes)
+ HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "chunk_nbytes parameter cannot be NULL")
if(H5D_CHUNKED != dset->shared->layout.type)
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a chunked dataset")
- /* Call private function */
+ /* Get the dataset creation property list */
if(H5D__get_chunk_storage_size(dset, offset, chunk_nbytes) < 0)
HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "can't get storage size of chunk")
@@ -1140,7 +1114,7 @@ done:
/*-------------------------------------------------------------------------
* Function: H5Dget_num_chunks
*
- * Purpose: Retrieves the number of chunks that have nonempty intersection
+ * Purpose: Retrieves the number of chunks that have non-empty intersection
* with a specified selection.
*
* Note: Currently, this function only gets the number of all written
@@ -1149,7 +1123,7 @@ done:
* Parameters:
* hid_t dset_id; IN: Chunked dataset ID
* hid_t fspace_id; IN: File dataspace ID
- * hsize_t *nchunks; OUT:: Number of non-empty chunks
+ * hsize_t *nchunks; OUT: Number of non-empty chunks
*
* Return: Non-negative on success, negative on failure
*
@@ -1163,16 +1137,16 @@ H5Dget_num_chunks(hid_t dset_id, hid_t fspace_id, hsize_t *nchunks)
{
H5D_t *dset = NULL;
const H5S_t *space; /* Dataspace for dataset */
- herr_t ret_value = SUCCEED;
+ herr_t ret_value = SUCCEED;
FUNC_ENTER_API(FAIL)
H5TRACE3("e", "ii*h", dset_id, fspace_id, nchunks);
/* Check arguments */
if(NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataset")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid dataset identifier")
if(NULL == (space = (const H5S_t *)H5I_object_verify(fspace_id, H5I_DATASPACE)))
- HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a dataspace ID")
+ HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid dataspace identifier")
if(NULL == nchunks)
HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid argument (null)")
@@ -1181,7 +1155,7 @@ H5Dget_num_chunks(hid_t dset_id, hid_t fspace_id, hsize_t *nchunks)
/* Get the number of written chunks */
if(H5D__get_num_chunks(dset, space, nchunks) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "error getting number of chunks")
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "Can't get number of chunks")
done:
FUNC_LEAVE_API(ret_value);
@@ -1196,9 +1170,10 @@ done:
* Parameters:
* hid_t dset_id; IN: Chunked dataset ID
* hid_t fspace_id; IN: File dataspace ID
- * hsize_t chk_idx; IN: Index of allocated/written chunk
- * hsize_t *offset OUT: Offset coordinates of the chunk
- * unsigned *filter_mask OUT: Filter mask
+ * hsize_t index; IN: Index of written chunk
+ * hsize_t *offset OUT: Logical position of the chunk’s
+ * first element in the dataspace
+ * unsigned *filter_mask OUT: Mask for identifying the filters in use
* haddr_t *addr OUT: Address of the chunk
* hsize_t *size OUT: Size of the chunk
*
@@ -1210,15 +1185,15 @@ done:
*-------------------------------------------------------------------------
*/
herr_t
-H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_idx, hsize_t *offset, unsigned *filter_mask, haddr_t *addr, hsize_t *size)
+H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_index, hsize_t *offset, unsigned *filter_mask, haddr_t *addr, hsize_t *size)
{
H5D_t *dset = NULL;
const H5S_t *space; /* Dataspace for dataset */
- herr_t ret_value = SUCCEED;
+ herr_t ret_value = SUCCEED;
FUNC_ENTER_API(FAIL)
- H5TRACE7("e", "iih*h*Iu*a*h", dset_id, fspace_id, chk_idx, offset, filter_mask,
- addr, size);
+ H5TRACE7("e", "iih*h*Iu*a*h", dset_id, fspace_id, chk_index, offset,
+ filter_mask, addr, size);
/* Check arguments */
if(NULL == (dset = (H5D_t *)H5I_object_verify(dset_id, H5I_DATASET)))
@@ -1232,8 +1207,8 @@ H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_idx, hsize_t *offs
HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a chunked dataset")
/* Call private function to get the chunk info given the chunk's index */
- if(H5D__get_chunk_info(dset, space, chk_idx, offset, filter_mask, addr, size) < 0)
- HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "can't get chunk info")
+ if(H5D__get_chunk_info(dset, space, chk_index, offset, filter_mask, addr, size) < 0)
+ HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "Can't get chunk info by index")
done:
FUNC_LEAVE_API(ret_value);
@@ -1243,13 +1218,14 @@ done:
/*-------------------------------------------------------------------------
* Function: H5Dget_chunk_info_by_coord
*
- * Purpose: Retrieves information about a chunk specified by its offset
+ * Purpose: Retrieves information about a chunk specified by its logical
* coordinates.
*
* Parameters:
- * hid_t dset_id IN: Chunked dataset ID
- * hsize_t *offset IN: Offset coordinates of the chunk
- * unsigned *filter_mask OUT: Filter mask
+ * hid_t dset_id; IN: Chunked dataset ID
+ * hsize_t *offset IN: Logical position of the chunk’s
+ * first element in the dataspace
+ * unsigned *filter_mask OUT: Mask for identifying the filters in use
* haddr_t *addr OUT: Address of the chunk
* hsize_t *size OUT: Size of the chunk
*