- Created by Barbara Jones, last modified on Jul 10, 2019
H5P_SET_EFILE_PREFIX
Sets the external dataset storage file prefix in the dataset access property list
Procedure:
H5P_SET_EFILE_PREFIX ( dapl_id, prefix )
Signature:
herr_t H5Pset_efile_prefix(
hid_t dapl_id,
const char *prefix
)
NONE
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.) |
Description:
H5P_SET_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.
H5P_SET_EFILE_PREFIX is used in conjunction with H5P_SET_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 default behavior of the library is to search for the dataset’s external storage raw data files in the same directory as the HDF5 file which contains the dataset.
- If the prefix is set to an absolute path, the target directory will be searched for the dataset’s external storage raw data files.
- If the prefix is set to a relative path, the target directory, relative to the current working directory, will be searched for the dataset’s external storage raw data files.
- If the prefix is set to a relative path that begins with the special token
${ORIGIN}, that directory, relative to the HDF5 file containing the dataset, will be searched for the dataset’s external storage raw data files.
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 H5D_CREATE or H5D_OPEN is the equivalent of calling H5P_SET_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 H5D_CREATE or H5D_OPEN call.
Calling H5P_SET_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 H5P_SET_EFILE_PREFIX had never been called.
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. H5P_SET_EFILE_PREFIX and H5P_GET_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.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Example:
Coming Soon!
History:
| Release | Change |
|---|---|
| 1.10.0 and 1.8.17 | C function introduced in these releases. |
--- Last Modified: July 10, 2019 | 02:29 PM