# Utilities

*DIRTREE | Return Directory Tree

## Invocation

CALL "*dirtree", starting_dir$, file_list$, file_sep$, include_dir_flag

Where:

starting_dir$ | Required | Input | This string variable/expression defines the directory whose tree structure is to be returned.
file_list$ | Required | Output | This string variable will be loaded with the pathnames of all the files (and optional sub-directories) with the directory provided. Each pathname will be separated by the character defined in file_sep$.
file_sep$ | Optional | Input | This optional string variable/expression defines the character (or string of characters) to be inserted between each pathname returned. If omitted, the default system separator character will be used. If it is null and the include_dir_flag parameter is included, file_sep$ is null and no character is inserted between each pathname.
include_dir_flag | Optional | Input | This numeric variable/expression, if non-zero, indicates that sub-directory names are to be included. If omitted or zero, only file names will be included in file_list$. Sign of include_dir_flag indicates if directory names precede or follow files. If +, it precedes files; if -, it follows (suitable for deletes).

## Description

This routine will return a string consisting of a list of the pathnames to all the files in a directory, including its sub-directories.

Calling Sequence:

> CALL "*dirtree", start_dir$, file_list$, sep_char$, include_flag

An error will be generated if the starting directory does not exist. Passing a filename in the starting_dir$ will have unpredictable results.

When including sub-directory names (include_dir_flag non-zero), the directory names will be included in the file list. If include_dir_flag is positive, the directory names will precede the file names; if negative, the directory names will occur following all the file names. Using a negative value in include_dir_flag will allow the resultant file list to be used when deleting sub-directory structures.

#### Note:
The filenames "." and ".." will be omitted from the resultant file list.

(The *DirTree utility was added in PxPlus v10.20.)