Last modified: 22 April 2011
Name: H5Pset_external
Signature:
  herr_t `H5Pset_external`(hid_t `plist`, const char `*name`, off_t `offset`, hsize_t `size` )

Purpose:
  Adds an external file to the list of external files.

Description:
  The first call to `H5Pset_external` sets the external storage property in the property list, thus designating that the dataset will be stored in one or more non-HDF5 file(s) external to the HDF5 file. This call also adds the file `name` as the first file in the list of external files. Subsequent calls to the function add the named file as the next file in the list.

  If a dataset is split across multiple files, then the files should be defined in order. The total size of the dataset is the sum of the `size` arguments for all the external files. If the total size is larger than the size of a dataset then the dataset can be extended (provided the data space also allows the extending).

  The `size` argument specifies the number of bytes reserved for data in the external file. If `size` is set to `H5F_UNLIMITED`, the external file can be of unlimited size and no more files can be added to the external files list. If `size` is set to `0` (zero), no external file will actually be created.

  All of the external files for a given dataset must be specified with `H5Pset_external` before `H5Dcreate` is called to create the dataset. If one these files does not exist on the system when `H5Dwrite` is called to write data to it, the library will create the file.

Parameters:

  hid_t `plist` | IN: Identifier of a dataset creation property list.
  const char `*name` | IN: Name of an external file.
  off_t `offset` | IN: Offset, in bytes, from the beginning of the file to the location in the file where the data starts.
  hsize_t `size` | IN: Number of bytes reserved in the file for the data.

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

Fortran90 Interface: h5pset_external_f

      SUBROUTINE h5pset_external_f(prp_id, name, offset,bytes, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: prp_id  ! Property list identifier
        CHARACTER(LEN=*), INTENT(IN) :: name  ! Name of an external file
        INTEGER, INTENT(IN) :: offset         ! Offset, in bytes, from the
                                              ! beginning of the file to the
                                              ! location in the file where
                                              ! the data starts
        INTEGER(HSIZE_T), INTENT(IN) :: bytes ! Number of bytes reserved in
                                              ! the file for the data
        INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                              ! 0 on success and -1 on failure
      END SUBROUTINE h5pset_external_f