Last modified: 9 December 2015

Name: H5DOappend

Signature:
herr_t H5DOappend( hid_t dset_id, hid_t dxpl_id, unsigned index, size_t num_elem, hid_t memtype, const void *buffer )

Purpose:
Appends data to a dataset along a specified dimension.

Description:
The H5DOappend routine extends a dataset by num_elem number of elements along a dimension specified by a dimension index and writes buffer of elements to the dataset. Dimension index is 0-based. Elements’ type is described by memtype.

This routine combines calling H5Dset_extent, H5Sselect_hyperslab, and H5Dwrite into a single routine that simplifies application development for the common case of appending elements to an existing dataset.

For a multi-dimensional dataset, appending to one dimension will write a contiguous hyperslab over the other dimensions. For example, if a 3-D dataset has dimension sizes (3, 5, 8), extending the 0th dimension (currently of size 3) by 3 will append 3*5*8 = 120 elements (which must be pointed to by the buffer parameter) to the dataset, making its final dimension sizes (6, 5, 8).

If a dataset has more than one unlimited dimension, any of those dimensions may be appended to, although only along one dimension per call to H5DOappend.


Parameters:
hid_t dset_id IN: Dataset identifier.
hid_t dxpl_id IN: Dataset transfer property list identifier.
unsigned index IN: Dimension number (0-based).
size_t num_elem    IN: Number of elements to add along the dimension.
hid_t memtype IN: Memory type identifier.
void *buffer IN: Data buffer.

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Example Usage:
See the example in the entry for the H5Pset_append_flush API. The example illustrates the usage of H5DOappend to append to a dataset.

Fortran Interface:
None

See Also:



History:
Release     Change
1.10.0 C function introduced with this release.