HDF5
Page tree

Expand all   Collapse all

 

Summary

Description

Example

JAVA

FORTRAN

C++

C

 

Link

H5P_SET_VIRTUAL

Sets the mapping between virtual and source datasets

Procedure:

H5P_SET_VIRTUAL ( dcpl_id, vspace_id, src_file_name, src_dset_name, src_space_id )

Signature:

herr_t H5Pset_virtual(
        hid_t dcpl_id,
        hid_t vspace_id,
        const char *src_file_name,
        const char *src_dset_name,
        hid_t src_space_id
        )
    

Fortran Interface: h5pset_virtual_f
 
Signature:
  SUBROUTINE h5pset_virtual_f(dcpl_id, vspace_id, src_file_name, 
                              src_dset_name, src_space_id, hdferr)
    INTEGER(HID_T), INTENT(IN)   :: dcpl_id
    INTEGER(HID_T), INTENT(IN)   :: vspace_id
    CHARACTER(LEN=*), INTENT(IN) :: src_file_name
    CHARACTER(LEN=*), INTENT(IN) :: src_dset_name
    INTEGER(HID_T), INTENT(IN)   :: src_space_id
    INTEGER, INTENT(OUT)         :: hdferr


Inputs:
  dcpl_id       - The identifier of the dataset creation property list that 
                  will be used when creating the virtual dataset.
  vspace_id     - The dataspace identifier with the selection within the virtual 
                  dataset applied, possibly an unlimited selection.
  src_file_name - The name of the HDF5 file where the source dataset is located.
  src_dset_name - The path to the HDF5 dataset in the file specified by 
                  src_file_name.
  src_space_id  - The source dataset's dataspace identifier with a selection 
                  applied, possibly an unlimited selection


Outputs:
  hdferr  - Returns 0 if successful and -1 if fails

Parameters:
hid_t dcpl_idIN: The identifier of the dataset creation property list that will be used when creating the virtual dataset
hid_t vspace_idIN: The dataspace identifier with the selection within the virtual dataset applied, possibly an unlimited selection
const char *src_file_nameIN: The name of the HDF5 file where the source dataset is located or a "." (period) for a source dataset in the same file. The file might not exist yet. The name can be specified using a C-style printf statement as described below.
const char *src_dset_nameIN: The path to the HDF5 dataset in the file specified by src_file_name. The dataset might not exist yet. The dataset name can be specified using a C-style printf statement as described below.
hid_t src_space_idIN: The source dataset’s dataspace identifier with a selection applied, possibly an unlimited selection

Description:

H5P_SET_VIRTUAL maps elements of the virtual dataset (VDS) described by the virtual dataspace identifier vspace_id to the elements of the source dataset described by the source dataset dataspace identifier src_space_id. The source dataset is identified by the name of the file where it is located, src_file_name, and the name of the dataset, src_dset_name.

C-style printf Formatting Statements:

C-style printf formatting allows a pattern to be specified in the name of a source file or dataset. Strings for the file and dataset names are treated as literals except for the following substitutions:

"%%"Replaced with a single "%" (percent) character.
"%<d>b"

Where "<d> is the virtual dataset dimension axis (0-based) and "b" indicates that the block count of the selection in that dimension should be used. The full expression (for example, "%0b") is replaced with a single numeric value when the mapping is evaluated at VDS access time. Example code for many source and virtual dataset mappings is available in the “Examples of Source to Virtual Dataset Mapping” chapter in the RFC: HDF5 Virtual Dataset.

 

If the printf form is used for the source file or dataset names, the selection in the source dataset’s dataspace must be fixed-size.

 

Source File Resolutions:

When a source dataset residing in a different file is accessed, the library will search for the source file src_file_name as described below:

  • If src_file_name is a "." (period) then it refers to the file containing the virtual dataset.
  • If src_file_name is a relative pathname, the following steps are performed:
    • The library will get the prefix(es) set in the environment variable HDF5_VDS_PREFIX and will try to prepend each prefix to src_file_name to form a new src_file_name.
      If the new src_file_name does not exist or if HDF5_VDS_PREFIX is not set, the library will get the prefix set via H5P_SET_VIRTUAL_PREFIX and prepend it to src_file_name to form a new src_file_name. If the new src_file_name does not exist or no prefix is being set by H5P_SET_VIRTUAL_PREFIX then the path of the file containing the virtual dataset is obtained. This path can be the absolute path or the current working directory plus the relative path of that file when it is created/opened. The library will prepend this path to src_file_name to form a new src_file_name.
    • If the new src_file_name does not exist, then the library will look for src_file_name and will return failure/success accordingly.
  • If src_file_name is an absolute pathname, the library will first try to find src_file_name. If src_file_name does not exist, src_file_name is stripped of directory paths to form a new src_file_name. The search for the new src_file_name then follows the same steps as described above for a relative pathname. See examples below illustrating how src_file_name is stripped to form a new src_file_name.

Note that src_file_name is considered to be an absolute pathname when the following condition is true:

  • For Unix, the first character of src_file_name is a slash ( / ).

    For example, consider a src_file_name of /tmp/A.h5. If that source file does not exist, the new src_file_name after stripping will be A.h5.

  • For Windows, there are 6 cases:
    1. src_file_name is an absolute drive with absolute pathname.

      For example, consider a src_file_name of /tmp/A.h5. If that source file does not exist, the new src_file_name after stripping will be A.h5.

    2. src_file_name is an absolute pathname without specifying drive name.

      For example, consider a src_file_name of /tmp/A.h5. If that source file does not exist, the new src_file_name after stripping will be A.h5.

    3. src_file_name is an absolute drive with relative pathname.

      For example, consider a src_file_name of /tmp/A.h5. If that source file does not exist, the new src_file_name after stripping will be tmp\A.h5.

    4. src_file_name is in UNC (Uniform Naming Convention) format with server name, share name, and pathname.

      For example, consider a src_file_name of /tmp/A.h5. If that source file does not exist, the new src_file_name after stripping will be A.h5.

    5. src_file_name is in Long UNC (Uniform Naming Convention) format with server name, share name, and pathname.

      For example, consider a src_file_name of /tmp/A.h5. If that source file does not exist, the new src_file_name after stripping will be A.h5

    6. src_file_name is in Long UNC (Uniform Naming Convention) format with an absolute drive and an absolute pathname.

      For example, consider a src_file_name of /tmp/A.h5. If that source file does not exist, the new src_file_name after stripping will be A.h5

 

See Also:

Virtual Dataset Overview

Supporting Functions:

 

VDS Functions:

 

Returns:

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

Example:

Include Bitbucket Server for Confluence: File content cannot be shown

Unauthenticated access to this resource is not allowed. Please login to Confluence first.

History:
Release    Change
1.10.2A change was made to the method of searching for VDS source files.
1.10.0The C function was introduced with this release.

--- Last Modified: May 18, 2020 | 02:35 PM

 

The HDF Group

Copyright © 2006
All rights reserved

HDF is a registered trademark of The HDF Group.

Privacy Policy | Terms of Service

Site
Resources
Connect