6.7.32SHOW FILE

#Syntax

#Description

Show (i.e. get) the files within a directory named object_name or check for the existence of a file named object_name. If object_name is not specified, all files within the directory currently in use are returned. Otherwise, if object_name is specified and the keyword LIKE is not specified, one of the following behaviors applies:

• If it ends with “/”, object_name will be treated as a directory and all files within this directory are returned.
• If it does not end with “/”, object_name will be checked for existence as a file. If it exists, object_name is returned; otherwise, if it does not exist, an error is raised.

In case the keyword LIKE is specified, only files with names complying with a regular expression named regular_expression will be returned (in HDFql, regular expressions are the ones specified by PCRE, which closely follows Perl 5 syntax – please refer to https://www.pcre.org and https://perldoc.perl.org/perlre for additional information). As a general rule, in case regular_expression contains spaces or special characters, it should be enclosed in double quotes (“). Otherwise, if it is not enclosed in double quotes, files are not returned, and an error is raised. If regular_expression includes “**”, a recursive search is performed (i.e. HDFql will search in all existing directories and subdirectories for files to return). If object_name is specified, the recursive search starts from within object_name, which is assumed to be a directory. To limit the recursiveness, the keyword DEEP may be specified along with a value deep_value that represents the maximum recursiveness limit. In case the keyword SKIP is specified, HDFql will skip (i.e. ignore) a directory that cannot be opened (due to, e.g., permission restrictions) and continue searching (instead of stopping and raising an error).

#Parameter(s)

object_name – optional string that specifies the name of the directory within which to show (i.e. get) existing files or to check for the existence of the object as a file.

regular_expression – optional string that specifies the regular expression with which the names of files must comply for those files to be returned. If regular_expression includes “**”, a recursive search is performed.

deep_value – optional integer that specifies the maximum recursiveness limit (i.e. how deep the recursive search is performed). If deep_value is specified, it must be equal to or greater than 0 (otherwise an error is raised).

post_processing_option – optional option that transforms the result set according to the programmer’s needs, such as ordering or truncating (please refer to the section PROCESSING for additional information).

output_redirecting_option – optional option that specifies the cursor in use, an HDF5 object (i.e. dataset or attribute), a (text, binary, or Excel) file, or memory (i.e. user-defined variable) to write the result set into (please refer to the subsection INTO for additional information). If not specified, the cursor in use is populated with the result set instead (please refer to the chapter CURSOR for additional information).

#Return

The file names within a directory or the existence of a file as an HDFQL_VARCHAR.

#Example(s)

# create three HDF5 files named "my_file0.h5", "my_file1.h5", and "my_file2.h5" within the working directory currently in use
CREATE FILE my_file0.h5, my_file1.h5, my_file2.h5

# create two HDF5 files named "my_file3.h5" and "my_file4.h5" within a directory named "my_directory" (create directory if it does not exist)
CREATE FILE my_directory/my_file3.h5, my_directory/my_file4.h5

# show (i.e. get) files within the working directory currently in use (should return "my_file0.h5", "my_file1.h5", and "my_file2.h5")
SHOW FILE

# show (i.e. get) files within directory "my_directory" (should return "my_file3.h5" and "my_file4.h5")
SHOW FILE my_directory/

# show (i.e. get) files within the working directory currently in use and within subdirectories recursively (should return "my_file0.h5", "my_file1.h5", "my_file2.h5", "my_directory/my_file3.h5", and "my_directory/my_file4.h5")
SHOW FILE LIKE **

# show (i.e. get) files that finish with ".h5" in their names starting from the root directory (i.e. "/") and skip directories that cannot be opened (due to, e.g., permission restrictions)
SHOW FILE / LIKE **/\.h5$ SKIP

# check for the existence of a file named "my_file0.h5" within the working directory currently in use (should return "my_file0.h5" (i.e. it exists))
SHOW FILE my_file0.h5