Last modified: 8 December 2015
Name: H5LDget_dset_elmts
Signature:
  `herr_t H5LDget_dset_elmts( hid_t dset_id, hsize_t *prev_dims, hsize_t *cur_dims, char *fields, void *buf )`
Purpose:
  Retrieves selected data from the dataset.
Description:
  This routine retrieves selected data of the dataset `dset_id` and stores the data in the parameter `buf`. The difference between the parameters `prev_dims` and `cur_dims` indicates the dimension sizes of the data to be selected from the dataset. Note that `cur_dims` must have at least one dimension whose size is greater than the corresponding dimension in `prev_dims`. Users can determine the size of `buf` by multipling the datatype size of the dataset by the number of selected elements.

  If the parameter `fields` is NULL, this routine returns data for the selected elements of the dataset. If `fields` is not NULL and the dataset has a compound datatype, `fields` is a string containing a comma-separated list of fields. Each name in `fields` specifies a field in the compound datatype, and this routine returns data of the selected fields for the dataset's selected elements. Note that ’,’ is the separator for the fields of a compound datatype while ’.’ is the separator for a nested field. Use backslash to escape characters in field names that conflict with these two separators.

Parameters:

  `hid_t dset_id` | IN: The dataset identifier
  `hsize_t *prev_dims` | IN: The previous dimension size of the dataset
  `hsize_t *cur_dims` | IN: The current dimension size of the dataset
  `char *fields` | IN: A string containing a comma-separated list of fields for a compound datatype.
  `void *buf` | OUT: Buffer for storing data retrieved from the dataset

Returns:
  If successful, returns zero; otherwise returns a negative value.
Example Usage:
  For the first example, `DSET1` is a two-dimensional chunked dataset with atomic type defined below:

          DATASET "DSET1" {
      	DATATYPE  H5T_STD_I32LE
      	DATASPACE  SIMPLE { ( 4, 13 ) / ( 60, 100 ) }
      	:
      	:
          }

  The following coding sample illustrates the reading of data elements appended to the dataset `DSET1`:

          /* open the HDF5 file */
          fid = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);

          /* open the dataset */
          did = H5Dopen2(fid, "DSET1", H5P_DEFAULT);
              :
              :
          /* define hsize_t dims[2]; */
          /* define hsize_t new_dims[2]; */
          /* get the dataset's current dimension sizes */
          H5LDget_dset_dims(did, dims);

          /* extend the dataset by 2 */
          new_dims[0] = dims[0] + 2;
          new_dims[1] = dims[1] + 2;
          H5Dset_extent(did, new_dims)

          /* write data to the extended dataset */
              :
              :
          /* get the size of the dataset's data type */
          type_size = H5LDget_dset_type_size(did, NULL);
              :
              :
          /* allocate buffer for storing selected data elements from the dataset */
          /* calculate # of selected elements from dims & new_dims */
          /* buffer size = type_size * number of selected elements */
              :
              :
          /* read the selected elements from the dataset into buf */
          H5LDget_dset_elmts(did, dims, new_dims, NULL, buf);
              :
              :
          H5Dclose(did);
          H5Fclose(fid);

  The output buffer will contain data elements selected from `DSET1` as follows:

          data for elements (0, 13), (0, 14)
          data for elements (1, 13), (1, 14)
          data for elements (2, 13), (2, 14)
          data for elements (3, 13), (3, 14)
          data for elements (4, 0), (4, 1), (4, 2)......................(4, 13), (4, 14)
          data for elements (5, 0), (5, 1), (5, 2)......................(5, 13), (5, 14)

  For the second example, `DSET2` is a one-dimensional chunked dataset with compound type defined below:

          DATASET "DSET2" {
      	DATATYPE  H5T_COMPOUND {
      	    H5T_STD_I32LE "a";
      	    H5T_STD_I32LE "b";
      	    H5T_ARRAY { [4] H5T_STD_I32LE } "c";
      	    H5T_STD_I32LE "d";
      	    H5T_STD_I32LE "e";
      	    H5T_COMPOUND {
      		H5T_STD_I32LE "a";
      		H5T_STD_I32LE "b";
      		H5T_ARRAY {[4] H5T_STD_I32LE} "c";
      		H5T_STD_I32LE "d";
      		H5T_STD_I32LE "e";
      	    } "s2";
      	}
      	DATASPACE  SIMPLE { ( 5 ) / ( 5 ) }
      	:
      	:
          }

  The following coding sample illustrates the reading of data elements appended to the dataset `DSET2` with compound datatype This example selects only 2 fields: the fourth field `d` and a subfield of the sixth field `s2.c`:

          /* open the HDF5 file */
          fid = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);

          /* open the dataset */
          did = H5Dopen2(fid, "DSET2", H5P_DEFAULT);

          /* define hsize_t dims[1]; */
          /* define hsize_t new_dims[1]; */
              :
              :
          /* get the dataset's current dimension size */
          H5LDget_dset_dims(did, dims);

          /* extend the dataset by 2 */
          new_dims[0] = dims[0] + 2;
          H5Dset_extent(did, new_dims);
              :
              :
          /* write data to the extended part of the dataset */
              :
              :
          /* #define fields "d,s2.c" */
          /* get the size of the dataset's data type for the selected fields */
          type_size = H5LDget_dset_type_size(did, fields);
              :
              :
          /* allocate buffer for storing selected data elements from the dataset */
          /* calculate # of selected elements from dims & new_dims */
          /* buffer size = type_size * number of selected elements */
              :
              :
          /* read the selected elements from the dataset into buf */
          H5LD_get_dset_elmts(did, dims, new_dims, fields, buf);
              :
              :
          H5Dclose(did);
          H5Fclose(fid);

  The output buffer will contain data for `d` and `s2.c` selected from `DSET2` as follows:

          Data for element (5): integer value for "d", 4 integer values for array "s2.c"
          Data for element (6): integer value for "d", 4 integer values for array "s2.c"

Fortran Interface:
  None
See Also:

- H5LDget_dset_type_size
- H5LDget_dset_dims
- H5LDget_dset_elmts
- h5watch

History:

  Release | Change
  1.10.0 | C function introduced with this release.