Last modified: 8 December 2015

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:

History:

Release	Change
1.10.0	C function introduced with this release.