Last modified: 13 August 2013
Name: H5Dset_extent
Signature:
  herr_t `H5Dset_extent`( hid_t `dset_id`, const hsize_t `size[]` )

Purpose:
  Changes the sizes of a dataset’s dimensions.

Description:
  `H5Dset_extent` sets the current dimensions of the chunked dataset `dset_id` to the sizes specified in `size`.

  `size` is a 1-dimensional array with n elements, where n is the rank of the dataset’s current dataspace.

  This function can be applied to the following datasets:

  - A chunked dataset with unlimited dimensions
  - A chunked dataset with fixed dimensions if the new dimension sizes are less than the maximum sizes set with `maxdims` (see `H5Screate_simple`)
  - An external dataset with unlimited dimensions
  - An external dataset with fixed dimensions if the new dimension sizes are less than the maximum sizes set with `maxdims`

    Note that external datasets are always contiguous and can be extended only along the first dimension.

  Space on disk is immediately allocated for the new dataset extent if the dataset’s space allocation time is set to `H5D_ALLOC_TIME_EARLY`.

  Fill values will be written to the dataset in either of the following situations, but not otherwise:

  - If the dataset’s fill time is set to `H5D_FILL_TIME_IFSET` and a fill value is defined (see `H5Pset_fill_time` and `H5Pset_fill_value`)
  - If the dataset’s fill time is set to `H5D_FILL_TIME_ALLOC` (see `H5Pset_alloc_time`)

Notes:
  - If the sizes specified in `size` are smaller than the dataset’s current dimension sizes, `H5Dset_extent` will reduce the dataset’s dimension sizes to the specified values. It is the user application’s responsibility to ensure that valuable data is not lost as `H5Dset_extent` does not check.

  - Except for external datasets, `H5Dset_extent` is for use with chunked datasets only, not contiguous datasets.

  - If a dataset is open for either writing or reading data when `H5Dset_extent` is called, the dataset’s dataspace must be refreshed before more data is written to the dataset and should be refreshed before any further data is read. This can be accomplished with a call to `H5Dget_space`.

Parameters:

  hid_t `dset_id` | IN: Dataset identifier
  const hsize_t `size[]` | IN: Array containing the new magnitude of each dimension of the dataset.

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

Fortran90 Interface: H5Dset_extent

      SUBROUTINE h5dset_extent_f(dataset_id, size, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: dataset_id   ! Dataset identifier
        INTEGER(HSIZE_T), DIMENSION(*), INTENT(IN) :: size
                                                   ! Array containing
                                                   ! dimensions’ sizes
        INTEGER, INTENT(OUT) :: hdferr             ! Error code:
                                                   ! 0 on success and -1 on failure
      END SUBROUTINE h5dset_extent_f

See Also:

  `H5Pset_alloc_time` `H5Pset_fill_time` `H5Pset_fill_value` | `` | `H5Screate_simple` `H5Dget_space`

History:

  Release | Change
  1.6.0 | Function implemented but not supported in this release.
  1.8.0 | Function supported in this release.