6.7.31SHOW DIRECTORY

#Syntax

#Description

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

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

In case the keyword LIKE is specified, only directories 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, directories 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 directories to return). If directory_name is specified, the recursive search starts from within directory_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)

directory_name – optional string that specifies the name of the directory within which to show (i.e. get) existing subdirectories or to check for the existence of the directory.

regular_expression – optional string that specifies the regular expression with which the names of directories must comply for those directories 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 directory names within a directory or the existence of a directory as an HDFQL_VARCHAR.

#Example(s)

# create three directories named "my_directory0", "my_directory1", and "my_directory2" within the working directory currently in use
CREATE DIRECTORY my_directory0, my_directory1, my_directory2

# create two directories named "my_subdirectory0" and "my_subdirectory1" within the directory "my_directory0", and a directory named "my_subsubdirectory0" within directory "my_directory0/my_subdirectory1"
CREATE DIRECTORY my_directory0/my_subdirectory0, my_directory0/my_subdirectory1, my_directory0/my_subdirectory1/my_subsubdirectory0

# show (i.e. get) directories within the working directory currently in use (should return "my_directory0", "my_directory1", and "my_directory2")
SHOW DIRECTORY

# show (i.e. get) directories within directory "my_directory0" (should return "my_subdirectory0" and "my_subdirectory1")
SHOW DIRECTORY my_directory0/

# show (i.e. get) directories within the working directory currently in use and within subdirectories recursively (should return "my_directory0", "my_directory1", "my_directory2", "my_directory0/my_subdirectory0", "my_directory0/my_subdirectory1", and "my_directory0/my_subdirectory1/my_subsubdirectory0")
SHOW DIRECTORY LIKE **

# show (i.e. get) directories that contain "directory1" in their names within the working directory currently in use and within subdirectories recursively (should return "my_directory1" and "my_directory0/my_subdirectory1")
SHOW DIRECTORY LIKE **/directory1

# show (i.e. get) directories within directory "my_directory0" and within subdirectories recursively (should return "my_subdirectory0", "my_subdirectory1", and "my_subdirectory1/my_subsubdirectory0")
SHOW DIRECTORY my_directory0/ LIKE **

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