6.4.2CREATE FILE

#Syntax

#Description

Create an HDF5 file named file_name. Multiple files can be created at once by separating their names with a comma (,). If file_name already exists, it is not overwritten, no subsequent files are created, and an error is raised. To overwrite an existing file, specify the keyword TRUNCATE (all data stored in the file will be permanently lost). In case the keyword AND USE is specified, the file is used (i.e. opened) after being successfully created (please refer to the operation USE FILE for additional information). In case the keyword IN PARALLEL³⁴ is specified, HDFql creates the file in parallel using all the processes associated with the default MPI communicator (MPI_COMM_WORLD) or with a user-defined MPI communicator (that may have been set through the function hdfql_mpi_use_communicator). In case the keyword LIBRARY BOUNDS is specified, HDFql creates the file using these bounds (instead of the library bounds that may have been set through the operation SET LIBRARY BOUNDS). By default, the root (i.e. “/”) of the file to create does not track objects (i.e. groups, datasets, (soft) links, and external links) stored within it by their creation order. To track the creation order of objects stored in the root, the keyword ORDER TRACKED must be specified. In case the keyword ORDER INDEXED is specified, objects stored within the root are also tracked by their creation order and using an index (to speed up retrieval of object names). By default, the root does not track attributes stored within it by their creation order. To track the creation order of attributes stored in the root, the keyword ATTRIBUTE ORDER TRACKED must be specified. In case the keyword ATTRIBUTE ORDER INDEXED is specified, attributes stored within the root are also tracked by their creation order and using an index (to speed up retrieval of attribute names). In case the keyword USERBLOCK is specified, a user-defined block of data may be specified and stored within the file in a space reserved for this purpose.

#Parameter(s)

file_name – mandatory string that specifies the name of the HDF5 file to create. 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 file 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_max_compact – optional integer that specifies the maximum number of links (i.e. objects) to store in the compact format. In case the number of links (stored in the root (i.e. “/”) of the HDF5 file to create) exceeds object_max_compact, the storage of links switches to the dense format. If not specified, its default value is 8 (defined by the HDF5 library).

object_min_dense – optional integer that specifies the minimum number of links (i.e. objects) to store in the dense format. In case the number of links (stored in the root (i.e. “/”) of the HDF5 file to create) falls below object_min_dense, the storage of links switches to the compact format. If not specified, its default value is 6 (defined by the HDF5 library).

attribute_max_compact – optional integer that specifies the maximum number of attributes to store in the compact format. In case the number of attributes (stored in the root (i.e. “/”) of the HDF5 file to create) exceeds attribute_max_compact, the storage of attributes switches to the dense format. If not specified, its default value is 8 (defined by the HDF5 library).

attribute_min_dense – optional integer that specifies the minimum number of attributes to store in the dense format. In case the number of attributes (stored in the root (i.e. “/”) of the HDF5 file to create) falls below attribute_min_dense, the storage of attributes switches to the compact format. If not specified, its default value is 6 (defined by the HDF5 library).

userblock_size – optional integer that specifies the size (in bytes) of a user-defined block of data stored within the HDF5 file to create. The size must be a power of 2 that is at least 512 (e.g. 512, 1024, 2048) (any other value will raise an error).

userblock_value – optional integer, float, or string to write as a user-defined block of data stored within the HDF5 file to create.

input_redirecting_option – optional option that specifies the cursor in use, a (text, binary, or Excel) file, or memory (i.e. a user-defined variable) from which to read data to write as a user-defined block within the HDF5 file to create (please refer to the subsection FROM for additional information).

#Return

Nothing

#Example(s)

# create an HDF5 file named "my_file0.h5" (the file will not be overwritten if it already exists)
CREATE FILE my_file0.h5

# create an HDF5 file named "my_file1.h5" in a root directory named "data" (the file will not be overwritten if it already exists)
CREATE FILE /data/my_file1.h5

# create two HDF5 files named "my_file2.h5" and "my_file3.h5" (both files will be overwritten if they already exist)
CREATE TRUNCATE FILE my_file2.h5, my_file3.h5

# create an HDF5 file named "my_file4.h5" (the file will not be overwritten if it already exists) with the latest version of the HDF5 library
CREATE FILE my_file4.h5 LIBRARY BOUNDS FROM LATEST TO LATEST 

# create an HDF5 file named "this is a long file name.h5" (the file will not be overwritten if it already exists) and use (i.e. open) it for subsequent operations
CREATE AND USE FILE "this is a long file name.h5" 

# create an HDF5 file named "my_file5.h5" (the file will not be overwritten if it already exists) in parallel (i.e. all MPI processes specified when launching the program (that employs HDFql) will collectively create the file – e.g. if the program is launched as "mpiexec -n 3 ./my_program", all three MPI processes will participate in the creation of the file)
CREATE FILE my_file5.h5 IN PARALLEL 

# create an HDF5 file named "my_file6.h5" (the file will be overwritten if it already exists) with a user-defined block of data (size 512) storing values 50, 60, and 70
CREATE TRUNCATE FILE my_file6.h5 USERBLOCK SIZE 512 VALUES(50, 60, 70)