6.4.7CREATE EXTERNAL LINK

#Syntax

#Description

Create an HDF5 external link named link_name to a group or dataset named object_name stored in another HDF5 file named target_file_name. Multiple external links can be created at once by separating their names with a comma (,). If link_name already exists, it is not overwritten, no subsequent external links are created, and an error is raised. To overwrite an existing external link, specify the keyword TRUNCATE.

#Parameter(s)

file_name – optional string that specifies the name of the HDF5 file in which the external link is to be created. If file_name is specified, the file is opened on the fly, the external link is created within it, and the file is subsequently closed. If not specified, the file currently in use is used instead. As a general rule, in case file_name contains spaces or special characters, it should be enclosed in double quotes (“). Otherwise, if it is not enclosed in double quotes, the link is not created, and an error is raised. This rule also applies to any other HDFql operation that works with file names (e.g. RENAME FILE).

link_name – mandatory string that specifies the name of the HDF5 external link to create. As a general rule, in case link_name contains spaces or special characters, it should be enclosed in double quotes (“). Otherwise, if it is not enclosed in double quotes, the link is not created, and an error is raised. This rule also applies to any other HDFql operation that works with external link names (e.g. RENAME EXTERNAL LINK).

target_file_name – mandatory string that specifies the name of the HDF5 file in which object_name is stored and to which link_name points. As a general rule, in case target_file_name contains spaces or special characters, it should be enclosed in double quotes (“). Otherwise, if it is not enclosed in double quotes, the link is not created, and an error is raised. This rule also applies to any other HDFql operation that works with file names (e.g. RENAME FILE).

object_name – mandatory string that specifies the name of the HDF5 group or dataset (stored in file_name) to which link_name points. As a general rule, in case object_name contains spaces or special characters, it should be enclosed in double quotes (“). Otherwise, if it is not enclosed in double quotes, the link is not created, and an error is raised. This rule also applies to any other HDFql operation that works with external link names (e.g. RENAME EXTERNAL LINK).

#Return

Nothing

#Example(s)

# use (i.e. open) an HDF5 file named "my_file0.h5" 
USE FILE my_file0.h5

# create an HDF5 group named "my_group0" 
CREATE GROUP my_group0

# create an HDF5 dataset named "my_dataset0" of data type variable-length unsigned int 
CREATE DATASET my_dataset0 AS UNSIGNED VARINT

# create an HDF5 external link named "my_link0" to object "my_group0" in file "my_file0.h5" (the external link will not be overwritten if it already exists)
CREATE EXTERNAL LINK my_link0 TO my_file0.h5 my_group0

# create an HDF5 external link named "my_link1" to object "my_object0" in file "my_file1.h5" (the external link will be overwritten if it already exists)
CREATE TRUNCATE EXTERNAL LINK my_link1 TO my_file1.h5 my_object0

# create two HDF5 external links named "my_link2" and "my_link3" to object "my_object1" in file "my_file1.h5" and object "my_object2" in file "my_file2.h5", respectively (neither external links will be overwritten if they already exist)
CREATE EXTERNAL LINK my_link2, my_link3 TO my_file1.h5 my_object1, my_file2.h5 my_object2

# create an HDF5 external link named "this is a long external link name" to object "my_object3" in file "my_file3.h5" (the external link will not be overwritten if it already exists)
CREATE EXTERNAL LINK "this is a long external link name" TO my_file3.h5 my_object3

# use (i.e. open) an HDF5 file named "my_file4.h5" 
USE FILE my_file4.h5

# create an HDF5 external link named "my_link4" in the HDF5 file currently in use (i.e. file "my_file4.h5") to object "my_object4" in file "my_file5.h5"
CREATE EXTERNAL LINK my_link4 TO my_file5.h5 my_object4

# close HDF5 file currently in use (i.e. file "my_file4.h5") 
CLOSE FILE 

# create an HDF5 external link named "my_link5" in file "my_file4.h5" to object "my_object5" in file "my_file6.h5"
CREATE EXTERNAL LINK my_file4.h5 my_link5 TO my_file6.h5 my_object5