#### DIR

#### Synopsis

    HELP:   Defines how to handle directories and various file types if wildcards used
    TYPE:   OBJECT
    SYNTAX: DIR(LINK,ALIAS,HIDDEN,RECURSIVE,ARCHIVE,ONEFILESYSTEM,TAPE,OBTAIN)

#### Description

This object defines multiple switches that control how input files are found. This is especially important when using wildcards in input filenames. There are switches to enable recursion into subdirectories, following symbolic links, finding hidden files, recursion into archive files, include files on tapes, resolving aliases and enforcing to not leave the filesystem.

If the `recursive` flag is set, the filename portion of the input file string is searched for recursively. If a directory path containing wildcards is present, the filename portion is searched for recursively in all paths that match the directory path pattern, e.g. "/path/.txt" matches my/path/hugo.txt, another/path/hugo.txt as well as my/path/subdir/hugo.txt. Without the recursive flag, the last file would not be found.

If the `archive` switch is enabled, FLAMFILES, TARBALLS, ZIP files and other kinds of supported archives are searched. All the matching members are extracted. In other words, archives are interpreted like subdirectories if the flag is enabled.

If the `tape` switch is enabled, then datasets stored on tapes or if migrated (if VOLSER = 'MIGRAT' or 'ARCIVE' on z/OS) files are searched. If the name of such a file matches the pattern, then it might occur that console input and a manual intervention is required to retrieve the respective dataset(s).

A special behavior was implemented for z/OS for files on DASD, where a SVC27(OBTAIN) is issued for nonVSAM data sets (normal PS/PO). To collect also files if the SVC27 failed the obtain switch must be set. Normally this will result in a warning and completion code 4. If the obtain switch is not defined, files without a corresponding control blocks are skipped.

If the `link` switch is enabled, symbolic links are followed (otherwise they are ignored). Links are mainly supported on modern file systems. For dataset aliases on mainframe systems, see the alias flag.

With the `alias` switch enabled, datasets names which are aliases of the real dataset are resolved to their actual names (otherwise they are ignored). Dataset aliases only exist on mainframe systems. This flag has no effect on other platforms.

If a transparent read method (e.g. read.auto()) is used, then the `archive` flag is enabled by default and cannot be disabled.

#### Arguments

- `SWITCH: LINK - Include symbolic links`
- `SWITCH: ALIAS - Resolve data set aliases`
- `SWITCH: HIDDEN - Include hidden files`
- `SWITCH: RECURSIVE - Include sub directories`
- `SWITCH: ARCHIVE - Include archives (FLAMFILEs, ZIP, ...)`
- `SWITCH: ONEFILESYSTEM - Don't cross file system boundaries`
- `SWITCH: TAPE - Include files deposited on tapes (or if migrated or archived)`
- `SWITCH: OBTAIN - Obtain control blocks if DSAD (z/OS only, warning if SVC27 failed)`