Last modified: 26 April 2016

Name: H5Pset_efile_prefix

Signature:
herr_t H5Pset_efile_prefix( hid_t dapl_id, const char *prefix )

Purpose:
Sets the external dataset storage file prefix in the dataset access property list.

Description:
H5Pset_efile_prefix sets the prefix used to locate raw data files for a dataset that uses external storage. This prefix can provide either an absolute path or a relative path to the external files.

H5Pset_efile_prefix is used in conjunction with H5Pset_external to control the behavior of the HDF5 Library when searching for the raw data files associated with a dataset that uses external storage:

The HDF5_EXTFILE_PREFIX environment variable can be used to override the above behavior (the environment variable supersedes the API call). Setting the variable to a path string and calling H5Dcreate or H5Dopen is the equivalent of calling H5Pset_efile_prefix and calling the same create or open function. The environment variable is checked at the time of the create or open action and copied so it can be safely changed after the H5Dcreate or H5Dopen call.

Calling H5Pset_efile_prefix with prefix set to NULL or the empty string returns the search path to the default. The result would be the same as if H5Pset_efile_prefix had never been called.


Notes:
If the external file prefix is not an absolute path and the HDF5 file is moved, the external storage files will also need to be moved so they can be accessed at the new location.

As stated above, the use of the HDF5_EXTFILE_PREFIX environment variable overrides any property list setting. H5Pset_efile_prefix and H5Pget_efile_prefix, being property functions, set and retrieve only the property list setting; they are unaware of the environment variable.

On Windows, the prefix must be an ASCII string since the Windows standard C library’s I/O functions cannot handle UTF-8 file names.


Parameters:
hid_t dapl_id   IN: Dataset access property list identifier
const char *prefix   IN: Dataset external storage prefix in UTF-8 or ASCII
(Path and filename must be ASCII on Windows systems.)

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

Fortran Interface:
None

See Also:

History:
Release     Change
1.10.0 and 1.8.17    C function introduced in these releases.